1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>playbin3: GStreamer Base Plugins 1.0 Plugins Reference Manual</title> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="GStreamer Base Plugins 1.0 Plugins Reference Manual"> 8<link rel="up" href="ch01.html" title="gst-plugins-base Elements"> 9<link rel="prev" href="gst-plugins-base-plugins-playbin.html" title="playbin"> 10<link rel="next" href="gst-plugins-base-plugins-playsink.html" title="playsink"> 11<meta name="generator" content="GTK-Doc V1.28 (XML mode)"> 12<link rel="stylesheet" href="style.css" type="text/css"> 13</head> 14<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 15<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> 16<td width="100%" align="left" class="shortcuts"> 17<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> 18 <a href="#gst-plugins-base-plugins-playbin3.description" class="shortcut">Description</a></span> 19</td> 20<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> 21<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> 22<td><a accesskey="p" href="gst-plugins-base-plugins-playbin.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> 23<td><a accesskey="n" href="gst-plugins-base-plugins-playsink.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> 24</tr></table> 25<div class="refentry"> 26<a name="gst-plugins-base-plugins-playbin3"></a><div class="titlepage"></div> 27<div class="refnamediv"><table width="100%"><tr> 28<td valign="top"> 29<h2><span class="refentrytitle"><a name="gst-plugins-base-plugins-playbin3.top_of_page"></a>playbin3</span></h2> 30<p>playbin3</p> 31</td> 32<td class="gallery_image" valign="top" align="right"></td> 33</tr></table></div> 34<div class="refsect1"> 35<a name="gst-plugins-base-plugins-playbin3.description"></a><h2>Description</h2> 36<p>playbin3 provides a stand-alone everything-in-one abstraction for an 37audio and/or video player. It differs from the previous playbin (playbin2) 38by supporting publication and selection of available streams via the 39<a href="/usr/share/gtk-doc/html/gstreamer-1.0/gstreamer-GstStreamCollection.html#GstStreamCollection"><span class="type">GstStreamCollection</span></a> message and <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstEvent.html#GST-EVENT-SELECT-STREAMS:CAPS"><span class="type">GST_EVENT_SELECT_STREAMS</span></a> event API.</p> 40<p><span class="emphasis"><em>playbin3 is still experimental API and a technology preview. 41Its behaviour and exposed API is subject to change.</em></span></p> 42<p>playbin3 can handle both audio and video files and features</p> 43<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 44<li class="listitem"><p>automatic file type recognition and based on that automatic 45selection and usage of the right audio/video/subtitle demuxers/decoders</p></li> 46<li class="listitem"><p>auxilliary files - such as external subtitles and audio tracks</p></li> 47<li class="listitem"><p>visualisations for audio files</p></li> 48<li class="listitem"><p>subtitle support for video files. Subtitles can be store in external 49files.</p></li> 50<li class="listitem"><p>stream selection between different video/audio/subtitles streams</p></li> 51<li class="listitem"><p>meta info (tag) extraction</p></li> 52<li class="listitem"><p>easy access to the last video sample</p></li> 53<li class="listitem"><p>buffering when playing streams over a network</p></li> 54<li class="listitem"><p>volume control with mute option</p></li> 55</ul></div> 56<div class="refsect3"> 57<a name="id-1.2.84.3.6"></a><h4>Usage</h4> 58<p>A playbin element can be created just like any other element using 59<a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElementFactory.html#gst-element-factory-make"><code class="function">gst_element_factory_make()</code></a>. The file/URI to play should be set via the <span class="type">“uri”</span> 60property. This must be an absolute URI, relative file paths are not allowed. 61Example URIs are file:///home/joe/movie.avi or http://www.joedoe.com/foo.ogg</p> 62<p>Playbin3 is a <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstPipeline.html#GstPipeline-struct"><span class="type">GstPipeline</span></a>. It will notify the application of everything 63that's happening (errors, end of stream, tags found, state changes, etc.) 64by posting messages on its <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstBus.html#GstBus-struct"><span class="type">GstBus</span></a>. The application needs to watch the 65bus.</p> 66<p>Playback can be initiated by setting the element to PLAYING state using 67<a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElement.html#gst-element-set-state"><code class="function">gst_element_set_state()</code></a>. Note that the state change will take place in 68the background in a separate thread, when the function returns playback 69is probably not happening yet and any errors might not have occured yet. 70Applications using playbin3 should ideally be written to deal with things 71completely asynchroneous.</p> 72<p>When playback has finished (an EOS message has been received on the bus) 73or an error has occured (an ERROR message has been received on the bus) or 74the user wants to play a different track, playbin3 should be set back to 75READY or NULL state, then the <span class="type">“uri”</span> property should be set to the 76new location and then playbin3 be set to PLAYING state again.</p> 77<p>Seeking can be done using <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElement.html#gst-element-seek-simple"><code class="function">gst_element_seek_simple()</code></a> or <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElement.html#gst-element-seek"><code class="function">gst_element_seek()</code></a> 78on the playbin3 element. Again, the seek will not be executed 79instantaneously, but will be done in a background thread. When the seek 80call returns the seek will most likely still be in process. An application 81may wait for the seek to finish (or fail) using <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElement.html#gst-element-get-state"><code class="function">gst_element_get_state()</code></a> with 82-1 as the timeout, but this will block the user interface and is not 83recommended at all.</p> 84<p>Applications may query the current position and duration of the stream 85via <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElement.html#gst-element-query-position"><code class="function">gst_element_query_position()</code></a> and <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElement.html#gst-element-query-duration"><code class="function">gst_element_query_duration()</code></a> and 86setting the format passed to GST_FORMAT_TIME. If the query was successful, 87the duration or position will have been returned in units of nanoseconds.</p> 88</div> 89<div class="refsect3"> 90<a name="id-1.2.84.3.7"></a><h4>Advanced Usage: specifying the audio and video sink</h4> 91<p>By default, if no audio sink or video sink has been specified via the 92<span class="type">“audio-sink”</span> or <span class="type">“video-sink”</span> property, playbin3 will use the autoaudiosink 93and autovideosink elements to find the first-best available output method. 94This should work in most cases, but is not always desirable. Often either 95the user or application might want to specify more explicitly what to use 96for audio and video output.</p> 97<p>If the application wants more control over how audio or video should be 98output, it may create the audio/video sink elements itself (for example 99using <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstElementFactory.html#gst-element-factory-make"><code class="function">gst_element_factory_make()</code></a>) and provide them to playbin3 using the 100<span class="type">“audio-sink”</span> or <span class="type">“video-sink”</span> property.</p> 101<p>GNOME-based applications, for example, will usually want to create 102gconfaudiosink and gconfvideosink elements and make playbin3 use those, 103so that output happens to whatever the user has configured in the GNOME 104Multimedia System Selector configuration dialog.</p> 105<p>The sink elements do not necessarily need to be ready-made sinks. It is 106possible to create container elements that look like a sink to playbin3, 107but in reality contain a number of custom elements linked together. This 108can be achieved by creating a <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstBin.html#GstBin-struct"><span class="type">GstBin</span></a> and putting elements in there and 109linking them, and then creating a sink <a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstGhostPad.html#GstGhostPad-struct"><span class="type">GstGhostPad</span></a> for the bin and pointing 110it to the sink pad of the first element within the bin. This can be used 111for a number of purposes, for example to force output to a particular 112format or to modify or observe the data before it is output.</p> 113<p>It is also possible to 'suppress' audio and/or video output by using 114'fakesink' elements (or capture it from there using the fakesink element's 115"handoff" signal, which, nota bene, is fired from the streaming thread!).</p> 116</div> 117<div class="refsect3"> 118<a name="id-1.2.84.3.8"></a><h4>Retrieving Tags and Other Meta Data</h4> 119<p>Most of the common meta data (artist, title, etc.) can be retrieved by 120watching for TAG messages on the pipeline's bus (see above).</p> 121<p>Other more specific meta information like width/height/framerate of video 122streams or samplerate/number of channels of audio streams can be obtained 123from the negotiated caps on the sink pads of the sinks.</p> 124</div> 125<div class="refsect3"> 126<a name="id-1.2.84.3.9"></a><h4>Buffering</h4> 127<p>Playbin3 handles buffering automatically for the most part, but applications 128need to handle parts of the buffering process as well. Whenever playbin3 is 129buffering, it will post BUFFERING messages on the bus with a percentage 130value that shows the progress of the buffering process. Applications need 131to set playbin3 to PLAYING or PAUSED state in response to these messages. 132They may also want to convey the buffering progress to the user in some 133way. Here is how to extract the percentage information from the message:</p> 134<div class="informalexample"> 135 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> 136 <tbody> 137 <tr> 138 <td class="listing_lines" align="right"><pre>1 1392 1403 1414 1425 1436 1447 1458 1469</pre></td> 147 <td class="listing_code"><pre class="programlisting"><span class="keyword">switch</span> <span class="gtkdoc opt">(</span><span class="function"><a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstMessage.html#GST-MESSAGE-TYPE:CAPS">GST_MESSAGE_TYPE</a></span> <span class="gtkdoc opt">(</span>msg<span class="gtkdoc opt">)) {</span> 148 <span class="keyword">case</span> GST_MESSAGE_BUFFERING<span class="gtkdoc opt">: {</span> 149 gint percent <span class="gtkdoc opt">=</span> <span class="number">0</span><span class="gtkdoc opt">;</span> 150 <span class="function"><a href="/usr/share/gtk-doc/html/gstreamer-1.0/GstMessage.html#gst-message-parse-buffering">gst_message_parse_buffering</a></span> <span class="gtkdoc opt">(</span>msg<span class="gtkdoc opt">, &</span>percent<span class="gtkdoc opt">);</span> 151 <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-Warnings-and-Assertions.html#g-print">g_print</a></span> <span class="gtkdoc opt">(</span><span class="string">"Buffering (%u percent done)"</span><span class="gtkdoc opt">,</span> percent<span class="gtkdoc opt">);</span> 152 <span class="keyword">break</span><span class="gtkdoc opt">;</span> 153 <span class="gtkdoc opt">}</span> 154 <span class="gtkdoc opt">...</span> 155<span class="gtkdoc opt">}</span></pre></td> 156 </tr> 157 </tbody> 158 </table> 159</div> 160 161<p></p> 162<p>Note that applications should keep/set the pipeline in the PAUSED state when 163a BUFFERING message is received with a buffer percent value < 100 and set 164the pipeline back to PLAYING state when a BUFFERING message with a value 165of 100 percent is received (if PLAYING is the desired state, that is).</p> 166</div> 167<div class="refsect3"> 168<a name="id-1.2.84.3.10"></a><h4>Embedding the video window in your application</h4> 169<p>By default, playbin3 (or rather the video sinks used) will create their own 170window. Applications will usually want to force output to a window of their 171own, however. This can be done using the <a href="../html/GstVideoOverlay.html#GstVideoOverlay-struct"><span class="type">GstVideoOverlay</span></a> interface, which most 172video sinks implement. See the documentation there for more details.</p> 173</div> 174<div class="refsect3"> 175<a name="id-1.2.84.3.11"></a><h4>Specifying which CD/DVD device to use</h4> 176<p>The device to use for CDs/DVDs needs to be set on the source element playbin3 177creates before it is opened. The most generic way of doing this is to connect 178to playbin3's "source-setup" signal, which will be emitted by playbin3 when 179it has created the source element for a particular URI. In the signal 180callback you can check if the source element has a "device" property and set 181it appropriately. In some cases the device can also be set as part of the 182URI, but it depends on the elements involved if this will work or not. For 183example, for DVD menu playback, the following syntax might work (if the 184resindvd plugin is used): dvd://[/path/to/device]</p> 185</div> 186<div class="refsect3"> 187<a name="id-1.2.84.3.12"></a><h4>Handling redirects</h4> 188<p>Some elements may post 'redirect' messages on the bus to tell the 189application to open another location. These are element messages containing 190a structure named 'redirect' along with a 'new-location' field of string 191type. The new location may be a relative or an absolute URI. Examples 192for such redirects can be found in many quicktime movie trailers.</p> 193</div> 194<div class="refsect3"> 195<a name="id-1.2.84.3.13"></a><h4>Examples</h4> 196<div class="informalexample"> 197 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> 198 <tbody> 199 <tr> 200 <td class="listing_lines" align="right"><pre>1</pre></td> 201 <td class="listing_code"><pre class="programlisting">gst<span class="gtkdoc opt">-</span>launch<span class="gtkdoc opt">-</span><span class="number">1.0</span> <span class="gtkdoc opt">-</span>v playbin3 uri<span class="gtkdoc opt">=</span>file<span class="gtkdoc opt">:</span><span class="gtkdoc slc">///path/to/somefile.mp4</span></pre></td> 202 </tr> 203 </tbody> 204 </table> 205</div> 206 207<p> 208 This will play back the given AVI video file, given that the video and 209audio decoders required to decode the content are installed. Since no 210special audio sink or video sink is supplied (via playbin3's audio-sink or 211video-sink properties) playbin3 will try to find a suitable audio and 212video sink automatically using the autoaudiosink and autovideosink elements.</p> 213<div class="informalexample"> 214 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> 215 <tbody> 216 <tr> 217 <td class="listing_lines" align="right"><pre>1</pre></td> 218 <td class="listing_code"><pre class="programlisting">gst<span class="gtkdoc opt">-</span>launch<span class="gtkdoc opt">-</span><span class="number">1.0</span> <span class="gtkdoc opt">-</span>v playbin3 uri<span class="gtkdoc opt">=</span>cdda<span class="gtkdoc opt">:</span><span class="gtkdoc slc">//4</span></pre></td> 219 </tr> 220 </tbody> 221 </table> 222</div> 223 224<p> 225 This will play back track 4 on an audio CD in your disc drive (assuming 226the drive is detected automatically by the plugin).</p> 227<div class="informalexample"> 228 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> 229 <tbody> 230 <tr> 231 <td class="listing_lines" align="right"><pre>1</pre></td> 232 <td class="listing_code"><pre class="programlisting">gst<span class="gtkdoc opt">-</span>launch<span class="gtkdoc opt">-</span><span class="number">1.0</span> <span class="gtkdoc opt">-</span>v playbin3 uri<span class="gtkdoc opt">=</span>dvd<span class="gtkdoc opt">:</span><span class="gtkdoc slc">//</span></pre></td> 233 </tr> 234 </tbody> 235 </table> 236</div> 237 238<p> 239 This will play back the DVD in your disc drive (assuming 240the drive is detected automatically by the plugin).</p> 241</div> 242<div class="refsynopsisdiv"> 243<h2>Synopsis</h2> 244<div class="refsect2"> 245<a name="id-1.2.84.3.14.1"></a><h3>Element Information</h3> 246<div class="variablelist"><table border="0" class="variablelist"> 247<colgroup> 248<col align="left" valign="top"> 249<col> 250</colgroup> 251<tbody> 252<tr> 253<td><p><span class="term">plugin</span></p></td> 254<td> 255 <a class="link" href="gst-plugins-base-plugins-plugin-playback.html#plugin-playback">playback</a> 256 </td> 257</tr> 258<tr> 259<td><p><span class="term">author</span></p></td> 260<td>Wim Taymans <wim.taymans@gmail.com></td> 261</tr> 262<tr> 263<td><p><span class="term">class</span></p></td> 264<td>Generic/Bin/Player</td> 265</tr> 266</tbody> 267</table></div> 268</div> 269<hr> 270<div class="refsect2"> 271<a name="id-1.2.84.3.14.2"></a><h3>Element Pads</h3> 272</div> 273</div> 274</div> 275<div class="refsect1"> 276<a name="gst-plugins-base-plugins-playbin3.functions_details"></a><h2>Functions</h2> 277<p></p> 278</div> 279<div class="refsect1"> 280<a name="gst-plugins-base-plugins-playbin3.other_details"></a><h2>Types and Values</h2> 281</div> 282</div> 283<div class="footer"> 284<hr>Generated by GTK-Doc V1.28</div> 285</body> 286</html>
