docs/pwg/advanced-clock.xml

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