pwg-advanced-clock.md

   1 ---
   2 title: Clocking
   3 ...
   4
   5 # Clocking
   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 ## Clocks
  12
  13 Time in GStreamer is defined as the value returned from a particular
  14 `GstClock` object from the method `gst_clock_get_time ()`.
  15
  16 In a typical computer, there are many sources that can be used as a time
  17 source, e.g., the system time, soundcards, CPU performance counters, ...
  18 For this reason, there are many `GstClock` implementations available in
  19 GStreamer. The clock time doesn't always start from 0 or from some known
  20 value. Some clocks start counting from some known start date, other
  21 clocks start counting since last reboot, etc...
  22
  23 As clocks return an absolute measure of time, they are not usually used
  24 directly. Instead, differences between two clock times are used to
  25 measure elapsed time according to a clock.
  26
  27 ## Clock running-time
  28
  29 A clock returns the **absolute-time** according to that clock with
  30 `gst_clock_get_time ()`. From the absolute-time is a **running-time**
  31 calculated, which is simply the difference between a previous snapshot
  32 of the absolute-time called the **base-time**. So:
  33
  34 running-time = absolute-time - base-time
  35
  36 A GStreamer `GstPipeline` object maintains a `GstClock` object and a
  37 base-time when it goes to the PLAYING state. The pipeline gives a handle
  38 to the selected `GstClock` to each element in the pipeline along with
  39 selected base-time. The pipeline will select a base-time in such a way
  40 that the running-time reflects the total time spent in the PLAYING
  41 state. As a result, when the pipeline is PAUSED, the running-time stands
  42 still.
  43
  44 Because all objects in the pipeline have the same clock and base-time,
  45 they can thus all calculate the running-time according to the pipeline
  46 clock.
  47
  48 ## Buffer running-time
  49
  50 To calculate a buffer running-time, we need a buffer timestamp and the
  51 SEGMENT event that preceded the buffer. First we can convert the SEGMENT
  52 event into a `GstSegment` object and then we can use the
  53 `gst_segment_to_running_time ()` function to perform the calculation of
  54 the buffer running-time.
  55
  56 Synchronization is now a matter of making sure that a buffer with a
  57 certain running-time is played when the clock reaches the same
  58 running-time. Usually this task is done by sink elements. Sink also have
  59 to take into account the latency configured in the pipeline and add this
  60 to the buffer running-time before synchronizing to the pipeline clock.
  61
  62 ## Obligations of each element.
  63
  64 Let us clarify the contract between GStreamer and each element in the
  65 pipeline.
  66
  67 ### Non-live source elements
  68
  69 Non-live source elements must place a timestamp in each buffer that they
  70 deliver when this is possible. They must choose the timestamps and the
  71 values of the SEGMENT event in such a way that the running-time of the
  72 buffer starts from 0.
  73
  74 Some sources, such as filesrc, is not able to generate timestamps on all
  75 buffers. It can and must however create a timestamp on the first buffer
  76 (with a running-time of 0).
  77
  78 The source then pushes out the SEGMENT event followed by the timestamped
  79 buffers.
  80
  81 ### Live source elements
  82
  83 Live source elements must place a timestamp in each buffer that they
  84 deliver. They must choose the timestamps and the values of the SEGMENT
  85 event in such a way that the running-time of the buffer matches exactly
  86 the running-time of the pipeline clock when the first byte in the buffer
  87 was captured.
  88
  89 ### Parser/Decoder/Encoder elements
  90
  91 Parser/Decoder elements must use the incoming timestamps and transfer
  92 those to the resulting output buffers. They are allowed to interpolate
  93 or reconstruct timestamps on missing input buffers when they can.
  94
  95 ### Demuxer elements
  96
  97 Demuxer elements can usually set the timestamps stored inside the media
  98 file onto the outgoing buffers. They need to make sure that outgoing
  99 buffers that are to be played at the same time have the same
 100 running-time. Demuxers also need to take into account the incoming
 101 timestamps on buffers and use that to calculate an offset on the
 102 outgoing buffer timestamps.
 103
 104 ### Muxer elements
 105
 106 Muxer elements should use the incoming buffer running-time to mux the
 107 different streams together. They should copy the incoming running-time
 108 to the outgoing buffers.
 109
 110 ### Sink elements
 111
 112 If the element is intended to emit samples at a specific time (real time
 113 playing), the element should require a clock, and thus implement the
 114 method `set_clock`.
 115
 116 The sink should then make sure that the sample with running-time is
 117 played exactly when the pipeline clock reaches that running-time +
 118 latency. Some elements might use the clock API such as
 119 `gst_clock_id_wait()` to perform this action. Other sinks might need to
 120 use other means of scheduling timely playback of the data.
 121