What is Livius?

Livius is a small framework for making videos out of talks/presentations. It uses as input a video stream containing all the relevant informations: slides, speaker, sounds… and applies corrections to it:

  • slide contrast and aspect is corrected automatically
  • speaker is tracked (in progress)
  • title/epilog/credit pages may be added
  • the talk duration is cropped and pauses can be added as well (in progress)

Getting started

Livius defines workflow and jobs: those are convenient tools for being able to process the videos.

  • A job is a small processing unit that takes input and produces outputs, and maintains a state so that outputs are not being reprocessed if the inputs have not changed.
  • A workflow is a set of jobs with their dependencies (which defines a Directed Acyclic Graph)

Livius already contains many different jobs as well as some workflows.

Running Livius

Once you know more about the workflow you want to use, you may run the processing of this workflow over a bunch of videos simply by running

cd $livius_src
python -m livius \
  --workflow=my_workflow \
  --output-folder=/a/big/disk \
  --video-folder=my_folder_full_of_videos \
  --option=meta_location=/a/folder/containing/annotations

The detailed options of Livius are given below (just type --help in the previous command line):

usage: python -m livius [options]

Livius video processing. This project automate the process of creating video
files from recorded presentation. It takes asa input a directory containing
videos (or a single video)

optional arguments:
  -h, --help            show this help message and exit
  --video-folder VDIR   Indicates a folder containing videos to be processed.
                        All videos in the specified folders will be processed
                        (subfolders are not explored). This option may appear
                        multiple times.
  --video-file VFILE    Specific video file to process. This option may appear
                        multiple time.
  --list-workflows      lists all available workflows and exits
  --workflow WORKFLOW   specifies the workflow to use
  --thumbnails-folder THUMBNAILS_FOLDER
                        specifies the folder where the thumbnails will be
                        stored/retrieved
  --output-folder OUTPUT_FOLDER
                        specifies the output folder
  --process-only-index INDEX
                        process only the file specified by the INDEX. The
                        files are sorted so that this option may be used as an
                        option for dispatching the processing of all the files
                        on different machines (such as a cluster)
  --option KEY=VALUE    Additional runtime option. Each parameter has the form
                        --option=key=value. This option may appear multiple
                        times.
  --non-interactive     indicates that the processing will be not interactive
                        (mainly for matplotlib backend)
  --option-file FILE.json
                        Reads a set of additional runtime options from a json
                        file. This options in this file may be overriden by
                        the --option.
  --print-workflow      Prints the workflow (text) and exits.
  --dot-workflow        Prints the workflow (dot) and exits.
  --is-visual-test      If set on the command line, the video is processed
                        only for 10 seconds. This however does not prevent the
                        full thumbnail extraction.

The parameter --option may be used to define additional options needed by the runtime behaviour of the Jobs. The parameters accepted by the jobs are described in each job documentation under the rubric Runtime parameters.

Note

Every job in the current workflow will see all of --option settings.

Setting several parameters from the command line may be cumbersome. It is possible to pass --option-file which will read several parameters from a json file. A default configuration file is provided as default_config.json. The parameters set by the --option may override the parameters set by the --option-file so that it is possible to override the default settings from the command line.

--is_visual_test permits to limit the processing of the final video to 10 seconds, which may be convenient for visual checks. However the thumbnail extraction is (currently) performed for the full video.

--process-only-index makes the command run the processing of only one video. This is convenient in case the processing is run on a eg. cluster and each processing of a unique video spans one process.

--non-interactive might be needed in environment where no front-end interaction is possible (eg. remote session).

If you want to see more about the details of the workflow, you may use the options --print-workflow and --dot-workflow that print the selected workflow to the console, either in text or in dot format (that then may be rendered with graphviz).

The following lines:

python -m livius --workflow=workflow_extract_slide_clip --dot-workflow > test.dot
dot test.dot -Tsvg -otest.svg

yields this:

_images/output_workflow.svg

Installation

For FFMpeg related processing, ffmpeg should be installed and accessible from the command line. The dependencies of Livius are the following (which may be installed in a virtual environment, see/search in the wiki for more details).

pip install numpy matplotlib
pip install moviepy

# for the documentation
pip install sphinx
pip install sphinxcontrib-programoutput
pip install sphinx_bootstrap_theme

And finally, you can install Livius:

pip install .

Note

As always it is recommended to install everything in a dedicated virtual environment.

Font on Linux

Some specific fonts are used (see Lato font below). On Linux those fonts sa .ttf files should be installed as follow:

cp *.ttf $HOME/.fonts
fc-cache -fv

Meta information associated to the videos

The metadata associated to the video files describe the following:

  • the title of the talk
  • the speaker
  • the date
  • optionally an image used as introduction
  • optionally the pauses and begin/end of the video

The meta data is loaded by the Job Metadata. If your metadata is stored in a way that differs with the expectation of Metadata, it is easy to adapt this class to your needs (such an example if given in the file containing Metadata).

Relocatable files

The design of Livius attempts to have relocatable files, which means that the some root folder (eg. videos, metadata, cached values) might be specified and changed at runtime (command line invocation) without recomputing the intermediate or final results.

With this design, it is also possible to compute the results with different machines, from the same sources, and having different mount points.

Available ressources

The repository contains images that can be used out of the box for running Livius on videos. Those images are more or less related to the /Machine Learning Summer School/ (2013, 2015), but may be adapted easily.

  • livius/ressources/background_mlss2015.png the background image during the talk, containing visual cues (grey area on which the slides and the speaker are overlayed), mainly for visual sanity check
  • livius/ressources/background_no_grey_mlss2015.png, same as background_mlss2015 without grey areas (if one of the stream is smaller than the target one).
  • livius/ressources/Lato2OFL.zip is an archive containing the Lato fonts that are used by Livius (for overlaying the title etc.). This font was downloaded from this web site. It is licensed under the SIL Open Font License (OFL) v1.1 (“/The fonts can be used with­out any lim­i­ta­tions for com­mer­cial and non-​​commercial pur­poses/”).

Indices and tables