docs/design/part-latency.txt

   1 Latency
   2 -------
   3
   4 The latency is the time it takes for a sample captured at timestamp 0 to reach the
   5 sink. This time is measured against the clock in the pipeline. For pipelines
   6 where the only elements that synchronize against the clock are the sinks, the
   7 latency is always 0 since no other element is delaying the buffer.
   8
   9 For pipelines with live sources, a latency is introduced, mostly because of the
  10 way a live source works. Consider an audio source, it will start capturing the
  11 first sample at time 0. If the source pushes buffers with 44100 samples at a
  12 time at 44100Hz it will have collected the buffer at second 1.
  13 Since the timestamp of the buffer is 0 and the time of the clock is now >= 1
  14 second, the sink will drop this buffer because it is too late.
  15 Without any latency compensation in the sink, all buffers will be dropped.
  16
  17 The situation becomes more complex in the presence of:
  18
  19  - 2 live sources connected to 2 live sinks with different latencies
  20     * audio/video capture with synchronized live preview.
  21     * added latencies due to effects (delays, resamplers...)
  22  - 1 live source connected to 2 live sinks
  23     * firewire DV
  24     * RTP, with added latencies because of jitter buffers.
  25  - mixed live source and non-live source scenarios.
  26     * synchronized audio capture with non-live playback. (overdubs,..)
  27  - clock slaving in the sinks due to the live sources providing their own
  28    clocks.
  29
  30 To perform the needed latency corrections in the above scenarios, we must
  31 develop an algorithm to calculate a global latency for the pipeline. The
  32 algorithm must be extensible so that it can optimize the latency at runtime.
  33 It must also be possible to disable or tune the algorithm based on specific
  34 application needs (required minimal latency).
  35
  36
  37 Pipelines without latency compensation
  38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39
  40 We show some examples to demonstrate the problem of latency in typical
  41 capture pipelines.
  42
  43 - Example 1
  44
  45   An audio capture/playback pipeline.
  46
  47    asrc: audio source, provides a clock
  48    asink audio sink, provides a clock
  49
  50    .--------------------------.
  51    | pipeline                 |
  52    | .------.      .-------.  |
  53    | | asrc |      | asink |  |
  54    | |     src -> sink     |  |
  55    | '------'      '-------'  |
  56    '--------------------------'
  57
  58  NULL->READY:
  59   asink: NULL->READY: probes device, returns SUCCESS
  60   asrc: NULL->READY:  probes device, returns SUCCESS
  61
  62  READY->PAUSED:
  63   asink: READY:->PAUSED open device, returns ASYNC
  64   asrc: READY->PAUSED:  open device, returns NO_PREROLL
  65
  66   * Since the source is a live source, it will only produce data in the
  67     PLAYING state. To note this fact, it returns NO_PREROLL from the state change
  68     function.
  69   * This sink returns ASYNC because it can only complete the state change to
  70     PAUSED when it receives the first buffer.
  71
  72   At this point the pipeline is not processing data and the clock is not
  73   running. Unless a new action is performed on the pipeline, this situation will
  74   never change.
  75
  76  PAUSED->PLAYING:
  77   asrc clock selected because it is the most upstream clock provider. asink can
  78   only provide a clock when it received the first buffer and configured the
  79   device with the samplerate in the caps.
  80
  81   asink: PAUSED:->PLAYING, sets pending state to PLAYING, returns ASYNC becaus
  82                          it is not prerolled. The sink will commit state to
  83                          PLAYING when it prerolls.
  84   asrc: PAUSED->PLAYING: starts pushing buffers.
  85
  86   * since the sink is still performing a state change from READY -> PAUSED, it
  87     remains ASYNC. The pending state will be set to PLAYING.
  88   * The clock starts running as soon as all the elements have been set to
  89     PLAYING.
  90   * the source is a live source with a latency. Since it is synchronized with
  91     the clock, it will produce a buffer with timestamp 0 and duration D after
  92     time D, ie. it will only be able to produce the last sample of the buffer
  93     (with timestamp D) at time D. This latency depends on the size of the
  94     buffer.
  95   * the sink will receive the buffer with timestamp 0 at time >= D. At this
  96     point the buffer is too late already and might be dropped. This state of
  97     constantly dropping data will not change unless a constant latency
  98     correction is added to the incoming buffer timestamps.
  99
 100   The problem is due to the fact that the sink is set to (pending) PLAYING
 101   without being prerolled, which only happens in live pipelines.
 102
 103 - Example 2
 104
 105   An audio/video capture/playback pipeline. We capture both audio and video and
 106   have them played back synchronized again.
 107
 108    asrc: audio source, provides a clock
 109    asink audio sink, provides a clock
 110    vsrc: video source
 111    vsink video sink
 112
 113    .--------------------------.
 114    | pipeline                 |
 115    | .------.      .-------.  |
 116    | | asrc |      | asink |  |
 117    | |     src -> sink     |  |
 118    | '------'      '-------'  |
 119    | .------.      .-------.  |
 120    | | vsrc |      | vsink |  |
 121    | |     src -> sink     |  |
 122    | '------'      '-------'  |
 123    '--------------------------'
 124
 125   The state changes happen in the same way as example 1. Both sinks end up with
 126   pending state of PLAYING and a return value of ASYNC until they receive the
 127   first buffer.
 128
 129   For audio and video to be played in sync, both sinks must compensate for the
 130   latency of its source but must also use exactly the same latency correction.
 131
 132   Suppose asrc has a latency of 20ms and vsrc a latency of 33ms, the total
 133   latency in the pipeline has to be at least 33ms. This also means that the
 134   pipeline must have at least a 33 - 20 = 13ms buffering on the audio stream or
 135   else the audio src will underrun while the audiosink waits for the previous
 136   sample to play.
 137
 138 - Example 3
 139
 140   An example of the combination of a non-live (file) and a live source (vsrc)
 141   connected to live sinks (vsink, sink).
 142
 143    .--------------------------.
 144    | pipeline                 |
 145    | .------.      .-------.  |
 146    | | file |      | sink  |  |
 147    | |     src -> sink     |  |
 148    | '------'      '-------'  |
 149    | .------.      .-------.  |
 150    | | vsrc |      | vsink |  |
 151    | |     src -> sink     |  |
 152    | '------'      '-------'  |
 153    '--------------------------'
 154
 155   The state changes happen in the same way as example 1. Except sink will be
 156   able to preroll (commit its state to PAUSED).
 157
 158   In this case sink will have no latency but vsink will. The total latency
 159   should be that of vsink.
 160
 161   Note that because of the presence of a live source (vsrc), the pipeline can be
 162   set to playing before sink is able to preroll. Without compensation for the
 163   live source, this might lead to synchronisation problems because the latency
 164   should be configured in the element before it can go to PLAYING.
 165
 166
 167 - Example 4
 168
 169   An example of the combination of a non-live and a live source. The non-live
 170   source is connected to a live sink and the live source to a non-live sink.
 171
 172    .--------------------------.
 173    | pipeline                 |
 174    | .------.      .-------.  |
 175    | | file |      | sink  |  |
 176    | |     src -> sink     |  |
 177    | '------'      '-------'  |
 178    | .------.      .-------.  |
 179    | | vsrc |      | files |  |
 180    | |     src -> sink     |  |
 181    | '------'      '-------'  |
 182    '--------------------------'
 183
 184   The state changes happen in the same way as example 3. Sink will be
 185   able to preroll (commit its state to PAUSED). files will not be able to
 186   preroll.
 187
 188   sink will have no latency since it is not connected to a live source. files
 189   does not do synchronisation so it does not care about latency.
 190
 191   The total latency in the pipeline is 0. The vsrc captures in sync with the
 192   playback in sink.
 193
 194   As in example 3, sink can only be set to PLAYING after it successfully
 195   prerolled.
 196
 197
 198 State Changes
 199 ~~~~~~~~~~~~~
 200
 201 A Sink is never set to PLAYING before it is prerolled. In order to do this, the
 202 pipeline (at the GstBin level) keeps track of all
 203 elements that require preroll (the ones that return ASYNC from the state
 204 change). These elements posted a ASYNC_START message without a matching
 205 ASYNC_DONE message.
 206
 207 The pipeline will not change the state of the elements that are still doing an
 208 ASYNC state change.
 209
 210 When an ASYNC element prerolls, it commits its state to PAUSED and posts an
 211 ASYNC_DONE message. The pipeline notices this ASYNC_DONE message and matches it
 212 with the ASYNC_START message it cached for the corresponding element.
 213
 214 When all ASYNC_START messages are matched with an ASYNC_DONE message, the
 215 pipeline proceeds with setting the elements to the final state again.
 216
 217 The base time of the element was already set by the pipeline when it changed the
 218 NO_PREROLL element to PLAYING. This operation has to be performed in the
 219 separate async state change thread (like the one currently used for going from
 220 PAUSED->PLAYING in a non-live pipeline).
 221
 222
 223 Latency compensation
 224 ~~~~~~~~~~~~~~~~~~~~
 225
 226 Latency calculation and compensation is performed before the pipeline proceeds to
 227 the PLAYING state.
 228
 229 When the pipeline collected all ASYNC_DONE messages it can calculate the global
 230 latency as follows:
 231
 232   - perform a latency query on all sinks.
 233   - latency = MAX (all min latencies)
 234   - if MIN (all max latencies) < latency we have an impossible situation and we
 235     must generate an error indicating that this pipeline cannot be played. This
 236     usually means that there is not enough buffering in some chain of the
 237     pipeline. A queue can be added to those chains.
 238
 239 The sinks gather this information with a LATENCY query upstream. Intermediate
 240 elements pass the query upstream and add the amount of latency they add to the
 241 result.
 242
 243 ex1:
 244   sink1: [20 - 20]
 245   sink2: [33 - 40]
 246
 247   MAX (20, 33) = 33
 248   MIN (20, 40) = 20 < 33 -> impossible
 249
 250 ex2:
 251   sink1: [20 - 50]
 252   sink2: [33 - 40]
 253
 254   MAX (20, 33) = 33
 255   MIN (50, 40) = 40 >= 33 -> latency = 33
 256
 257 The latency is set on the pipeline by sending a LATENCY event to the sinks
 258 in the pipeline. This event configures the total latency on the sinks. The
 259 sink forwards this LATENCY event upstream so that intermediate elements can
 260 configure themselves as well.
 261
 262 After this step, the pipeline continues setting the pending state on its
 263 elements.
 264
 265 A sink adds the latency value, received in the LATENCY event, to
 266 the times used for synchronizing against the clock. This will effectively
 267 delay the rendering of the buffer with the required latency. Since this delay is
 268 the same for all sinks, all sinks will render data relatively synchronised.
 269
 270
 271 Flushing a playing pipeline
 272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 273
 274 We can implement resynchronisation after an uncontrolled FLUSH in (part of) a
 275 pipeline in the same way. Indeed, when a flush is performed on
 276 a PLAYING live element, a new base time must be distributed to this element.
 277
 278 A flush in a pipeline can happen in the following cases:
 279
 280  - flushing seek in the pipeline
 281     - performed by the application on the pipeline
 282     - performed by the application on an element
 283  - flush preformed by an element
 284     - after receiving a navigation event (DVD, ...)
 285
 286 When a playing sink is flushed by a FLUSH_START event, an ASYNC_START  message is
 287 posted by the element. As part of the message, the fact that the element got
 288 flushed is included. The element also goes to a pending PAUSED state and has to
 289 be set to the PLAYING state again later.
 290
 291 The ASYNC_START message is kept by the parent bin. When the element prerolls,
 292 it posts an ASYNC_DONE message.
 293
 294 When all ASYNC_START messages are matched with an ASYNC_DONE message, the bin
 295 will capture a new base_time from the clock and will bring all the sinks back to
 296 PLAYING after setting the new base time on them. It's also possible
 297 to perform additional latency calculations and adjustments before doing this.
 298
 299
 300 Dynamically adjusting latency
 301 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 302
 303 An element that want to change the latency in the pipeline can do this by
 304 posting a LATENCY message on the bus. This message instructs the pipeline to:
 305
 306  - query the latency in the pipeline (which might now have changed) with a
 307    LATENCY query.
 308  - redistribute a new global latency to all elements with a LATENCY event.
 309
 310 A use case where the latency in a pipeline can change could be a network element
 311 that observes an increased inter packet arrival jitter or excessive packet loss
 312 and decides to increase its internal buffering (and thus the latency). The
 313 element must post a LATENCY message and perform the additional latency
 314 adjustments when it receives the LATENCY event from the downstream peer element.
 315
 316 In a similar way can the latency be decreased when network conditions are
 317 improving again.
 318
 319 Latency adjustments will introduce glitches in playback in the sinks and must
 320 only be performed in special conditions.