mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-28 03:00:35 +00:00
encoding-profile: Cleanup profile serialization documentation
Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-base/-/merge_requests/1002>
This commit is contained in:
Thibault Saunier
GStreamer Merge Bot
parent
57029ba098
commit
a8fdaba2ab
1 changed files with 44 additions and 32 deletions
|
|
@ -37,53 +37,60 @@
|
|||
* reference one or more #GstEncodingProfile(s) which indicate which encoding
|
||||
* format should be used on each individual streams.
|
||||
*
|
||||
* #GstEncodingProfile(s) can be provided to the 'encodebin' element, which
|
||||
* will take care of selecting and setting up the required elements to produce
|
||||
* an output stream conforming to the specifications of the profile.
|
||||
* #GstEncodingProfile(s) can be provided to the 'encodebin' element, which will
|
||||
* take care of selecting and setting up the required elements to produce an
|
||||
* output stream conforming to the specifications of the profile.
|
||||
*
|
||||
* Unlike other systems, the encoding profiles do not specify which #GstElement
|
||||
* to use for the various encoding and muxing steps, but instead relies on
|
||||
* specifying the format one wishes to use.
|
||||
* The encoding profiles do not necessarily specify which #GstElement to use for
|
||||
* the various encoding and muxing steps, as they allow to specifying the format
|
||||
* one wishes to use.
|
||||
*
|
||||
* Encoding profiles can be created at runtime by the application or loaded
|
||||
* from (and saved to) file using the #GstEncodingTarget API.
|
||||
* Encoding profiles can be created at runtime by the application or loaded from
|
||||
* (and saved to) file using the #GstEncodingTarget API.
|
||||
*
|
||||
* ## Defining a GstEncodingProfile as a string
|
||||
* ## The encoding profile serialization format
|
||||
*
|
||||
* ### Serialized encoding profile formats
|
||||
* Encoding profiles can be serialized to be used in the command line tools or
|
||||
* to set it on other other #GObject-s using #gst_util_set_object_arg for
|
||||
* example.
|
||||
*
|
||||
* #### Using encoders and muxer element factory name:
|
||||
* The serialization format aims at being simple to understand although flexible
|
||||
* enough to describe any possible encoding profile. There are several ways to
|
||||
* describe the profile depending on the context but the general idea is that it
|
||||
* is a colon separated list of EncodingProfiles descriptions, the first one
|
||||
* needs to describe a #GstEncodingContainerProfile and the following ones
|
||||
* describe elementary streams.
|
||||
*
|
||||
* ### Using encoders and muxer element factory name
|
||||
*
|
||||
* ```
|
||||
* muxer_factory_name:video_encoder_factory_name:audio_encoder_factory_name
|
||||
* ```
|
||||
*
|
||||
* For example to encode a stream into a WebM container, with an OGG audio
|
||||
* stream and a VP8 video stream, the serialized #GstEncodingProfile looks
|
||||
* like:
|
||||
* stream and a VP8 video stream, the serialized #GstEncodingProfile looks like:
|
||||
*
|
||||
* ```
|
||||
* webmmux:vp8enc:vorbisenc
|
||||
* ```
|
||||
*
|
||||
* #### Define the encoding profile in a generic way using caps:
|
||||
* ### Define the encoding profile in a generic way using caps:
|
||||
*
|
||||
* ```
|
||||
* muxer_source_caps:video_encoder_source_caps:audio_encoder_source_caps
|
||||
* ```
|
||||
*
|
||||
* For example to encode a stream into a WebM container, with an OGG audio
|
||||
* stream and a VP8 video stream, the serialized #GstEncodingProfile looks
|
||||
* like:
|
||||
* stream and a VP8 video stream, the serialized #GstEncodingProfile looks like:
|
||||
*
|
||||
* ```
|
||||
* video/webm:video/x-vp8:audio/x-vorbis
|
||||
* ```
|
||||
*
|
||||
* It is possible to mix caps and element type names so you can specify a specific
|
||||
* video encoder while using caps for other encoders/muxer.
|
||||
* It is possible to mix caps and element type names so you can specify a
|
||||
* specific video encoder while using caps for other encoders/muxer.
|
||||
*
|
||||
* ### Advanced encoding format serialization features:
|
||||
* ### Using preset
|
||||
*
|
||||
* You can also set the preset name of the encoding profile using the
|
||||
* caps+preset_name syntax as in:
|
||||
|
|
@ -92,6 +99,8 @@
|
|||
* video/webm:video/x-vp8+youtube-preset:audio/x-vorbis
|
||||
* ```
|
||||
*
|
||||
* ### Setting properties on muxers or on the encoding profile itself
|
||||
*
|
||||
* Moreover, you can set extra properties `presence`, `single-segment` and
|
||||
* `variable-framerate` * of an * encoding profile using the `|presence=` syntax
|
||||
* as in:
|
||||
|
|
@ -104,15 +113,17 @@
|
|||
* #GstEncodingProfile can be used inside an encodebin. If 0, it is not a
|
||||
* mandatory stream and can be used as many times as necessary.
|
||||
*
|
||||
* ### Enforcing properties to the stream itself (video size, number of audio channels, etc..)
|
||||
*
|
||||
* You can also use the `restriction_caps->encoded_format_caps` syntax to
|
||||
* specify the restriction caps to be set on a #GstEncodingProfile
|
||||
*
|
||||
* It corresponds to the restriction #GstCaps to apply before the encoder that
|
||||
* will be used in the profile. The fields present in restriction caps are
|
||||
* properties of the raw stream (that is, before encoding), such as height and
|
||||
* width for video and depth and sampling rate for audio. This property does
|
||||
* not make sense for muxers. See #gst_encoding_profile_get_restriction for
|
||||
* more details.
|
||||
* will be used in the profile (See #gst_encoding_profile_get_restriction). The
|
||||
* fields present in restriction caps are properties of the raw stream (that is,
|
||||
* before encoding), such as height and width for video and depth and sampling
|
||||
* rate for audio. This property does not make sense for muxers. See
|
||||
* #gst_encoding_profile_get_restriction for more details.
|
||||
*
|
||||
* To force a video stream to be encoded with a Full HD resolution (using WebM
|
||||
* as the container format, VP8 as the video codec and Vorbis as the audio
|
||||
|
|
@ -125,27 +136,28 @@
|
|||
* > NOTE: Make sure to enclose into quotes to avoid '>' to be reinterpreted by
|
||||
* > the shell.
|
||||
*
|
||||
* In the case you are using encoder types, the following is also possible:
|
||||
* In the case you are specifying encoders directly, the following is also
|
||||
* possible:
|
||||
*
|
||||
* ```
|
||||
* "matroskamux:x264enc,width=1920,height=1080:audio/x-vorbis"
|
||||
* matroskamux:x264enc,width=1920,height=1080:audio/x-vorbis
|
||||
* ```
|
||||
*
|
||||
* ## Some serialized encoding formats examples:
|
||||
* ## Some serialized encoding formats examples
|
||||
*
|
||||
* MP3 audio and H264 in MP4:
|
||||
* ### MP3 audio and H264 in MP4**
|
||||
*
|
||||
* ```
|
||||
* video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3
|
||||
* ```
|
||||
*
|
||||
* Vorbis and theora in OGG:
|
||||
* ### Vorbis and theora in OGG
|
||||
*
|
||||
* ```
|
||||
* application/ogg:video/x-theora:audio/x-vorbis
|
||||
* ```
|
||||
*
|
||||
* AC3 and H264 in MPEG-TS:
|
||||
* ### AC3 and H264 in MPEG-TS
|
||||
*
|
||||
* ```
|
||||
* video/mpegts:video/x-h264:audio/x-ac3
|
||||
|
|
@ -153,8 +165,8 @@
|
|||
*
|
||||
* ## Loading a profile from encoding targets
|
||||
*
|
||||
* Anywhere where you have to use a string to define a #GstEncodingProfile,
|
||||
* you can use load it from a #GstEncodingTarget using the following syntaxes:
|
||||
* Anywhere you have to use a string to define a #GstEncodingProfile, you
|
||||
* can use load it from a #GstEncodingTarget using the following syntaxes:
|
||||
*
|
||||
* ```
|
||||
* target_name[/profilename/category]
|
||||
|
|
|
|||
Loading…
Reference in a new issue