Using Videos with Bob¶

Codec and Format Availability¶

To get a list of all FFmpeg (or libav) supported formats for a given build of Bob, use the bob_video_test.py application provided by this module:

$ ./bin/bob_video_test.py --list-all-codecs # lists all codecs available

$ ./bin/bob_video_test.py --list-all-formats # lists all formats available

These listings represent all that is compiled with your current installation of FFmpeg or libav. To list supported formats and codecs by Bob use another set of command-line options:

$ ./bin/bob_video_test.py --list-codecs # lists all codecs currently supported

$ ./bin/bob_video_test.py --list-formats # lists all formats currently supported

The program bob_video_test.py can be used to run a sequence of tests using all combinations of supported formats and tests:

$ ./bin/bob_video_test.py # runs all tests

This will run through all combinations of supported codecs and formats and will report average distortion figures for each of 4 different tests, which exercise different aspects of each combination of format and codec. Here is a an example output:

Video Encoding/Decoding Test Tool v1.2.0a0 (bob_video_test)
Settings:
  Width    : 128 pixels
  Height   : 128 pixels
  Length   : 30 frames
  Framerate: 30.000000 Hz
Legend:
  C: Color test
  N: Noise test
  U: User test
  S: Frameskip test
Running 4 test(s)...CSNU

=========== ===== ======= =======================================
 test        fmt   codec   figure (lower means better quality)
=========== ===== ======= =======================================
 color       mov   h264    4.603 min=0.890@22 max=8.387@9
 frameskip   mov   h264    0.108 min=0.009@11 max=0.344@0
 noise       mov   h264    44.900 min=43.916@4 max=46.103@29
 user        mov   h264    1.983 min=1.525@0 max=2.286@7
=========== ===== ======= =======================================

Each line in the output table represents the average distortion patterns for the particular test using the format and codec described. The lower the distortion, the better the combination of format and codecs is. Different tests have different levels of baseline performance. The figures above were obtained in a healthy (no know bugs) system, running libav 0.8.13 (Ubuntu 12.10). Each line indicates, besides the average distortion per frame, the minimum and the maximum obtained and in which frame (counting from 0 - zero), that figure was obtained.

The video tests are made on temporary files that are discarded after the test is completed. You can use the option --output=<directory> to specify a directory in which the generated files will be saved. You can then go to these directories and explore potential problems you may find.

Each test creates a video from an artificially generated test signal, encodes it using the defined format and codec and reads it back, comparing the output result with the original sequence. The sole exception is the user test. In this test, a user test sequence is (partially) loaded and tested. If you don’t specify any sequence, a default sequence from Bob is used. If you want to test a specific sequence of your own, use --user-video to specify the path of the video sequence you want to test with. By default, only the first 10 frames of the sequence are used for the test, to speed-up execution. You can change this behavior with the option --user-frames. Here is an example:

$ ./bin/bob_video_test.py --user-video=test_sample.avi

All tests are executed by default, on all combination of formats and codecs. That can be long. You can limit the test execution by properly choosing the format (--format), the codec (--codec) and the tests to execute. For example:

# execute only the user video test with a user provided video and
# using the H.264 built-in codec and a MOV output file format.
$ ./bin/bob_video_test.py --format mov --codec h264 --user-video=test_sample.avi -- user

>>> import bob.io.video
>>> codecs = bob.io.video.supported_videowriter_formats()['mp4']['supported_codecs'].keys()
>>> print(codecs) 
['h264', 'libx264', 'mjpeg', 'mpeg1video']

You can test new combinations of formats and codecs which are not currently supported by Bob, as long as they are supported by the underlying FFmpeg or libav installations. In this case, just specify the format and/or codec names using --format and --codec options in the application bob_video_test.py. The advantage of using supported formats and codecs is that we make sure a minimal distortion figure is respected in all platform nightly builds, with our unit and integration tests. We cannot, currently, test all possible combinations of codecs and formats.

Know Your Platforms¶

One important aspect when working with videos is to know there will be some lossy compression applied to the output. This means you will loose information when re-encoding. When working with videos, you will want to choose the combination of format and codec that will work well accross different platforms. We recommend to run bob_video_test.py with a few of your video inputs to make sure they can be decoded with low distortion where you plan to work.

Example Output in Different Platforms¶

In what follows, you will find some tabbed output for different combinations of operating systems and FFmpeg/libav versions. To run these tests we only executed:

$ ./bin/bob_video_test.py