GstPlay.Play¶

Subclasses:: None

Methods¶

Inherited:: Gst.Object (27), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`config_get_pipeline_dump_in_error_details` (config)
class	`config_get_position_update_interval` (config)
class	`config_get_seek_accurate` (config)
class	`config_get_user_agent` (config)
class	`config_set_pipeline_dump_in_error_details` (config, value)
class	`config_set_position_update_interval` (config, interval)
class	`config_set_seek_accurate` (config, accurate)
class	`config_set_user_agent` (config, agent)
class	`get_audio_streams` (info)
class	`get_subtitle_streams` (info)
class	`get_video_streams` (info)
class	`is_play_message` (msg)
class	`new` (video_renderer)
class	`visualizations_free` (viss)
class	`visualizations_get` ()
	`get_audio_video_offset` ()
	`get_color_balance` (type)
	`get_config` ()
	`get_current_audio_track` ()
	`get_current_subtitle_track` ()
	`get_current_video_track` ()
	`get_current_visualization` ()
	`get_duration` ()
	`get_media_info` ()
	`get_message_bus` ()
	`get_multiview_flags` ()
	`get_multiview_mode` ()
	`get_mute` ()
	`get_pipeline` ()
	`get_position` ()
	`get_rate` ()
	`get_subtitle_uri` ()
	`get_subtitle_video_offset` ()
	`get_uri` ()
	`get_video_snapshot` (format, config)
	`get_volume` ()
	`has_color_balance` ()
	`pause` ()
	`play` ()
	`seek` (position)
	`set_audio_track` (stream_index)
	`set_audio_track_enabled` (enabled)
	`set_audio_track_id` (stream_id)
	`set_audio_video_offset` (offset)
	`set_color_balance` (type, value)
	`set_config` (config)
	`set_multiview_flags` (flags)
	`set_multiview_mode` (mode)
	`set_mute` (val)
	`set_rate` (rate)
	`set_subtitle_track` (stream_index)
	`set_subtitle_track_enabled` (enabled)
	`set_subtitle_track_id` (stream_id)
	`set_subtitle_uri` (uri)
	`set_subtitle_video_offset` (offset)
	`set_track_ids` (audio_stream_id, video_stream_id, subtitle_stream_id)
	`set_uri` (uri)
	`set_video_track` (stream_index)
	`set_video_track_enabled` (enabled)
	`set_video_track_id` (stream_id)
	`set_visualization` (name)
	`set_visualization_enabled` (enabled)
	`set_volume` (val)
	`stop` ()

Virtual Methods¶

Inherited:: Gst.Object (1), GObject.Object (7)

Properties¶

Inherited:: Gst.Object (2)

Name	Type	Flags	Short Description
`audio-video-offset`	`int`	r/w	The synchronisation offset between audio and video in nanoseconds
`current-audio-track`	`GstPlay.PlayAudioInfo`	r	Current audio track information
`current-subtitle-track`	`GstPlay.PlaySubtitleInfo`	r	Current audio subtitle information
`current-video-track`	`GstPlay.PlayVideoInfo`	r	Current video track information
`duration`	`int`	r	Duration
`media-info`	`GstPlay.PlayMediaInfo`	r	Current media information
`mute`	`bool`	r/w	Mute
`pipeline`	`Gst.Element`	r	GStreamer pipeline that is used
`position`	`int`	r	Current Position
`rate`	`float`	r/w	Playback rate
`subtitle-video-offset`	`int`	r/w	The synchronisation offset between text and video in nanoseconds
`suburi`	`str`	r/w	Current Subtitle URI
`uri`	`str`	r/w	Current URI
`video-multiview-flags`	`GstVideo.VideoMultiviewFlags`	r/w	Override details of the multiview frame layout
`video-multiview-mode`	`GstVideo.VideoMultiviewFramePacking`	r/w	Re-interpret a video stream as one of several frame-packed stereoscopic modes.
`video-renderer`	`GstPlay.PlayVideoRenderer`	r/w	Video renderer to use for rendering videos
`volume`	`float`	r/w	Volume

Signals¶

Inherited:: Gst.Object (1), GObject.Object (1)

Fields¶

Inherited:: Gst.Object (1), GObject.Object (1)

Class Details¶

class GstPlay.Play(**kwargs)¶

Bases:: Gst.Object
Abstract:: No
Structure:: GstPlay.PlayClass

The goal of the GstPlay.Play library is to ease the integration of multimedia playback features in applications. Thus, if you need to build a media player from the ground-up, GstPlay.Play provides the features you will most likely need.

An example player is available in gst-examples/playback/player/gst-play/.

Internally the GstPlay.Play makes use of the playbin3 element. The legacy playbin2 can be selected if the GST_PLAY_USE_PLAYBIN3=0 environment variable has been set.

**Important note**: If your application relies on the Gst.Bus to get notifications from GstPlay.Play, you need to add some explicit clean-up code in order to prevent the GstPlay.Play object from leaking. See below for the details. If you use the GstPlay.PlaySignalAdapter, no special clean-up is required.

When the GstPlay.PlaySignalAdapter is not used, the Gst.Bus owned by GstPlay.Play should be set to flushing state before any attempt to drop the last reference of the GstPlay.Play object. An example in C:

``c¶

GstBus *bus = gst_play_get_message_bus (player); gst_bus_set_flushing (bus, TRUE); gst_object_unref (bus); gst_object_unref (player); ``

The messages managed by the player contain a reference to itself, and if the bus watch is just removed together with dropping the player then the bus will simply keep them around forever (and the bus never goes away because the player has a strong reference to it, so there’s a reference cycle as long as there are messages). Setting the bus to flushing state forces it to get rid of its queued messages, thus breaking any possible reference cycle.

New in version 1.20.

classmethod config_get_pipeline_dump_in_error_details(config)¶

Parameters:: config (Gst.Structure) – a GstPlay.Play configuration
Returns:: True if pipeline dumps are included in GstPlay.Play error message details.
Return type:: bool

New in version 1.24.

classmethod config_get_position_update_interval(config)¶

Parameters:: config (Gst.Structure) – a GstPlay.Play configuration
Returns:: current position update interval in milliseconds
Return type:: int

New in version 1.20.

classmethod config_get_seek_accurate(config)¶

Parameters:: config (Gst.Structure) – a GstPlay.Play configuration
Returns:: True if accurate seeking is enabled
Return type:: bool

New in version 1.20.

classmethod config_get_user_agent(config)¶

Parameters:: config (Gst.Structure) – a GstPlay.Play configuration
Returns:: the configured agent, or None
Return type:: str or None

Return the user agent which has been configured using GstPlay.Play.config_set_user_agent() if any.

New in version 1.20.

classmethod config_set_pipeline_dump_in_error_details(config, value)¶

Parameters:

config (Gst.Structure) – a GstPlay.Play configuration
value (bool) – Include pipeline dumps in error details, or not.

When enabled, the error message emitted by GstPlay.Play will include a pipeline dump (in Graphviz DOT format) in the error details Gst.Structure. The field name is pipeline-dump.

This option is disabled by default.

New in version 1.24.

classmethod config_set_position_update_interval(config, interval)¶

Parameters:

config (Gst.Structure) – a GstPlay.Play configuration
interval (int) – interval in ms

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

New in version 1.20.

classmethod config_set_seek_accurate(config, accurate)¶

Parameters:

config (Gst.Structure) – a GstPlay.Play configuration
accurate (bool) – accurate seek or not

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.

New in version 1.20.

classmethod config_set_user_agent(config, agent)¶

Parameters:

config (Gst.Structure) – a GstPlay.Play configuration
agent (str or None) – the string to use as user agent

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

New in version 1.20.

classmethod get_audio_streams(info)¶

Parameters:: info (GstPlay.PlayMediaInfo) – a GstPlay.PlayMediaInfo
Returns:: A GLib.List of matching GstPlay.PlayAudioInfo.
Return type:: [GstPlay.PlayAudioInfo]

New in version 1.20.

classmethod get_subtitle_streams(info)¶

Parameters:: info (GstPlay.PlayMediaInfo) – a GstPlay.PlayMediaInfo
Returns:: A GLib.List of matching GstPlay.PlaySubtitleInfo.
Return type:: [GstPlay.PlaySubtitleInfo]

New in version 1.20.

classmethod get_video_streams(info)¶

Parameters:: info (GstPlay.PlayMediaInfo) – a GstPlay.PlayMediaInfo
Returns:: A GLib.List of matching GstPlay.PlayVideoInfo.
Return type:: [GstPlay.PlayVideoInfo]

New in version 1.20.

classmethod is_play_message(msg)¶

Parameters:: msg (Gst.Message) – A Gst.Message
Returns:: A bool indicating whether the passed message represents a GstPlay.Play message or not.
Return type:: bool

New in version 1.20.

classmethod new(video_renderer)¶

Parameters:: video_renderer (GstPlay.PlayVideoRenderer or None) – GstPlay.PlayVideoRenderer to use
Returns:: a new GstPlay.Play instance
Return type:: GstPlay.Play

Creates a new GstPlay.Play instance.

Video is going to be rendered by video_renderer, or if None 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.

New in version 1.20.

classmethod visualizations_free(viss)¶

Parameters:: viss (GstPlay.PlayVisualization) – a None terminated array of GstPlay.PlayVisualization to free

Frees a None terminated array of GstPlay.PlayVisualization.

New in version 1.20.

classmethod visualizations_get()¶

Returns:: a None terminated array containing all available visualizations. Use GstPlay.Play.visualizations_free() after usage.
Return type:: [GstPlay.PlayVisualization]

New in version 1.20.

get_audio_video_offset()¶

Returns:: The current value of audio-video-offset in nanoseconds
Return type:: int

Retrieve the current value of audio-video-offset property

New in version 1.20.

get_color_balance(type)¶

Parameters:: type (GstPlay.PlayColorBalanceType) – GstPlay.PlayColorBalanceType
Returns:: The current value of type, between [0,1]. In case of error -1 is returned.
Return type:: float

Retrieve the current value of the indicated type.

New in version 1.20.

get_config()¶

Returns:: a copy of the current configuration of self. Use Gst.Structure.free() after usage or GstPlay.Play.set_config().
Return type:: Gst.Structure

Get a copy of the current configuration of the play. This configuration can either be modified and used for the GstPlay.Play.set_config() call or it must be freed after usage.

New in version 1.20.

get_current_audio_track()¶

Returns:

current audio track.

The caller should free it with GObject.Object.unref()

Return type:

GstPlay.PlayAudioInfo or None

A Function to get current audio GstPlay.PlayAudioInfo instance.

New in version 1.20.

get_current_subtitle_track()¶

Returns:

current subtitle track.

The caller should free it with GObject.Object.unref()

Return type:

GstPlay.PlaySubtitleInfo or None

A Function to get current subtitle GstPlay.PlaySubtitleInfo instance.

New in version 1.20.

get_current_video_track()¶

Returns:

current video track.

The caller should free it with GObject.Object.unref()

Return type:

GstPlay.PlayVideoInfo or None

A Function to get current video GstPlay.PlayVideoInfo instance.

New in version 1.20.

get_current_visualization()¶

Returns:: Name of the currently enabled visualization. GLib.free() after usage.
Return type:: str or None

New in version 1.20.

get_duration()¶

Returns:: the duration of the currently-playing media stream, in nanoseconds.
Return type:: int

Retrieves the duration of the media stream that self represents.

New in version 1.20.

get_media_info()¶

Returns:

media info instance.

The caller should free it with GObject.Object.unref()

Return type:

GstPlay.PlayMediaInfo or None

A Function to get the current media info GstPlay.PlayMediaInfo instance.

New in version 1.20.

get_message_bus()¶

Returns:: The play message bus instance
Return type:: Gst.Bus

GstPlay.Play API exposes a Gst.Bus instance which purpose is to provide data structures representing play-internal events in form of Gst.Message s of type Gst.MessageType.APPLICATION.

Each message carries a “play-message” field of type GstPlay.PlayMessage. Further fields of the message data are specific to each possible value of that enumeration.

Applications can consume the messages asynchronously within their own event-loop / UI-thread etc. Note that in case the application does not consume the messages, the bus will accumulate these internally and eventually fill memory. To avoid that, the bus has to be set “flushing”.

New in version 1.20.

get_multiview_flags()¶

Returns:: The current value of type, Default: 0x00000000 “none
Return type:: GstVideo.VideoMultiviewFlags

Retrieve the current value of the indicated type.

New in version 1.20.

get_multiview_mode()¶

Returns:: The current value of type, Default: -1 “none”
Return type:: GstVideo.VideoMultiviewFramePacking

Retrieve the current value of the indicated type.

New in version 1.20.

get_mute()¶

Returns:: True if the currently-playing stream is muted.
Return type:: bool

New in version 1.20.

get_pipeline()¶

Returns:

The internal playbin instance.

The caller should free it with GObject.Object.unref()

Return type:

Gst.Element

New in version 1.20.

get_position()¶

Returns:: the absolute position time, in nanoseconds, of the currently-playing stream.
Return type:: int

New in version 1.20.

get_rate()¶

Returns:: current playback rate
Return type:: float

New in version 1.20.

get_subtitle_uri()¶

Returns:: URI of the current external subtitle. GLib.free() after usage.
Return type:: str or None

Current subtitle URI

New in version 1.20.

get_subtitle_video_offset()¶

Returns:: The current value of subtitle-video-offset in nanoseconds
Return type:: int

Retrieve the current value of subtitle-video-offset property

New in version 1.20.

get_uri()¶

Returns:: a string containing the URI of the currently-playing stream. GLib.free() after usage.
Return type:: str or None

Gets the URI of the currently-playing stream.

New in version 1.20.

get_video_snapshot(format, config)¶

Parameters:

format (GstPlay.PlaySnapshotFormat) – output format of the video snapshot
config (Gst.Structure or None) – Additional configuration

Returns:

Current video snapshot sample or None on failure

Return type:

Gst.Sample or None

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 GObject.TYPE_INT
pixel-aspect-ratio of type GST_TYPE_FRACTION Except for GstPlay.PlaySnapshotFormat.RAW_NATIVE format, if no config is set, pixel-aspect-ratio would be 1/1

New in version 1.20.

get_volume()¶

Returns:: the volume as percentage between 0 and 1.
Return type:: float

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

New in version 1.20.

has_color_balance()¶

Returns:: True if self has color balance support. Otherwise, False.
Return type:: bool

Checks whether the self has color balance support available.

New in version 1.20.

pause()¶: Pauses the current stream.

New in version 1.20.

play()¶: Request to play the loaded stream.

New in version 1.20.

seek(position)¶

Parameters:: position (int) – position to seek in nanoseconds

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

New in version 1.20.

set_audio_track(stream_index)¶

Parameters:

stream_index (int) – stream index

Returns:

True or False

Sets the audio track stream_index.

Return type:

bool

New in version 1.20.

Deprecated since version 1.26: Use GstPlay.Play.set_audio_track_id() instead.

set_audio_track_enabled(enabled)¶

Parameters:: enabled (bool) – True or False

Enable or disable the current audio track.

New in version 1.20.

set_audio_track_id(stream_id)¶

Parameters:

stream_id (str or None) – stream id

Returns:

True or False

Sets the audio track stream_id.

Return type:

bool

New in version 1.26.

set_audio_video_offset(offset)¶

Parameters:: offset (int) – #gint64 in nanoseconds

Sets audio-video-offset property by value of offset

New in version 1.20.

set_color_balance(type, value)¶

Parameters:

type (GstPlay.PlayColorBalanceType) – GstPlay.PlayColorBalanceType
value (float) – The new value for the type, ranged [0,1]

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

New in version 1.20.

set_config(config)¶

Parameters:: config (Gst.Structure) – a Gst.Structure
Returns:: True when the configuration could be set.
Return type:: bool

Set the configuration of the play. If the play is already configured, and the configuration hasn’t changed, this function will return True. If the play is not in the GstPlay.PlayState.STOPPED, this method will return False and active configuration will remain.

config is a Gst.Structure that contains the configuration parameters for the play.

This function takes ownership of config.

New in version 1.20.

set_multiview_flags(flags)¶

Parameters:: flags (GstVideo.VideoMultiviewFlags) – The new value for the type

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

New in version 1.20.

set_multiview_mode(mode)¶

Parameters:: mode (GstVideo.VideoMultiviewFramePacking) – The new value for the type

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

New in version 1.20.

set_mute(val)¶

Parameters:: val (bool) – Mute state the should be set

True if the currently-playing stream should be muted.

New in version 1.20.

set_rate(rate)¶

Parameters:: rate (float) – playback rate

Playback at specified rate

New in version 1.20.

set_subtitle_track(stream_index)¶

Parameters:

stream_index (int) – stream index

Returns:

True or False

Sets the subtitle stack stream_index.

Return type:

bool

New in version 1.20.

Deprecated since version 1.26: Use GstPlay.Play.set_subtitle_track_id() instead.

set_subtitle_track_enabled(enabled)¶

Parameters:: enabled (bool) – True or False

Enable or disable the current subtitle track.

New in version 1.20.

set_subtitle_track_id(stream_id)¶

Parameters:

stream_id (str or None) – stream id

Returns:

True or False

Sets the subtitle track stream_id.

Return type:

bool

New in version 1.26.

set_subtitle_uri(uri)¶

Parameters:: uri (str or None) – subtitle URI

Sets the external subtitle URI. This should be combined with a call to GstPlay.Play.set_subtitle_track_enabled(self, True) so the subtitles are actually rendered.

New in version 1.20.

set_subtitle_video_offset(offset)¶

Parameters:: offset (int) – #gint64 in nanoseconds

Sets subtitle-video-offset property by value of offset

New in version 1.20.

set_track_ids(audio_stream_id, video_stream_id, subtitle_stream_id)¶

Parameters:

audio_stream_id (str or None) – audio stream id
video_stream_id (str or None) – video stream id
subtitle_stream_id (str or None) – subtitle stream id

Returns:

True or False

Sets the selected track stream ids. Setting None as stream id disables the corresponding track.

Return type:

bool

New in version 1.26.

set_uri(uri)¶

Parameters:: uri (str or None) – next URI to play.

Sets the next URI to play.

New in version 1.20.

set_video_track(stream_index)¶

Parameters:

stream_index (int) – stream index

Returns:

True or False

Sets the video track stream_index.

Return type:

bool

New in version 1.20.

Deprecated since version 1.26: Use GstPlay.Play.set_video_track_id() instead.

set_video_track_enabled(enabled)¶

Parameters:: enabled (bool) – True or False

Enable or disable the current video track.

New in version 1.20.

set_video_track_id(stream_id)¶

Parameters:

stream_id (str or None) – stream id

Returns:

True or False

Sets the video track stream_id.

Return type:

bool

New in version 1.26.

set_visualization(name)¶

Parameters:: name (str or None) – visualization element obtained from GstPlay.Play.visualizations_get()
Returns:: True if the visualization was set correctly. Otherwise, False.
Return type:: bool

New in version 1.20.

set_visualization_enabled(enabled)¶

Parameters:: enabled (bool) – True or False

Enable or disable the visualization.

New in version 1.20.

set_volume(val)¶

Parameters:: val (float) – the new volume level, as a percentage between 0 and 1

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

New in version 1.20.

stop()¶: Stops playing the current stream and resets to the first position in the stream.

New in version 1.20.

Property Details¶

GstPlay.Play.props.audio_video_offset¶

Name:: audio-video-offset
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The synchronisation offset between audio and video in nanoseconds

GstPlay.Play.props.current_audio_track¶

Name:: current-audio-track
Type:: GstPlay.PlayAudioInfo
Default Value:: None
Flags:: READABLE

Current audio track information

GstPlay.Play.props.current_subtitle_track¶

Name:: current-subtitle-track
Type:: GstPlay.PlaySubtitleInfo
Default Value:: None
Flags:: READABLE

Current audio subtitle information

GstPlay.Play.props.current_video_track¶

Name:: current-video-track
Type:: GstPlay.PlayVideoInfo
Default Value:: None
Flags:: READABLE

Current video track information

GstPlay.Play.props.duration¶

Name:: duration
Type:: int
Default Value:: 18446744073709551615
Flags:: READABLE

Duration

GstPlay.Play.props.media_info¶

Name:: media-info
Type:: GstPlay.PlayMediaInfo
Default Value:: None
Flags:: READABLE

Current media information

GstPlay.Play.props.mute¶

Name:: mute
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Mute

GstPlay.Play.props.pipeline¶

Name:: pipeline
Type:: Gst.Element
Default Value:: None
Flags:: READABLE

GStreamer pipeline that is used

GstPlay.Play.props.position¶

Name:: position
Type:: int
Default Value:: 18446744073709551615
Flags:: READABLE

Current Position

GstPlay.Play.props.rate¶

Name:: rate
Type:: float
Default Value:: 1.0
Flags:: READABLE, WRITABLE

Playback rate

GstPlay.Play.props.subtitle_video_offset¶

Name:: subtitle-video-offset
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The synchronisation offset between text and video in nanoseconds

GstPlay.Play.props.suburi¶

Name:: suburi
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

Current Subtitle URI

GstPlay.Play.props.uri¶

Name:: uri
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

Current URI

GstPlay.Play.props.video_multiview_flags¶

Name:: video-multiview-flags
Type:: GstVideo.VideoMultiviewFlags
Default Value:: GstVideo.VideoMultiviewFlags.NONE
Flags:: READABLE, WRITABLE

Override details of the multiview frame layout

GstPlay.Play.props.video_multiview_mode¶

Name:: video-multiview-mode
Type:: GstVideo.VideoMultiviewFramePacking
Default Value:: GstVideo.VideoMultiviewFramePacking.NONE
Flags:: READABLE, WRITABLE

Re-interpret a video stream as one of several frame-packed stereoscopic modes.

GstPlay.Play.props.video_renderer¶

Name:: video-renderer
Type:: GstPlay.PlayVideoRenderer
Default Value:: None
Flags:: READABLE, WRITABLE

Video renderer to use for rendering videos

GstPlay.Play.props.volume¶

Name:: volume
Type:: float
Default Value:: 1.0
Flags:: READABLE, WRITABLE

Volume