Plugin selection: the transcoders file

The transcoders file

Using a transcoders file, we 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 ffmpeg- and x264-based
# plugins for video transcoding. The Intel Media SDK is not required
# nor used.

# Please note that the x264 AVC video encoding plugin (new in version
# 1.15.0) relies on a running instance of the x264_encoding_service.

# Transcoder type     Implementation    Attributes (as of version 1.14.3)

video_decoder_avc     avcodec           # <none>
video_filter_resize   swscale           # <none>
video_encoder_avc     x264              # service_host=::1 service_port=11264
video_encoder_jpg     avcodec           # quality=30

Note

This example transcoders file can be used as-is for any of the supported use cases and represents a good starting point if you plan on not using the Intel Media SDK or you are migrating away from it.

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.

Available video transcoding plugins

New in version 1.15.0: the x264 plugin for the video_encoder_avc transcoder type was added.

Each individual plugin may require the installation of a specific USP package. Currently, the following video transcoding plugins are available:

Transcoder type	Implementation name	Provided in USP Package	Attributes (as of version 1.14.3)	Default attribute value
video_decoder_avc	mfx [2]	mp4split	mode [6]	auto
video_decoder_avc	avcodec [3]	mp4split-ffmpeg-plugins
video_filter_resize	mfx [2]	mp4split	mode [6]	auto
video_filter_resize	swscale [4]	mp4split-ffmpeg-plugins
video_encoder_avc	mfx [2]	mp4split	mode [6]	auto
video_encoder_avc	x264 [5]	mp4split-x264-plugins	service_host [8] service_port [9]	::1 11264
video_encoder_jpg	mfx [2]	mp4split	mode [6] quality [7]	auto 30
video_encoder_jpg	avcodec [3]	mp4split-ffmpeg-plugins	quality [7]	30

Default implementation names

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 default implementation names apply:

Transcoder type	Default implementation name
video_decoder_avc	mfx [2]
video_filter_resize	mfx [2]
video_encoder_avc	mfx [2]
video_encoder_jpg	mfx [2]

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.

Specifying which transcoders file to use

Remote transcoding on a media processing unit

A media processing unit is an Apache web server configured to serve transcoding requests by installing and enabling mod_unified_transcode (see How to Install), installing any additionally required transcoding plugin packages, 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) 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.

Note

Changes to the configuration of the Apache web server only take effect after restarting it.

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 [10]. 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 implementation names is applied.

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. Only available on either Windows or Ubuntu 20.04 and later.

[3] (1,2)

Uses libavcodec, which is part of the FFmpeg libraries.

[4]

Uses libswscale, which is part of the FFmpeg libraries.

[5]

Connects to the x264 encoding service, which uses libx264.

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

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

[7] (1,2)

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

[8]

service_host: host name for connecting to the x264 encoding service.

[9]

service_port: TCP port number for connecting to the x264 encoding service.

[10]

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