gstplayer

gstplayer — GStreamer Player API

Functions

GstPlayer * gst_player_new ()
GstPlayer * gst_player_new_full ()
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 ()
#define GST_PLAYER_ERROR
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 ()
GstPlayerVisualization ** gst_player_visualizations_get ()
void gst_player_visualizations_free ()
GstPlayerVisualization * gst_player_visualization_copy ()
void gst_player_visualization_free ()
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 ()
GstPlayerSignalDispatcher * gst_player_g_main_context_signal_dispatcher_new ()
GstPlayerVideoRenderer * gst_player_video_overlay_video_renderer_new ()
gpointer gst_player_video_overlay_video_renderer_get_window_handle ()
void gst_player_video_overlay_video_renderer_set_window_handle ()

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

Types and Values

Object Hierarchy

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

Prerequisites

GstPlayerSignalDispatcher requires GObject.

GstPlayerVideoRenderer requires GObject.

Description

Functions

gst_player_new ()

GstPlayer *
gst_player_new (void);

Returns

a new GstPlayer instance


gst_player_new_full ()

GstPlayer *
gst_player_new_full (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

#define      GST_PLAYER_ERROR                         (gst_player_error_quark ())


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_visualizations_get ()

GstPlayerVisualization **
gst_player_visualizations_get (void);

Returns

a NULL terminated array containing all available visualizations. Use gst_player_visualizations_free() after usage.

[transfer full][array zero-terminated=1][element-type GstPlayerVisualization]


gst_player_visualizations_free ()

void
gst_player_visualizations_free (GstPlayerVisualization **viss);

Frees a NULL terminated array of GstPlayerVisualization.

Parameters

viss

a NULL terminated array of GstPlayerVisualization to free

 

gst_player_visualization_copy ()

GstPlayerVisualization *
gst_player_visualization_copy (const GstPlayerVisualization *vis);

Makes a copy of the GstPlayerVisualization. The result must be freed using gst_player_visualization_free().

Parameters

vis

GstPlayerVisualization instance

 

Returns

an allocated copy of vis .

[transfer full]


gst_player_visualization_free ()

void
gst_player_visualization_free (GstPlayerVisualization *vis);

Frees GstPlayerVisualization allocated using g_new() or gst_player_visualization_copy().

Parameters

vis

GstPlayerVisualization instance

 

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

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

 

gst_player_g_main_context_signal_dispatcher_new ()

GstPlayerSignalDispatcher *
gst_player_g_main_context_signal_dispatcher_new
                               (GMainContext *application_context);

Parameters

application_context

GMainContext to use or NULL.

[allow-none]

Returns

.

[transfer full]


gst_player_video_overlay_video_renderer_new ()

GstPlayerVideoRenderer *
gst_player_video_overlay_video_renderer_new
                               (gpointer window_handle);

Parameters

window_handle

Window handle to use or NULL.

[allow-none]

Returns

.

[transfer full]


gst_player_video_overlay_video_renderer_get_window_handle ()

gpointer
gst_player_video_overlay_video_renderer_get_window_handle
                               (GstPlayerVideoOverlayVideoRenderer *self);

Parameters

self

GstPlayerVideoRenderer instance

 

Returns

The currently set, platform specific window handle.

[transfer none]


gst_player_video_overlay_video_renderer_set_window_handle ()

void
gst_player_video_overlay_video_renderer_set_window_handle
                               (GstPlayerVideoOverlayVideoRenderer *self,
                                gpointer window_handle);

Sets the platform specific window handle into which the video should be rendered

Parameters

self

GstPlayerVideoRenderer instance

 

window_handle

handle referencing to the platform specific window

 

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.

 

enum GstPlayerError

Members

GST_PLAYER_ERROR_FAILED

generic error.

 

struct GstPlayerVisualization

struct GstPlayerVisualization {
  gchar *name;
  gchar *description;
};

A GstPlayerVisualization descriptor.

Members

gchar *name;

name of the visualization.

 

gchar *description;

description of the visualization.

 

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,
                    void (*emitter) (gpointer data),
                    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)

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “duration-changed” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “end-of-stream” signal

void
user_function (GstPlayer *gstplayer,
               gpointer   user_data)

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “error” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “media-info-updated” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “mute-changed” signal

void
user_function (GstPlayer *gstplayer,
               gpointer   user_data)

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “position-updated” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “seek-done” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “state-changed” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “video-dimensions-changed” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “volume-changed” signal

void
user_function (GstPlayer *gstplayer,
               gpointer   user_data)

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “warning” signal

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

Parameters

gstplayer

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks