From d7bdf0d49a65571b1f67578952a83771c386a2ac Mon Sep 17 00:00:00 2001 From: Edward Hervey Date: Fri, 7 Jan 2011 12:51:11 +0100 Subject: [PATCH] encodebin: Extend documentation https://bugzilla.gnome.org/show_bug.cgi?id=638901 --- gst/encoding/gstencodebin.c | 83 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 2 deletions(-) diff --git a/gst/encoding/gstencodebin.c b/gst/encoding/gstencodebin.c index 1d44132..311d8d3 100644 --- a/gst/encoding/gstencodebin.c +++ b/gst/encoding/gstencodebin.c @@ -32,10 +32,70 @@ /** * SECTION:element-encodebin * - * encodebin provides a bin for encoding/muxing various streams according to + * EncodeBin provides a bin for encoding/muxing various streams according to * a specified #GstEncodingProfile. * - * + * Based on the profile that was set (via the #GstEncodeBin:profile property), + * EncodeBin will internally select and configure the required elements + * (encoders, muxers, but also audio and video converters) so that you can + * provide it raw or pre-encoded streams of data in input and have your + * encoded/muxed/converted stream in output. + * + * + * Features + * + * + * Automatic encoder and muxer selection based on elements available on the + * system. + * + * + * Conversion of raw audio/video streams (scaling, framerate conversion, + * colorspace conversion, samplerate conversion) to conform to the profile + * output format. + * + * + * Variable number of streams. If the presence property for a stream encoding + * profile is 0, you can request any number of sink pads for it via the + * standard request pad gstreamer API or the #GstEncodeBin::request-pad action + * signal. + * + * + * Avoid reencoding (passthrough). If the input stream is already encoded and is + * compatible with what the #GstEncodingProfile expects, then the stream won't + * be re-encoded but just passed through downstream to the muxer or the output. + * + * + * Mix pre-encoded and raw streams as input. In addition to the passthrough + * feature above, you can feed both raw audio/video *AND* already-encoded data + * to a pad. #GstEncodeBin will take care of passing through the compatible + * segments and re-encoding the segments of media that need encoding. + * + * + * Standard behaviour is to use a #GstEncodingContainerProfile to have both + * encoding and muxing performed. But you can also provide a single stream + * profile (like #GstEncodingAudioProfile) to only have the encoding done and + * handle the encoded output yourself. + * + * + * Audio imperfection corrections. Incoming audio streams can have non perfect + * timestamps (jitter), like the streams coming from ASF files. #GstEncodeBin + * will automatically fix those imperfections for you. See + * #GstEncodeBin:audio-jitter-tolerance for more details. + * + * + * Variable or Constant video framerate. If your #GstEncodingVideoProfile has + * the variableframerate property deactivated (default), then the incoming + * raw video stream will be retimestampped in order to produce a constant + * framerate. + * + * + * Cross-boundary re-encoding. When feeding compatible pre-encoded streams that + * fall on segment boundaries, and for supported formats (right now only H263), + * the GOP will be decoded/reencoded when needed to produce an encoded output + * that fits exactly within the request GstSegment. + * + * + * */ @@ -227,6 +287,13 @@ gst_encode_bin_class_init (GstEncodeBinClass * klass) gobject_klass->get_property = gst_encode_bin_get_property; /* Properties */ + + /** + * GstEncodeBin:profile: + * + * The #GstEncodingProfile to use. This property must be set before going + * to %GST_STATE_PAUSED or higher. + */ g_object_class_install_property (gobject_klass, PROP_PROFILE, gst_param_spec_mini_object ("profile", "Profile", "The GstEncodingProfile to use", GST_TYPE_ENCODING_PROFILE, @@ -262,6 +329,18 @@ gst_encode_bin_class_init (GstEncodeBinClass * klass) G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /* Signals */ + /** + * GstEncodeBin::request-pad + * @encodebin: a #GstEncodeBin instance + * @caps: a #GstCaps + * + * Use this method to request an unused sink request #GstPad that can take the + * provided @caps as input. You must release the pad with + * gst_element_release_request_pad() when you are done with it. + * + * Returns: A compatible #GstPad, or %NULL if no compatible #GstPad could be + * created or is available. + */ gst_encode_bin_signals[SIGNAL_REQUEST_PAD] = g_signal_new ("request-pad", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstEncodeBinClass, -- 2.7.4