Encoding and Muxing
Problems this proposal attempts to solve
Duplication of pipeline code for gstreamer-based applications wishing to encode and or mux streams, leading to subtle differences and inconsistencies across those applications.
No unified system for describing encoding targets for applications in a user-friendly way.
No unified system for creating encoding targets for applications, resulting in duplication of code across all applications, differences and inconsistencies that come with that duplication, and applications hardcoding element names and settings resulting in poor portability.
Convenience encoding element
Create a convenience
GstBinfor encoding and muxing several streams, hereafter called 'EncodeBin'.
This element will only contain one single property, which is a profile.
Define a encoding profile system
Encoding profile helper library
Create a helper library to:
create EncodeBin instances based on profiles, and
help applications to create/load/save/browse those profiles.
EncodeBin is a
It implements the
GstTagSetter interface, by which it will proxy the
calls to the muxer.
Only two introspectable property (i.e. usable without extra API):
- The name of the profile to use
When a profile is selected, encodebin will:
- Add REQUEST sinkpads for all the
- Create the muxer and expose the source pad
Whenever a request pad is created, encodebin will:
- Create the chain of elements for that pad
- Ghost the sink pad
- Return that ghost pad
This allows reducing the code to the minimum for applications wishing to encode a source for a given profile:
encbin = gst_element_factory_make ("encodebin, NULL); g_object_set (encbin, "profile", "N900/H264 HQ", NULL); gst_element_link (encbin, filesink); vsrcpad = gst_element_get_src_pad (source, "src1"); vsinkpad = gst_element_get_request_pad (encbin, "video\_%u"); gst_pad_link (vsrcpad, vsinkpad);
Explanation of the Various stages in EncodeBin
This describes the various stages which can happen in order to end up with a multiplexed stream that can then be stored or streamed.
The streams fed to EncodeBin can be of various types:
- Uncompressed (but maybe subsampled)
- Uncompressed (audio/x-raw)
- Timed text
- Private streams
Steps involved for raw video encoding
Transform raw video feed (optional)
Here we modify the various fundamental properties of a raw video stream
to be compatible with the intersection of: * The encoder
GstCaps and *
The specified "Stream Restriction" of the profile/target
The fundamental properties that can be modified are: * width/height This is done with a video scaler. The DAR (Display Aspect Ratio) MUST be respected. If needed, black borders can be added to comply with the target DAR. * framerate * format/colorspace/depth All of this is done with a colorspace converter
- Actual encoding (optional for raw streams)
An encoder (with some optional settings) is used.
A muxer (with some optional settings) is used.
- Outgoing encoded and muxed stream
Steps involved for raw audio encoding
This is roughly the same as for raw video, expect for (1)
- Transform raw audo feed (optional)
We modify the various fundamental properties of a raw audio stream to be
compatible with the intersection of: * The encoder
GstCaps and * The
specified "Stream Restriction" of the profile/target
The fundamental properties that can be modifier are: * Number of channels * Type of raw audio (integer or floating point) * Depth (number of bits required to encode one sample)
Steps involved for encoded audio/video streams
Steps (1) and (2) are replaced by a parser if a parser is available for the given format.
Steps involved for other streams
Other streams will just be forwarded as-is to the muxer, provided the muxer accepts the stream type.
Encoding Profile System
This work is based on:
The existing GstPreset API documentation system for elements
The gnome-media GConf audio profile system
- Encoding Target Category A Target Category is a classification of devices/systems/use-cases for encoding.
Such a classification is required in order for: * Applications with a very-specific use-case to limit the number of profiles they can offer the user. A screencasting application has no use with the online services targets for example. * Offering the user some initial classification in the case of a more generic encoding application (like a video editor or a transcoder).
Ex: Consumer devices Online service Intermediate Editing Format Screencast Capture Computer
Encoding Profile Target A Profile Target describes a specific entity for which we wish to encode. A Profile Target must belong to at least one Target Category. It will define at least one Encoding Profile.
Examples (with category): Nokia N900 (Consumer device) Sony PlayStation 3 (Consumer device) Youtube (Online service) DNxHD (Intermediate editing format) HuffYUV (Screencast) Theora (Computer)
Encoding Profile A specific combination of muxer, encoders, presets and limitations.
Examples: Nokia N900/H264 HQ, Ipod/High Quality, DVD/Pal, Youtube/High Quality HTML5/Low Bandwith, DNxHD
An encoding profile requires the following information:
- Name This string is not translatable and must be unique. A
recommendation to guarantee uniqueness of the naming could be:
- Description This is a translatable string describing the profile
- Muxing format This is a string containing the GStreamer media-type of the container format.
- Muxing preset This is an optional string describing the preset(s) to use on the muxer.
- Multipass setting This is a boolean describing whether the profile requires several passes.
- List of Stream Profile
2.3.1 Stream Profiles
A Stream Profile consists of:
- Type The type of stream profile (audio, video, text, private-data)
- Encoding Format This is a string containing the GStreamer media-type of the encoding format to be used. If encoding is not to be applied, the raw audio media type will be used.
- Encoding preset This is an optional string describing the preset(s) to use on the encoder.
- Restriction This is an optional
GstCapscontaining the restriction of the stream that can be fed to the encoder. This will generally containing restrictions in video width/heigh/framerate or audio depth.
- presence This is an integer specifying how many streams can be used in the containing profile. 0 means that any number of streams can be used.
- pass This is an integer which is only meaningful if the multipass flag has been set in the profile. If it has been set it indicates which pass this Stream Profile corresponds to.
2.4 Example profile
The representation used here is XML only as an example. No decision is made as to which formatting to use for storing targets and profiles.
<gst-encoding-target> <name>Nokia N900</name> <category>Consumer Device</category> <profiles> <profile>Nokia N900/H264 HQ</profile> <profile>Nokia N900/MP3</profile> <profile>Nokia N900/AAC</profile> </profiles> </gst-encoding-target> <gst-encoding-profile> <name>Nokia N900/H264 HQ</name> <description> High Quality H264/AAC for the Nokia N900 </description> <format>video/quicktime,variant=iso</format> <streams> <stream-profile> <type>audio</type> <format>audio/mpeg,mpegversion=4</format> <preset>Quality High/Main</preset> <restriction>audio/x-raw,channels=[1,2]</restriction> <presence>1</presence> </stream-profile> <stream-profile> <type>video</type> <format>video/x-h264</format> <preset>Profile Baseline/Quality High</preset> <restriction> video/x-raw,width=[16, 800],\ height=[16, 480],framerate=[1/1, 30000/1001] </restriction> <presence>1</presence> </stream-profile> </streams> </gst-encoding-profile>
A proposed C API is contained in the gstprofile.h file in this directory.
Modifications required in the existing GstPreset system
Currently a preset needs to be saved on disk in order to be used.
This makes it impossible to have temporary presets (that exist only during the lifetime of a process), which might be required in the new proposed profile system
Categorisation of presets.
Currently presets are just aliases of a group of property/value without any meanings or explanation as to how they exclude each other.
Take for example the H264 encoder. It can have presets for: * passes (1,2 or 3 passes) * profiles (Baseline, Main, ...) * quality (Low, medium, High)
In order to programmatically know which presets exclude each other, we here propose the categorisation of these presets.
This can be done in one of two ways 1. in the name (by making the name
[<category>:]<name>) This would give for example: "Quality:High",
"Profile:Baseline" 2. by adding a new
_meta key This would give for
Aggregation of presets.
There can be more than one choice of presets to be done for an element (quality, profile, pass).
This means that one can not currently describe the full configuration of an element with a single string but with many.
The proposal here is to extend the
GstPreset API to be able to set all
presets using one string and a well-known separator ('/').
This change only requires changes in the core preset handling code.
This would allow doing the following:
gst_preset_load_preset (h264enc, "pass:1/profile:baseline/quality:high")
Points to be determined
This document hasn't determined yet how to solve the following problems:
Storage of profiles
One proposal for storage would be to use a system wide directory (like $prefix/share/gstreamer-0.10/profiles) and store XML files for every individual profiles.
Users could then add their own profiles in ~/.gstreamer-0.10/profiles
This poses some limitations as to what to do if some applications want to have some profiles limited to their own usage.
Helper library for profiles
These helper methods could also be added to existing libraries (like
The various API proposed are in the accompanying gstprofile.h file.
Getting user-readable names for formats
This is already provided by
Hierarchy of profiles
The goal is for applications to be able to present to the user a list of combo-boxes for choosing their output profile:
[ Category ] # optional, depends on the application [ Device/Site/.. ] # optional, depends on the application [ Profile ]
Convenience methods are offered to easily get lists of categories, devices, and profiles.
The goal is for applications to be able to easily create profiles.
The applications needs to be able to have a fast/efficient way to: * select a container format and see all compatible streams he can use with it. * select a codec format and see which container formats he can use with it.
The remaining parts concern the restrictions to encoder input.
Ensuring availability of plugins for Profiles
When an application wishes to use a Profile, it should be able to query whether it has all the needed plugins to use it.
This part will use
GstPbUtils to query, and if needed install the
missing plugins through the installed distribution plugin installer.
This is a list of various use-cases where encoding/muxing is being used.
The goal is to convert with as minimal loss of quality any input file for a target use. A specific variant of this is transmuxing (see below).
Example applications: Arista, Transmageddon
The incoming streams are a collection of various segments that need to be rendered. Those segments can vary in nature (i.e. the video width/height can change). This requires the use of identiy with the single-segment property activated to transform the incoming collection of segments to a single continuous segment.
Example applications: PiTiVi, Jokosher
Encoding of live sources
The major risk to take into account is the encoder not encoding the incoming stream fast enough. This is outside of the scope of encodebin, and should be solved by using queues between the sources and encodebin, as well as implementing QoS in encoders and sources (the encoders emitting QoS events, and the upstream elements adapting themselves accordingly).
Example applications: camerabin, cheese
This is similar to encoding of live sources. The difference being that due to the nature of the source (size and amount/frequency of updates) one might want to do the encoding in two parts: * The actual live capture is encoded with a 'almost-lossless' codec (such as huffyuv) * Once the capture is done, the file created in the first step is then rendered to the desired target format.
Fixing sources to only emit region-updates and having encoders capable of encoding those streams would fix the need for the first step but is outside of the scope of encodebin.
Example applications: Istanbul, gnome-shell, recordmydesktop
This is the case of an incoming live stream which will be broadcasted/transmitted live. One issue to take into account is to reduce the encoding latency to a minimum. This should mostly be done by picking low-latency encoders.
Example applications: Rygel, Coherence
Given a certain file, the aim is to remux the contents WITHOUT decoding into either a different container format or the same container format. Remuxing into the same container format is useful when the file was not created properly (for example, the index is missing). Whenever available, parsers should be applied on the encoded streams to validate and/or fix the streams before muxing them.
Metadata from the original file must be kept in the newly created file.
Example applications: Arista, Transmaggedon
Given a certain file, the aim is to extract a certain part of the file without going through the process of decoding and re-encoding that file. This is similar to the transmuxing use-case.
Example applications: PiTiVi, Transmageddon, Arista, ...
Some encoders allow doing a multi-pass encoding. The initial pass(es) are only used to collect encoding estimates and are not actually muxed and outputted. The final pass uses previously collected information, and the output is then muxed and outputted.
Archiving and intermediary format
The requirement is to have lossless
Example applications: Sound-juicer
Example application: Thoggen
Some of these are still active documents, some other not
The results of the search are