| <chapter id="chapter-clocks"> |
| <title>Clocks in GStreamer</title> |
| |
| <para> |
| To maintain sync in pipeline playback (which is the only case where this |
| really matters), &GStreamer; uses <emphasis>clocks</emphasis>. Clocks |
| are exposed by some elements, whereas other elements are merely clock |
| slaves. The primary task of a clock is to represent the time progress |
| according to the element exposing the clock, based on its own playback |
| rate. If no clock provider is available in a pipeline, the system clock |
| is used instead. |
| </para> |
| |
| <para> |
| &GStreamer; derives several <emphasis>time value</emphasis> from the clock |
| and the playback state. |
| It is important to note, that a <emphasis>clock-time</emphasis> is |
| monotonically rising, but the value itself is not meaningful. |
| Subtracting the <emphasis>base-time</emphasis> yields the |
| <emphasis>running-time</emphasis>. It is the same as the |
| <emphasis>stream-time</emphasis> if one plays from start to end at original |
| rate. The <emphasis>stream-time</emphasis> indicates the position in the |
| media. The <emphasis>running-time</emphasis> is (re-)set to 0 when the |
| pipeline starts to play and also after <emphasis>flushing</emphasis> seeks. |
| </para> |
| |
| <figure float="1" id="chapter-clock-img"> |
| <title>&GStreamer; clock and various times</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata scale="75" fileref="images/clocks.ℑ" format="&IMAGE;" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| |
| <sect1 id="section-clocks-providers"> |
| <title>Clock providers</title> |
| |
| <para> |
| Clock providers exist because they play back media at some rate, and |
| this rate is not necessarily the same as the system clock rate. For |
| example, a soundcard may playback at 44,1 kHz, but that doesn't mean |
| that after <emphasis>exactly</emphasis> 1 second <emphasis>according |
| to the system clock</emphasis>, the soundcard has played back 44.100 |
| samples. This is only true by approximation. Therefore, generally, |
| pipelines with an audio output use the audiosink as clock provider. |
| This ensures that one second of video will be played back at the same |
| rate as that the soundcard plays back 1 second of audio. |
| </para> |
| <para> |
| Whenever some part of the pipeline requires to know the current clock |
| time, it will be requested from the clock through |
| <function>gst_clock_get_time ()</function>. The clock-time does not |
| need to start at 0. The pipeline, which contains the global clock that |
| all elements in the pipeline will use, in addition has a <quote>base |
| time</quote>, which is the clock time at the point where the |
| pipeline went to the PLAYING state. Each element can subtract the |
| <quote>base time</quote> from the clock-time to know the current |
| running time. |
| </para> |
| <para> |
| The clock provider is responsible for making sure that the clock time |
| always represents the current media time as closely as possible; it |
| has to take care of things such as playback latencies, buffering in |
| audio-kernel modules, and so on, since all those could affect a/v sync |
| and thus decrease the user experience. |
| </para> |
| </sect1> |
| |
| <sect1 id="section-clocks-slaves"> |
| <title>Clock slaves</title> |
| <para> |
| Clock slaves get assigned a clock by their containing pipeline. Their |
| task is to make sure that media playback follows the time progress as |
| represented by this clock as closely as possible. For most elements, |
| that will simply mean to wait until the buffer running-time is reached |
| before playing back their current sample. |
| </para> |
| <para> |
| The buffer running-time is derived from the buffer timestamp and the |
| newsegment event preceeding the buffer. A buffer is played synchronized |
| with the clock when the clock's running-time has reached exactly the |
| buffer running-time; this can be done with the function |
| <function>gst_clock_id_wait ()</function>. |
| </para> |
| <para> |
| For more information on how to write elements that conform to this |
| required behaviour, see the Plugin Writer's Guide. |
| </para> |
| </sect1> |
| </chapter> |