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