docs/manual/advanced-position.xml

   1 <chapter id="chapter-queryevents">
   2   <title>Position tracking and seeking</title>
   3
   4   <para>
   5     So far, we've looked at how to create a pipeline to do media processing
   6     and how to make it run ("iterate"). Most application developers will be
   7     interested in providing feedback to the user on media progress. Media
   8     players, for example, will want to show a slider showing the progress in
   9     the song, and usually also a label indicating stream length. Transcoding
  10     applications will want to show a progress bar on how much % of the task
  11     is done. &GStreamer; has built-in support for doing all this using a
  12     concept known as <emphasis>querying</emphasis>. Since seeking is very
  13     similar, it will be discussed here as well. Seeking is done using the
  14     concept of <emphasis>events</emphasis>.
  15   </para>
  16
  17   <sect1 id="section-querying">
  18     <title>Querying: getting the position or length of a stream</title>
  19
  20     <para>
  21       Querying is defined as requesting a specific stream-property related
  22       to progress tracking. This includes getting the length of a stream (if
  23       available) or getting the current position. Those stream properties
  24       can be retrieved in various formats such as time, audio samples, video
  25       frames or bytes. The functions used are <function>gst_element_query
  26       ()</function> and <function>gst_pad_query ()</function>.
  27     </para>
  28
  29     <para>
  30       Obviously, using either of the above-mentioned functions requires the
  31       application to know <emphasis>which</emphasis> element or pad to run
  32       the query on. This is tricky, but there are some good sides to the
  33       story. The good thing is that elements (or, rather, pads - since
  34       <function>gst_element_query ()</function> internally calls
  35       <function>gst_pad_query ()</function>) forward (<quote>dispatch</quote>)
  36       events and queries to peer pads (or elements) if they don't handle it
  37       themselves. The bad side is that some elements (or pads) will handle
  38       events, but not the specific formats that you want, and therefore it
  39       still won't work.
  40     </para>
  41
  42     <para>
  43       Most queries will, fortunately, work fine. Queries are always
  44       dispatched backwards. This means, effectively, that it's easiest to
  45       run the query on your video or audio output element, and it will take
  46       care of dispatching the query to the element that knows the answer
  47       (such as the current position or the media length; usually the demuxer
  48       or decoder).
  49     </para>
  50
  51     <programlisting>
  52 #include &lt;gst/gst.h&gt;
  53
  54 gint
  55 main (gint   argc,
  56       gchar *argv[])
  57 {
  58   GstElement *sink, *pipeline;
  59 [..]
  60
  61   /* run pipeline */
  62   do {
  63     gint64 len, pos;
  64     GstFormat fmt = GST_FORMAT_TIME;
  65
  66     if (gst_element_query (sink, GST_QUERY_POSITION, &amp;fmt, &amp;pos) &amp;&amp;
  67         gst_element_query (sink, GST_QUERY_TOTAL, &amp;fmt, &amp;len)) {
  68       g_print ("Time: %" GST_FORMAT_TIME " / %" GST_FORMAT_TIME "\r",
  69                GST_TIME_ARGS (pos), GST_TIME_ARGS (len));
  70     }
  71   } while (gst_bin_iterate (GST_BIN (pipeline)));
  72
  73 [..]
  74 }
  75     </programlisting>
  76
  77     <para>
  78       If you are having problems with the dispatching behaviour, your best
  79       bet is to manually decide which element to start running the query on.
  80       You can get a list of supported formats and query-types with
  81       <function>gst_element_get_query_types ()</function> and
  82       <function>gst_element_get_formats ()</function>.
  83     </para>
  84   </sect1>
  85
  86   <sect1 id="section-eventsseek">
  87     <title>Events: seeking (and more)</title>
  88
  89     <para>
  90       Events work in a very similar way as queries. Dispatching, for
  91       example, works exactly the same for events (and also has the same
  92       limitations). Although there are more ways in which applications
  93       and elements can interact using events, we will only focus on seeking
  94       here. This is done using the seek-event. A seek-event contains a
  95       seeking offset, a seek method (which indicates relative to what the
  96       offset was given), a seek format (which is the unit of the offset,
  97       e.g. time, audio samples, video frames or bytes) and optionally a
  98       set of seeking-related flags (e.g. whether internal buffers should be
  99       flushed). The behaviour of a seek is also wrapped in the function
 100       <function>gst_element_seek ()</function>.
 101     </para>
 102
 103     <programlisting>
 104 #include &lt;gst/gst.h&gt;
 105
 106 static void
 107 seek_to_time (GstElement *audiosink,
 108               gint64      time_nanonseconds)
 109 {
 110   gst_element_seek (audiosink,
 111                     GST_SEEK_METHOD_SET | GST_FORMAT_TIME |
 112                     GST_SEEK_FLAG_FLUSH, time_nanoseconds);
 113 }
 114     </programlisting>
 115   </sect1>
 116 </chapter>
 117