markdown/design/element-source.md

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