mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-06-07 07:58:51 +00:00
Code Issues 1 Projects Releases Wiki Activity

encoding-profile: Cleanup profile serialization documentation

Browse source 
Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-base/-/merge_requests/1002>
This commit is contained in:
Thibault Saunier 2020-11-20 18:35:49 -03:00 committed by GStreamer Merge Bot
parent 57029ba098
commit a8fdaba2ab
1 changed files with 44 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
gst-libs/gst/pbutils/encoding-profile.c
View file

@ -37,53 +37,60 @@
* reference one or more #GstEncodingProfile(s) which indicate which encoding * reference one or more #GstEncodingProfile(s) which indicate which encoding
* format should be used on each individual streams. * format should be used on each individual streams.
* *
* #GstEncodingProfile(s) can be provided to the 'encodebin' element, which * #GstEncodingProfile(s) can be provided to the 'encodebin' element, which will
* will take care of selecting and setting up the required elements to produce * take care of selecting and setting up the required elements to produce an
* an output stream conforming to the specifications of the profile. * output stream conforming to the specifications of the profile.
* *
* Unlike other systems, the encoding profiles do not specify which #GstElement * The encoding profiles do not necessarily specify which #GstElement to use for
* to use for the various encoding and muxing steps, but instead relies on * the various encoding and muxing steps, as they allow to specifying the format
* specifying the format one wishes to use. * one wishes to use.
* *
* Encoding profiles can be created at runtime by the application or loaded * Encoding profiles can be created at runtime by the application or loaded from
* from (and saved to) file using the #GstEncodingTarget API. * (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 * 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 * For example to encode a stream into a WebM container, with an OGG audio
* stream and a VP8 video stream, the serialized #GstEncodingProfile looks * stream and a VP8 video stream, the serialized #GstEncodingProfile looks like:
* like:
* *
* ``` * ```
* webmmux:vp8enc:vorbisenc * 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 * 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 * For example to encode a stream into a WebM container, with an OGG audio
* stream and a VP8 video stream, the serialized #GstEncodingProfile looks * stream and a VP8 video stream, the serialized #GstEncodingProfile looks like:
* like:
* *
* ``` * ```
* video/webm:video/x-vp8:audio/x-vorbis * video/webm:video/x-vp8:audio/x-vorbis
* ``` * ```
* *
* It is possible to mix caps and element type names so you can specify a specific * It is possible to mix caps and element type names so you can specify a
* video encoder while using caps for other encoders/muxer. * 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 * You can also set the preset name of the encoding profile using the
* caps+preset_name syntax as in: * caps+preset_name syntax as in:
@ -92,6 +99,8 @@
* video/webm:video/x-vp8+youtube-preset:audio/x-vorbis * 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 * Moreover, you can set extra properties `presence`, `single-segment` and
* `variable-framerate` * of an * encoding profile using the `|presence=` syntax * `variable-framerate` * of an * encoding profile using the `|presence=` syntax
* as in: * as in:
@ -104,15 +113,17 @@
* #GstEncodingProfile can be used inside an encodebin. If 0, it is not a * #GstEncodingProfile can be used inside an encodebin. If 0, it is not a
* mandatory stream and can be used as many times as necessary. * 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 * You can also use the `restriction_caps->encoded_format_caps` syntax to
* specify the restriction caps to be set on a #GstEncodingProfile * specify the restriction caps to be set on a #GstEncodingProfile
* *
* It corresponds to the restriction #GstCaps to apply before the encoder that * 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 * will be used in the profile (See #gst_encoding_profile_get_restriction). The
* properties of the raw stream (that is, before encoding), such as height and * fields present in restriction caps are properties of the raw stream (that is,
* width for video and depth and sampling rate for audio. This property does * before encoding), such as height and width for video and depth and sampling
* not make sense for muxers. See #gst_encoding_profile_get_restriction for * rate for audio. This property does not make sense for muxers. See
* more details. * #gst_encoding_profile_get_restriction for more details.
* *
* To force a video stream to be encoded with a Full HD resolution (using WebM * 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 * 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 * > NOTE: Make sure to enclose into quotes to avoid '>' to be reinterpreted by
* > the shell. * > 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 * 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 * 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 * video/mpegts:video/x-h264:audio/x-ac3
@ -153,8 +165,8 @@
* *
* ## Loading a profile from encoding targets * ## Loading a profile from encoding targets
* *
* Anywhere where you have to use a string to define a #GstEncodingProfile, * Anywhere you have to use a string to define a #GstEncodingProfile, you
* you can use load it from a #GstEncodingTarget using the following syntaxes: * can use load it from a #GstEncodingTarget using the following syntaxes:
* *
* ``` * ```
* target_name[/profilename/category] * target_name[/profilename/category]