Clapper.Player¶

Subclasses:: None

Methods¶

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

class	`new` ()
	`add_feature` (feature)
	`get_audio_enabled` ()
	`get_audio_filter` ()
	`get_audio_offset` ()
	`get_audio_sink` ()
	`get_audio_streams` ()
	`get_autoplay` ()
	`get_current_audio_decoder` ()
	`get_current_video_decoder` ()
	`get_mute` ()
	`get_position` ()
	`get_queue` ()
	`get_speed` ()
	`get_state` ()
	`get_subtitle_font_desc` ()
	`get_subtitle_offset` ()
	`get_subtitle_streams` ()
	`get_subtitles_enabled` ()
	`get_video_enabled` ()
	`get_video_filter` ()
	`get_video_sink` ()
	`get_video_streams` ()
	`get_volume` ()
	`pause` ()
	`play` ()
	`seek` (position)
	`seek_custom` (position, method)
	`set_audio_enabled` (enabled)
	`set_audio_filter` (element)
	`set_audio_offset` (offset)
	`set_audio_sink` (element)
	`set_autoplay` (enabled)
	`set_mute` (mute)
	`set_speed` (speed)
	`set_subtitle_font_desc` (font_desc)
	`set_subtitle_offset` (offset)
	`set_subtitles_enabled` (enabled)
	`set_video_enabled` (enabled)
	`set_video_filter` (element)
	`set_video_sink` (element)
	`set_volume` (volume)
	`stop` ()

Virtual Methods¶

Inherited:: Clapper.ThreadedObject (2), Gst.Object (1), GObject.Object (7)

Properties¶

Inherited:: Gst.Object (2)

Name	Type	Flags
`audio-enabled`	`bool`	r/w/en
`audio-filter`	`Gst.Element`	r/w/en
`audio-offset`	`float`	r/w/en
`audio-sink`	`Gst.Element`	r/w/en
`audio-streams`	`Clapper.StreamList`	r/en
`autoplay`	`bool`	r/w/en
`current-audio-decoder`	`Gst.Element`	r/en
`current-video-decoder`	`Gst.Element`	r/en
`mute`	`bool`	r/w/en
`position`	`float`	r/en
`queue`	`Clapper.Queue`	r/en
`speed`	`float`	r/w/en
`state`	`Clapper.PlayerState`	r/en
`subtitle-font-desc`	`str`	r/w/en
`subtitle-offset`	`float`	r/w/en
`subtitle-streams`	`Clapper.StreamList`	r/en
`subtitles-enabled`	`bool`	r/w/en
`video-enabled`	`bool`	r/w/en
`video-filter`	`Gst.Element`	r/w/en
`video-sink`	`Gst.Element`	r/w/en
`video-streams`	`Clapper.StreamList`	r/en
`volume`	`float`	r/w/en

Signals¶

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

Name	Short Description
`error`	These are normal error messages.
`missing-plugin`	A #GStreamer plugin or one of its features needed for playback is missing.
`seek-done`	A seeking operation has finished.
`warning`	These are some usually more minor error messages that should be treated like warnings.

Fields¶

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

Class Details¶

class Clapper.Player(**kwargs)¶

Bases:: Clapper.ThreadedObject
Abstract:: No
Structure:: Clapper.PlayerClass

The media player object used for playback.

Clapper.Player was written in an easy to use way, so no special GStreamer experience is needed to get started with making various playback applications.

Scheduling media for playback is done using a [class`Clapper`.Queue] upon which player operates.

Player uses GStreamer internally and handles playback on a separate thread, while serializing all events/commands between player and the thread it was created upon (usually main app thread). This makes it very easy to integrate with UI toolkits that operate on a single thread like (but not limited to) GTK.

To listen for property changes, you can connect to property “notify” signal.

classmethod new()¶

Returns:: a new Clapper.Player instance.
Return type:: Clapper.Player

Creates a new Clapper.Player instance.

add_feature(feature)¶

Parameters:: feature (Clapper.Feature) – a Clapper.Feature

Add another Clapper.Feature to the player.

get_audio_enabled()¶

Returns:: True if enabled, False otherwise.
Return type:: bool

Get whether audio stream is enabled.

get_audio_filter()¶

Returns:: Gst.Element set as audio filter.
Return type:: Gst.Element

Get Gst.Element used as audio filter.

get_audio_offset()¶

Returns:: the audio stream offset.
Return type:: float

Get the currently set audio stream offset.

The returned value is in seconds as a decimal number.

get_audio_sink()¶

Returns:: Gst.Element set as audio sink.
Return type:: Gst.Element

Get Gst.Element used as audio sink.

get_audio_streams()¶

Returns:: a Clapper.StreamList of audio Clapper.Stream.
Return type:: Clapper.StreamList

Get a list of audio streams within media item.

get_autoplay()¶

Returns:: True if autoplay is enabled, False otherwise.
Return type:: bool

Get the autoplay value.

get_current_audio_decoder()¶

Returns:: Gst.Element currently used as audio decoder.
Return type:: Gst.Element

Get Gst.Element currently used as audio decoder.

get_current_video_decoder()¶

Returns:: Gst.Element currently used as video decoder.
Return type:: Gst.Element

Get Gst.Element currently used as video decoder.

get_mute()¶

Returns:: True if player is muted, False otherwise.
Return type:: bool

Get the mute state of the player.

get_position()¶

Returns:: the position of the player.
Return type:: float

Get the current player playback position.

The returned value is in seconds as a decimal number.

get_queue()¶

Returns:: the Clapper.Queue of the player.
Return type:: Clapper.Queue

Get the Clapper.Queue of the player.

The queue belongs to the player and can be accessed for as long as Clapper.Player object instance it belongs to is alive.

get_speed()¶

Returns:: the playback speed multiplier.
Return type:: float

Get the speed of the player used for playback.

get_state()¶

Returns:: the Clapper.PlayerState of the player.
Return type:: Clapper.PlayerState

Get the current Clapper.PlayerState.

get_subtitle_font_desc()¶

Returns:: the subtitle font description.
Return type:: str

Get the currently set font description used for subtitle stream rendering.

get_subtitle_offset()¶

Returns:: the subtitle stream offset.
Return type:: float

Get the currently set subtitle stream offset.

The returned value is in seconds as a decimal number.

get_subtitle_streams()¶

Returns:: a Clapper.StreamList of subtitle Clapper.Stream.
Return type:: Clapper.StreamList

Get a list of subtitle streams within media item.

get_subtitles_enabled()¶

Returns:: True if enabled, False otherwise.
Return type:: bool

Get whether subtitles are to be shown when available.

get_video_enabled()¶

Returns:: True if enabled, False otherwise.
Return type:: bool

Get whether video stream is enabled.

get_video_filter()¶

Returns:: Gst.Element set as video filter.
Return type:: Gst.Element

Get Gst.Element used as video filter.

get_video_sink()¶

Returns:: Gst.Element set as video sink.
Return type:: Gst.Element

Get Gst.Element used as video sink.

get_video_streams()¶

Returns:: a Clapper.StreamList of video Clapper.Stream.
Return type:: Clapper.StreamList

Get a list of video streams within media item.

get_volume()¶

Returns:: current volume level.
Return type:: float

Get the volume of the player.

pause()¶

Pause the playback of current media item.

This function will queue a request for the underlaying #GStreamer pipeline to go into PAUSED state, thus can also be used on a not yet started video to go into PAUSED state first.

play()¶

Either start or resume the playback of current media item.

This function will queue a request for the underlaying #GStreamer pipeline to go into PLAYING state.

seek(position)¶

Parameters:: position (float) – a decimal number with position to seek to (in seconds)

Request the player to perform a seek operation.

This function will use [enum`Clapper`.PlayerSeekMethod.NORMAL] as a seeking method. If you wish to specify what method to use per seeking request, use [method`Clapper`.Player.seek_custom] instead.

Note that seeking requests are per selected media item. Seeking requests will be ignored if player is stopped. You need to at least call [method`Clapper`.Player.pause] before seeking and then your requested seek will be handled if item could be played.

seek_custom(position, method)¶

Parameters:

position (float) – a decimal number with position to seek to (in seconds)
method (Clapper.PlayerSeekMethod) – a Clapper.PlayerSeekMethod

Request the player to perform a seek operation.

Same as [method`Clapper`.Player.seek], but also allows to specify [enum`Clapper`.PlayerSeekMethod] to use for seek.

set_audio_enabled(enabled)¶

Parameters:: enabled (bool) – whether enabled

Set whether enable audio stream.

set_audio_filter(element)¶

Parameters:: element (Gst.Element or None) – a Gst.Element or None for none.

Set Gst.Element to be used as audio filter.

set_audio_offset(offset)¶

Parameters:: offset (float) – a decimal audio offset (in seconds)

Set synchronisation offset between the audio stream and video.

Positive values make the audio ahead of the video and negative values make the audio go behind the video.

set_audio_sink(element)¶

Parameters:: element (Gst.Element or None) – a Gst.Element or None to use default.

Set Gst.Element to be used as audio sink.

set_autoplay(enabled)¶

Parameters:: enabled (bool) – True to enable autoplay, False otherwise.

Set the autoplay state of the player.

When autoplay is enabled, player will always try to start playback after current media item changes. When disabled current playback state is preserved when changing items.

set_mute(mute)¶

Parameters:: mute (bool) – True if player should be muted, False otherwise.

Set the mute state of the player.

set_speed(speed)¶

Parameters:: speed (float) – the playback speed multiplier.

Set the speed multiplier of the player.

set_subtitle_font_desc(font_desc)¶

Parameters:: font_desc (str) – Font description

Set Pango font description to be used for subtitle stream rendering.

set_subtitle_offset(offset)¶

Parameters:: offset (float) – a decimal subtitle stream offset (in seconds)

Set synchronisation offset between the subtitle stream and video.

Positive values make the subtitles ahead of the video and negative values make the subtitles go behind the video.

set_subtitles_enabled(enabled)¶

Parameters:: enabled (bool) – whether enabled

Set whether subtitles should be shown if any.

set_video_enabled(enabled)¶

Parameters:: enabled (bool) – whether enabled

Set whether enable video stream.

set_video_filter(element)¶

Parameters:: element (Gst.Element or None) – a Gst.Element or None for none.

Set Gst.Element to be used as video filter.

set_video_sink(element)¶

Parameters:: element (Gst.Element or None) – a Gst.Element or None to use default.

Set Gst.Element to be used as video sink.

set_volume(volume)¶

Parameters:: volume (float) – the volume level.

Set the volume of the player.

The value should be within 0 - 2.0 range, where 1.0 is 100% volume and anything above results with an overamplification.

stop()¶

Stop the playback of current media item.

This function will queue a request for the underlaying #GStreamer pipeline to go into READY state.

Signal Details¶

Clapper.Player.signals.error(player, error, debug_info)¶

Signal Name:

error

Flags:

RUN_LAST, NO_RECURSE, NO_HOOKS

Parameters:

player (Clapper.Player) – The object which received the signal
error (GLib.Error) – a GLib.Error
debug_info (str or None) – an additional debug message.

These are normal error messages. Upon emitting this signal, playback will stop due to the error.

Clapper.Player.signals.missing_plugin(player, name, installer_detail)¶

Signal Name:

missing-plugin

Flags:

RUN_LAST, NO_RECURSE, NO_HOOKS

Parameters:

player (Clapper.Player) – The object which received the signal
name (str) – a localised string describing the missing feature, for use in error dialogs and the like.
installer_detail (str or None) – a string containing all the details about the missing element to be passed to an external installer called via either GstPbutils.install_plugins_async() or GstPbutils.install_plugins_sync() function.

A #GStreamer plugin or one of its features needed for playback is missing.

The description and installer_detail can be used to present the user more info about what is missing and prompt him to install it with an external installer.

Clapper.Player.signals.seek_done(player)¶

Signal Name:: seek-done
Flags:: RUN_LAST, NO_RECURSE, NO_HOOKS
Parameters:: player (Clapper.Player) – The object which received the signal

A seeking operation has finished. Player is now at playback position after seek.

Clapper.Player.signals.warning(player, error, debug_info)¶

Signal Name:

warning

Flags:

RUN_LAST, NO_RECURSE, NO_HOOKS

Parameters:

player (Clapper.Player) – The object which received the signal
error (GLib.Error) – a GLib.Error
debug_info (str or None) – an additional debug message.

These are some usually more minor error messages that should be treated like warnings. Should not generally prevent/stop playback.

Property Details¶

Clapper.Player.props.audio_enabled¶

Name:: audio-enabled
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether audio stream is enabled.

Clapper.Player.props.audio_filter¶

Name:: audio-filter
Type:: Gst.Element
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Optional audio filter to use (none by default).

Clapper.Player.props.audio_offset¶

Name:: audio-offset
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Audio stream offset relative to video.

Clapper.Player.props.audio_sink¶

Name:: audio-sink
Type:: Gst.Element
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Audio sink to use (autoaudiosink by default).

Clapper.Player.props.audio_streams¶

Name:: audio-streams
Type:: Clapper.StreamList
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

List of currently available audio streams.

Clapper.Player.props.autoplay¶

Name:: autoplay
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Always try to start playback after media item changes.

Clapper.Player.props.current_audio_decoder¶

Name:: current-audio-decoder
Type:: Gst.Element
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

Currently used audio decoder.

Clapper.Player.props.current_video_decoder¶

Name:: current-video-decoder
Type:: Gst.Element
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

Currently used video decoder.

Clapper.Player.props.mute¶

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

Mute audio without changing volume.

Clapper.Player.props.position¶

Name:: position
Type:: float
Default Value:: 0.0
Flags:: READABLE, EXPLICIT_NOTIFY

Current playback position as a decimal number in seconds.

Clapper.Player.props.queue¶

Name:: queue
Type:: Clapper.Queue
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

Clapper playback queue.

Clapper.Player.props.speed¶

Name:: speed
Type:: float
Default Value:: 1.0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Current playback speed.

Clapper.Player.props.state¶

Name:: state
Type:: Clapper.PlayerState
Default Value:: Clapper.PlayerState.STOPPED
Flags:: READABLE, EXPLICIT_NOTIFY

Current playback state.

Clapper.Player.props.subtitle_font_desc¶

Name:: subtitle-font-desc
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Subtitle stream font description.

Clapper.Player.props.subtitle_offset¶

Name:: subtitle-offset
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Subtitle stream offset relative to video.

Clapper.Player.props.subtitle_streams¶

Name:: subtitle-streams
Type:: Clapper.StreamList
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

List of currently available subtitle streams.

Clapper.Player.props.subtitles_enabled¶

Name:: subtitles-enabled
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether subtitles stream is enabled.

Clapper.Player.props.video_enabled¶

Name:: video-enabled
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether video stream is enabled.

Clapper.Player.props.video_filter¶

Name:: video-filter
Type:: Gst.Element
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Optional video filter to use (none by default).

Clapper.Player.props.video_sink¶

Name:: video-sink
Type:: Gst.Element
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Video sink to use (autovideosink by default).

Clapper.Player.props.video_streams¶

Name:: video-streams
Type:: Clapper.StreamList
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

List of currently available video streams.

Clapper.Player.props.volume¶

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

Current volume as a decimal number (1.0 = 100%).

Note that Clapper.Player uses a CUBIC volume scale, meaning that this property value reflects human hearing level and can be easily bound to volume sliders as-is.