docs/design/part-synchronisation.txt

   1 Synchronisation
   2 ---------------
   3
   4 This document outlines the techniques used for doing synchronised playback of
   5 multiple streams.
   6
   7 Synchronisation in a GstPipeline is achieved using the following 3 components:
   8
   9  - a GstClock, which is global for all elements in a GstPipeline.
  10  - Timestamps on a GstBuffer.
  11  - the NEW_SEGMENT event preceding the buffers.
  12
  13
  14 A GstClock
  15 ----------
  16
  17 This object provides a counter that represents the current time in nanoseconds.
  18 This value is called the absolute_time.
  19
  20 Different sources exist for this counter:
  21
  22  - the system time (with g_get_current_time() and with microsecond accuracy)
  23  - an audio device (based on number of samples played)
  24  - a network source based on packets received + timestamps in those packets (a
  25    typical example is an RTP source)
  26  - ...
  27
  28 In GStreamer any element can provide a GstClock object that can be used in the
  29 pipeline. The GstPipeline object will select a clock from all the providers and
  30 will distribute it to all other elements (see part-gstpipeline.txt).
  31
  32 A GstClock always counts time upwards and does not necessarily start at 0.
  33
  34
  35 Running time
  36 ------------
  37
  38 After a pipeline selected a clock it will maintain the running_time based on the
  39 selected clock. This running_time represents the total time spent in the PLAYING
  40 state and is calculated as follows:
  41
  42  - If the pipeline is NULL/READY, the running_time is undefined.
  43  - In PAUSED, the running_time remains at the time when it was last
  44    PAUSED. When the stream is PAUSED for the first time, the running_time
  45    is 0.
  46  - In PLAYING, the running_time is the delta between the absolute_time
  47    and the base time. The base time is defined as the absolute_time minus
  48    the running_time at the time when the pipeline is set to PLAYING.
  49  - after a flushing seek, the running_time is set to 0 (see part-seeking.txt).
  50    This is accomplished by redistributing a new base_time to the elements that
  51    got flushed.
  52
  53 This algorithm captures the running_time when the pipeline is set from PLAYING
  54 to PAUSED and restores this time based on the current absolute_time when going
  55 back to PLAYING. This allows for both clocks that progress when in the PAUSED
  56 state (systemclock) and clocks that don't (audioclock).
  57
  58 The clock and pipeline now provides a running_time to all elements that want to
  59 perform synchronisation. Indeed, the running time can be observed in each
  60 element (during the PLAYING state) as:
  61
  62   running_time = absolute_time - base_time
  63
  64
  65 Timestamps
  66 ----------
  67
  68 The GstBuffer timestamps and the preceeding NEW_SEGMENT event (See
  69 part-streams.txt) define a transformation of the buffers to running_time as
  70 follows:
  71
  72 The following notation is used:
  73
  74  B: GstBuffer
  75   - B.timestamp = buffer timestamp (GST_BUFFER_TIMESTAMP)
  76
  77  NS:  NEWSEGMENT event preceeding the buffers.
  78   - NS.start: start field in the NEWSEGMENT event
  79   - NS.rate: rate field of NEWSEGMENT event
  80   - NS.abs_rate: absolute value of rate field of NEWSEGMENT event
  81   - NS.time: time field in the NEWSEGMENT event
  82   - NS.accum: total accumulated time of all previous NEWSEGMENT events. This
  83               field is kept in the GstSegment structure.
  84
  85 Valid buffers for synchronisation are those with B.timestamp between NS.start
  86 and NS.stop. All other buffers outside this range should be dropped or clipped
  87 to these boundaries (see also part-segments.txt).
  88
  89 The following transformation to running_time exist:
  90
  91     if (NS.rate > 0.0)
  92       running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
  93     else
  94       running_time = (NS.stop - B.timestamp) / NS.abs_rate + NS.accum
  95
  96 The first displayable buffer will yield a value of 0 (since B.timestamp ==
  97 NS.start and NS.accum == 0).
  98
  99 For NS.rate > 1.0, the timestamps will be scaled down to increase the playback
 100 rate. Likewise, a rate between 0.0 and 1.0 will slow down playback.
 101
 102 For negative rates, timestamps are received stop NS.stop to NS.start so that the
 103 first buffer received will be transformed into running_time of 0 (B.timestamp ==
 104 NS.stop and NS.accum == 0).
 105
 106
 107 Synchronisation
 108 ---------------
 109
 110 As we have seen, we can get a running_time:
 111
 112  - using the clock and the element's base_time with:
 113
 114     C.running_time = absolute_time - base_time
 115
 116  - using the buffer timestamp and the preceeding NEWSEGMENT event as (assuming
 117    positive playback rate):
 118
 119     B.running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
 120
 121 We prefix C. and B. before the two running times to note how they were
 122 calculated.
 123
 124 The task of synchronized playback is to make sure that we play be buffer with
 125 B.running_time at the moment when the clock reaches the same C.running_time.
 126
 127 Thus the following must hold:
 128
 129    B.running_time = C.running_time
 130
 131 expaning:
 132
 133    B.running_time = absolute_time - base_time
 134
 135 or:
 136
 137    absolute_time = B.running_time + base_time
 138
 139 The absolute_time when a buffer with B.running_time should be played is noted
 140 with B.sync_time. Thus:
 141
 142   B.sync_time = B.running_time + base_time
 143
 144 One then waits for the clock to reach B.sync_time before rendering the buffer in
 145 the sink (See also part-clocks.txt).
 146
 147 For multiple streams this means that buffers with the same running_time are to
 148 be displayed at the same time.
 149
 150 A demuxer must make sure that the NEWSEGMENT it emits on its output pads yield
 151 the same running_time for buffers that should be played synchronized. This
 152 usually means sending the same NEWSEGMENT on all pads and making sure that the
 153 synchronized buffers have the same timestamps.
 154
 155
 156 Stream time
 157 -----------
 158
 159 The stream time is also known as the position in the stream and is a value
 160 between 0 and the total duration of the media file.
 161
 162 It is the stream time that is used for:
 163
 164   - report the POSITION query in the pipeline
 165   - the position used in seek queries
 166   - the position used to synchronize controller values
 167
 168 Stream time is calculated using the buffer times and the preceeding NEWSEGMENT
 169 event as follows:
 170
 171     stream_time = (B.timestamp - NS.start) * NS.abs_applied_rate + NS.time
 172
 173 For negative rates, B.timestamp will go backwards from NS.stop to NS.start,
 174 making the stream time go backwards.
 175
 176 Note that the stream time is never used for synchronisation against the clock.
 177