From d67f94517737a1b3fd8eea74adea639ba6ae8227 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Fri, 16 Dec 2016 11:11:57 -0300 Subject: [PATCH] encoding-profile: Fix documentation and port to gtk markdown And remove some trailling whitepsaces --- gst-libs/gst/pbutils/encoding-profile.c | 212 +++++++++++------------- gst/encoding/gstencodebin.c | 4 +- gst/typefind/gsttypefindfunctions.c | 12 +- 3 files changed, 105 insertions(+), 123 deletions(-) diff --git a/gst-libs/gst/pbutils/encoding-profile.c b/gst-libs/gst/pbutils/encoding-profile.c index f7fada4267..4aea4d179d 100644 --- a/gst-libs/gst/pbutils/encoding-profile.c +++ b/gst-libs/gst/pbutils/encoding-profile.c @@ -22,114 +22,102 @@ * SECTION:encoding-profile * @short_description: Encoding profile library * - * - * * Functions to create and handle encoding profiles. - * - * - * Encoding profiles describe the media types and settings one wishes to use for - * an encoding process. The top-level profiles are commonly + * + * Encoding profiles describe the media types and settings one wishes to use + * for an encoding process. The top-level profiles are commonly * #GstEncodingContainerProfile(s) (which contains a user-readable name and * description along with which container format to use). These, in turn, * 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. - * - * - * 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. - * - * - * Encoding profiles can be created at runtime by the application or loaded from (and saved - * to) file using the #GstEncodingTarget API. - * - * * - * - * The encoding profile serialization format - * This is the serialization format of a GstEncodingProfile. - * - * Internally the transcoding application uses GstEncodeBin. gst-validate-transcoding-&GST_API_VERSION; uses its own - * serialization format to describe the GstEncodeBin.profile - * property of the encodebin. - * - * - * The simplest serialized profile looks like: - * - * - * muxer_source_caps:videoencoder_source_caps:audioencoder_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 will look like: - * - * - * video/webm:video/x-vp8:audio/x-vorbis - * - * - * You can also set the preset name of the encoding profile using the caps+preset_name syntax as in: - * - * - * video/webm:video/x-vp8+youtube-preset:audio/x-vorbis - * - * - * Moreover, you can set the presence property of an - * encoding profile using the |presence syntax as in: - * - * - * video/webm:video/x-vp8|1:audio/x-vorbis - * - * - * This field allows you to specify how many times maximum a GstEncodingProfile can be used inside an encodebin. - * - * - * 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. - * - * - * 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 codec), you should use: - * - * - * video/webm:video/x-raw,width=1920,height=1080->video/x-vp8:audio/x-vorbis - * - * - * Some serialized encoding formats examples: - * - * MP3 audio and H264 in MP4: - * - * - * video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3 - * - * - * Vorbis and theora in OGG: - * - * - * application/ogg:video/x-theora:audio/x-vorbis - * - * - * AC3 and H264 in MPEG-TS: - * - * - * video/mpegts:video/x-h264:audio/x-ac3 - * - * - * - * - * Example: Creating a 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. + * + * Encoding profiles can be created at runtime by the application or loaded + * from (and saved to) file using the #GstEncodingTarget API. + * + * # The encoding profile serialization format + * + * This is the serialization format of a #GstEncodingProfile The simplest + * serialized profile looks like: + * * |[ + * muxer_source_caps:videoencoder_source_caps:audioencoder_source_caps + * ]| + * + * For example to encode a stream into a WebM container, with an OGG audio + * stream and a VP8 video stream, the serialized #GstEncodingProfilewill look + * like: + * + * |[ + * video/webm:video/x-vp8:audio/x-vorbis + * ]| + * + * You can also set the preset name of the encoding profile using the + * caps+preset_name syntax as in: + * + * |[ + * video/webm:video/x-vp8+youtube-preset:audio/x-vorbis + * ]| + * + * Moreover, you can set the `presence` property of an + * encoding profile using the `|presence` syntax as in: + * + * |[ + * video/webm:video/x-vp8|1:audio/x-vorbis + * ]| + * + * This field allows specifies the maximum number of times a + * #GstEncodingProfile can be used inside an encodebin. If 0, it is not a + * mandatory stream. + * + * 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. + * + * 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 + * codec), you should use: + * + * |[ + * video/webm:video/x-raw,width=1920,height=1080->video/x-vp8:audio/x-vorbis + * ]| +* + * ## Some serialized encoding formats examples: + * + * MP3 audio and H264 in MP4: + * + * |[ + * video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3 + * ]| + * + * Vorbis and theora in OGG: + * + * |[ + * application/ogg:video/x-theora:audio/x-vorbis + * ]| + * + * AC3 and H264 in MPEG-TS: + * + * |[ + * video/mpegts:video/x-h264:audio/x-ac3 + * ]| + * + * # Example: Creating a profile + * + * |[ * #include * ... * GstEncodingProfile * @@ -159,12 +147,10 @@ * * * ]| - * - * - * - * Example: Using an encoder preset with a profile - * - * |[ + * + * # Example: Using an encoder preset with a profile + * + * |[ * #include * ... * GstEncodingProfile * @@ -204,12 +190,10 @@ * * * ]| - * - * - * - * Example: Listing categories, targets and profiles - * - * |[ + * + * # Example: Listing categories, targets and profiles + * + * |[ * #include * ... * GstEncodingProfile *prof; @@ -238,8 +222,6 @@ * * ... * ]| - * - * */ #ifdef HAVE_CONFIG_H diff --git a/gst/encoding/gstencodebin.c b/gst/encoding/gstencodebin.c index 1f5de54796..3ff77b17c5 100644 --- a/gst/encoding/gstencodebin.c +++ b/gst/encoding/gstencodebin.c @@ -1204,7 +1204,7 @@ _create_stream_group (GstEncodeBin * ebin, GstEncodingProfile * sprof, sgroup->profile = sprof; /* NOTE for people reading this code: - * + * * We construct the group starting by the furthest downstream element * and making our way up adding/syncing/linking as we go. * @@ -1881,7 +1881,7 @@ create_elements_and_pads (GstEncodeBin * ebin) /* 2. Ghost the muxer source pad */ - /* FIXME : We should figure out if it's a static/request/dyamic pad, + /* FIXME : We should figure out if it's a static/request/dyamic pad, * but for the time being let's assume it's a static pad :) */ muxerpad = gst_element_get_static_pad (muxer, "src"); if (G_UNLIKELY (muxerpad == NULL)) diff --git a/gst/typefind/gsttypefindfunctions.c b/gst/typefind/gsttypefindfunctions.c index 7df74fc596..ca8b83b734 100644 --- a/gst/typefind/gsttypefindfunctions.c +++ b/gst/typefind/gsttypefindfunctions.c @@ -2079,7 +2079,7 @@ static GstStaticCaps multipart_caps = GST_STATIC_CAPS ("multipart/x-mixed-replace"); #define MULTIPART_CAPS gst_static_caps_get(&multipart_caps) -/* multipart/x-mixed replace is: +/* multipart/x-mixed replace is: * --[\r]\n * [\r]\nContent-type:[\r]\n */ static void @@ -2136,7 +2136,7 @@ static GstStaticCaps mpeg_sys_caps = GST_STATIC_CAPS ("video/mpeg, " #define IS_MPEG_PES_HEADER(data) (IS_MPEG_HEADER (data) && \ IS_MPEG_PES_CODE (((guint8 *)(data))[3])) -#define MPEG2_MAX_PROBE_LENGTH (128 * 1024) /* 128kB should be 64 packs of the +#define MPEG2_MAX_PROBE_LENGTH (128 * 1024) /* 128kB should be 64 packs of the * most common 2kB pack size. */ #define MPEG2_MIN_SYS_HEADERS 2 @@ -2356,7 +2356,7 @@ mpeg_sys_type_find (GstTypeFind * tf, gpointer unused) } /* If we at least saw MIN headers, and *some* were pes headers (pack headers - * are optional in an mpeg system stream) then return a lower-probability + * are optional in an mpeg system stream) then return a lower-probability * result */ if (pes_headers > 0 && (pack_headers + pes_headers) > MPEG2_MIN_SYS_HEADERS) goto suggest; @@ -2448,7 +2448,7 @@ mpeg_ts_probe_headers (GstTypeFind * tf, guint64 offset, gint packet_size) static void mpeg_ts_type_find (GstTypeFind * tf, gpointer unused) { - /* TS packet sizes to test: normal, DVHS packet size and + /* TS packet sizes to test: normal, DVHS packet size and * FEC with 16 or 20 byte codes packet size. */ const gint pack_sizes[] = { 188, 192, 204, 208 }; const guint8 *data = NULL; @@ -2477,7 +2477,7 @@ mpeg_ts_type_find (GstTypeFind * tf, gpointer unused) if (found >= GST_MPEGTS_TYPEFIND_MIN_HEADERS) { gint probability; - /* found at least 4 headers. 10 headers = MAXIMUM probability. + /* found at least 4 headers. 10 headers = MAXIMUM probability. * Arbitrarily, I assigned 10% probability for each header we * found, 40% -> 100% */ probability = MIN (10 * found, GST_TYPE_FIND_MAXIMUM); @@ -2719,7 +2719,7 @@ h264_video_type_find (GstTypeFind * tf, gpointer unused) { DataScanCtx c = { 0, NULL, 0 }; - /* Stream consists of: a series of sync codes (00 00 00 01) followed + /* Stream consists of: a series of sync codes (00 00 00 01) followed * by NALs */ gboolean seen_idr = FALSE;