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

Contents:

1. Getting the source code
2. Building the Turing codec
   • Microsoft Windows (with Visual Studio 2015)
   • Linux
   • Integration with ffmpeg
3. Running the encoder
   • Encoder options
   • Speed presets
   • Examples of usage
   • Known issues

 

1. Getting the source code

First, clone the Turing codec repository 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:

• Visual Studio 2015.
• CMake for Windows (version 3.4.1 used when writing these instructions).

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” will be emitted into “./build/{debug|release}/turing/”.

Integration with FFmpeg

Warning: the following instructions are for Linux only.

Prerequisites:

• You need to rebuild the code to install the Turing codec’s libraries on the FFmpeg source directories. To do this, type the following:

  cmake -DCMAKE_INSTALL_PREFIX="$HOME/ffmpeg_build" ..
  make install

• Get the required ffmpeg dependencies at https://trac.ffmpeg.org/wiki/CompilationGuide/Ubuntu#GettheDependencies.

Build:

• Create the directory where the FFmpeg sources will be downloaded.

  mkdir ~/ffmpeg_sources

• Follow the instructions in https://trac.ffmpeg.org/wiki/CompilationGuide/Ubuntu#ffmpeg but:
  • Instead of using wget and tar, clone ffmpeg from this branch https://github.com/kupix/FFmpeg-1/tree/libturing.
  • Add --enable-libturing and remove --enable-xxx for libraries you don’t have (e.g. libx264).

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 under Windows or turing under Linux.
When executed without any command line parameters, the following output is displayed:

Turing codec version: x.y

usage: turing <command> [<args>]

Supported turing 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 help <command>' for more information on a specific command.

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

turing 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.
• --sao (=true) enables the Sample Adaptive Offset filter.
• --rdoq enables rate-distortion optimised quantisation.
• --tskip (=false) enables transform skip.

Coding 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. This includes fade detection as well.

Video Usability Information (VUI) options:

• --sar arg specifies the Sample Aspect Ratio (SAR) in the form "w:h".
• --display-window arg specifies the position of the display window as  <left,right,top,bottom>.
• --overscan arg specifies the display of the over scan area. The argument takes these values <show|crop>.
• --video-format arg specifies the video format according to Table E.2 of the HEVC specification.
• --range arg specifies the pixel values range (full or limited).
• --colourprim arg specifies the colour primaries as in Table E.3 of the HEVC specification.
• --transfer-characteristics arg specifies the value for the transfer_characteristics syntax element of the HEVC VUI. Valid values are listed in Table E.4 of the HEVC specification.
• --colour-matrix arg specifies the colour matrix used to derive the luma and chroma components of the compressed signal. Valid values are listed in Table E.5 of the HEVC specification.
• --chroma-loc arg specifies the location of chroma samples. Valid values are in the range 0..5 with semantics described in Annex E of the HEVC specification.

Compression of HDR content options:

The Turing codec can compress HDR video content graded with both Hybrid Log-Gamma (HLG) and Perceptual Quantiser (PQ) transfer characteristics. These two curves are specified in ITU-R Recommendation BT.2100 and the codec automatically infers the use of Main10 profile of HEVC. Accordingly, the command line options are.

• --transfer-characteristics from the VUI above shall be set to 18 for HLG and 16 for PQ.
• --atc-sei arg (=-1) enables the insertion of the Alternative Transfer Characteristics (ATC) SEI message. This SEI message allows to exploits the backward compatibility of some transfer characteristics such as HLG. The argument is set to the transfer characteristics value to override the one associated with the transfer_characteristics in the VUI of HEVC.
• --mastering-display-info arg enables the insertion of the mastering display information SEI message. The argument is a string in the form “G(x,y)B(x,y)R(x,y)WP(x,y)L(max,min)”, where G(x,y) denotes the normalised chromaticity values for the green component (and similarly for blue and red), WP is the white point with associated normalised chromaticity values and L is the max and min value of the mastering display’s luminance.

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 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 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. Under Mac OS the Turing codec can only build using gcc 6.0. We are working to build the source using Clang.