| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>playbin3: GStreamer Base Plugins 1.0 Plugins Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GStreamer Base Plugins 1.0 Plugins Reference Manual"> |
| <link rel="up" href="ch01.html" title="gst-plugins-base Elements"> |
| <link rel="prev" href="gst-plugins-base-plugins-playbin.html" title="playbin"> |
| <link rel="next" href="gst-plugins-base-plugins-playsink.html" title="playsink"> |
| <meta name="generator" content="GTK-Doc V1.25 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"> |
| <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> |
| <a href="#gst-plugins-base-plugins-playbin3.description" class="shortcut">Description</a></span> |
| </td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <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> |
| <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> |
| </tr></table> |
| <div class="refentry"> |
| <a name="gst-plugins-base-plugins-playbin3"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle"><a name="gst-plugins-base-plugins-playbin3.top_of_page"></a>playbin3</span></h2> |
| <p>playbin3</p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-plugins-playbin3.description"></a><h2>Description</h2> |
| <p>playbin3 provides a stand-alone everything-in-one abstraction for an |
| audio and/or video player. It differs from the previous playbin (playbin2) |
| by supporting publication and selection of available streams via the |
| <a href="/usr/share/gtk-doc/html/gstreamer-1.0gstreamer-GstStreamCollection.html#GstStreamCollection"><span class="type">GstStreamCollection</span></a> message and <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstEvent.html#GST-EVENT-SELECT-STREAMS:CAPS"><span class="type">GST_EVENT_SELECT_STREAMS</span></a> event API.</p> |
| <p><span class="emphasis"><em>playbin3 is still experimental API and a technology preview. |
| Its behaviour and exposed API is subject to change.</em></span></p> |
| <p>playbin3 can handle both audio and video files and features</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"> |
| automatic file type recognition and based on that automatic |
| selection and usage of the right audio/video/subtitle demuxers/decoders |
| </li> |
| <li class="listitem"> |
| auxilliary files - such as external subtitles and audio tracks |
| </li> |
| <li class="listitem"> |
| visualisations for audio files |
| </li> |
| <li class="listitem"> |
| subtitle support for video files. Subtitles can be store in external |
| files. |
| </li> |
| <li class="listitem"> |
| stream selection between different video/audio/subtitles streams |
| </li> |
| <li class="listitem"> |
| meta info (tag) extraction |
| </li> |
| <li class="listitem"> |
| easy access to the last video sample |
| </li> |
| <li class="listitem"> |
| buffering when playing streams over a network |
| </li> |
| <li class="listitem"> |
| volume control with mute option |
| </li> |
| </ul></div> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.6"></a><h3>Usage</h3> |
| <p> |
| A playbin element can be created just like any other element using |
| <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElementFactory.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> |
| property. This must be an absolute URI, relative file paths are not allowed. |
| Example URIs are file:///home/joe/movie.avi or http://www.joedoe.com/foo.ogg |
| |
| Playbin3 is a <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstPipeline.html#GstPipeline-struct"><span class="type">GstPipeline</span></a>. It will notify the application of everything |
| that's happening (errors, end of stream, tags found, state changes, etc.) |
| by posting messages on its <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstBus.html#GstBus-struct"><span class="type">GstBus</span></a>. The application needs to watch the |
| bus. |
| |
| Playback can be initiated by setting the element to PLAYING state using |
| <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElement.html#gst-element-set-state"><code class="function">gst_element_set_state()</code></a>. Note that the state change will take place in |
| the background in a separate thread, when the function returns playback |
| is probably not happening yet and any errors might not have occured yet. |
| Applications using playbin3 should ideally be written to deal with things |
| completely asynchroneous. |
| |
| When playback has finished (an EOS message has been received on the bus) |
| or an error has occured (an ERROR message has been received on the bus) or |
| the user wants to play a different track, playbin3 should be set back to |
| READY or NULL state, then the <span class="type">“uri”</span> property should be set to the |
| new location and then playbin3 be set to PLAYING state again. |
| |
| Seeking can be done using <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElement.html#gst-element-seek-simple"><code class="function">gst_element_seek_simple()</code></a> or <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElement.html#gst-element-seek"><code class="function">gst_element_seek()</code></a> |
| on the playbin3 element. Again, the seek will not be executed |
| instantaneously, but will be done in a background thread. When the seek |
| call returns the seek will most likely still be in process. An application |
| may wait for the seek to finish (or fail) using <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElement.html#gst-element-get-state"><code class="function">gst_element_get_state()</code></a> with |
| -1 as the timeout, but this will block the user interface and is not |
| recommended at all. |
| |
| Applications may query the current position and duration of the stream |
| via <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElement.html#gst-element-query-position"><code class="function">gst_element_query_position()</code></a> and <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElement.html#gst-element-query-duration"><code class="function">gst_element_query_duration()</code></a> and |
| setting the format passed to GST_FORMAT_TIME. If the query was successful, |
| the duration or position will have been returned in units of nanoseconds. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.7"></a><h3>Advanced Usage: specifying the audio and video sink</h3> |
| <p> |
| By default, if no audio sink or video sink has been specified via the |
| <span class="type">“audio-sink”</span> or <span class="type">“video-sink”</span> property, playbin3 will use the autoaudiosink |
| and autovideosink elements to find the first-best available output method. |
| This should work in most cases, but is not always desirable. Often either |
| the user or application might want to specify more explicitly what to use |
| for audio and video output. |
| |
| If the application wants more control over how audio or video should be |
| output, it may create the audio/video sink elements itself (for example |
| using <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstElementFactory.html#gst-element-factory-make"><code class="function">gst_element_factory_make()</code></a>) and provide them to playbin3 using the |
| <span class="type">“audio-sink”</span> or <span class="type">“video-sink”</span> property. |
| |
| GNOME-based applications, for example, will usually want to create |
| gconfaudiosink and gconfvideosink elements and make playbin3 use those, |
| so that output happens to whatever the user has configured in the GNOME |
| Multimedia System Selector configuration dialog. |
| |
| The sink elements do not necessarily need to be ready-made sinks. It is |
| possible to create container elements that look like a sink to playbin3, |
| but in reality contain a number of custom elements linked together. This |
| can be achieved by creating a <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstBin.html#GstBin-struct"><span class="type">GstBin</span></a> and putting elements in there and |
| linking them, and then creating a sink <a href="/usr/share/gtk-doc/html/gstreamer-1.0GstGhostPad.html#GstGhostPad-struct"><span class="type">GstGhostPad</span></a> for the bin and pointing |
| it to the sink pad of the first element within the bin. This can be used |
| for a number of purposes, for example to force output to a particular |
| format or to modify or observe the data before it is output. |
| |
| It is also possible to 'suppress' audio and/or video output by using |
| 'fakesink' elements (or capture it from there using the fakesink element's |
| "handoff" signal, which, nota bene, is fired from the streaming thread!). |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.8"></a><h3>Retrieving Tags and Other Meta Data</h3> |
| <p> |
| Most of the common meta data (artist, title, etc.) can be retrieved by |
| watching for TAG messages on the pipeline's bus (see above). |
| |
| Other more specific meta information like width/height/framerate of video |
| streams or samplerate/number of channels of audio streams can be obtained |
| from the negotiated caps on the sink pads of the sinks. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.9"></a><h3>Buffering</h3> |
| Playbin3 handles buffering automatically for the most part, but applications |
| need to handle parts of the buffering process as well. Whenever playbin3 is |
| buffering, it will post BUFFERING messages on the bus with a percentage |
| value that shows the progress of the buffering process. Applications need |
| to set playbin3 to PLAYING or PAUSED state in response to these messages. |
| They may also want to convey the buffering progress to the user in some |
| way. Here is how to extract the percentage information from the message: |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2 |
| 3 |
| 4 |
| 5 |
| 6 |
| 7 |
| 8 |
| 9</pre></td> |
| <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.0GstMessage.html#GST-MESSAGE-TYPE:CAPS">GST_MESSAGE_TYPE</a></span> <span class="gtkdoc opt">(</span>msg<span class="gtkdoc opt">)) {</span> |
| <span class="keyword">case</span> GST_MESSAGE_BUFFERING<span class="gtkdoc opt">: {</span> |
| gint percent <span class="gtkdoc opt">=</span> <span class="number">0</span><span class="gtkdoc opt">;</span> |
| <span class="function"><a href="/usr/share/gtk-doc/html/gstreamer-1.0GstMessage.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> |
| <span class="function"><a href="/usr/share/gtk-doc/html/glibglib-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> |
| <span class="keyword">break</span><span class="gtkdoc opt">;</span> |
| <span class="gtkdoc opt">}</span> |
| <span class="gtkdoc opt">...</span> |
| <span class="gtkdoc opt">}</span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| Note that applications should keep/set the pipeline in the PAUSED state when |
| a BUFFERING message is received with a buffer percent value < 100 and set |
| the pipeline back to PLAYING state when a BUFFERING message with a value |
| of 100 percent is received (if PLAYING is the desired state, that is). |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.10"></a><h3>Embedding the video window in your application</h3> |
| By default, playbin3 (or rather the video sinks used) will create their own |
| window. Applications will usually want to force output to a window of their |
| own, however. This can be done using the <a href="../html/gst-plugins-base-libs-gstvideooverlay.html#GstVideoOverlay-struct"><span class="type">GstVideoOverlay</span></a> interface, which most |
| video sinks implement. See the documentation there for more details. |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.11"></a><h3>Specifying which CD/DVD device to use</h3> |
| The device to use for CDs/DVDs needs to be set on the source element |
| playbin3 creates before it is opened. The most generic way of doing this |
| is to connect to playbin3's "source-setup" (or "notify::source") signal, |
| which will be emitted by playbin3 when it has created the source element |
| for a particular URI. In the signal callback you can check if the source |
| element has a "device" property and set it appropriately. In some cases |
| the device can also be set as part of the URI, but it depends on the |
| elements involved if this will work or not. For example, for DVD menu |
| playback, the following syntax might work (if the resindvd plugin is used): |
| dvd://[/path/to/device] |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.12"></a><h3>Handling redirects</h3> |
| <p> |
| Some elements may post 'redirect' messages on the bus to tell the |
| application to open another location. These are element messages containing |
| a structure named 'redirect' along with a 'new-location' field of string |
| type. The new location may be a relative or an absolute URI. Examples |
| for such redirects can be found in many quicktime movie trailers. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.13"></a><h3>Examples</h3> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1</pre></td> |
| <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> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| This will play back the given AVI video file, given that the video and |
| audio decoders required to decode the content are installed. Since no |
| special audio sink or video sink is supplied (via playbin3's audio-sink or |
| video-sink properties) playbin3 will try to find a suitable audio and |
| video sink automatically using the autoaudiosink and autovideosink elements. |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1</pre></td> |
| <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> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| This will play back track 4 on an audio CD in your disc drive (assuming |
| the drive is detected automatically by the plugin). |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1</pre></td> |
| <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> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| This will play back the DVD in your disc drive (assuming |
| the drive is detected automatically by the plugin). |
| </div> |
| <div class="refsynopsisdiv"> |
| <h2>Synopsis</h2> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.14.1"></a><h3>Element Information</h3> |
| <div class="variablelist"><table border="0" class="variablelist"> |
| <colgroup> |
| <col align="left" valign="top"> |
| <col> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td><p><span class="term">plugin</span></p></td> |
| <td> |
| <a class="link" href="gst-plugins-base-plugins-plugin-playback.html#plugin-playback">playback</a> |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term">author</span></p></td> |
| <td>Wim Taymans <wim.taymans@gmail.com></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">class</span></p></td> |
| <td>Generic/Bin/Player</td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="id-1.2.34.3.14.2"></a><h3>Element Pads</h3> |
| </div> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-plugins-playbin3.functions_details"></a><h2>Functions</h2> |
| <p></p> |
| </div> |
| <div class="refsect1"> |
| <a name="gst-plugins-base-plugins-playbin3.other_details"></a><h2>Types and Values</h2> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25</div> |
| </body> |
| </html> |
