playbin3

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 GstStreamCollection message and GST_EVENT_SELECT_STREAMS event API.

playbin3 can handle both audio and video files and features

• automatic file type recognition and based on that automatic selection and usage of the right audio/video/subtitle demuxers/decoders

• auxiliary files - such as external subtitles and audio tracks

• visualisations for audio files

• subtitle support for video files. Subtitles can be store in external files.

• stream selection between different video/audio/subtitles streams

• meta info (tag) extraction

• easy access to the last video sample

• buffering when playing streams over a network

• volume control with mute option

Usage

A playbin element can be created just like any other element using gst_element_factory_make. The file/URI to play should be set via the uri 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 GstPipeline. It will notify the application of everything that's happening (errors, end of stream, tags found, state changes, etc.) by posting messages on its GstBus. The application needs to watch the bus.

Playback can be initiated by setting the element to PLAYING state using gst_element_set_state. 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 occurred 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 occurred (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 uri property should be set to the new location and then playbin3 be set to PLAYING state again.

Seeking can be done using gst_element_seek_simple or gst_element_seek 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 gst_element_get_state 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 gst_element_query_position and gst_element_query_duration 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.

Selecting streams

The recommended way to select streams (instead of the default selection) is to listen to GST_MESSAGE_STREAM_COLLECTION messages on the GstBus and send a GST_EVENT_SELECT_STREAMS on the pipeline with the selected streams. This provides more information and flexibility compared to the legacy playbin property and signal-based mechanism.

Note: The application should not assume that collections will not change throughout a single file. If it wishes to modify the default selection, it should always respond to new collections posted on the bus with a GST_EVENT_SELECT_STREAMS.

Advanced Usage: specifying the audio and video sink

By default, if no audio sink or video sink has been specified via the audio-sink or video-sink 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 gst_element_factory_make) and provide them to playbin3 using the audio-sink or video-sink property.

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 GstBin and putting elements in there and linking them, and then creating a sink GstGhostPad 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!).

Retrieving Tags and Other Meta Data

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.

Buffering

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:

 switch (GST_MESSAGE_TYPE (msg)) {
   case GST_MESSAGE_BUFFERING: {
     gint percent = 0;
     gst_message_parse_buffering (msg, &percent);
     g_print ("Buffering (%u percent done)", percent);
     break;
   }
   ...
 }

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).

Embedding the video window in your application

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 GstVideoOverlay interface, which most video sinks implement. See the documentation there for more details.

Specifying which CD/DVD device to use

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" 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]

Handling redirects

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.

NOTE: playbin3 (via uridecodebin3) will handle the redirect messages if possible. The message will only be forwarded if it can't handle it.

Examples

 gst-launch-1.0 -v playbin3 uri=file:///path/to/somefile.mp4

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.

 gst-launch-1.0 -v playbin3 uri=cdda://4

This will play back track 4 on an audio CD in your disc drive (assuming the drive is detected automatically by the plugin).

 gst-launch-1.0 -v playbin3 uri=dvd://

This will play back the DVD in your disc drive (assuming the drive is detected automatically by the plugin).