markdown/design/decodebin.md

   1 # Decodebin design
   2
   3 ## GstDecodeBin
   4
   5 ### Description
   6
   7  - Autoplug and decode to raw media
   8
   9  - Input: single pad with ANY caps
  10
  11  - Output: Dynamic pads
  12
  13 ### Contents
  14
  15  - a `GstTypeFindElement` connected to the single sink pad
  16
  17  - optionally a demuxer/parser
  18
  19  - optionally one or more DecodeGroup
  20
  21 ### Autoplugging
  22
  23 The goal is to reach 'target' caps (by default raw media).
  24
  25 This is done by using the `GstCaps` of a source pad and finding the
  26 available demuxers/decoders `GstElement` that can be linked to that pad.
  27
  28 The process starts with the source pad of typefind and stops when no
  29 more non-target caps are left. It is commonly done while pre-rolling,
  30 but can also happen whenever a new pad appears on any element.
  31
  32 Once a target caps has been found, that pad is ghosted and the
  33 'pad-added' signal is emitted.
  34
  35 If no compatible elements can be found for a `GstCaps`, the pad is ghosted
  36 and the 'unknown-type' signal is emitted.
  37
  38 ### Assisted auto-plugging
  39
  40 When starting the auto-plugging process for a given `GstCaps`, two signals
  41 are emitted in the following way in order to allow the application/user
  42 to assist or fine-tune the process.
  43
  44  - **'autoplug-continue'**:
  45
  46 ```
  47     gboolean user_function (GstElement * decodebin, GstPad *pad, GstCaps * caps)
  48 ```
  49
  50     This signal is fired at the very beginning with the source pad `GstCaps`. If
  51     the callback returns TRUE, the process continues normally. If the
  52     callback returns FALSE, then the `GstCaps` are considered as a target caps
  53     and the autoplugging process stops.
  54
  55   - **'autoplug-factories'**:
  56
  57 ```
  58     GValueArray user_function (GstElement* decodebin, GstPad* pad, GstCaps* caps);
  59 ```
  60
  61     Get a list of elementfactories for `@pad` with `@caps`. This function is
  62     used to instruct decodebin2 of the elements it should try to
  63     autoplug. The default behaviour when this function is not overriden
  64     is to get all elements that can handle @caps from the registry
  65     sorted by rank.
  66
  67   - **'autoplug-select'**:
  68
  69 ```
  70     gint user_function (GstElement* decodebin, GstPad* pad, GstCaps*caps, GValueArray* factories);
  71 ```
  72
  73     This signal is fired once autoplugging has got a list of compatible
  74     `GstElementFactory`. The signal is emitted with the `GstCaps` of the
  75     source pad and a pointer on the GValueArray of compatible factories.
  76
  77     The callback should return the index of the elementfactory in
  78     @factories that should be tried next.
  79
  80     If the callback returns -1, the autoplugging process will stop as if
  81     no compatible factories were found.
  82
  83 The default implementation of this function will try to autoplug the
  84 first factory of the list.
  85
  86 ### Target Caps
  87
  88 The target caps are a read/write `GObject` property of decodebin.
  89
  90 By default the target caps are:
  91
  92  - Raw audio: audio/x-raw
  93
  94  - Raw video: video/x-raw
  95
  96  - Raw text: text/x-raw, format={utf8,pango-markup}
  97
  98 ### Media chain/group handling
  99
 100 When autoplugging, all streams coming out of a demuxer will be grouped
 101 in a `DecodeGroup`.
 102
 103 All new source pads created on that demuxer after it has emitted the
 104 'no-more-pads' signal will be put in another `DecodeGroup`.
 105
 106 Only one decodegroup can be active at any given time. If a new
 107 decodegroup is created while another one exists, that `DecodeGroup` will
 108 be set as blocking until the existing one has drained.
 109
 110 ## DecodeGroup
 111
 112 ### Description
 113
 114 Streams belonging to the same group/chain of a media file.
 115
 116 ### Contents
 117
 118 The DecodeGroup contains:
 119
 120  - a `GstMultiQueue` to which all streams of the media group are connected.
 121
 122  - the eventual decoders which are autoplugged in order to produce the
 123    requested target pads.
 124
 125 ### Proper group draining
 126
 127 The `DecodeGroup` takes care that all the streams in the group are
 128 completely drained (`EOS` has come through all source ghost pads).
 129
 130 ### Pre-roll and block
 131
 132 The `DecodeGroup` has a global blocking feature. If enabled, all the
 133 ghosted source pads for that group will be blocked.
 134
 135 A method is available to unblock all blocked pads for that group.
 136
 137 ## GstMultiQueue
 138
 139 Multiple input-output data queue.
 140
 141 `multiqueue` achieves the same functionality as `queue`, with a
 142 few differences:
 143
 144   - Multiple streams handling.
 145
 146     The element handles queueing data on more than one stream at once.
 147     To achieve such a feature it has request sink pads (`sink_%u`) and
 148     'sometimes' src pads (`src_%u`).
 149
 150     When requesting a given sinkpad, the associated srcpad for that
 151     stream will be created. Ex: requesting `sink_1` will generate `src_1`.
 152
 153   - Non-starvation on multiple streams.
 154
 155     If more than one stream is used with the element, the streams'
 156     queues will be dynamically grown (up to a limit), in order to ensure
 157     that no stream is risking data starvation. This guarantees that at
 158     any given time there are at least N bytes queued and available for
 159     each individual stream.
 160
 161     If an `EOS` event comes through a srcpad, the associated queue should
 162     be considered as 'not-empty' in the queue-size-growing algorithm.
 163
 164   - Non-linked srcpads graceful handling.
 165
 166     A `GstTask` is started for all srcpads when going to
 167     `GST_STATE_PAUSED`.
 168
 169     The task are blocking against a GCondition which will be fired in
 170     two different cases:
 171
 172     - When the associated queue has received a buffer.
 173
 174     - When the associated queue was previously declared as 'not-linked'
 175       and the first buffer of the queue is scheduled to be pushed
 176       synchronously in relation to the order in which it arrived globally
 177       in the element (see 'Synchronous data pushing' below).
 178
 179     When woken up by the `GCondition`, the `GstTask` will try to push the
 180     next `GstBuffer`/`GstEvent` on the queue. If pushing returns
 181     `GST_FLOW_NOT_LINKED`, the associated queue is marked as `not-linked`.
 182     If pushing succeeds, the queue will no longer be marked as `not-linked`.
 183
 184     If pushing on all srcpads returns a `GstFlowReturn` different from
 185     `GST_FLOW_OK`, then all the srcpads' tasks are stopped and
 186     subsequent pushes on sinkpads will return `GST_FLOW_NOT_LINKED`.
 187
 188   - Synchronous data pushing for non-linked pads.
 189
 190     In order to better support dynamic switching between streams, the
 191     multiqueue (unlike the current GStreamer queue) continues to push
 192     buffers on non-linked pads rather than shutting down.
 193
 194     In addition, to prevent a non-linked stream from very quickly
 195     consuming all available buffers and thus 'racing ahead' of the other
 196     streams, the element must ensure that buffers and inlined events for
 197     a non-linked stream are pushed in the same order as they were
 198     received, relative to the other streams controlled by the element.
 199     This means that a buffer cannot be pushed to a non-linked pad any
 200     sooner than buffers in any other stream which were received before
 201     it.
 202
 203 ## Parsers, decoders and auto-plugging
 204
 205 This section has DRAFT status.
 206
 207 Some media formats come in different "flavours" or "stream formats".
 208 These formats differ in the way the setup data and media data is
 209 signalled and/or packaged. An example for this is H.264 video, where
 210 there is a bytestream format (with codec setup data signalled inline and
 211 units prefixed by a sync code and packet length information) and a "raw"
 212 format where codec setup data is signalled out of band (via the caps)
 213 and the chunking is implicit in the way the buffers were muxed into a
 214 container, to mention just two of the possible variants.
 215
 216 Especially on embedded platforms it is common that decoders can only
 217 handle one particular stream format, and not all of them.
 218
 219 Where there are multiple stream formats, parsers are usually expected to
 220 be able to convert between the different formats. This will, if
 221 implemented correctly, work as expected in a static pipeline such as
 222
 223 ```
 224 ... ! parser ! decoder ! sink
 225 ```
 226
 227 where the parser can query the decoder's capabilities even before
 228 processing the first piece of data, and configure itself to convert
 229 accordingly, if conversion is needed at all.
 230
 231 In an auto-plugging context this is not so straight-forward though,
 232 because elements are plugged incrementally and not before the previous
 233 element has processed some data and decided what it will output exactly
 234 (unless the template caps are completely fixed, then it can continue
 235 right away, this is not always the case here though, see below). A
 236 parser will thus have to decide on *some* output format so auto-plugging
 237 can continue. It doesn't know anything about the available decoders and
 238 their capabilities though, so it's possible that it will choose a format
 239 that is not supported by any of the available decoders, or by the
 240 preferred decoder.
 241
 242 If the parser had sufficiently concise but fixed source pad template
 243 caps, decodebin could continue to plug a decoder right away, allowing
 244 the parser to configure itself in the same way as it would with a static
 245 pipeline. This is not an option, unfortunately, because often the parser
 246 needs to process some data to determine e.g. the format's profile or
 247 other stream properties (resolution, sample rate, channel configuration,
 248 etc.), and there may be different decoders for different profiles (e.g.
 249 DSP codec for baseline profile, and software fallback for main/high
 250 profile; or a DSP codec only supporting certain resolutions, with a
 251 software fallback for unusual resolutions). So if decodebin just plugged
 252 the most highest-ranking decoder, that decoder might not be be able to
 253 handle the actual stream later on, which would yield an error (this is a
 254 data flow error then which would be hard to intercept and avoid in
 255 decodebin). In other words, we can't solve this issue by plugging a
 256 decoder right away with the parser.
 257
 258 So decodebin needs to communicate to the parser the set of available
 259 decoder caps (which would contain the relevant capabilities/restrictions
 260 such as supported profiles, resolutions, etc.), after the usual
 261 "autoplug-\*" signal filtering/sorting of course.
 262
 263 This is done by plugging a capsfilter element right after the parser,
 264 and constructing set of filter caps from the list of available decoders
 265 (one appends at the end just the name(s) of the caps structures from the
 266 parser pad template caps to function as an 'ANY other' caps equivalent).
 267 This let the parser negotiate to a supported stream format in the same
 268 way as with the static pipeline mentioned above, but of course incur
 269 some overhead through the additional capsfilter element.
 270