Using a transcoders file

Transcoding plugins

To perform a transcoding operation, the Unified Streaming transcoding framework uses a so-called transcoding pipeline. Such a pipeline consists of:

• a decoder, which decodes compressed media data (in some specific format) to uncompressed ('raw') media data;

• a list of (zero or more) filters that manipulate the raw media data, and

• an encoder, which converts the raw media data to some specific (and possibly different) compressed format.

Most of our decoders, filters, and encoders are implemented as plugins in the form of dynamically loaded DLLs/shared libraries, which allows the user to select a specific implementation.

These plugins may differ in terms of performance, media quality, or requirements on the computing environment, such as the operating system, the availability of some run-time library component, a specific GPU, or the ability to run in a containerized environment.

For example, for decoding AVC video data, we offer a plugin that uses the mfx library from the Intel Media SDK (which, on Linux, requires an Intel GPU and cannot be used in a standard containerized environment), and one based on FFmpeg's avcodec library (which is more portable and adapts itself to the available hardware resources).

The transcoders file

Using a transcoders file, the user can specify which plugins to use when a transcoding pipeline is created. This is probably best illustrated by an example transcoders file:

# Example transcoders file selecting the mfx plugins (Intel Media SDK)
# for video transcoding

# Transcoder type       Implementation     Attributes (as of version 1.14.3)

video_decoder_avc       mfx                mode=auto
video_filter_resize     mfx                mode=auto
video_encoder_avc       mfx                mode=auto
video_encoder_jpg       mfx                mode=auto quality=30

Each non-empty [1] line specifies a transcoder type, followed by the name of the user-selected implementation for that transcoder type. Each transcoder type/implementation pair is mapped to some platform- and version-specific plugin name, which is dynamically loaded when the transcoding pipeline is created.

New in version 1.14.3: In addition to the transcoder type and its corresponding implementation, a list of zero or more attributes in the form of <key>=<value> pairs may be added at the end of the line to configure the plugin. Each plugin has its own set of accepted attributes; if an attribute is not set explicitly, a default value applies.

Specifying which transcoders file to use

Remote transcoding

An Apache web server can be configured to serve transcoding requests by installing and enabling mod_unified_transcode, installing any additionally required transcoding plugin packages [7], and defining a transcoding location within a VirtualHost directive (or the main server configuration). For example:

<LocationMatch "^\/transcoding/.*\.mp4$">
  UspHandleTranscode On
  UspTranscodersFile /etc/apache2/transcoders.usp
</LocationMatch>

The UspHandleTranscode directive enables transcode request handling for this location (here, URL paths starting with /transcoding/ and ending in .mp4); the UspTranscodersFile directive specifies the absolute path to the transcoders file to use for requests directed at this location.

USP command line clients (mp4split, unified_remix, unified_capture and unified_transcode) can then use the remote transcoding server with the --transcode_proxy_pass=<URL> command line option. For the example location above, that would be:

mp4split -o <output> \
  --transcode_proxy_pass=http://<transcoding host>/transcoding/ \
  <other options and arguments>

It is possible to define multiple transcoding locations, each configured with its own transcoders file:

<LocationMatch "^\/mfx-transcoding/.*\.mp4$">
  UspHandleTranscode On
  UspTranscodersFile /etc/apache2/mfx-transcoders.usp
</LocationMatch>

<LocationMatch "^\/ffmpeg-transcoding/.*\.mp4$">
  UspHandleTranscode On
  UspTranscodersFile /etc/apache2/ffmpeg-transcoders.usp
</LocationMatch>

This allows clients to select a pre-configured set of transcoding plugins by using a different path in the URL passed to the --transcode_proxy_pass option.

Local transcoding

As an alternative to the --transcoder_proxy_pass=<URL> command line option, you can select a locally available transcoders file with the --transcoders_file=<path> option. This results in local transcoding: the transcoding pipeline is run as an integral part of the locally invoked OS process [8]. For an example use of local transcoding, see Tiled Thumbnails with FFmpeg.

Note

The --transcoders_file option is ignored if the --transcode_proxy_pass option is present: in that case, the transcoders file as configured in the remote transcoding server is used.

For backward compatibility, if both --transcode_proxy_pass and --transcoders_file are missing on the command line, transcoding operations (if any) are run locally, and a set of default settings is applied.

Available video transcoding plugins

Currently, the following video transcoding plugins are available [7]:

Transcoder type	Implementation	Attributes (as of version 1.14.3)
video_decoder_avc	mfx [2]	mode [5]
video_decoder_avc	avcodec [3]
video_decoder_hvc	avcodec [3]
video_filter_resize	mfx [2]	mode [5]
video_filter_resize	swscale [4]
video_encoder_avc	mfx [2]	mode [5]
video_encoder_jpg	mfx [2]	mode [5], quality [6]
video_encoder_jpg	avcodec [3]	quality [6]

Default video transcoding plugin settings

For backward compatibility reasons, in the absence of an explicitly specified transcoders file, or if a particular transcoder type is not listed in this file, the following defaults apply:

Transcoder type	Implementation	Attributes (as of version 1.14.3)
video_decoder_avc	mfx [2]	mode=auto [5]
video_decoder_hvc	avcodec [3]
video_filter_resize	mfx [2]	mode=auto [5]
video_encoder_avc	mfx [2]	mode=auto [5]
video_encoder_jpg	mfx [2]	mode=auto [5] quality=30 [6]

Warning

Because we're in the process of providing alternatives for the use of the Intel Media SDK/libmfx, the default implementation names listed above may change in some future USP release. Instead of relying on any defaults, it is better to always specify the implementation names in a transcoders file.

Footnotes

[1]

Comments, that is, everything from a #-character to the end of the line it appears on, are skipped first.

[2] (1,2,3,4,5,6,7,8)

Uses libmfx, which is part of the Intel Media SDK.

[3] (1,2,3,4)

Uses libavcodec, which is part of the FFmpeg libraries.

[4]

Uses libswscale, which is part of the FFmpeg libraries.

[5] (1,2,3,4,5,6,7,8)

Valid values for mode are hw (use hardware transcoding), sw (use software transcoding, only available on Windows) and auto (select best mode). Defaults to auto.

[6] (1,2,3)

quality: a number ranging from 1 to 100 (inclusive). A higher value results in better output, but requires more time (and CPU/GPU resources) to produce. Defaults to 30.

[7] (1,2)

If available for your platform, the mfx plugins are contained in the mp4split package. The mp4split-ffmpeg-plugins package contains the avcodec and swscale plugins.

[8]

This implies that the local computing environment must satisfy the requirements of the plugins selected in the transcoders file.