Skip to content

Installation Guide for Novices

Jump to bottom
Zhiming Wang edited this page Dec 30, 2017 · 4 revisions

Before you start

  • This guide was last updated on December 30, 2017. Information here is time-sensitive. If you are reading this more than one year later, please ask around before following the instructions.

  • This is an opinionated guide, so I don't tell you about MacPorts or standalone Windows executable installers (well, I do, but this is all I'm going to say). These are ultimately for the better.

Contents

macOS

On macOS you should use the Homebrew package manager.

  • Follow official instructions to install Homebrew;

  • To install the latest FFmpeg and Python, run

    brew install ffmpeg python3

  • To install caterpillar, run

    pip3 install caterpillar-hls

  • You should now be able to use caterpillar:

    caterpillar -h

Windows

On Windows you should use the Chocolatey package manager.

  • Follow official instructions to install Chocolatey;

  • To install the latest FFmpeg and Python, open cmd.exe or PowerShell.exe as administrator, and run

    choco install ffmpeg python

    You can now use Python in new cmd.exe or PowerShell.exe shells, administrator or not.

  • To install caterpillar, open a new cmd.exe or PowerShell.exe shell and run

    pip install caterpillar-hls

  • You should now be able to use caterpillar:

    caterpillar -h

I made a video tutorial for this process.

Ubuntu

On Ubuntu, you should use the default package manager, but the official repos will most likely fetch you dated stuff only, unless you're on the bleeding edge release (most people, at least server folks, stay on LTS though). On well.

Basic proficiency with the Linux command line (e.g. knowledge of setting the PATH environment variable) is assumed.

FFmpeg

Artful (17.10) or later

The FFmpeg in the official repository should be good enough.

sudo apt update
sudo apt install ffmpeg

Zesty (17.04)

Unfortunately, the FFmpeg in the official repository (3.2.4 at the moment) does not appear to work with caterpillar. However, Zesty reaches end of life in January 2018, so you should upgrade to Artful anyway.

LTS: Trusty (14.04) or Xenial (16.04)

You may use the reputable jonathonf/ffmpeg-3 PPA to install the latest FFmpeg on Trusty or Xenial.

sudo add-apt-repository ppa:jonathonf/ffmpeg-3
sudo apt-get update
sudo apt-get install ffmpeg

Python and caterpillar

You need to install Python 3.6 or later, which, depending on your Ubuntu release, could vary in the number of hoops you need to jump through.

Artful (17.10) or later

Artful or later comes with Python 3.6+ right in the official repository.

sudo apt update
sudo apt install python3 python3-pip

You can now use pip3 to install caterpillar:

pip3 install caterpillar-hls

You need to add $HOME/.local/bin to your $PATH to use caterpillar.

Zesty (17.04) or earlier with pyenv

You can install Python 3.6 or later on any Ubuntu release (including Artful or later) with pyenv. In fact, this is the choice of many highly experienced Python developers.

  • Follow these instructions on the pyenv wiki to install prerequisite packages with apt;

  • Follow the official instructions to install pyenv; follow the instructions carefully;

  • Install the latest version of Python with pyenv, e.g. 3.6.4 at the moment:

    pyenv install 3.6.4

  • Run

    pyenv shell 3.6.4

    (replace 3.6.4 with the version you installed) to activate this Python version. Read the official instructions to learn how to make your choice persistent.

  • Install caterpillar with pip:

    pip install caterpillar-hls

LTS: Trusty (14.04) or Xenial (16.04) with deadsnakes

If you don't want to build Python yourself with pyenv, you may use the reputable deadsnakes PPA to install Python 3.6 on Trusty or Xenial. Note, however, that since the python3.6 package from deadsnakes need to coexist with the system python3 package, you do need to jump through hoops to use pip with Python 3.6.

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.6 python3.6-venv

Next you want to create a venv, a Python 3.6 virtual environment, to host caterpillar. Pick a path to your liking for the venv (it should be a not-yet-existent directory), and run

python3.6 -m venv /path/to/venv

Now, activate the venv:

. /path/to/venv/bin/activate

and install caterpillar:

pip install caterpillar-hls

You can now use caterpillar:

caterpillar -h

Do note that you need to activate the venv as above every time you want to use caterpillar.

To avoid activating the venv every time, either

  • Add /path/to/venv/bin to your $PATH (caution: you're overriding system python, python3, pip and pip3 this way); or
  • Put a symlink to /path/to/venv/bin/caterpillar in, say, $HOME/bin, then add $HOME/bin to $PATH.

Do keep in mind that in general there are subtleties with using executables in unactivated venvs, which most likely won't manifest with caterpillar.

Clone this wiki locally