docs/design/part-element-source.txt

   1 Source elements
   2 ---------------
   3
   4 A source element is an element that provides data to the pipeline. It
   5 does typically not have any sink (input) pads.
   6
   7 Typical source elements include:
   8
   9  - file readers
  10  - network elements (live or not)
  11  - capture elements (video/audio/...)
  12  - generators (signals/video/audio/...)
  13
  14
  15 Live sources
  16 ~~~~~~~~~~~~
  17
  18 A source is said to be a live source when it has the following property:
  19
  20  * temporarily stopping reading from the source causes data to be lost.
  21
  22 In general when this property holds, the source also produces data at a fixed
  23 rate. Most sources have a limit to the rate at which they can deliver data, which
  24 might be faster or slower than the consumption rate. this property however does
  25 not make them a live source.
  26
  27 Let's look at some example sources.
  28
  29  - file readers: you can PAUSE without losing data. There is however a limit to
  30    how fast you can read from this source. This limit is usually much higher
  31    than the consumption rate. In some cases it might be slower (an NFS share,
  32    for example) in which case you might need to use some buffering
  33    (see part-buffering.txt).
  34
  35  - http network element: you can PAUSE without data loss. Depending on the
  36    available network bandwidth, consumption rate might be higher than production
  37    rate in which case buffering should be used (see part-buffering.txt).
  38
  39  - audio source: pausing the audio capture will lead to lost data. this source
  40    is therefore definatly live. In addition, an audio source will produce data
  41    at a fixed rate (the samplerate). Also depending on the buffersize, this
  42    source will introduce a latency (see part-latency.txt).
  43
  44  - udp network source: Pausing the receiving part will lead to lost data. This
  45    source is therefore a live source. Also in a typical case the udp packets
  46    will be received at a certain rate, which might be difficult to guess because
  47    of network jitter. This source does not necessarily introduce latency on its
  48    own.
  49
  50  - dvb source: PAUSING this element will lead to data loss, it's a live source
  51    similar to a UDP source.
  52
  53
  54 Source types
  55 ~~~~~~~~~~~~
  56
  57 A source element can operate in three ways:
  58
  59   - it is fully seekable, this means that random access can be performed
  60     on it in an efficient way. (a file reader,...). This also typically
  61     means that the source is not live.
  62
  63   - data can be obtained from it with a variable size. This means that
  64     the source can give N bytes of data. An example is an audio source.
  65     A video source always provides the same amount of data (one video
  66     frame). Note that this is not a fully seekable source.
  67
  68   - it is a live source, see above.
  69
  70 When writing a source, one has to look at how the source can operate to
  71 decide on the scheduling methods to implement on the source.
  72
  73   - fully seekable sources implement a getrange function on the source pad.
  74
  75   - sources that can give N bytes but cannot do seeking also implement a
  76     getrange function but state that they cannot do random access.
  77
  78   - sources that are purely live sources implement a task to push out
  79     data.
  80
  81 Any source that has a getrange function must also implement a push based
  82 scheduling mode. In this mode the source starts a task that gets N bytes
  83 and pushes them out. Whenever possible, the peer element will select the
  84 getrange based scheduling method of the source, though.
  85
  86 A source with a getrange function must activate itself in the pad activate
  87 function. This is needed because the downstream peer element will decide
  88 and activate the source element in its state change function before the
  89 source's state change function is called.
  90
  91
  92 Source base classes
  93 ~~~~~~~~~~~~~~~~~~~
  94
  95 GstBaseSrc:
  96
  97 This base class provides an implementation of a random access source and
  98 is very well suited for file reader like sources.
  99
 100
 101 GstPushSrc:
 102
 103 Base class for block-based sources. This class is mostly useful for
 104 elements that cannot do random access, or at least very slowly. The
 105 source usually prefers to push out a fixed size buffer.
 106
 107 Classes extending this base class will usually be scheduled in a push
 108 based mode. It the peer accepts to operate without offsets and withing
 109 the limits of the allowed block size, this class can operate in getrange
 110 based mode automatically.
 111
 112 The subclass should extend the methods from the baseclass in
 113 addition to the create method. If the source is seekable, it
 114 needs to override GstBaseSrc::event() in addition to
 115 GstBaseSrc::is_seekable() in order to retrieve the seek offset,
 116 which is the offset of the next buffer to be requested.
 117
 118 Flushing, scheduling and sync is all handled by this base class.
 119
 120
 121 Timestamps
 122 ~~~~~~~~~~
 123
 124 A non-live source should timestamp the buffers it produces starting from 0. If
 125 it is not possible to timestamp every buffer (filesrc), the source is allowed to
 126 only timestamp the first buffer (as 0).
 127
 128 Live sources only produce data in the PLAYING state, when the clock is running.
 129 They should timestamp each buffer they produce with the current running_time of
 130 the pipeline, which is expressed as:
 131
 132     absolute_time - base_time
 133
 134 With absolute_time the time obtained from the global pipeline with
 135 gst_clock_get_time() and base_time being the time of that clock when the
 136 pipeline was last set to PLAYING.
 137