manual-clocks.md

   1 ---
   2 title: Clocks and synchronization in GStreamer
   3 ...
   4
   5 # Clocks and synchronization in GStreamer
   6
   7 When playing complex media, each sound and video sample must be played
   8 in a specific order at a specific time. For this purpose, GStreamer
   9 provides a synchronization mechanism.
  10
  11 GStreamer provides support for the following use cases:
  12
  13   - Non-live sources with access faster than playback rate. This is the
  14     case where one is reading media from a file and playing it back in a
  15     synchronized fashion. In this case, multiple streams need to be
  16     synchronized, like audio, video and subtitles.
  17
  18   - Capture and synchronized muxing/mixing of media from multiple live
  19     sources. This is a typical use case where you record audio and video
  20     from a microphone/camera and mux it into a file for storage.
  21
  22   - Streaming from (slow) network streams with buffering. This is the
  23     typical web streaming case where you access content from a streaming
  24     server with http.
  25
  26   - Capture from live source and and playback to live source with
  27     configurable latency. This is used when, for example, capture from a
  28     camera, apply an effect and display the result. It is also used when
  29     streaming low latency content over a network with UDP.
  30
  31   - Simultaneous live capture and playback from prerecorded content.
  32     This is used in audio recording cases where you play a previously
  33     recorded audio and record new samples, the purpose is to have the
  34     new audio perfectly in sync with the previously recorded data.
  35
  36 GStreamer uses a `GstClock` object, buffer timestamps and a SEGMENT
  37 event to synchronize streams in a pipeline as we will see in the next
  38 sections.
  39
  40 ## Clock running-time
  41
  42 In a typical computer, there are many sources that can be used as a time
  43 source, e.g., the system time, soundcards, CPU performance counters, ...
  44 For this reason, there are many `GstClock` implementations available in
  45 GStreamer. The clock time doesn't always start from 0 or from some known
  46 value. Some clocks start counting from some known start date, other
  47 clocks start counting since last reboot, etc...
  48
  49 A `GstClock` returns the **absolute-time** according to that clock with
  50 `gst_clock_get_time ()`. The absolute-time (or clock time) of a clock is
  51 monotonically increasing. From the absolute-time is a **running-time**
  52 calculated, which is simply the difference between a previous snapshot
  53 of the absolute-time called the **base-time**. So:
  54
  55 running-time = absolute-time - base-time
  56
  57 A GStreamer `GstPipeline` object maintains a `GstClock` object and a
  58 base-time when it goes to the PLAYING state. The pipeline gives a handle
  59 to the selected `GstClock` to each element in the pipeline along with
  60 selected base-time. The pipeline will select a base-time in such a way
  61 that the running-time reflects the total time spent in the PLAYING
  62 state. As a result, when the pipeline is PAUSED, the running-time stands
  63 still.
  64
  65 Because all objects in the pipeline have the same clock and base-time,
  66 they can thus all calculate the running-time according to the pipeline
  67 clock.
  68
  69 ## Buffer running-time
  70
  71 To calculate a buffer running-time, we need a buffer timestamp and the
  72 SEGMENT event that preceeded the buffer. First we can convert the
  73 SEGMENT event into a `GstSegment` object and then we can use the
  74 `gst_segment_to_running_time ()` function to perform the calculation of
  75 the buffer running-time.
  76
  77 Synchronization is now a matter of making sure that a buffer with a
  78 certain running-time is played when the clock reaches the same
  79 running-time. Usually this task is done by sink elements. Sink also have
  80 to take into account the latency configured in the pipeline and add this
  81 to the buffer running-time before synchronizing to the pipeline clock.
  82
  83 Non-live sources timestamp buffers with a running-time starting from 0.
  84 After a flushing seek, they will produce buffers again from a
  85 running-time of 0.
  86
  87 Live sources need to timestamp buffers with a running-time matching the
  88 pipeline running-time when the first byte of the buffer was captured.
  89
  90 ## Buffer stream-time
  91
  92 The buffer stream-time, also known as the position in the stream, is
  93 calculated from the buffer timestamps and the preceding SEGMENT event.
  94 It represents the time inside the media as a value between 0 and the
  95 total duration of the media.
  96
  97 The stream-time is used in:
  98
  99   - Report the current position in the stream with the POSITION query.
 100
 101   - The position used in the seek events and queries.
 102
 103   - The position used to synchronize controlled values.
 104
 105 The stream-time is never used to synchronize streams, this is only done
 106 with the running-time.
 107
 108 ## Time overview
 109
 110 Here is an overview of the various timelines used in GStreamer.
 111
 112 The image below represents the different times in the pipeline when
 113 playing a 100ms sample and repeating the part between 50ms and 100ms.
 114
 115 ![GStreamer clock and various times](images/clocks.png "fig:")
 116
 117 You can see how the running-time of a buffer always increments
 118 monotonically along with the clock-time. Buffers are played when their
 119 running-time is equal to the clock-time - base-time. The stream-time
 120 represents the position in the stream and jumps backwards when
 121 repeating.
 122
 123 ## Clock providers
 124
 125 A clock provider is an element in the pipeline that can provide a
 126 `GstClock` object. The clock object needs to report an absolute-time
 127 that is monotonically increasing when the element is in the PLAYING
 128 state. It is allowed to pause the clock while the element is PAUSED.
 129
 130 Clock providers exist because they play back media at some rate, and
 131 this rate is not necessarily the same as the system clock rate. For
 132 example, a soundcard may playback at 44,1 kHz, but that doesn't mean
 133 that after *exactly* 1 second *according to the system clock*, the
 134 soundcard has played back 44.100 samples. This is only true by
 135 approximation. In fact, the audio device has an internal clock based on
 136 the number of samples played that we can expose.
 137
 138 If an element with an internal clock needs to synchronize, it needs to
 139 estimate when a time according to the pipeline clock will take place
 140 according to the internal clock. To estimate this, it needs to slave its
 141 clock to the pipeline clock.
 142
 143 If the pipeline clock is exactly the internal clock of an element, the
 144 element can skip the slaving step and directly use the pipeline clock to
 145 schedule playback. This can be both faster and more accurate. Therefore,
 146 generally, elements with an internal clock like audio input or output
 147 devices will be a clock provider for the pipeline.
 148
 149 When the pipeline goes to the PLAYING state, it will go over all
 150 elements in the pipeline from sink to source and ask each element if
 151 they can provide a clock. The last element that can provide a clock will
 152 be used as the clock provider in the pipeline. This algorithm prefers a
 153 clock from an audio sink in a typical playback pipeline and a clock from
 154 source elements in a typical capture pipeline.
 155
 156 There exist some bus messages to let you know about the clock and clock
 157 providers in the pipeline. You can see what clock is selected in the
 158 pipeline by looking at the NEW\_CLOCK message on the bus. When a clock
 159 provider is removed from the pipeline, a CLOCK\_LOST message is posted
 160 and the application should go to PAUSED and back to PLAYING to select a
 161 new clock.
 162
 163 ## Latency
 164
 165 The latency is the time it takes for a sample captured at timestamp X to
 166 reach the sink. This time is measured against the clock in the pipeline.
 167 For pipelines where the only elements that synchronize against the clock
 168 are the sinks, the latency is always 0 since no other element is
 169 delaying the buffer.
 170
 171 For pipelines with live sources, a latency is introduced, mostly because
 172 of the way a live source works. Consider an audio source, it will start
 173 capturing the first sample at time 0. If the source pushes buffers with
 174 44100 samples at a time at 44100Hz it will have collected the buffer at
 175 second 1. Since the timestamp of the buffer is 0 and the time of the
 176 clock is now \>= 1 second, the sink will drop this buffer because it is
 177 too late. Without any latency compensation in the sink, all buffers will
 178 be dropped.
 179
 180 ### Latency compensation
 181
 182 Before the pipeline goes to the PLAYING state, it will, in addition to
 183 selecting a clock and calculating a base-time, calculate the latency in
 184 the pipeline. It does this by doing a LATENCY query on all the sinks in
 185 the pipeline. The pipeline then selects the maximum latency in the
 186 pipeline and configures this with a LATENCY event.
 187
 188 All sink elements will delay playback by the value in the LATENCY event.
 189 Since all sinks delay with the same amount of time, they will be
 190 relative in sync.
 191
 192 ### Dynamic Latency
 193
 194 Adding/removing elements to/from a pipeline or changing element
 195 properties can change the latency in a pipeline. An element can request
 196 a latency change in the pipeline by posting a LATENCY message on the
 197 bus. The application can then decide to query and redistribute a new
 198 latency or not. Changing the latency in a pipeline might cause visual or
 199 audible glitches and should therefore only be done by the application
 200 when it is allowed.
 201