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     syncrhonization mechanism.
   8   </para>
   9
  10   <sect1 id="section-clock-time-types" xreflabel="Types of time">
  11     <title> Types of time </title>
  12
  13     <para>
  14       There are kinds of time in GStreamer. <emphasis
  15         role="strong">Clock time</emphasis> is an absolute time. By contrast,
  16       <emphasis role="strong">element time</emphasis> is the relative time,
  17       usually to the start of the current media stream. The element time
  18       represents the time that should have a media sample that is being
  19       processed by the element at this time. The element time is calculated by
  20       adding an offset to the clock time.
  21     </para>
  22   </sect1>
  23   <sect1 id="section-clocks" xreflabel="Clocks">
  24     <title>Clocks</title>
  25     <para>
  26       GStreamer can use different clocks. Though the system time can be used
  27       as a clock, soundcards and other devices provides a better time source. For
  28       this reason some elements provide a clock. The method
  29       <function>get_clock</function> is implemented in elements that provide
  30       one.
  31     </para>
  32
  33     <para>
  34       As clocks return an absolute measure of time, they are not usually used
  35       directly. Instead, a reference to a clock is stored in any element that needs
  36       it, and it is used internaly by GStreamer to calculate the element time.
  37     </para>
  38   </sect1>
  39
  40   <sect1 id="section-time-data-flow" xreflabel="Flow of data between elements
  41     and time">
  42     <title>
  43       Flow of data between elements and time
  44     </title>
  45     <para>
  46       Now we will see how time information travels the pipeline in different states.
  47     </para>
  48
  49     <para>
  50       The pipeline starts playing.
  51       The source element typically knows the time of each sample.
  52       <footnote>
  53         <para>
  54           Sometimes it
  55           is a parser element the one that knows the time, for instance if a pipeline
  56           contains a filesrc element connected to a MPEG decoder element, the former
  57           is the one that knows the time of each sample, because the knowledge of
  58           when to play each sample is embedded in the MPEG format. In this case this
  59           element will be regarded as the source element for this discussion.
  60         </para>
  61       </footnote>
  62       First, the source element sends a discontinous event. This event carries information
  63       about the current relative time of the next sample. This relative time is
  64       arbitrary, but it must be consistent with the timestamp that will be
  65       placed in buffers. It is expected to be the relative time to the start
  66       of the media stream, or whatever makes sense in the case of each media.
  67       When receiving it, the other elements adjust their offset of the element time so that this
  68       time matches the time written in the event.
  69     </para>
  70
  71     <para>
  72       Then the source element sends media samples in buffers. This element places a
  73       timestamp in each buffer saying when the sample should be played. When the
  74       buffer reachs the sink pad of the last element, this element compares the
  75       current element time with the timestamp of the buffer. If the timestamp is
  76       higher or equal it plays the buffer, otherwise it waits until the time to
  77       place the buffer arrives with <function>gst_element_wait()</function>.
  78     </para>
  79
  80
  81     <para>
  82       If the stream is seeked, the next samples sent will have a timestamp that
  83       is not adjusted with the element time. Therefore, the source element must
  84       send a discontinous event.
  85     </para>
  86   </sect1>
  87   <sect1 id="section-clock-obligations-of-each-element" xreflabel="Obligations
  88     of each element">
  89     <title>
  90       Obligations of each element.
  91     </title>
  92
  93     <para>
  94       Let us clarify the contract between GStreamer and each element in the
  95       pipeline.
  96     </para>
  97
  98     <sect2>
  99       <title>Source elements </title>
 100       <para>
 101         Source elements (or parsers of formats that provide notion of time, such
 102         as MPEG, as explained above). must place a timestamp in each buffer that
 103         they deliver. The origin of the time used is arbitrary, but it must match
 104         the time delivered in the discontinous event (see bellow). However, it is
 105         expected that the origin is the origin of the media stream.
 106       </para>
 107       <para>
 108         In order to initialize the element time of the rest of the pipeline, a
 109         source element must send a discontinous event before starting to play.
 110         In addition, after seeking, a discontinious event must be sent, because
 111         the timestamp of the next element does not match the element time of the
 112         rest of the pipeline.
 113       </para>
 114
 115     </sect2>
 116
 117     <sect2> <title> Sink elements </title>
 118       <para>
 119         If the element is intended to emit samples at a specific time (real time
 120         playing), the element should require a clock, and thus implement the
 121         method <function>set_clock</function>.
 122       </para>
 123
 124       <para>
 125         In addition, before playing each sample, if the current element time is
 126         less than the timestamp in the sample, it wait until the current time
 127         arrives should call <function>gst_element_wait()</function>
 128         <footnote>
 129           <para>
 130             With some schedulers, <function>gst_element_wait()</function>
 131             blocks the pipeline. For instance, if there is one audio sink element
 132             and one video sink element, while the audio element is waiting for a
 133             sample the video element cannot play other sample. This behaviour is
 134             under discussion, and might change in a future release.
 135           </para>
 136         </footnote>
 137         See an example in <xref linkend="other-sink-processing"/>
 138       </para>
 139     </sect2>
 140   </sect1>
 141
 142 </chapter>