gstplayer: GStreamer Bad Plugins 1.0 Library Reference Manual

## gstplayer gstplayer — Player |

## Functions

GstPlayer * | gst_player_new ()
void | gst_player_play ()
void | gst_player_pause ()
void | gst_player_stop ()
void | gst_player_seek ()
void | gst_player_set_uri ()
gchar * | gst_player_get_uri ()
GstClockTime | gst_player_get_duration ()
GstClockTime | gst_player_get_position ()
void | gst_player_set_volume ()
void | gst_player_set_mute ()
gdouble | gst_player_get_volume ()
gboolean | gst_player_get_mute ()
GstElement * | gst_player_get_pipeline ()
void | gst_player_set_position_update_interval ()
guint | gst_player_get_position_update_interval ()
const gchar * | gst_player_state_get_name ()
const gchar * | gst_player_error_get_name ()
GstPlayerMediaInfo * | gst_player_get_media_info ()
GList * | gst_player_get_audio_streams ()
GList * | gst_player_get_video_streams ()
GList * | gst_player_get_subtitle_streams ()
gboolean | gst_player_set_audio_track ()
gboolean | gst_player_set_video_track ()
gboolean | gst_player_set_subtitle_track ()
GstPlayerAudioInfo * | gst_player_get_current_audio_track ()
GstPlayerVideoInfo * | gst_player_get_current_video_track ()
GstPlayerSubtitleInfo * | gst_player_get_current_subtitle_track ()
void | gst_player_set_audio_track_enabled ()
void | gst_player_set_video_track_enabled ()
void | gst_player_set_subtitle_track_enabled ()
gboolean | gst_player_set_subtitle_uri ()
gchar * | gst_player_get_subtitle_uri ()
gboolean | gst_player_set_visualization ()
void | gst_player_set_visualization_enabled ()
gchar * | gst_player_get_current_visualization ()
const gchar * | gst_player_color_balance_type_get_name ()
gboolean | gst_player_has_color_balance ()
void | gst_player_set_color_balance ()
gdouble | gst_player_get_color_balance ()
gdouble | gst_player_get_rate ()
void | gst_player_set_rate ()

## Properties

GstPlayerAudioInfo * | current-audio-track | Read
GstPlayerSubtitleInfo * | current-subtitle-track | Read
GstPlayerVideoInfo * | current-video-track | Read
guint64 | duration | Read
GstPlayerMediaInfo * | media-info | Read
gboolean | mute | Read / Write
GstElement * | pipeline | Read
guint64 | position | Read
guint | position-update-interval | Read / Write
gdouble | rate | Read / Write
GstPlayerSignalDispatcher * | signal-dispatcher | Write / Construct Only
gchar * | suburi | Read / Write
gchar * | uri | Read / Write
GstPlayerVideoRenderer * | video-renderer | Write / Construct Only
gdouble | volume | Read / Write

## Signals

void | buffering | No Hooks
void | duration-changed | No Hooks
void | end-of-stream | No Hooks
void | error | No Hooks
void | media-info-updated | No Hooks
void | mute-changed | No Hooks
void | position-updated | No Hooks
void | seek-done | No Hooks
void | state-changed | No Hooks
void | video-dimensions-changed | No Hooks
void | volume-changed | No Hooks
void | warning | No Hooks

## Types and Values

| GstPlayer
enum | GstPlayerState
#define | GST_PLAYER_ERROR
enum | GstPlayerError
enum | GstPlayerColorBalanceType
| GstPlayerSignalDispatcher
struct | GstPlayerSignalDispatcherInterface
| GstPlayerVideoRenderer
struct | GstPlayerVideoRendererInterface

## Object Hierarchy

        GEnum
        ├── GstPlayerColorBalanceType
        ├── GstPlayerError
        ╰── GstPlayerState
        GInterface
        ├── GstPlayerSignalDispatcher
        ╰── GstPlayerVideoRenderer
        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstPlayer

## Prerequisites

GstPlayerSignalDispatcher requires GObject.

GstPlayerVideoRenderer requires GObject.

## Known Implementations

GstPlayerVideoRenderer is implemented by GstPlayerVideoOverlayVideoRenderer.

## Description

## Functions

### gst_player_new ()

    GstPlayer *
    gst_player_new (GstPlayerVideoRenderer *video_renderer,
                    GstPlayerSignalDispatcher *signal_dispatcher);

Creates a new GstPlayer instance that uses `signal_dispatcher` to dispatch signals to some event loop system, or emits signals directly if NULL is passed. See `gst_player_g_main_context_signal_dispatcher_new()`.

Video is going to be rendered by `video_renderer` , or if `NULL` is provided no special video set up will be done and some default handling will be performed.

#### Parameters

video_renderer | GstPlayerVideoRenderer to use. | [transfer full][allow-none]
signal_dispatcher | GstPlayerSignalDispatcher to use. | [transfer full][allow-none]

#### Returns

a new GstPlayer instance

### gst_player_play ()

    void
    gst_player_play (GstPlayer *player);

Request to play the loaded stream.

#### Parameters

player | GstPlayer instance |

### gst_player_pause ()

    void
    gst_player_pause (GstPlayer *player);

Pauses the current stream.

#### Parameters

player | GstPlayer instance |

### gst_player_stop ()

    void
    gst_player_stop (GstPlayer *player);

Stops playing the current stream and resets to the first position in the stream.

#### Parameters

player | GstPlayer instance |

### gst_player_seek ()

    void
    gst_player_seek (GstPlayer *player,
                     GstClockTime position);

Seeks the currently-playing stream to the absolute `position` time in nanoseconds.

#### Parameters

player | GstPlayer instance |
position | position to seek in nanoseconds |

### gst_player_set_uri ()

    void
    gst_player_set_uri (GstPlayer *player,
                        const gchar *uri);

Sets the next URI to play.

#### Parameters

player | GstPlayer instance |
uri | next URI to play. |

### gst_player_get_uri ()

    gchar *
    gst_player_get_uri (GstPlayer *player);

Gets the URI of the currently-playing stream.

#### Parameters

player | GstPlayer instance |

#### Returns

a string containing the URI of the currently-playing stream. `g_free()` after usage.

[transfer full]

### gst_player_get_duration ()

    GstClockTime
    gst_player_get_duration (GstPlayer *player);

Retrieves the duration of the media stream that self represents.

#### Parameters

player | GstPlayer instance |

#### Returns

the duration of the currently-playing media stream, in nanoseconds.

### gst_player_get_position ()

    GstClockTime
    gst_player_get_position (GstPlayer *player);

#### Parameters

player | GstPlayer instance |

#### Returns

the absolute position time, in nanoseconds, of the currently-playing stream.

### gst_player_set_volume ()

    void
    gst_player_set_volume (GstPlayer *player,
                           gdouble val);

Sets the volume level of the stream as a percentage between 0 and 1.

#### Parameters

player | GstPlayer instance |
val | the new volume level, as a percentage between 0 and 1 |

### gst_player_set_mute ()

    void
    gst_player_set_mute (GstPlayer *player,
                         gboolean val);

`TRUE` if the currently-playing stream should be muted.

#### Parameters

player | GstPlayer instance |
val | Mute state the should be set |

### gst_player_get_volume ()

    gdouble
    gst_player_get_volume (GstPlayer *player);

Returns the current volume level, as a percentage between 0 and 1.

#### Parameters

player | GstPlayer instance |

#### Returns

the volume as percentage between 0 and 1.

### gst_player_get_mute ()

    gboolean
    gst_player_get_mute (GstPlayer *player);

#### Parameters

player | GstPlayer instance |

#### Returns

`TRUE` if the currently-playing stream is muted.

### gst_player_get_pipeline ()

    GstElement *
    gst_player_get_pipeline (GstPlayer *player);

#### Parameters

player | GstPlayer instance |

#### Returns

The internal playbin instance.

[transfer full]

### gst_player_set_position_update_interval ()

    void
    gst_player_set_position_update_interval
                                   (GstPlayer *player,
                                    guint interval);

Set interval in milliseconds between two position-updated signals. Pass 0 to stop updating the position.

#### Parameters

player | GstPlayer instance |
interval | interval in ms |

### gst_player_get_position_update_interval ()

    guint
    gst_player_get_position_update_interval
                                   (GstPlayer *player);

#### Parameters

player | GstPlayer instance |

#### Returns

current position update interval in milliseconds

### gst_player_state_get_name ()

    const gchar *
    gst_player_state_get_name (GstPlayerState state);

Gets a string representing the given state.

#### Parameters

state | a GstPlayerState |

#### Returns

a string with the name of the state.

[transfer none]

### gst_player_error_get_name ()

    const gchar *
    gst_player_error_get_name (GstPlayerError error);

Gets a string representing the given error.

#### Parameters

error | a GstPlayerError |

#### Returns

a string with the given error.

[transfer none]

### gst_player_get_media_info ()

    GstPlayerMediaInfo *
    gst_player_get_media_info (GstPlayer *player);

A Function to get the current media info GstPlayerMediaInfo instance.

#### Parameters

player | GstPlayer instance |

#### Returns

media info instance.

The caller should free it with `g_object_unref()`.

[transfer full]

### gst_player_get_audio_streams ()

    GList *
    gst_player_get_audio_streams (const GstPlayerMediaInfo *info);

#### Parameters

info | a GstPlayerMediaInfo |

#### Returns

A GList of matching GstPlayerAudioInfo.

[transfer none][element-type GstPlayerAudioInfo]

### gst_player_get_video_streams ()

    GList *
    gst_player_get_video_streams (const GstPlayerMediaInfo *info);

#### Parameters

info | a GstPlayerMediaInfo |

#### Returns

A GList of matching GstPlayerVideoInfo.

[transfer none][element-type GstPlayerVideoInfo]

### gst_player_get_subtitle_streams ()

    GList *
    gst_player_get_subtitle_streams (const GstPlayerMediaInfo *info);

#### Parameters

info | a GstPlayerMediaInfo |

#### Returns

A GList of matching GstPlayerSubtitleInfo.

[transfer none][element-type GstPlayerSubtitleInfo]

### gst_player_set_audio_track ()

    gboolean
    gst_player_set_audio_track (GstPlayer *player,
                                gint stream_index);

#### Parameters

player | GstPlayer instance |
stream_index | stream index |

#### Returns

`TRUE` or `FALSE`

Sets the audio track `stream_idex` .

### gst_player_set_video_track ()

    gboolean
    gst_player_set_video_track (GstPlayer *player,
                                gint stream_index);

#### Parameters

player | GstPlayer instance |
stream_index | stream index |

#### Returns

`TRUE` or `FALSE`

Sets the video track `stream_index` .

### gst_player_set_subtitle_track ()

    gboolean
    gst_player_set_subtitle_track (GstPlayer *player,
                                   gint stream_index);

#### Parameters

player | GstPlayer instance |
stream_index | stream index |

#### Returns

`TRUE` or `FALSE`

Sets the subtitle strack `stream_index` .

### gst_player_get_current_audio_track ()

    GstPlayerAudioInfo *
    gst_player_get_current_audio_track (GstPlayer *player);

A Function to get current audio GstPlayerAudioInfo instance.

#### Parameters

player | GstPlayer instance |

#### Returns

current audio track.

The caller should free it with `g_object_unref()`.

[transfer full]

### gst_player_get_current_video_track ()

    GstPlayerVideoInfo *
    gst_player_get_current_video_track (GstPlayer *player);

A Function to get current video GstPlayerVideoInfo instance.

#### Parameters

player | GstPlayer instance |

#### Returns

current video track.

The caller should free it with `g_object_unref()`.

[transfer full]

### gst_player_get_current_subtitle_track ()

    GstPlayerSubtitleInfo *
    gst_player_get_current_subtitle_track (GstPlayer *player);

A Function to get current subtitle GstPlayerSubtitleInfo instance.

#### Parameters

player | GstPlayer instance |

#### Returns

current subtitle track.

The caller should free it with `g_object_unref()`.

[transfer none]

### gst_player_set_audio_track_enabled ()

    void
    gst_player_set_audio_track_enabled (GstPlayer *player,
                                        gboolean enabled);

Enable or disable the current audio track.

#### Parameters

player | GstPlayer instance |
enabled | TRUE or FALSE |

### gst_player_set_video_track_enabled ()

    void
    gst_player_set_video_track_enabled (GstPlayer *player,
                                        gboolean enabled);

Enable or disable the current video track.

#### Parameters

player | GstPlayer instance |
enabled | TRUE or FALSE |

### gst_player_set_subtitle_track_enabled ()

    void
    gst_player_set_subtitle_track_enabled (GstPlayer *player,
                                           gboolean enabled);

Enable or disable the current subtitle track.

#### Parameters

player | GstPlayer instance |
enabled | TRUE or FALSE |

### gst_player_set_subtitle_uri ()

    gboolean
    gst_player_set_subtitle_uri (GstPlayer *player,
                                 const gchar *uri);

#### Parameters

player | GstPlayer instance |
uri | subtitle URI |

#### Returns

`TRUE` or `FALSE`

Sets the external subtitle URI.

### gst_player_get_subtitle_uri ()

    gchar *
    gst_player_get_subtitle_uri (GstPlayer *player);

current subtitle URI

#### Parameters

player | GstPlayer instance |

#### Returns

URI of the current external subtitle. `g_free()` after usage.

[transfer full]

### gst_player_set_visualization ()

    gboolean
    gst_player_set_visualization (GstPlayer *player,
                                  const gchar *name);

#### Parameters

player | GstPlayer instance |
name | visualization element obtained from `gst_player_visualizations_get()` |

#### Returns

`TRUE` if the visualizations was set correctly. Otherwise, `FALSE`.

### gst_player_set_visualization_enabled ()

    void
    gst_player_set_visualization_enabled (GstPlayer *player,
                                          gboolean enabled);

Enable or disable the visualization.

#### Parameters

player | GstPlayer instance |
enabled | TRUE or FALSE |

### gst_player_get_current_visualization ()

    gchar *
    gst_player_get_current_visualization (GstPlayer *player);

#### Parameters

player | GstPlayer instance |

#### Returns

Name of the currently enabled visualization. `g_free()` after usage.

[transfer full]

### gst_player_color_balance_type_get_name ()

    const gchar *
    gst_player_color_balance_type_get_name
                                   (GstPlayerColorBalanceType type);

Gets a string representing the given color balance type.

#### Parameters

type | a GstPlayerColorBalanceType |

#### Returns

a string with the name of the color balance type.

[transfer none]

### gst_player_has_color_balance ()

    gboolean
    gst_player_has_color_balance (GstPlayer *player);

Checks whether the `player` has color balance support available.

#### Parameters

player | GstPlayer instance |

#### Returns

`TRUE` if `player` has color balance support. Otherwise, `FALSE`.

### gst_player_set_color_balance ()

    void
    gst_player_set_color_balance (GstPlayer *player,
                                  GstPlayerColorBalanceType type,
                                  gdouble value);

Sets the current value of the indicated channel `type` to the passed value.

#### Parameters

player | GstPlayer instance |
type | GstPlayerColorBalanceType |
value | The new value for the `type` , ranged [0,1] |

### gst_player_get_color_balance ()

    gdouble
    gst_player_get_color_balance (GstPlayer *player,
                                  GstPlayerColorBalanceType type);

Retrieve the current value of the indicated `type` .

#### Parameters

player | GstPlayer instance |
type | GstPlayerColorBalanceType |

#### Returns

The current value of `type` , between [0,1]. In case of error -1 is returned.

### gst_player_get_rate ()

    gdouble
    gst_player_get_rate (GstPlayer *player);

#### Parameters

player | GstPlayer instance |

#### Returns

current playback rate

### gst_player_set_rate ()

    void
    gst_player_set_rate (GstPlayer *player,
                         gdouble rate);

Playback at specified rate

#### Parameters

player | GstPlayer instance |
rate | playback rate |

## Types and Values

### GstPlayer

    typedef struct _GstPlayer GstPlayer;

### enum GstPlayerState

#### Members

GST_PLAYER_STATE_STOPPED | the player is stopped. |
GST_PLAYER_STATE_BUFFERING | the player is buffering. |
GST_PLAYER_STATE_PAUSED | the player is paused. |
GST_PLAYER_STATE_PLAYING | the player is currently playing a stream. |

### GST_PLAYER_ERROR

    #define      GST_PLAYER_ERROR                         (gst_player_error_quark ())

### enum GstPlayerError

#### Members

GST_PLAYER_ERROR_FAILED | generic error. |

### enum GstPlayerColorBalanceType

#### Members

GST_PLAYER_COLOR_BALANCE_BRIGHTNESS | brightness or black level. |
GST_PLAYER_COLOR_BALANCE_CONTRAST | contrast or luma gain. |
GST_PLAYER_COLOR_BALANCE_SATURATION | color saturation or chroma gain. |
GST_PLAYER_COLOR_BALANCE_HUE | hue or color balance. |

### GstPlayerSignalDispatcher

    typedef struct _GstPlayerSignalDispatcher GstPlayerSignalDispatcher;

### struct GstPlayerSignalDispatcherInterface

    struct GstPlayerSignalDispatcherInterface {
      GTypeInterface parent_iface;

      void (*dispatch) (GstPlayerSignalDispatcher * self,
                        GstPlayer * player,
                        GstPlayerSignalDispatcherFunc emitter,
                        gpointer data,
                        GDestroyNotify destroy);
    };

### GstPlayerVideoRenderer

    typedef struct _GstPlayerVideoRenderer GstPlayerVideoRenderer;

### struct GstPlayerVideoRendererInterface

    struct GstPlayerVideoRendererInterface {
      GTypeInterface parent_iface;

      GstElement * (*create_video_sink) (GstPlayerVideoRenderer * self, GstPlayer * player);
    };

## Property Details

### The `“current-audio-track”` property

      “current-audio-track”      GstPlayerAudioInfo *

Current audio track information.

Flags: Read

### The `“current-subtitle-track”` property

      “current-subtitle-track”   GstPlayerSubtitleInfo *

Current audio subtitle information.

Flags: Read

### The `“current-video-track”` property

      “current-video-track”      GstPlayerVideoInfo *

Current video track information.

Flags: Read

### The `“duration”` property

      “duration”                 guint64

Duration.

Flags: Read

Default value: 18446744073709551615

### The `“media-info”` property

      “media-info”               GstPlayerMediaInfo *

Current media information.

Flags: Read

### The `“mute”` property

      “mute”                     gboolean

Mute.

Flags: Read / Write

Default value: FALSE

### The `“pipeline”` property

      “pipeline”                 GstElement *

GStreamer pipeline that is used.

Flags: Read

### The `“position”` property

      “position”                 guint64

Current Position.

Flags: Read

Default value: 18446744073709551615

### The `“position-update-interval”` property

      “position-update-interval” guint

Interval in milliseconds between two position-updated signals.Pass 0 to stop updating the position.

Flags: Read / Write

Allowed values: <= 10000

Default value: 100

### The `“rate”` property

      “rate”                     gdouble

Playback rate.

Flags: Read / Write

Allowed values: [-64,64]

Default value: 1

### The `“signal-dispatcher”` property

      “signal-dispatcher”        GstPlayerSignalDispatcher *

Dispatcher for the signals to e.g. event loops.

Flags: Write / Construct Only

### The `“suburi”` property

      “suburi”                   gchar *

Current Subtitle URI.

Flags: Read / Write

Default value: NULL

### The `“uri”` property

      “uri”                      gchar *

Current URI.

Flags: Read / Write

Default value: NULL

### The `“video-renderer”` property

      “video-renderer”           GstPlayerVideoRenderer *

Video renderer to use for rendering videos.

Flags: Write / Construct Only

### The `“volume”` property

      “volume”                   gdouble

Volume.

Flags: Read / Write

Allowed values: [0,10]

Default value: 1

## Signal Details

### The `“buffering”` signal

    void
    user_function (GstPlayer *gstplayer,
                   gint       arg1,
                   gpointer   user_data)

Flags: No Hooks

### The `“duration-changed”` signal

    void
    user_function (GstPlayer *gstplayer,
                   guint64    arg1,
                   gpointer   user_data)

Flags: No Hooks

### The `“end-of-stream”` signal

    void
    user_function (GstPlayer *gstplayer,
                   gpointer   user_data)

Flags: No Hooks

### The `“error”` signal

    void
    user_function (GstPlayer *gstplayer,
                   GError    *arg1,
                   gpointer   user_data)

Flags: No Hooks

### The `“media-info-updated”` signal

    void
    user_function (GstPlayer          *gstplayer,
                   GstPlayerMediaInfo *arg1,
                   gpointer            user_data)

Flags: No Hooks

### The `“mute-changed”` signal

    void
    user_function (GstPlayer *gstplayer,
                   gpointer   user_data)

Flags: No Hooks

### The `“position-updated”` signal

    void
    user_function (GstPlayer *gstplayer,
                   guint64    arg1,
                   gpointer   user_data)

Flags: No Hooks

### The `“seek-done”` signal

    void
    user_function (GstPlayer *gstplayer,
                   guint64    arg1,
                   gpointer   user_data)

Flags: No Hooks

### The `“state-changed”` signal

    void
    user_function (GstPlayer     *gstplayer,
                   GstPlayerState arg1,
                   gpointer       user_data)

Flags: No Hooks

### The `“video-dimensions-changed”` signal

    void
    user_function (GstPlayer *gstplayer,
                   gint       arg1,
                   gint       arg2,
                   gpointer   user_data)

Flags: No Hooks

### The `“volume-changed”` signal

    void
    user_function (GstPlayer *gstplayer,
                   gpointer   user_data)

Flags: No Hooks

### The `“warning”` signal

    void
    user_function (GstPlayer *gstplayer,
                   GError    *arg1,
                   gpointer   user_data)

Flags: No Hooks