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 times from the clock and the playback state.
  16     It is important to note, that a  <emphasis>clock-time</emphasis> is
  17     monotonically rising, but the value itself is not meaningful.
  18     Subtracting the <emphasis>base-time</emphasis> yields the
  19     <emphasis>running-time</emphasis>. It is the same as the
  20     <emphasis>stream-time</emphasis> if one plays from start to end at original
  21     rate. The <emphasis>stream-time</emphasis> indicates the position in the
  22     media.
  23   </para>
  24
  25   <figure float="1" id="chapter-clock-img">
  26     <title>&GStreamer; clock and various times</title>
  27     <mediaobject>
  28       <imageobject>
  29         <imagedata scale="75" fileref="images/clocks.&image;" format="&IMAGE;" />
  30       </imageobject>
  31     </mediaobject>
  32   </figure>
  33
  34   <sect1 id="section-clocks-providers">
  35     <title>Clock providers</title>
  36
  37     <para>
  38       Clock providers exist because they play back media at some rate, and
  39       this rate is not necessarily the same as the system clock rate. For
  40       example, a soundcard may playback at 44,1 kHz, but that doesn't mean
  41       that after <emphasis>exactly</emphasis> 1 second <emphasis>according
  42       to the system clock</emphasis>, the soundcard has played back 44.100
  43       samples. This is only true by approximation. Therefore, generally,
  44       pipelines with an audio output use the audiosink as clock provider.
  45       This ensures that one second of video will be played back at the same
  46       rate as that the soundcard plays back 1 second of audio.
  47     </para>
  48     <para>
  49       Whenever some part of the pipeline requires to know the current clock
  50       time, it will be requested from the clock through
  51       <function>gst_clock_get_time ()</function>. The clock-time does not
  52       need to start at 0. The pipeline, which contains the global clock that
  53       all elements in the pipeline will use, in addition has a <quote>base
  54       time</quote>, which is the clock time at the the point where media time
  55       is starting from zero. This timestamp is subtracted from the clock
  56       time, and that value is returned by <function>_get_time ()</function>.
  57     </para>
  58     <para>
  59       The clock provider is responsible for making sure that the clock time
  60       always represents the current media time as closely as possible; it
  61       has to take care of things such as playback latencies, buffering in
  62       audio-kernel modules, and so on, since all those could affect a/v sync
  63       and thus decrease the user experience.
  64     </para>
  65   </sect1>
  66
  67   <sect1 id="section-clocks-slaves">
  68     <title>Clock slaves</title>
  69     <para>
  70       Clock slaves get assigned a clock by their containing pipeline. Their
  71       task is to make sure that media playback follows the time progress as
  72       represented by this clock as closely as possible. For most elements,
  73       that will simply mean to wait until a certain time is reached before
  74       playing back their current sample; this can be done with the function
  75       <function>gst_clock_id_wait ()</function>. Some elements may need to
  76       support dropping samples too, however.
  77     </para>
  78     <para>
  79       For more information on how to write elements that conform to this
  80       required behaviour, see the Plugin Writer's Guide.
  81     </para>
  82   </sect1>
  83 </chapter>