4 Configure Transcoding
The transcoding section allows to define ways on how to transcode content.
4.1 Transcoding
<transcoding enabled="yes" fetch-buffer-size="262144" fetch-buffer-fill-size="0">
This tag defines the transcoding section.
4.1.1 Transcoding Attributes
- transcoding enabled
enabled="no"
This attribute defines if transcoding is enabled as a whole.
- fetch-buffer-size
fetch-buffer-size="1048576"
In case you have transcoders that can not handle online content directly (see the accept-url parameter below), it is possible to put the transcoder between two FIFOs, in this case Gerbera will fetch the online content. This setting defines the buffer size in bytes, that will be used when fetching content from the web. The value must not be less than allowed by the curl library (usually 16384 bytes).
- fetch-buffer-fill-size
fetch-buffer-fill-size="262144"
This setting allows to prebuffer a certain amount of data before sending it to the transcoder, this should ensure a constant data flow in case of slow connections. Usually this setting is not needed, because most transcoders will just patiently wait for data and we anyway buffer on the output end. However, we observed that ffmpeg will fail to transcode flv files if it encounters buffer underruns - this setting helps to avoid this situation.
- fetch-buffer-timeout
Added in version 3.2.0.
fetch-buffer-timeout="15"
This setting allows to set the timeout for fetch operations to fill the buffer. Increase it for chunked streams or on connections with high latency.
- fetch-buffer-retry-count
Added in version 3.2.0.
fetch-buffer-retry-count="5"
This setting allows to set the number of retries after a timeout occured. Increase it for unrelyable streams.
4.1.2 Mimetype Profile Mappings
<mimetype-profile-mappings allow-unused="no"> <transcode mimetype="audio/x-flac" using="oggflac-pcm"/> </mimetype-profile-mappings>
The mime type to profile mappings define which mime type is handled by which profile.
Different mime types can map to the same profile in case that the transcoder in use supports various input formats. The same mime type can also map to several profiles, in this case multiple resources in the XML will be generated, allowing the player to decide which one to take.
Suppress errors when loading profiles. Mappings pointing to missing transcoding profiles are ignored as well as unknown mimetypes.
4.1.2.1 Transcode
The mappings under mimetype-profile are defined in the following manner:
<transcode mimetype="audio/x-flac" using="oggflac-pcm"/>
In this example we want to transcode our flac audio files (they have the mimetype audio/x-flac) using the ”oggflac-pcm” profile which is defined below.
- no-transcoding
Selects the mimetype of the source media that should be transcoded.
Wildcards like
video/*can be used to match all sub types. In that case the attributeno-transcodingcontains a comma separated list of mime types that should be excluded. This is intended for devices that only support a very limited number of media formats.
- source-profile
Defines the DLNA profile string of the transcoding source. If set, only files with the DLNA profile are transcoded. See Import section how to determine the profile.
- client-flags
Changed in version 3.1.0: allow negation with
~client-flags="TRANSCODING1" client-flags="~TRANSCODING1"If the flags match the ones defined in Supported Devices, the profile is selected for that client. Choose
TRANSCODING1,TRANSCODING2,TRANSCODING3or an unused flag, e.g. “0x10000000”, to avoid collisions with other features.Multiple flags can be separated by
|. The profile is selected if at least one flag is present for the client.If the value starts with
~(negation), the profile will be active for all clients that do not have the respectiveflags.
- client-without-flag
Added in version 3.1.0.
client-without-flag="true"If clients do not have flags they will not get the transcoding resource even if all flags are set. This option adds these clients to get transcoding also.
- using
Selects the transcoding profile that will handle the mime type above. Information on how to define transcoding profiles can be found below.
4.1.3 Profiles
<profiles allow-unused="no">
This section defines the various transcoding profiles.
- profiles allow-unused
allow-unused="yes"
Suppress errors when loading profiles. If no Unused profiles are not allowed in config and gerbera refuses to start.
4.1.3.1 Profile
<profile name="vlcmpeg" enabled="no" type="external" no-transcoding="" dlna-profile="MP4"> <mimetype>video/mpeg</mimetype> <accept-url>yes</accept-url> <first-resource>yes</first-resource> <accept-ogg-theora>yes</accept-ogg-theora> <sample-frequency>-1</sample-frequency> <audio-channels>-1</audio-channels> <thumbnail>no</thumbnail> <hide-original-resource>no</hide-original-resource> <avi-fourcc-list mode="Ignore"> <fourcc>XVID</fourcc> <fourcc>DX50</fourcc> </avi-fourcc-list> <agent command="vlc" arguments="-I dummy %in --sout #transcode{venc=ffmpeg,vcodec=mp2v,vb=4096,fps=25,aenc=ffmpeg,acodec=mpga,ab=192,samplerate=44100,channels=2}:standard{access=file,mux=ps,dst=%out} vlc://quit" /> <buffer size="14400000" chunk-size="512000" fill-size="120000" /> </profile>
Definition of a transcoding profile.
4.1.3.1.1 Profile Attributes
name="prfle"Name of the transcoding profile, this is the name that is specified in the mime type to profile mappings.
enabled="yes"Enables or disables the profile.
- profile client-flags
Changed in version 3.1.0: allow negation with
~client-flags="TRANSCODING1" client-flags="~TRANSCODING1"If the flags match the ones defined in clients, the profile is selected for that client. There are are
TRANSCODING1,TRANSCODING2,TRANSCODING3or choose an unused flag, e.g.0x100000000, to avoid collisions with other features.Multiple flags can be separated by
|. The profile is selected if at least one flag is present for the client.If the value starts with
~(negation), the profile will be active for all clients that do not have the respectiveflags.
- profile client-without-flag
Added in version 3.1.0.
client-without-flag="true"If clients do not have flags they will not get the transcoding resource even if all flags are set. This option adds these clients to get transcoding also.
type="external"Defines the profile type, currently only
externalis supported, this will change in the future.
4.1.3.1.2 Profile Items
Changed in version 2.3.0.
<mimetype>audio/x-wav</mimetype> <mimetype value="audio/L16"> <mime-property key="rate" resource="sampleFrequency"/> <mime-property key="channels" resource="nrAudioChannels"/> <mime-property key="date" metadata="M_DATE"/> </mimetype>Defines the mimetype of the transcoding result (i.e. of the transcoded stream). In the above example we transcode to PCM. There are two variation of this tag. The simple version accepts the target mime type in the content. The second version allows setting additional properties which will be appended to the mimetype if the respective property value is not empty. The above example will produce, e.g.
audio/L16;rate=16000;channels=2;date=2024-07-22.Key printed in front of the property value.
- profile mimetype resource
Name of a resource attribute to read. The attribute name must match one of the resource attributes and must be available on the content resource. See Supported Properties.
- profile mimetype metadata
Name of a resource attribute to read. The attribute name must match on of the metadata fields of the object. See Supported Properties.
- profile dlna-profile
Defines the DLNA profile string of the transcoding result (i.e. of the transcoded stream). If empty, it is determined from the mime type.
- accept-url
Some transcoders are able to handle non local content, i.e. instead giving a local file name you can pass an URL to the transcoder. However, some transcoders can only deal with local files, for this case set the value to
no.
- first-resource
It is possible to offer more than one resource in the browse result, a good player implementation will go through all resources and pick the one that it can handle best. Unfortunately most players only look at the first resource and ignore the rest. When you add a transcoding profile for a particular media type it will show up as an additional resource in the browse result, using this parameter you can make sure that the transcoded resource appears first in the list.
- Note:
if more than one transcoding profile is applied on one source media type (i.e. you transcode an OGG file to MP3 and to PCM), and the first-resource parameter is specified in both profiles, then the resource positions are undefined.
- hide-original-resource
This parameter will hide the resource of the original media when sending the browse result to the player, this can be useful if your device gets confused by multiple resources and allows you to send only the transcoded one.
- accept-ogg-theora
As you may know, OGG is just a container, the content could be Vorbis or Theora while the mimetype is
application/ogg. For transcoding we need to identify if we are dealing with audio or video content, specifying yes in this tag in the profile will make sure that only OGG files containing Theora will be processed.
- avi-fourcc-list
Section`Required:False<avi-fourcc-list mode="ignore">This option allows to specify a particular list of AVI fourcc strings that can be either set to be ignored or processed by the profile.
- Note:
This option has no effect on non AVI content.
- avi-fourcc-list mode
Specifies how the list should be handled by the transcoding engine, possible values are:
disabled: The option is completely disabled, fourcc list is not being processed.
process: Only the fourcc strings that are listed will be processed by the transcoding profile, AVI files with other fourcc strings will be ignored. Setting this is useful if you want to transcode only some specific fourcc’s and not transcode the rest.
ignore: The fourcc strings listed will not be transcoded, all other codecs will be transcoded. Setting this might be useful if you want to prevent a limited number of codecs from being transcoded, but want to apply transcoding on the rest (i.e. - do not transcode divx and xvid, but want to transcode mjpg and whatever else might be in the AVI container).The list of fourcc strings is enclosed in the avi-fourcc-list section:
- 4cc fourcc
- resolution
Allows you to tell the resolution of the transcoded media to your player. This may be helpful if you want to generate thumbnails for your photos, or if your player has the ability to pick video streams in a particular resolution. Of course the setting should match the real resolution of the transcoded media.
- sample-frequency
Specifies the sample frequency of the transcoded media, this information is passed to the player and is particularly important when streaming PCM data. Possible values are:
source: automatically set the same frequency as the frequency of the source content, which is useful if you are not doing any resampling
off: do not provide this information to the player
<frequency>specify a fixed value, where<frequency>is a numeric value > 0
- audio-channels
Specifies the number of audio channels in the transcoded media, this information is passed to the player and is particularly important when streaming PCM data. Possible values are:
source: automatically set the same number of audio channels as in the source content
off: do not provide this information to the player
<number>: specify a fixed value, where<number>is a numeric value > 0
- thumbnail
Boolean`Required:FalseDefault:no<thumbnail>yes</thumbnail>
- Note:
this is an experimental option, the implementation will be refined in the future releases.
This is a special option which was added for the PS3 users. If the
resolutionoption was set, then, depending on the resolution, a special DLNA tag will be added, marking the resource as a thumbnail. This is useful if you have a transcoding script that extracts an image out of the video and presents it as a thumbnail.Use the option with caution, no extra checking is being done if the resulting mimetype represents an image, also, it is will only work if the output of the profile is a JPG image.
4.1.3.2 Profile Agent
- agent
- Type:
Section`Required:True
<agent command="ogg123" arguments="-d wav -f %out %in"/> <agent command="vlc" arguments="-I dummy %in --sout #transcode{...}:standard{...} vlc:quit"> <environ name="LC_ALL" value="C"/> </agent>
Defines the transcoding agent and the parameters, in the example above we use ogg123 to convert ogg or flac to wav.
command="vlc"Defines the transcoder binary that will be executed by Gerbera upon a transcode request, the binary must be in $PATH. It is very important that the transcoder is capable of writing the output to a FIFO, some applications, for example ffmpeg, have problems with that. The command line arguments are specified separately (see below).
arguments="-I dummy %in --sout %out "#transcode{...}:standard{...}" vlc:quit"Changed in version 3.0.0: Arguments containing spaces ‘ ‘ can be enclosed in double quotes
" = "Specifies the command line arguments that will be given to the transcoder application upon execution. There are two special tokens:
%inand%out. Those tokens get substituted by the input file name and the output FIFO name before execution.
<environ name="..." value=".."/>
Sets environment variable which may be required by the transcoding process. Used to overwrite the environment of the gerbera process. The entry can appear multiple times.
4.1.3.3 Profile Buffer
Set value of environment variable.
<buffer size="1048576" chunk-size="131072" fill-size="262144" timeout="4" retry-count="5"/>
These settings help you to achieve a smooth playback of transcoded media. The actual values need to be tuned and depend on the speed of your system. The general idea is to buffer the data before sending it out to the player, it is also possible to delay first playback until the buffer is filled to a certain amount. The prefill should give you enough space to overcome some high bitrate scenes in case your system can not transcode them in real time.
size="262144"Size of the buffer in bytes.
chunk-size="65536"Size of chunks in bytes, that are read by the buffer from the transcoder. Smaller chunks will produce a more constant buffer fill ratio, however too small chunks may slow things down.
fill-size="65536"Initial fill size - number of bytes that have to be in the buffer before the first read (i.e. before sending the data to the player for the first time). Set this to
0(zero) if you want to disable prefilling.
- buffer timeout
Added in version 3.2.0.
timeout="15"This setting allows to set the timeout for operations to fill the buffer. Increase it for slow streams
- buffer retry-count
Added in version 3.2.0.
retry-count="5"This setting allows to set the number of retries after a timeout occured. Increase it for unrelyable streams.