markdown/additional/design/live-source.md

   1 # Live sources
   2
   3 A live source is a source that cannot be arbitrarily `PAUSED` without
   4 losing data.
   5
   6 A live source such as an element capturing audio or video, needs to be
   7 handled in a special way. It does not make sense to start the dataflow
   8 in the `PAUSED` state for those devices as the user might wait a long time
   9 between going from `PAUSED` to `PLAYING`, making the previously captured
  10 buffers irrelevant.
  11
  12 A live source therefore only produces buffers in the `PLAYING` state. This
  13 has implications for sinks waiting for a buffer to complete the preroll
  14 state since such a buffer might never arrive.
  15
  16 Live sources return `NO_PREROLL` when going to the `PAUSED` state to inform
  17 the bin/pipeline that this element will not be able to produce data in
  18 the `PAUSED` state. `NO_PREROLL` should be returned for both `READY→PAUSED`
  19 and `PLAYING→PAUSED`.
  20
  21 When performing a `get_state()` on a bin with a non-zero timeout value,
  22 the bin must be sure that there are no live sources in the pipeline
  23 because otherwise, `get_state()` would block on the sinks.
  24
  25 A `GstBin` therefore always performs a zero-timeout `get_state()` on its
  26 elements to discover the `NO_PREROLL` (and `ERROR`) elements before
  27 performing a blocking wait.
  28
  29 ## Scheduling
  30
  31 Live sources will not produce data in the `PAUSED` state. They block in
  32 `get_range()` or in the loop function until they go to `PLAYING`.
  33
  34 ## Latency
  35
  36 The live source timestamps its data with the time of the clock when
  37 the data was captured. Normally, it will take some time to capture
  38 the first sample of data and the last one. This means that when the
  39 buffer arrives at the sink, it will already be late and will be dropped.
  40
  41 The latency is the time it takes to construct one buffer of data and it's
  42 exposed with a `LATENCY` query.
  43
  44 See [latency](additional/design/latency.md)
  45
  46 ## Timestamps
  47
  48 Live sources always timestamp their buffers with the `running_time` of
  49 the pipeline. This is needed to be able to match the timestamps of
  50 different live sources in order to synchronize them.
  51
  52 This is in contrast to non-live sources, which timestamp their buffers
  53 starting from `running_time` 0.