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_adaptive_bandwidth` ()
	`get_adaptive_max_bitrate` ()
	`get_adaptive_min_bitrate` ()
	`get_adaptive_start_bitrate` ()
	`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_download_dir` ()
	`get_download_enabled` ()
	`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_adaptive_max_bitrate` (bitrate)
	`set_adaptive_min_bitrate` (bitrate)
	`set_adaptive_start_bitrate` (bitrate)
	`set_audio_enabled` (enabled)
	`set_audio_filter` (element)
	`set_audio_offset` (offset)
	`set_audio_sink` (element)
	`set_autoplay` (enabled)
	`set_download_dir` (path)
	`set_download_enabled` (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
`adaptive-bandwidth`	`int`	r/en
`adaptive-max-bitrate`	`int`	r/w/en
`adaptive-min-bitrate`	`int`	r/w/en
`adaptive-start-bitrate`	`int`	r/w/en
`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
`download-dir`	`str`	r/w/en
`download-enabled`	`bool`	r/w/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
`download-complete`	Media was fully downloaded to local cache directory.
`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_adaptive_bandwidth()¶

Returns:: the adaptive bandwidth.
Return type:: int

Get last fragment download bandwidth (bits/s) during adaptive streaming.

New in version 0.8.

get_adaptive_max_bitrate()¶

Returns:: the maximal bitrate value.
Return type:: int

Get currently set maximal bitrate (bits/s) for adaptive streaming.

New in version 0.8.

get_adaptive_min_bitrate()¶

Returns:: the minimal bitrate value.
Return type:: int

Get currently set minimal bitrate (bits/s) for adaptive streaming.

New in version 0.8.

get_adaptive_start_bitrate()¶

Returns:: the start bitrate value.
Return type:: int

Get currently set initial bitrate (bits/s) for adaptive streaming.

New in version 0.8.

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_download_dir()¶

Returns:: the path of a directory set for media downloads or None if no directory was set yet.
Return type:: str or None

Get path to a directory set for media downloads.

New in version 0.8.

get_download_enabled()¶

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

Get whether progressive download buffering is enabled.

New in version 0.8.

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_adaptive_max_bitrate(bitrate)¶

Parameters:: bitrate (int) – a bitrate to set (bits/s)

Set maximal bitrate to select for adaptive streaming such as DASH or HLS.

New in version 0.8.

set_adaptive_min_bitrate(bitrate)¶

Parameters:: bitrate (int) – a bitrate to set (bits/s)

Set minimal bitrate to select for adaptive streaming such as DASH or HLS.

New in version 0.8.

set_adaptive_start_bitrate(bitrate)¶

Parameters:: bitrate (int) – a bitrate to set (bits/s)

Set initial bitrate to select when starting adaptive streaming such as DASH or HLS.

New in version 0.8.

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_download_dir(path)¶

Parameters:: path (str) – the path of a directory to use for media downloads

Set a directory that self will use to store downloads.

See [property`Clapper`.Player:download-enabled] description for more info how this works.

New in version 0.8.

set_download_enabled(enabled)¶

Parameters:: enabled (bool) – whether enabled

Set whether player should attempt progressive download buffering.

For this to actually work a [property`Clapper`.Player:download-dir] must also be set.

New in version 0.8.

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.download_complete(player, item, location)¶

Signal Name:

download-complete

Flags:

RUN_LAST, NO_RECURSE, NO_HOOKS

Parameters:

player (Clapper.Player) – The object which received the signal
item (Clapper.MediaItem) – a Clapper.MediaItem
location (str) – a path to downloaded file

Media was fully downloaded to local cache directory. This signal will be only emitted when progressive download buffering is enabled by setting [property`Clapper`.Player:download-enabled] property to True.

New in version 0.8.

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.adaptive_bandwidth¶

Name:: adaptive-bandwidth
Type:: int
Default Value:: 0
Flags:: READABLE, EXPLICIT_NOTIFY

Last fragment download bandwidth (bits/s) during adaptive streaming.

This property only changes when adaptive streaming and later stays at the last value until streaming some adaptive content again.

Apps can use this to determine and set an optimal value for [property`Clapper`.Player:adaptive-start-bitrate].

New in version 0.8.

Clapper.Player.props.adaptive_max_bitrate¶

Name:: adaptive-max-bitrate
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

A maximal allowed bitrate (bits/s) during adaptive streaming such as DASH or HLS (0 for unlimited).

Setting this will prevent streaming from entering qualities with higher bandwidth than the one set. When set together with [property`Clapper`.Player:adaptive-min-bitrate] it can be used to enforce some specific quality.

New in version 0.8.

Clapper.Player.props.adaptive_min_bitrate¶

Name:: adaptive-min-bitrate
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

A minimal allowed bitrate (bits/s) during adaptive streaming such as DASH or HLS.

Setting this will prevent streaming from entering lower qualities (even when connection speed cannot keep up). When set together with [property`Clapper`.Player:adaptive-max-bitrate] it can be used to enforce some specific quality.

New in version 0.8.

Clapper.Player.props.adaptive_start_bitrate¶

Name:: adaptive-start-bitrate
Type:: int
Default Value:: 1600000
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

An initial bitrate (bits/s) to select during starting adaptive streaming such as DASH or HLS.

If value is higher than lowest available bitrate in streaming manifest, then lowest possible bitrate will be selected.

New in version 0.8.

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.download_dir¶

Name:: download-dir
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

A directory that player will use to download network content when [property`Clapper`.Player:download-enabled] is set to True.

If directory at path does not exist, it will be automatically created.

New in version 0.8.

Clapper.Player.props.download_enabled¶

Name:: download-enabled
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether progressive download buffering is enabled.

If progressive download is enabled and [property`Clapper`.Player:download-dir] is set, streamed network content will be cached to the disk space instead of memory whenever possible. This allows for faster seeking through currently played media.

Not every type of content is download applicable. Mainly applies to web content that does not use adaptive streaming.

Once data that media item URI points to is fully downloaded, player will emit [signal`Clapper`.Player::download-complete] signal with a location of downloaded file.

Playing again the exact same [class`Clapper`.MediaItem] object that was previously fully downloaded will cause player to automatically use that cached file if it still exists, avoiding any further network requests.

Please note that player will not delete nor manage downloaded content. It is up to application to cleanup data in created cache directory (e.g. before app exits), in order to remove any downloads that app is not going to use next time it is run and incomplete ones.

New in version 0.8.

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.