Transcoding

From TVMosaic Wiki
Jump to: navigation, search

General

Transcoding is a process of changing stream parameters so that resulting audio/video signal and stream format confirm to the specific requirements.

TVMosaic uses video transcoding for two purposes:

  • Video playback in players, which support only specific audio/video formats (browsers, mobile devices)
  • Video playback "on the go" with strict limitation on the upload bandwidth

Platforms that support transcoding

TVMosaic supports transcoding on the following platforms:

  • Windows (software transcoding, QSV hardware accelerated encoding on Intel CPUs and nvenc hardware accelerated transcoding with NVidia GPU)
  • Mac OS X (software transcoding)
  • Ubuntu/Debian (software transcoding and VAAPI hardware accelerated transcoding on Intel CPUs)
  • Intel-based NAS products (software transcoding and VAAPI hardware accelerated transcoding on Intel CPUs)

For the Intel CPUs, which support hardware trancoding, please refer to the table at the following link.

Usecases

Transcoding activities in TVMosaic are based on usecases. Each usecase is a scenario, which has a particular purpose, input and output parameters. Each usecase is identified by its ID and has a correspondent set of ffmpeg parameters.

The following list describes the TVMosaic usecases in which ffmpeg is used:

  • ID: sendto_transcode, name: Convert recording to (h264/aac) mp4. This scenario is performed when a recording is converted to mp4 file, having aac audio and h267 video, as part of SendTo operation.
  • ID: thumb_from_file, name: Generate thumbnail from recording. This scenario is performed when a thumbnail is generated from a recording.
  • ID: transcode_live_to_ts, Convert live TV to (h264/aac) transport stream. This scenario is performed when live TV stream is converted to a transport stream, having aac audio and h264 video. It corresponds to TVMosaic play channel transcoder parameter set to "h264ts".
  • ID: transcode_live_to_hls, name: Convert live TV to HLS. This scenario is performed when live TV stream is converted to HLS stream. It corresponds to TVMosaic play channel transcoder parameter set to "hls".
  • ID: transcode_recoding_to_hls, name: Convert recording to HLS. This scenario is performed when a recording is transcoded to HLS for playback on remote clients.
  • ID: transcode_live_to_mp4, name: Convert live TV to mp4 container with h264 video and AAC audio. This scenario is in particular used for Chromecast streaming. It corresponds to TVMosaic play channel transcoder parameter set to "mp4".

How to enable hardware accelerated transcoding in TVMosaic

First of all,you need to check if your CPU supports hardware accelerated video decoding/encoding features using the link above.

Also, please make sure that you have installed the latest graphic drivers / NAS firmware on your system.

If your system supports hardware accelerated transcoding, you need to enable it in TVMosaic settings.

Open TVMosaic desktop application, navigate to Settings/Transcoding tab and select a hardware accelerated ffmpeg profile for the desired usage scenarios (aka usecases):

Transcoding settings.jpg

Performance considerations

Software transcoding is a very CPU intensive operation. In general it is expected that most of the NAS, Windows, MacOS and Ubuntu installations should be able to transcode in software SD channels properly. However for HD channel software transcoding a powerful CPU is required.

It is suggested, providing that system supports it, to use hardware accelerated transcoding whenever possible (please, also refer to the video quality considerations below).

Troubleshooting

If transcoded playback does not start, the first thing you need to do is to set TVMosaic log level to info, reproduce the issue and inspect the TVMosaic log file. It night give you a clue on what is going wrong.

The more advanced method, during which you can see the ffmpeg running with its output, is to start TVMosaic in a command line mode. To do this, you need to stop TVMosaic daemon first (from Task Manager on Windows or using sudo ./stop.sh from a command line on all other platforms when in TVMosaic installation directory).

Then execute

tvmosaic_server.exe --command_line_mode

from the administrative command line prompt in TVMosaic installation directory on Windows or

sudo ./start.sh

from the linux command line in TVMosaic installation directory.

When done, press Ctrl-C and restart TVMosaic daemon (from Task Manager on Windows or by typing sudo ./start2.sh from a command line on all other platforms when in TVMosaic installation directory).

Video quality considerations

Intel hardware-based transcoders (especially on "before-Haswell" Intel CPUs) require a video bitrate of at least 1 mbit/sec to produce video of a reasonable quality.

Concurrent number of transcoding clients

Although not strictly limited, each new trancoding client may degrade an overall transcoding performance of the system.

The only hard limit exists for Intel Evansport-based Synology NAS models (DS214Play and DS415Play), which can only process one transcoded stream at a time.

Profiles

This paragraph provides advanced information on how ffmpeg-based transcoding works in TVMosaic and should be useful for those, willing to add transcoding support for new hardware-based accelerators and/or platforms.


Profiles group transcoding usecases on particular ffmpeg usage patterns - for example, by using a specific hardware accelerator.

Profiles are located inside the profiles directory of ffmpeg folder in a shared user data files directory.


Each profile is identified by its directory name. The following profile ids (directories) are reserved for TVMosaic internal use:

  • software. This is a default profile with software-only transcoding
  • qsv. This is a profile for Intel QuickSync hardware accelerated encoding on Windows platform
  • nvenc. This is a profile for NVidia GPU hardware accelerated transcoding on Windows platform
  • vaapi. This is a profile for VAAPI hardware accelerated transcoding on linux platforms (Intel CPUs)
  • evansport. This is a profile for DS214Play/DS415Play hardware accelerated transcoding on Intel Evansport CPU


Each profile is defined by the files inside a profile directory:

  • info file - a file, describing the general profile properties
  • one or more usecase files (usecase ID + .xml extension, for example transcode_live_to_hls.xml), listing ffmpeg launch parameters for this usecase

info file format

This is an xml file, describing general profile properties.

The file has a following structure and tags:

<?xml version="1.0" encoding="UTF-8"?>
<profile_info>
<name>Human readable name for this profile as it will appear on the Settings/Transcode tab</name>
<default>indicates if this profile is used when Default is selected on the Settings/Transcode tab. Values: true/false. </default>
<type>Indicates which ffmpeg to use. Values: builtin/external/system. See note below for the additional information.</type>
<env>
<var>environment variable for ffmpeg instance in the format var=value</var>
...
</env>


</profile_info>


info file itself and all tags inside it are optional. If not specified, the following defaults are used:

  • name is set to profile id (directory name)
  • default is set to false
  • type is set to builtin


builtin vs. external vs. system ffmpeg

Type tag indicates which ffmpeg installation has to be used for a given profile. The following values are allowed:

  • builtin - ffmpeg that ships with TVMosaic installation
  • external - custom ffmpeg build, which is put into bin directory of ffmpeg folder in a shared user data files directory. Please note that TVMosaic automatically sets LD_LIBRARY_PATH to this directory, when running on linux systems.
  • system - ffmpeg that is installed on the system. In this case ffmpeg is launched without link to any specific directory. LD_LIBRARY_PATH is not set.


environment variables

tags, listed under env section of the xml file describe additional environment variables, which may be required for ffmpeg to work properly. Each variable is in the form var=value and may contains the following parameters, which are initialized by TVMosaic on ffmpeg launch:

  •  %FFMPEGDIR% is the directory where ffmpeg executable resides

For example, vaapi i965 profile has the following environment variables:

<env>

<var>LIBVA_DRIVER_NAME=i965</var>
<var>LIBVA_DRIVERS_PATH=%FFMPEGDIR%/dri</var>

</env>

usecase file format

Each usecase file is an xml structured file, describing ffmpeg launch parameters for a specific usecase/profile combination.

Each file has the following format:

<?xml version="1.0" encoding="UTF-8"?>

<usecase>

<params>
<param condition="true/false">parameter value</param>
...
</params>

</usecase>

Each param line specifies a single ffmpeg launch parameter. Launch parameters may contain the following variables, which are initialized by TVMosaic on ffmpeg launch:

  •  %SRC% - stream source (can be file or pipe, depending on the use case)
  •  %DEST% - output (can be file or pipe, depending on the use case)
  •  %WIDTH% - width of the output video (optional, see conditions below)
  •  %HEIGHT% - height of the output video (optional, see conditions below)
  •  %SCALE% - scale 1/X of the output video dimensions in relation to the input video (optional, see conditions below)
  •  %BITRATE% - bitrate of the output stream (optional, see conditions below)
  •  %OFFSET% - offset in seconds in a source file for thumbnail generation usecase

conditions

Each parameter may have a set of conditions, which specify if a particular parameter is included when ffmpeg is launched. If a particular variable has no conditions, it is always included. If it has a condition, which is set to true, then it is included only if condition is true. If condition is set to false it is only included if condition is false. Multiple conditions are processed on logical AND basis.

The following conditions are defined:

  • dimensions. This condition evaluates to true if both width/height are set.
  • scale. This condition evaluates to true if scale is set. (please note that if both scale and width/height are set, then only scale is used)
  • bitrate. This condition evaluates to true if bitrate is set.

General considerations

Please, note the following when editing/adding profiles:

  • Always start new profile with looking at the existing profiles and their usecases
  • Create a new profile instead of editing an existing one. It's ok to edit the existing one for quick testing purposes, but when you are done, create a new profile with your changes. Otherwise it will be overwritten on TVMosaic update.
  • When launching a transcoder, TVMosaic does not know the actual video format in a source stream and relies on ffmpeg format autodetection. Only use explicit decoder for a specific format (e.g. -c:v flag before input) if you know that all your channels and recordings are broadcasted using this the same video format.