GstPlayer

Starting from GStreamer 1.20, application developers are strongly advised to migrate to GstPlay. GstPlayer will be deprecated in 1.20 and most likely removed by 1.24.

GstPlayer

GObject
    ╰──GInitiallyUnowned
        ╰──GstObject
            ╰──GstPlayer

Class structure

GstPlayerClass


Constructors

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.

This also initializes GStreamer via gst_init() on the first call if this didn't happen before.

Parameters:

video_renderer ( [transfer: full][allow-none])

GstPlayerVideoRenderer to use

signal_dispatcher ( [transfer: full][allow-none])

GstPlayerSignalDispatcher to use

Returns ( [transfer: full])

a new GstPlayer instance


Methods

gst_player_get_audio_video_offset

gint64
gst_player_get_audio_video_offset (GstPlayer * player)

Retrieve the current value of audio-video-offset property

Parameters:

player

GstPlayer instance

Returns

The current value of audio-video-offset in nanoseconds

Since : 1.10


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

Returns

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


gst_player_get_config

GstStructure *
gst_player_get_config (GstPlayer * player)

Get a copy of the current configuration of the player. This configuration can either be modified and used for the gst_player_set_config call or it must be freed after usage.

Parameters:

player

GstPlayer instance

Returns ( [transfer: full])

a copy of the current configuration of player. Use gst_structure_free after usage or gst_player_set_config.

Since : 1.10


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 ( [transfer: full][nullable])

current audio track.

The caller should free it with g_object_unref


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 ( [transfer: full][nullable])

current subtitle track.

The caller should free it with g_object_unref


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 ( [transfer: full][nullable])

current video track.

The caller should free it with g_object_unref


gst_player_get_current_visualization

gchar *
gst_player_get_current_visualization (GstPlayer * player)

Parameters:

player

GstPlayer instance

Returns ( [transfer: full][nullable])

Name of the currently enabled visualization. g_free after usage.


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_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 ( [transfer: full][nullable])

media info instance.

The caller should free it with g_object_unref


gst_player_get_multiview_flags

GstVideoMultiviewFlags
gst_player_get_multiview_flags (GstPlayer * player)

Retrieve the current value of the indicated type.

Parameters:

player

GstPlayer instance

Returns

The current value of type, Default: 0x00000000 "none

Since : 1.10


gst_player_get_multiview_mode

GstVideoMultiviewFramePacking
gst_player_get_multiview_mode (GstPlayer * player)

Retrieve the current value of the indicated type.

Parameters:

player

GstPlayer instance

Returns

The current value of type, Default: -1 "none"

Since : 1.10


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 ( [transfer: full])

The internal playbin instance.

The caller should free it with g_object_unref


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_get_rate

gdouble
gst_player_get_rate (GstPlayer * player)

Parameters:

player

GstPlayer instance

Returns

current playback rate


gst_player_get_subtitle_uri

gchar *
gst_player_get_subtitle_uri (GstPlayer * player)

current subtitle URI

Parameters:

player

GstPlayer instance

Returns ( [transfer: full][nullable])

URI of the current external subtitle. g_free after usage.


gst_player_get_subtitle_video_offset

gint64
gst_player_get_subtitle_video_offset (GstPlayer * player)

Retrieve the current value of subtitle-video-offset property

Parameters:

player

GstPlayer instance

Returns

The current value of subtitle-video-offset in nanoseconds

Since : 1.16


gst_player_get_uri

gchar *
gst_player_get_uri (GstPlayer * player)

Gets the URI of the currently-playing stream.

Parameters:

player

GstPlayer instance

Returns ( [transfer: full][nullable])

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


gst_player_get_video_snapshot

GstSample *
gst_player_get_video_snapshot (GstPlayer * player,
                               GstPlayerSnapshotFormat format,
                               const GstStructure * config)

Get a snapshot of the currently selected video stream, if any. The format can be selected with format and optional configuration is possible with config Currently supported settings are:

  • width, height of type G_TYPE_INT
  • pixel-aspect-ratio of type GST_TYPE_FRACTION Except for GST_PLAYER_THUMBNAIL_RAW_NATIVE format, if no config is set, pixel-aspect-ratio would be 1/1

Parameters:

player

GstPlayer instance

format

output format of the video snapshot

config ( [allow-none])

Additional configuration

Returns ( [transfer: full][nullable])

Current video snapshot sample or NULL on failure

Since : 1.12


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_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_pause

gst_player_pause (GstPlayer * player)

Pauses the current stream.

Parameters:

player

GstPlayer instance


gst_player_play

gst_player_play (GstPlayer * player)

Request to play the loaded stream.

Parameters:

player

GstPlayer instance


gst_player_seek

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_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_audio_track_enabled

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_audio_video_offset

gst_player_set_audio_video_offset (GstPlayer * player,
                                   gint64 offset)

Sets audio-video-offset property by value of offset

Parameters:

player

GstPlayer instance

offset

gint64 in nanoseconds

Since : 1.10


gst_player_set_color_balance

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

value

The new value for the type, ranged [0,1]


gst_player_set_config

gboolean
gst_player_set_config (GstPlayer * player,
                       GstStructure * config)

Set the configuration of the player. If the player is already configured, and the configuration haven't change, this function will return TRUE. If the player is not in the GST_PLAYER_STATE_STOPPED, this method will return FALSE and active configuration will remain.

config is a GstStructure that contains the configuration parameters for the player.

This function takes ownership of config.

Parameters:

player

GstPlayer instance

config ( [transfer: full])

a GstStructure

Returns

TRUE when the configuration could be set.

Since : 1.10


gst_player_set_multiview_flags

gst_player_set_multiview_flags (GstPlayer * player,
                                GstVideoMultiviewFlags flags)

Sets the current value of the indicated mode type to the passed value.

Parameters:

player

GstPlayer instance

flags

The new value for the type

Since : 1.10


gst_player_set_multiview_mode

gst_player_set_multiview_mode (GstPlayer * player,
                               GstVideoMultiviewFramePacking mode)

Sets the current value of the indicated mode type to the passed value.

Parameters:

player

GstPlayer instance

mode

The new value for the type

Since : 1.10


gst_player_set_mute

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_set_rate

gst_player_set_rate (GstPlayer * player,
                     gdouble rate)

Playback at specified rate

Parameters:

player

GstPlayer instance

rate

playback rate


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 stack stream_index.


gst_player_set_subtitle_track_enabled

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

gst_player_set_subtitle_uri (GstPlayer * player,
                             const gchar * uri)

Sets the external subtitle URI. This should be combined with a call to gst_player_set_subtitle_track_enabled(@player, TRUE) so the subtitles are actually rendered.

Parameters:

player

GstPlayer instance

uri ( [nullable])

subtitle URI


gst_player_set_subtitle_video_offset

gst_player_set_subtitle_video_offset (GstPlayer * player,
                                      gint64 offset)

Sets subtitle-video-offset property by value of offset

Parameters:

player

GstPlayer instance

offset

gint64 in nanoseconds

Since : 1.16


gst_player_set_uri

gst_player_set_uri (GstPlayer * player,
                    const gchar * uri)

Sets the next URI to play.

Parameters:

player

GstPlayer instance

uri ( [nullable])

next URI to play.


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_video_track_enabled

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_visualization

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

Parameters:

player

GstPlayer instance

name ( [nullable])

visualization element obtained from gst_player_visualizations_get()

Returns

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


gst_player_set_visualization_enabled

gst_player_set_visualization_enabled (GstPlayer * player,
                                      gboolean enabled)

Enable or disable the visualization.

Parameters:

player

GstPlayer instance

enabled

TRUE or FALSE


gst_player_set_volume

gst_player_set_volume (GstPlayer * player,
                       gdouble val)

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

This volume is a linear factor. For showing the volume in a GUI it might make sense to first convert from a different format. Volume sliders should usually use a cubic volume. See gst_stream_volume_convert_volume.

Parameters:

player

GstPlayer instance

val

the new volume level, as a percentage between 0 and 1


gst_player_stop

gst_player_stop (GstPlayer * player)

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

Parameters:

player

GstPlayer instance


Functions

gst_player_config_get_position_update_interval

guint
gst_player_config_get_position_update_interval (const GstStructure * config)

Parameters:

config

a GstPlayer configuration

Returns

current position update interval in milliseconds

Since : 1.10


gst_player_config_get_seek_accurate

gboolean
gst_player_config_get_seek_accurate (const GstStructure * config)

Parameters:

config

a GstPlayer configuration

Returns

TRUE if accurate seeking is enabled

Since : 1.12


gst_player_config_get_user_agent

gchar *
gst_player_config_get_user_agent (const GstStructure * config)

Return the user agent which has been configured using gst_player_config_set_user_agent if any.

Parameters:

config

a GstPlayer configuration

Returns ( [transfer: full][nullable])

the configured agent, or NULL

Since : 1.10


gst_player_config_set_position_update_interval

gst_player_config_set_position_update_interval (GstStructure * config,
                                                guint interval)

set interval in milliseconds between two position-updated signals. pass 0 to stop updating the position.

Parameters:

config

a GstPlayer configuration

interval

interval in ms

Since : 1.10


gst_player_config_set_seek_accurate

gst_player_config_set_seek_accurate (GstStructure * config,
                                     gboolean accurate)

Enable or disable accurate seeking. When enabled, elements will try harder to seek as accurately as possible to the requested seek position. Generally it will be slower especially for formats that don't have any indexes or timestamp markers in the stream.

If accurate seeking is disabled, elements will seek as close as the request position without slowing down seeking too much.

Accurate seeking is disabled by default.

Parameters:

config

a GstPlayer configuration

accurate

accurate seek or not

Since : 1.12


gst_player_config_set_user_agent

gst_player_config_set_user_agent (GstStructure * config,
                                  const gchar * agent)

Set the user agent to pass to the server if player needs to connect to a server during playback. This is typically used when playing HTTP or RTSP streams.

Parameters:

config

a GstPlayer configuration

agent ( [nullable])

the string to use as user agent

Since : 1.10


gst_player_get_audio_streams

GList *
gst_player_get_audio_streams (const GstPlayerMediaInfo * info)

Parameters:

info

a GstPlayerMediaInfo

Returns ( [transfer: none][element-typeGstPlayerAudioInfo])

A GList of matching GstPlayerAudioInfo.


gst_player_get_subtitle_streams

GList *
gst_player_get_subtitle_streams (const GstPlayerMediaInfo * info)

Parameters:

info

a GstPlayerMediaInfo

Returns ( [transfer: none][element-typeGstPlayerSubtitleInfo])

A GList of matching GstPlayerSubtitleInfo.


gst_player_get_video_streams

GList *
gst_player_get_video_streams (const GstPlayerMediaInfo * info)

Parameters:

info

a GstPlayerMediaInfo

Returns ( [transfer: none][element-typeGstPlayerVideoInfo])

A GList of matching GstPlayerVideoInfo.


gst_player_visualizations_free

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_visualizations_get

GstPlayerVisualization **
gst_player_visualizations_get ()
Returns

(transfer full) (array zero-terminated=1) (element-type GstPlayerVisualization): a NULL terminated array containing all available visualizations. Use gst_player_visualizations_free after usage.


Signals

buffering

buffering_callback (GstPlayer * self,
                    gint object,
                    gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


duration-changed

duration_changed_callback (GstPlayer * self,
                           guint64 object,
                           gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


end-of-stream

end_of_stream_callback (GstPlayer * self,
                        gpointer user_data)

Parameters:

self
No description available
user_data
No description available

Flags: Run Last / No Hooks


error

error_callback (GstPlayer * self,
                GError * object,
                gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


media-info-updated

media_info_updated_callback (GstPlayer * self,
                             GstPlayerMediaInfo * object,
                             gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


mute-changed

mute_changed_callback (GstPlayer * self,
                       gpointer user_data)

Parameters:

self
No description available
user_data
No description available

Flags: Run Last / No Hooks


position-updated

position_updated_callback (GstPlayer * self,
                           guint64 object,
                           gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


seek-done

seek_done_callback (GstPlayer * self,
                    guint64 object,
                    gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


state-changed

state_changed_callback (GstPlayer * self,
                        GstPlayerState * object,
                        gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


uri-loaded

uri_loaded_callback (GstPlayer * self,
                     gchar * object,
                     gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


video-dimensions-changed

video_dimensions_changed_callback (GstPlayer * self,
                                   gint object,
                                   gint p0,
                                   gpointer user_data)

Parameters:

self
No description available
object
No description available
p0
No description available
user_data
No description available

Flags: Run Last / No Hooks


volume-changed

volume_changed_callback (GstPlayer * self,
                         gpointer user_data)

Parameters:

self
No description available
user_data
No description available

Flags: Run Last / No Hooks


warning

warning_callback (GstPlayer * self,
                  GError * object,
                  gpointer user_data)

Parameters:

self
No description available
object
No description available
user_data
No description available

Flags: Run Last / No Hooks


Properties

audio-video-offset

“audio-video-offset” gint64

Flags : Read / Write


current-audio-track

“current-audio-track” GstPlayerAudioInfo *

Flags : Read


current-subtitle-track

“current-subtitle-track” GstPlayerSubtitleInfo *

Flags : Read


current-video-track

“current-video-track” GstPlayerVideoInfo *

Flags : Read


duration

“duration” guint64

Flags : Read


media-info

“media-info” GstPlayerMediaInfo *

Flags : Read


mute

“mute” gboolean

Flags : Read / Write


pipeline

“pipeline” GstElement *

Flags : Read


position

“position” guint64

Flags : Read


rate

“rate” gdouble

Flags : Read / Write


signal-dispatcher

“signal-dispatcher” GstPlayerSignalDispatcher *

Flags : Read / Write / Construct Only


subtitle-video-offset

“subtitle-video-offset” gint64

Flags : Read / Write


suburi

“suburi” gchar *

Flags : Read / Write


uri

“uri” gchar *

Flags : Read / Write


video-multiview-flags

“video-multiview-flags” GstVideoMultiviewFlags *

Flags : Read / Write


video-multiview-mode

“video-multiview-mode” GstVideoMultiviewFramePacking *

Flags : Read / Write


video-renderer

“video-renderer” GstPlayerVideoRenderer *

Flags : Read / Write / Construct Only


volume

“volume” gdouble

Flags : Read / Write


Functions

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 ( [transfer: none])

a string with the name of the color balance type.


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 ( [transfer: none])

a string with the given error.


gst_player_error_quark

GQuark
gst_player_error_quark ()
Returns
No description available

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 ( [transfer: none])

a string with the name of the state.


Function Macros

GST_PLAYER_CAST

#define GST_PLAYER_CAST(obj)        ((GstPlayer*)(obj))

Enumerations

GstPlayerColorBalanceType

Members
GST_PLAYER_COLOR_BALANCE_HUE (3) –

hue or color balance.

GST_PLAYER_COLOR_BALANCE_BRIGHTNESS (0) –

brightness or black level.

GST_PLAYER_COLOR_BALANCE_SATURATION (2) –

color saturation or chroma gain.

GST_PLAYER_COLOR_BALANCE_CONTRAST (1) –

contrast or luma gain.


GstPlayerError

Members
GST_PLAYER_ERROR_FAILED (0) –

generic error.


GstPlayerSnapshotFormat

Members
GST_PLAYER_THUMBNAIL_RAW_NATIVE (0) –
No description available
GST_PLAYER_THUMBNAIL_RAW_xRGB (1) –
No description available
GST_PLAYER_THUMBNAIL_RAW_BGRx (2) –
No description available
GST_PLAYER_THUMBNAIL_JPG (3) –
No description available
GST_PLAYER_THUMBNAIL_PNG (4) –
No description available

GstPlayerState

Members
GST_PLAYER_STATE_STOPPED (0) –

the player is stopped.

GST_PLAYER_STATE_BUFFERING (1) –

the player is buffering.

GST_PLAYER_STATE_PAUSED (2) –

the player is paused.

GST_PLAYER_STATE_PLAYING (3) –

the player is currently playing a stream.


The results of the search are