This page provides basic documentation for obtaining, building and using the Turing codec.

Contents:

  1. Getting the source code
  2. Building the Turing codec
  3. Running the encoder

 

1. Getting the source code

First, clone the source code from github:

git clone https://github.com/bbc/turingcodec.git
cd turingcodec
git checkout {stable|develop}

 

2. Building the Turing codec

Microsoft Windows (with Visual Studio 2015)

Prerequisites:

Building the project executable:

  • Open CMake for Windows
    • Set “Where is the source code” as the directory of your local repository.
    • Set “Where to build the binaries” to any new folder location you prefer.
    • Click ‘Configure’ and select the Win64 configuration corresponding to Visual Studio 2015.
    • Click ‘Generate’.
  •  A Visual Studio solution file (turing.sln) should be emitted into the new build folder location – open this with Visual Studio 2015 and build either as “Debug” or “Release”.

Linux

The instructions below were written for Ubuntu 14 and gcc/g++ version >= 4.8.2 although they should also be applicable to similar enviroments.

Prerequisites:

Run the following commands to install necessary tools and libraries:

sudo apt-get update
sudo apt-get install git-core g++ cmake make cmake-curses-gui

Build and test:

Go to the root folder of your local copy of the repository, cloned from Github. To have the code built in Debug and Release mode do the following:

mkdir -p build/debug build/release
cd build/debug
cmake ../../
ccmake ../../ (Make sure that the environment variable CMAKE_BUILD_TYPE is equal to "Debug". Press key "c" to configure and key "g" to generate and finally key "q" to quit)
make

cd build/release
cmake ../../
ccmake ../../ (Make sure that the environment variable CMAKE_BUILD_TYPE is equal to "Release". Press key "c" to configure and key "g" to generate and finally key "q" to quit)
make

If successful, an executable file called “turing-exe” will be emitted into “./build/{debug|release}/turing/”.

Integration with FFmpeg

Warning: the following instructions are for Linux only.

Please note that for the FFmpeg integration a version of the Boost libraries higher or equal than 1.58 is required to be installed in the system.

Prerequisites:

Build:

Test:

  • To test the encoder, type the following:
    ffmpeg -i in.mp4 -c:v libturing -turing-params speed=fast out.mp4
  • Command line options for the Turing codec are passed through FFmpeg using -turing-params option1=value1:option2=value2:...:optionN=valueN.

 

3. Running the encoder

The project is configured to build a single executable, turing-exe.exe under Windows or turing-exe under Linux.
When executed without any command line parameters, the following output is displayed:

Turing codec version: 

usage: turing-exe.exe  <command> [<args>]

Supported turing-exe.exe commands are:
   encode     Encode bitstream from input YUV
   decode     Decode bitstream to output YUV
   psnr       Report PSNR between two YUV files
   smoke      Run a minimal set of tests
   signature  Checks encoder integrity against expected outputs
   havoc      Runs havoc self test
   version    Concise version description

Use 'turing-exe.exe help <command>' for more information on a specific command.

In order to encode a YUV file (for instance input-file.yuv), use the command:

Turing.exe encode [options] input-file.yuv

Encoder options

The Turing codec supports a variety of input options to control many aspects of the encoder. Some of these options are required, while some other options are automatically defaulted to pre-defined values and can be omitted.

Two types of input options are supported: binary flags or parameters with arguments.

  • In case an option is controlled by a binary flag, simply passing the option --flag-name to the command line will prompt the encoder to act consequently (for instance enabling the corresponding tool). Most binary flags are paired with a disabling option in the form of --no-flag-name, which can be used to disable the corresponding option.
  • In case an option is controlled by a parameter with argument, the encoder expects the parameter to be followed by the corresponding argument as in --parameter arg.

A partial list of supported input options is shown below. Default values are shown in parentheses (a parameter is required when no default value is shown).

Input options:

  • --input-res arg input video resolution x (e.g. 1280×1024).
  • --frames arg number of frames to encode.
  • --seek arg (=0) number of initial frames to be skipped before encoding starts.

Output options:

  • -o [ --output-file ] arg output file name.
  • --dump-pictures arg reconstructed YUV file name (separate fields in case of field-coding).
  • --dump-frames arg reconstructed YUV file name (interleaved frames in case of field-coding).

Rate control options:

  • --qp arg (=26) quantization parameter.
  • --bitrate arg enables constant bitrate rate control based on lambda-rate model (arg is in kbps).

Parallelisation options:

  • --no-parallel-processing (=false) execute encoder in single threaded mode with no concurrent frames and no wpp.
  • --concurrent-frames arg (=4) number of concurrent frames that the encoder can encode in parallel.
  • --wpp (=true) wavefront parallel processing.
  • --threads arg (=0) number of threads that the encoder can execute in parallel. If set to 0, the encoder will automatically assign the optimal number of threads based on the current usage of the machine.

Coding tool options:

  • --deblock (=true) enables the deblocking filter.
  • --rdoq enables rate-distortion optimised quantisation.
  • --tskip (=false) enables transform skip.

Structure options:

  • --max-gop-n arg (=250) this corresponds to the intra period set by the user (which can change when the shot change detector is used).
  • --max-gop-m arg (=8) maximum anchor picture interval (1 or 8).
  • --ctu arg (=64) CTU size in luma pixels.
  • --min-cu arg (=8) minimum CU size in luma pixels.
  • --field-coding (=false) enables coding of interlaced pictures.
  • --shot-change (=false) enables shot change detection algorithm.

Reporting:

  • --psnr measure PSNR and report.
  • --profiler (=false) profile CPU usage and report.
  • --verbosity arg (=1) level of verboseness in the information the encoder outputs (0, 1 or 2).
  • -h [ --help ] display help message.

Performance options:

  • --speed arg (=slow) speed preset (one of slow, medium, fast).

Speed presets

Currently, the Turing codec supports three speed presets: slow, medium and fast.

The presets control the pre-defined values of many encoder options and tools. For instance, a given preset may enable/disable a given tool, or may assign a specific value to a certain parameter. The presets were designed to achieve specific trade-offs between computational complexity and encoder efficiency. As a general rule, when using the encoder in single-threaded mode without parallelisations (e.g. if using the –no-parallel-processing option), it can be expected that encoding using the medium preset is on average around 80-85% faster than encoding using the slow preset, and that encoding using the fast preset is 50-55% faster than encoding using the medium preset.

The table below shows a comprehensive list of all tools and options affected by the three speed presets and the pre-defined values associated with each preset. It should be noticed that users can at any time enforce the usage of any tool by passing the corresponding parameter or parameter value to the command line. Any option explicitly passed to the command line will take precedence over any pre-defined value associated with the speed preset currently being used.

Tool (options) Speed preset
Slow Medium Fast
AMPs disabled disabled disabled
2N × N, N × 2N enabled enabled disabled
RDOQ enabled enabled disabled
RQT enabled disabled disabled
APS disabled enabled enabled
MET disabled enabled enabled
RCU disabled enabled enabled
Sub-pel ME all all only half-pel
Search range for ME 64 64 32
Search range for bi-prediction 5 5 1
Number of merge candidates 5 5 2
Number of intra modes to test with RD search 8 8 4
Sign Data Hiding enabled enabled disabled
Deblocking filter enabled enabled enabled
Minimum CU size 8 8 8
CTU size 64 64 64

Examples of usage

turing-exe encode --speed medium --qp 38 --frame-rate 50  --max-gop-n 48  --frames 9 --psnr --verbosity 2 --input-res 3840x2160 --dump-pictures rec.yuv -o out.bit input_file.yuv

turing-exe encode --speed fast --bitrate 30000 --frame-rate 50 --max-gop-n 48  --frames 500 --input-res 3840x2160 -o out.bit input_file.yuv

 

Known issues

  1. When using the Turing codec from FFmpeg, the rate control module may not be as accurate as expected.
  2. Under Mac OS the Turing codec can only build using gcc 6.0. We are working to build the source using Clang.