docs/design/design-decodebin.txt

   1 Decodebin design
   2
   3 GstDecodeBin
   4 ------------
   5
   6 Description:
   7
   8   Autoplug and decode to raw media
   9
  10   Input : single pad with ANY caps Output : Dynamic pads
  11
  12 * Contents
  13
  14   _ a GstTypeFindElement connected to the single sink pad
  15
  16   _ optionnaly a demuxer/parser
  17
  18   _ optionnaly one or more DecodeGroup
  19
  20 * Autoplugging
  21
  22   The goal is to reach 'target' caps (by default raw media).
  23
  24   This is done by using the GstCaps of a source pad and finding the available
  25 demuxers/decoders GstElement that can be linked to that pad.
  26
  27   The process starts with the source pad of typefind and stops when no more
  28 non-target caps are left. It is commonly done while pre-rolling, but can also
  29 happen whenever a new pad appears on any element.
  30
  31   Once a target caps has been found, that pad is ghosted and the
  32 'new-decoded-pad' signal is emitted.
  33
  34   If no compatible elements can be found for a GstCaps, the pad is ghosted and
  35 the 'unknown-type' signal is emitted.
  36
  37
  38 * Assisted auto-plugging
  39
  40   When starting the auto-plugging process for a given GstCaps, two signals are
  41 emitted in the following way in order to allow the application/user to assist or
  42 fine-tune the process.
  43
  44   _ 'autoplug-continue' :
  45
  46     gboolean user_function (GstElement * decodebin, GstPad *pad, GstCaps * caps)
  47
  48     This signal is fired at the very beginning with the source pad GstCaps. If
  49   the callback returns TRUE, the process continues normally. If the callback
  50   returns FALSE, then the GstCaps are considered as a target caps and the
  51   autoplugging process stops.
  52
  53   - 'autoplug-factories' :
  54
  55     GValueArray user_function (GstElement* decodebin, GstPad* pad,
  56          GstCaps* caps);
  57
  58     Get a list of elementfactories for @pad with @caps. This function is used to
  59     instruct decodebin2 of the elements it should try to autoplug. The default
  60     behaviour when this function is not overridern is to get all elements that
  61     can handle @caps from the registry sorted by rank.
  62
  63   - 'autoplug-select' :
  64
  65     gint user_function (GstElement* decodebin, GstPad* pad, GstCaps* caps,
  66                 GValueArray* factories);
  67
  68     This signal is fired once autoplugging has got a list of compatible
  69   GstElementFactory. The signal is emitted with the GstCaps of the source pad
  70   and a pointer on the GValueArray of compatible factories.
  71
  72     The callback should return the index of the elementfactory in @factories
  73     that should be tried next.
  74
  75     If the callback returns -1, the autoplugging process will stop as if no
  76   compatible factories were found.
  77
  78   The default implementation of this function will try to autoplug the first
  79   factory of the list.
  80
  81 * Target Caps
  82
  83   The target caps are a read/write GObject property of decodebin.
  84
  85   By default the target caps are:
  86
  87   _ Raw audio : audio/x-raw-int, audio/x-raw-float
  88
  89   _ and raw video : video/x-raw-rgb, video/x-raw-yuv
  90
  91   _ and Text : text/plain, text/x-pango-markup
  92
  93
  94 * media chain/group handling
  95
  96   When autoplugging, all streams coming out of a demuxer will be grouped in a
  97 DecodeGroup.
  98
  99   All new source pads created on that demuxer after it has emitted the
 100 'no-more-pads' signal will be put in another DecodeGroup.
 101
 102   Only one decodegroup can be active at any given time. If a new decodegroup is
 103 created while another one exists, that decodegroup will be set as blocking until
 104 the existing one has drained.
 105
 106
 107
 108 DecodeGroup
 109 -----------
 110
 111 Description:
 112
 113   Streams belonging to the same group/chain of a media file.
 114
 115 * Contents
 116
 117   The DecodeGroup contains:
 118
 119   _ a GstMultiQueue to which all streams of a the media group are connected.
 120
 121   _ the eventual decoders which are autoplugged in order to produce the
 122   requested target pads.
 123
 124 * Proper group draining
 125
 126   The DecodeGroup takes care that all the streams in the group are completely
 127 drained (EOS has come through all source ghost pads).
 128
 129 * Pre-roll and block
 130
 131   The DecodeGroup has a global blocking feature. If enabled, all the ghosted
 132 source pads for that group will be blocked.
 133
 134   A method is available to unblock all blocked pads for that group.
 135
 136
 137
 138 GstMultiQueue
 139 -------------
 140
 141 Description:
 142
 143   Multiple input-output data queue
 144
 145   The GstMultiQueue achieves the same functionnality as GstQueue, with a few
 146 differences:
 147
 148   * Multiple streams handling.
 149
 150     The element handles queueing data on more than one stream at once. To
 151   achieve such a feature it has request sink pads (sink_%d) and 'sometimes' src
 152   pads (src_%d).
 153
 154     When requesting a given sinkpad, the associated srcpad for that stream will
 155   be created. Ex: requesting sink_1 will generate src_1.
 156
 157
 158   * Non-starvation on multiple streams.
 159
 160     If more than one stream is used with the element, the streams' queues will
 161   be dynamically grown (up to a limit), in order to ensure that no stream is
 162   risking data starvation. This guarantees that at any given time there are at
 163   least N bytes queued and available for each individual stream.
 164
 165     If an EOS event comes through a srcpad, the associated queue should be
 166   considered as 'not-empty' in the queue-size-growing algorithm.
 167
 168
 169   * Non-linked srcpads graceful handling.
 170
 171     A GstTask is started for all srcpads when going to GST_STATE_PAUSED.
 172
 173     The task are blocking against a GCondition which will be fired in two
 174   different cases:
 175
 176     _ When the associated queue has received a buffer.
 177
 178     _ When the associated queue was previously declared as 'not-linked' and the
 179     first buffer of the queue is scheduled to be pushed synchronously in
 180     relation to the order in which it arrived globally in the element (see
 181     'Synchronous data pushing' below).
 182
 183     When woken up by the GCondition, the GstTask will try to push the next
 184   GstBuffer/GstEvent on the queue. If pushing the GstBuffer/GstEvent returns
 185   GST_FLOW_NOT_LINKED, then the associated queue is marked as 'not-linked'. If
 186   pushing the GstBuffer/GstEvent succeeded the queue will no longer be marked as
 187   'not-linked'.
 188
 189     If pushing on all srcpads returns GstFlowReturn different from GST_FLOW_OK,
 190   then all the srcpads' tasks are stopped and subsequent pushes on sinkpads will
 191   return GST_FLOW_NOT_LINKED.
 192
 193   * Synchronous data pushing for non-linked pads.
 194
 195     In order to better support dynamic switching between streams, the multiqueue
 196   (unlike the current GStreamer queue) continues to push buffers on non-linked
 197   pads rather than shutting down.
 198
 199     In addition, to prevent a non-linked stream from very quickly consuming all
 200   available buffers and thus 'racing ahead' of the other streams, the element
 201   must ensure that buffers and inlined events for a non-linked stream are pushed
 202   in the same order as they were received, relative to the other streams
 203   controlled by the element. This means that a buffer cannot be pushed to a
 204   non-linked pad any sooner than buffers in any other stream which were received
 205   before it.