docs/manual/advanced-clocks.xml

   1 <chapter id="chapter-clocks">
   2   <title>Clocks in GStreamer</title>
   3
   4   <para>
   5     To maintain sync in pipeline playback (which is the only case where this
   6     really matters), &GStreamer; uses <emphasis>clocks</emphasis>. Clocks
   7     are exposed by some elements, whereas other elements are merely clock
   8     slaves. The primary task of a clock is to represent the time progress
   9     according to the element exposing the clock, based on its own playback
  10     rate. If no clock provider is available in a pipeline, the system clock
  11     is used instead.
  12   </para>
  13
  14   <para>
  15     &GStreamer; derives several <emphasis>time value</emphasis> from the clock
  16     and the playback state.
  17     It is important to note, that a  <emphasis>clock-time</emphasis> is
  18     monotonically rising, but the value itself is not meaningful.
  19     Subtracting the <emphasis>base-time</emphasis> yields the
  20     <emphasis>running-time</emphasis>. It is the same as the
  21     <emphasis>stream-time</emphasis> if one plays from start to end at original
  22     rate. The <emphasis>stream-time</emphasis> indicates the position in the
  23     media. The <emphasis>running-time</emphasis> is (re-)set to 0 when the
  24     pipeline starts to play and also after <emphasis>flushing</emphasis> seeks.
  25   </para>
  26
  27   <figure float="1" id="chapter-clock-img">
  28     <title>&GStreamer; clock and various times</title>
  29     <mediaobject>
  30       <imageobject>
  31         <imagedata scale="75" fileref="images/clocks.&image;" format="&IMAGE;" />
  32       </imageobject>
  33     </mediaobject>
  34   </figure>
  35
  36   <sect1 id="section-clocks-providers">
  37     <title>Clock providers</title>
  38
  39     <para>
  40       Clock providers exist because they play back media at some rate, and
  41       this rate is not necessarily the same as the system clock rate. For
  42       example, a soundcard may playback at 44,1 kHz, but that doesn't mean
  43       that after <emphasis>exactly</emphasis> 1 second <emphasis>according
  44       to the system clock</emphasis>, the soundcard has played back 44.100
  45       samples. This is only true by approximation. Therefore, generally,
  46       pipelines with an audio output use the audiosink as clock provider.
  47       This ensures that one second of video will be played back at the same
  48       rate as that the soundcard plays back 1 second of audio.
  49     </para>
  50     <para>
  51       Whenever some part of the pipeline requires to know the current clock
  52       time, it will be requested from the clock through
  53       <function>gst_clock_get_time ()</function>. The clock-time does not
  54       need to start at 0. The pipeline, which contains the global clock that
  55       all elements in the pipeline will use, in addition has a <quote>base
  56       time</quote>, which is the clock time at the point where the
  57       pipeline went to the PLAYING state. Each element can subtract the
  58       <quote>base time</quote> from the clock-time to know the current
  59       running time.
  60     </para>
  61     <para>
  62       The clock provider is responsible for making sure that the clock time
  63       always represents the current media time as closely as possible; it
  64       has to take care of things such as playback latencies, buffering in
  65       audio-kernel modules, and so on, since all those could affect a/v sync
  66       and thus decrease the user experience.
  67     </para>
  68   </sect1>
  69
  70   <sect1 id="section-clocks-slaves">
  71     <title>Clock slaves</title>
  72     <para>
  73       Clock slaves get assigned a clock by their containing pipeline. Their
  74       task is to make sure that media playback follows the time progress as
  75       represented by this clock as closely as possible. For most elements,
  76       that will simply mean to wait until the buffer running-time is reached
  77       before playing back their current sample.
  78     </para>
  79     <para>
  80       The buffer running-time is derived from the buffer timestamp and the
  81       newsegment event preceeding the buffer. A buffer is played synchronized
  82       with the clock when the clock's running-time has reached exactly the
  83       buffer running-time; this can be done with the function
  84       <function>gst_clock_id_wait ()</function>.
  85     </para>
  86     <para>
  87       For more information on how to write elements that conform to this
  88       required behaviour, see the Plugin Writer's Guide.
  89     </para>
  90   </sect1>
  91 </chapter>