## playbin2

playbin2 — Autoplug and play media from an uri

## Synopsis

    struct              GstPlayBin2;
    enum                GstPlayFlags;

## Object Hierarchy

      GObject
       +----GstObject
             +----GstElement
                   +----GstBin
                         +----GstPipeline
                               +----GstPlayBin2

## Implemented Interfaces

GstPlayBin2 implements GstChildProxy and GstStreamVolume.

## Properties

      "audio-sink"               GstElement*           : Read / Write
      "connection-speed"         guint                 : Read / Write
      "current-audio"            gint                  : Read / Write
      "current-text"             gint                  : Read / Write
      "current-video"            gint                  : Read / Write
      "flags"                    GstPlayFlags          : Read / Write
      "frame"                    GstBuffer*            : Read
      "n-audio"                  gint                  : Read
      "n-text"                   gint                  : Read
      "n-video"                  gint                  : Read
      "source"                   GstElement*           : Read
      "subtitle-encoding"        gchar*                : Read / Write
      "subtitle-font-desc"       gchar*                : Write
      "suburi"                   gchar*                : Read / Write
      "uri"                      gchar*                : Read / Write
      "video-sink"               GstElement*           : Read / Write
      "vis-plugin"               GstElement*           : Read / Write
      "volume"                   gdouble               : Read / Write
      "mute"                     gboolean              : Read / Write
      "buffer-duration"          gint64                : Read / Write
      "buffer-size"              gint                  : Read / Write
      "text-sink"                GstElement*           : Read / Write
      "subpic-sink"              GstElement*           : Read / Write

## Signals

      "about-to-finish"                                : Run Last
      "audio-changed"                                  : Run Last
      "get-audio-tags"                                 : Run Last / Action
      "get-text-tags"                                  : Run Last / Action
      "get-video-tags"                                 : Run Last / Action
      "text-changed"                                   : Run Last
      "video-changed"                                  : Run Last
      "convert-frame"                                  : Run Last / Action
      "get-audio-pad"                                  : Run Last / Action
      "get-text-pad"                                   : Run Last / Action
      "get-video-pad"                                  : Run Last / Action
      "audio-tags-changed"                             : Run Last
      "text-tags-changed"                              : Run Last
      "video-tags-changed"                             : Run Last

## Description

Playbin2 provides a stand-alone everything-in-one abstraction for an audio and/or video player.

At this stage, playbin2 is considered UNSTABLE. The API provided in the signals and properties may yet change in the near future. When playbin2 is stable, it will probably replace playbin

It 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
- 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 frame
- 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

Playbin 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 occured yet. Applications using playbin 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, playbin should be set back to READY or NULL state, then the "uri" property should be set to the new location and then playbin be set to PLAYING state again.

Seeking can be done using `gst_element_seek_simple()` or `gst_element_seek()` on the playbin 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.

### 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, playbin 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 playbin using the "audio-sink" or "video-sink" property.

GNOME-based applications, for example, will usually want to create gconfaudiosink and gconfvideosink elements and make playbin 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 playbin, 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

Playbin handles buffering automatically for the most part, but applications need to handle parts of the buffering process as well. Whenever playbin 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 playbin 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 (requires GStreamer >= 0.10.11):

    1
    2
    3
    4
    5
    6
    7
    8
    9

    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, playbin (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 GstXOverlay 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 playbin creates before it is opened. The only way to do this at the moment is to connect to playbin's "notify::source" signal, which will be emitted by playbin 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 future ways might be added to specify the device as part of the URI, but at the time of writing this is not possible yet.

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

### Examples

    1

    gst-launch -v playbin uri=file:///path/to/somefile.avi

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 (not possible via gst-launch), playbin will try to find a suitable audio and video sink automatically using the autoaudiosink and autovideosink elements.

    1

    gst-launch -v playbin 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).

    1

    gst-launch -v playbin uri=dvd://1

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

## Details

### struct GstPlayBin2

    struct GstPlayBin2;

playbin element structure

### enum GstPlayFlags

    typedef enum {
      GST_PLAY_FLAG_VIDEO         = (1 << 0),
      GST_PLAY_FLAG_AUDIO         = (1 << 1),
      GST_PLAY_FLAG_TEXT          = (1 << 2),
      GST_PLAY_FLAG_VIS           = (1 << 3),
      GST_PLAY_FLAG_SOFT_VOLUME   = (1 << 4),
      GST_PLAY_FLAG_NATIVE_AUDIO  = (1 << 5),
      GST_PLAY_FLAG_NATIVE_VIDEO  = (1 << 6),
      GST_PLAY_FLAG_DOWNLOAD      = (1 << 7),
      GST_PLAY_FLAG_BUFFERING     = (1 << 8)
    } GstPlayFlags;

Extra flags to configure the behaviour of the sinks.

`GST_PLAY_FLAG_VIDEO` | Enable rendering of the video stream
`GST_PLAY_FLAG_AUDIO` | Enable rendering of the audio stream
`GST_PLAY_FLAG_TEXT` | Enable rendering of subtitles
`GST_PLAY_FLAG_VIS` | Enable rendering of visualisations when there is no video stream.
`GST_PLAY_FLAG_SOFT_VOLUME` | Use software volume
`GST_PLAY_FLAG_NATIVE_AUDIO` | only allow native audio formats, this omits configuration of audioconvert and audioresample.
`GST_PLAY_FLAG_NATIVE_VIDEO` | only allow native video formats, this omits configuration of ffmpegcolorspace and videoscale.
`GST_PLAY_FLAG_DOWNLOAD` | enable progressice download buffering for selected formats.
`GST_PLAY_FLAG_BUFFERING` | enable buffering of the demuxed or parsed data.

## Property Details

### The `"audio-sink"` property

      "audio-sink"               GstElement*           : Read / Write

the audio output element to use (NULL = default sink).

### The `"connection-speed"` property

      "connection-speed"         guint                 : Read / Write

Network connection speed in kbps (0 = unknown).

Allowed values: <= 4294967

Default value: 0

### The `"current-audio"` property

      "current-audio"            gint                  : Read / Write

Get or set the currently playing audio stream. By default the first audio stream with data is played.

Allowed values: >= G_MAXULONG

Default value: -1

### The `"current-text"` property

      "current-text"             gint                  : Read / Write

Get or set the currently playing subtitle stream. By default the first subtitle stream with data is played.

Allowed values: >= G_MAXULONG

Default value: -1

### The `"current-video"` property

      "current-video"            gint                  : Read / Write

Get or set the currently playing video stream. By default the first video stream with data is played.

Allowed values: >= G_MAXULONG

Default value: -1

### The `"flags"` property

      "flags"                    GstPlayFlags          : Read / Write

Control the behaviour of playbin.

Default value: Render the video stream|Render the audio stream|Render subtitles|Use software volume

### The `"frame"` property

      "frame"                    GstBuffer*            : Read

Get the currently rendered or prerolled frame in the sink. The GstCaps on the buffer will describe the format of the buffer.

### The `"n-audio"` property

      "n-audio"                  gint                  : Read

Get the total number of available audio streams.

Allowed values: >= 0

Default value: 0

### The `"n-text"` property

      "n-text"                   gint                  : Read

Get the total number of available subtitle streams.

Allowed values: >= 0

Default value: 0

### The `"n-video"` property

      "n-video"                  gint                  : Read

Get the total number of available video streams.

Allowed values: >= 0

Default value: 0

### The `"source"` property

      "source"                   GstElement*           : Read

Source element.

### The `"subtitle-encoding"` property

      "subtitle-encoding"        gchar*                : Read / Write

Encoding to assume if input subtitles are not in UTF-8 encoding. If not set, the GST_SUBTITLE_ENCODING environment variable will be checked for an encoding to use. If that is not set either, ISO-8859-15 will be assumed.

Default value: NULL

### The `"subtitle-font-desc"` property

      "subtitle-font-desc"       gchar*                : Write

Pango font description of font to be used for subtitle rendering.

Default value: NULL

### The `"suburi"` property

      "suburi"                   gchar*                : Read / Write

Set the next subtitle URI that playbin will play. This property can be set from the about-to-finish signal to queue the next subtitle media file.

Default value: NULL

### The `"uri"` property

      "uri"                      gchar*                : Read / Write

Set the next URI that playbin will play. This property can be set from the about-to-finish signal to queue the next media file.

Default value: NULL

### The `"video-sink"` property

      "video-sink"               GstElement*           : Read / Write

the video output element to use (NULL = default sink).

### The `"vis-plugin"` property

      "vis-plugin"               GstElement*           : Read / Write

the visualization element to use (NULL = default).

### The `"volume"` property

      "volume"                   gdouble               : Read / Write

Get or set the current audio stream volume. 1.0 means 100%, 0.0 means mute. This uses a linear volume scale.

Allowed values: [0,10]

Default value: 1

### The `"mute"` property

      "mute"                     gboolean              : Read / Write

Mute the audio channel without changing the volume.

Default value: FALSE

### The `"buffer-duration"` property

      "buffer-duration"          gint64                : Read / Write

Buffer duration when buffering network streams.

Allowed values: >= G_MAXULONG

Default value: -1

### The `"buffer-size"` property

      "buffer-size"              gint                  : Read / Write

Buffer size when buffering network streams.

Allowed values: >= G_MAXULONG

Default value: -1

### The `"text-sink"` property

      "text-sink"                GstElement*           : Read / Write

the text output element to use (NULL = default textoverlay).

### The `"subpic-sink"` property

      "subpic-sink"              GstElement*           : Read / Write

the subpicture output element to use (NULL = default dvdspu).

## Signal Details

### The `"about-to-finish"` signal

    void                user_function                      (GstPlayBin2 *playbin,
                                                            gpointer     user_data)      : Run Last

This signal is emitted when the current uri is about to finish. You can set the uri and suburi to make sure that playback continues.

`playbin` : | a GstPlayBin2
`user_data` : | user data set when the signal handler was connected.

### The `"audio-changed"` signal

    void                user_function                      (GstPlayBin2 *playbin,
                                                            gpointer     user_data)      : Run Last

This signal is emitted whenever the number or order of the audio streams has changed. The application will most likely want to select a new audio stream.

`playbin` : | a GstPlayBin2
`user_data` : | user data set when the signal handler was connected.

### The `"get-audio-tags"` signal

    GstTagList*         user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last / Action

Action signal to retrieve the tags of a specific audio stream number. This information can be used to select a stream.

`playbin` : | a GstPlayBin2
`stream` : | an audio stream number
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstTagList with tags or NULL when the stream number does not exist.

### The `"get-text-tags"` signal

    GstTagList*         user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last / Action

Action signal to retrieve the tags of a specific text stream number. This information can be used to select a stream.

`playbin` : | a GstPlayBin2
`stream` : | a text stream number
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstTagList with tags or NULL when the stream number does not exist.

### The `"get-video-tags"` signal

    GstTagList*         user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last / Action

Action signal to retrieve the tags of a specific video stream number. This information can be used to select a stream.

`playbin` : | a GstPlayBin2
`stream` : | a video stream number
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstTagList with tags or NULL when the stream number does not exist.

### The `"text-changed"` signal

    void                user_function                      (GstPlayBin2 *playbin,
                                                            gpointer     user_data)      : Run Last

This signal is emitted whenever the number or order of the text streams has changed. The application will most likely want to select a new text stream.

`playbin` : | a GstPlayBin2
`user_data` : | user data set when the signal handler was connected.

### The `"video-changed"` signal

    void                user_function                      (GstPlayBin2 *playbin,
                                                            gpointer     user_data)      : Run Last

This signal is emitted whenever the number or order of the video streams has changed. The application will most likely want to select a new video stream.

`playbin` : | a GstPlayBin2
`user_data` : | user data set when the signal handler was connected.

### The `"convert-frame"` signal

    GstBuffer*          user_function                      (GstPlayBin2 *playbin,
                                                            GstCaps     *caps,
                                                            gpointer     user_data)      : Run Last / Action

Action signal to retrieve the currently playing video frame in the format specified by `caps`. If `caps` is `NULL`, no conversion will be performed and this function is equivalent to the "frame" property.

`playbin` : | a GstPlayBin2
`caps` : | the target format of the frame
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstBuffer of the current video frame converted to caps. The caps on the buffer will describe the final layout of the buffer data. `NULL` is returned when no current buffer can be retrieved or when the conversion failed.

### The `"get-audio-pad"` signal

    GstPad*             user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last / Action

Action signal to retrieve the stream-selector sinkpad for a specific audio stream. This pad can be used for notifications of caps changes, stream-specific queries, etc.

`playbin` : | a GstPlayBin2
`stream` : | an audio stream number
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstPad, or NULL when the stream number does not exist.

### The `"get-text-pad"` signal

    GstPad*             user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last / Action

Action signal to retrieve the stream-selector sinkpad for a specific text stream. This pad can be used for notifications of caps changes, stream-specific queries, etc.

`playbin` : | a GstPlayBin2
`stream` : | a text stream number
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstPad, or NULL when the stream number does not exist.

### The `"get-video-pad"` signal

    GstPad*             user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last / Action

Action signal to retrieve the stream-selector sinkpad for a specific video stream. This pad can be used for notifications of caps changes, stream-specific queries, etc.

`playbin` : | a GstPlayBin2
`stream` : | a video stream number
`user_data` : | user data set when the signal handler was connected.
Returns : | a GstPad, or NULL when the stream number does not exist.

### The `"audio-tags-changed"` signal

    void                user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last

This signal is emitted whenever the tags of an audio stream have changed. The application will most likely want to get the new tags.

`playbin` : | a GstPlayBin2
`stream` : | stream index with changed tags
`user_data` : | user data set when the signal handler was connected.

Since 0.10.24

### The `"text-tags-changed"` signal

    void                user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last

This signal is emitted whenever the tags of a text stream have changed. The application will most likely want to get the new tags.

`playbin` : | a GstPlayBin2
`stream` : | stream index with changed tags
`user_data` : | user data set when the signal handler was connected.

Since 0.10.24

### The `"video-tags-changed"` signal

    void                user_function                      (GstPlayBin2 *playbin,
                                                            gint         stream,
                                                            gpointer     user_data)      : Run Last

This signal is emitted whenever the tags of a video stream have changed. The application will most likely want to get the new tags.

`playbin` : | a GstPlayBin2
`stream` : | stream index with changed tags
`user_data` : | user data set when the signal handler was connected.

Since 0.10.24