RB.Player¶

Implementations:: None

Methods¶

class	`gst_find_element_with_property` (element, property)
class	`gst_try_audio_sink` (plugin_name, name)
class	`new` (want_crossfade)
	`close` (uri)
	`get_time` ()
	`get_volume` ()
	`multiple_open` ()
	`open` (uri, stream_data, stream_data_destroy)
	`opened` ()
	`pause` ()
	`play` (play_type, crossfade)
	`playing` ()
	`seekable` ()
	`set_time` (newtime)
	`set_volume` (volume)

Virtual Methods¶

	`do_buffering` (stream_data, progress)
	`do_close` (uri)
	`do_eos` (stream_data, early)
	`do_error` (stream_data, error)
	`do_event` (stream_data, data)
	`do_get_time` ()
	`do_get_volume` ()
	`do_image` (stream_data, image)
	`do_info` (stream_data, field, value)
	`do_multiple_open` ()
	`do_open` (uri, stream_data, stream_data_destroy)
	`do_opened` ()
	`do_pause` ()
	`do_play` (play_type, crossfade)
	`do_playing` ()
	`do_playing_stream` (stream_data)
	`do_redirect` (stream_data, uri)
	`do_seekable` ()
	`do_set_time` (newtime)
	`do_set_volume` (volume)
	`do_tick` (stream_data, elapsed, duration)
	`do_volume_changed` (volume)

Properties¶

None

Signals¶

Name	Short Description
`buffering`	The ‘buffering’ signal is emitted while a stream is paused so that a buffer can be filled.
`eos`	The ‘eos’ signal is emitted when a stream finishes, or in some cases, when it is about to finish (with early set to `True`) to allow for a new track to be played immediately afterwards.
`error`	The ‘error’ signal is emitted when an error is encountered while opening or playing a stream.
`event`	The ‘event’ signal provides a means for custom GStreamer elements to communicate events back to the rest of the application.
`image`	The ‘image’ signal is emitted to provide access to images extracted from the stream.
`info`	The ‘info’ signal is emitted when a metadata value is found in the stream.
`playing-stream`	The ‘playing-stream’ signal is emitted when the main playing stream changes.
`redirect`	The ‘redirect’ signal is emitted to indicate when a stream has change URI.
`tick`	The ‘tick’ signal is emitted repeatedly while the stream is playing.
`volume-changed`	The ‘volume-changed’ signal is emitted when the output stream volume is changed externally.

Fields¶

None

Class Details¶

class RB.Player¶

Bases:: GObject.GInterface
Structure:: RB.PlayerIface

This is the interface implemented by the rhythmbox playback backends. It allows the caller to control playback (open, play, pause, close), seek (set_time), control volume (get_volume, set_volume) and receive playback state information (get_time, various signals).

The playback interface allows for multiple streams to be playing (or at least open) concurrently. The caller associates some data with each stream it opens (RB.Player.open), which is included in the paramters with each signal emitted. The caller should not assume that the new stream is playing immediately upon returning from RB.Player.play. Instead, it should use the ‘playing-stream’ signal to determine that.

The player implementation should emit signals for metadata extracted from the stream using the ‘info’ signal

While playing, the player implementation should emit ‘tick’ signals frequently enough to update an elapsed/remaining time display consistently. The duration value included in tick signal emissions is used to prepare the next stream before the current stream reaches EOS, so it should be updated for each emission to account for variable bitrate streams that produce inaccurate duration estimates early on.

When playing a stream from the network, the player can report buffering status using the ‘buffering’ signal. The value included in the signal indicates the percentage of the buffer that has been filled.

The ‘event’ signal can be used to communicate events from the player to the application. For GStreamer-based player implementations, events are triggered by elements in the pipeline posting application messages. The name of the message becomes the name of the event.

classmethod gst_find_element_with_property(element, property)¶

Parameters:

element (Gst.Element) – element to search
property (str) – name of property to search for

Returns:

element instance, or None if not found

Return type:

Gst.Element

Finds an element inside element that has a property with the specified name.

classmethod gst_try_audio_sink(plugin_name, name)¶

Parameters:

plugin_name (str) – audio sink plugin name
name (str) – name to give to the element

Returns:

element instance, or None

Return type:

Gst.Element

Creates and tests an instance of the specified audio sink.

classmethod new(want_crossfade)¶

Parameters:: want_crossfade (bool) – if True, try to use a backend that supports crossfading and other track transitions.
Raises:: GLib.Error
Returns:: new player object.
Return type:: RB.Player

Creates a new player object.

close(uri)¶

Parameters:: uri (str) – optionally, the URI of the stream to close
Raises:: GLib.Error
Returns:: True if a stream was found and closed
Return type:: bool

If a URI is specified, this will close the stream corresponding to that URI and free any resources related resources. If uri is None, this will close all streams.

If no streams remain open after this call, the audio device will be released.

get_time()¶

Returns:: playback position
Return type:: int

Returns the current playback for the current stream in nanoseconds.

get_volume()¶

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

Returns the current volume level, between 0.0 and 1.0.

multiple_open()¶

Returns:: True if multiple open is supported
Return type:: bool

Determines whether the player supports multiple open streams.

open(uri, stream_data, stream_data_destroy)¶

Parameters:

uri (str) – URI to open
stream_data (object or None) – arbitrary data to associate with the stream
stream_data_destroy (GLib.DestroyNotify) – function to call to destroy the stream data

Raises:

GLib.Error

Returns:

True if the stream preparation was not unsuccessful

Return type:

bool

Prepares a stream for playback. Depending on the player implementation, this may stop any existing stream being played. The stream preparation process may continue asynchronously, in which case errors may be reported from RB.Player.play or using the ‘error’ signal.

opened()¶

Returns:: True if a stream is prepared for playback
Return type:: bool

Determines whether a stream has been prepared for playback.

pause()¶: Pauses playback of the most recently started stream. Any streams being faded out may continue until the fade is complete.

play(play_type, crossfade)¶

Parameters:

play_type (RB.PlayerPlayType) – requested playback start type
crossfade (int) – requested crossfade duration (nanoseconds)

Raises:

GLib.Error

Returns:

True if playback started successfully

Return type:

bool

Starts playback of the most recently opened stream. if play_type is RB.PlayerPlayType.CROSSFADE, the player may attempt to crossfade the new stream with any existing streams. If it does this, the it will use crossfade as the duration of the fade.

If play_type is RB.PlayerPlayType.START_AFTER_EOS, the player may attempt to start the stream immediately after the current playing stream reaches EOS. This may or may not result in the phenomemon known as ‘gapless playback’.

If play_type is RB.PlayerPlayType.REPLACE, the player will stop any existing stream before starting the new stream. It may do this anyway, regardless of the value of play_type.

The ‘playing-stream’ signal will be emitted when the new stream is actually playing. This may be before or after control returns to the caller.

playing()¶

Returns:: True if playing
Return type:: bool

Determines whether the player is currently playing a stream. A stream is playing if it’s not paused or being faded out.

seekable()¶

Returns:: True if the current stream is seekable
Return type:: bool

Determines whether seeking is supported for the current stream.

set_time(newtime)¶

Parameters:: newtime (int) – seek target position in seconds

Attempts to seek in the current stream. The player may ignore this if the stream is not seekable. The seek may take place asynchronously.

set_volume(volume)¶

Parameters:: volume (float) – new output volume level

Adjusts the output volume level. This affects all streams. The player may use a hardware volume control to implement this volume adjustment.

do_buffering(stream_data, progress) virtual¶

Parameters:

stream_data (object or None) –
progress (int) –

do_close(uri) virtual¶

Parameters:: uri (str) – optionally, the URI of the stream to close
Returns:: True if a stream was found and closed
Return type:: bool

If a URI is specified, this will close the stream corresponding to that URI and free any resources related resources. If uri is None, this will close all streams.

If no streams remain open after this call, the audio device will be released.

do_eos(stream_data, early) virtual¶

Parameters:

stream_data (object or None) –
early (bool) –

do_error(stream_data, error) virtual¶

Parameters:

stream_data (object or None) –
error (GLib.Error) –

do_event(stream_data, data) virtual¶

Parameters:

stream_data (object or None) –
data (object or None) –

do_get_time() virtual¶

Returns:: playback position
Return type:: int

Returns the current playback for the current stream in nanoseconds.

do_get_volume() virtual¶

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

Returns the current volume level, between 0.0 and 1.0.

do_image(stream_data, image) virtual¶

Parameters:

stream_data (object or None) –
image (GdkPixbuf.Pixbuf) –

do_info(stream_data, field, value) virtual¶

Parameters:

stream_data (object or None) –
field (RB.MetaDataField) –
value (GObject.Value) –

do_multiple_open() virtual¶

Returns:: True if multiple open is supported
Return type:: bool

Determines whether the player supports multiple open streams.

do_open(uri, stream_data, stream_data_destroy) virtual¶

Parameters:

uri (str) – URI to open
stream_data (object or None) – arbitrary data to associate with the stream
stream_data_destroy (GLib.DestroyNotify) – function to call to destroy the stream data

Returns:

True if the stream preparation was not unsuccessful

Return type:

bool

Prepares a stream for playback. Depending on the player implementation, this may stop any existing stream being played. The stream preparation process may continue asynchronously, in which case errors may be reported from RB.Player.play or using the ‘error’ signal.

do_opened() virtual¶

Returns:: True if a stream is prepared for playback
Return type:: bool

Determines whether a stream has been prepared for playback.

do_pause() virtual¶: Pauses playback of the most recently started stream. Any streams being faded out may continue until the fade is complete.

do_play(play_type, crossfade) virtual¶

Parameters:

play_type (RB.PlayerPlayType) – requested playback start type
crossfade (int) – requested crossfade duration (nanoseconds)

Returns:

True if playback started successfully

Return type:

bool

Starts playback of the most recently opened stream. if play_type is RB.PlayerPlayType.CROSSFADE, the player may attempt to crossfade the new stream with any existing streams. If it does this, the it will use crossfade as the duration of the fade.

If play_type is RB.PlayerPlayType.START_AFTER_EOS, the player may attempt to start the stream immediately after the current playing stream reaches EOS. This may or may not result in the phenomemon known as ‘gapless playback’.

If play_type is RB.PlayerPlayType.REPLACE, the player will stop any existing stream before starting the new stream. It may do this anyway, regardless of the value of play_type.

The ‘playing-stream’ signal will be emitted when the new stream is actually playing. This may be before or after control returns to the caller.

do_playing() virtual¶

Returns:: True if playing
Return type:: bool

Determines whether the player is currently playing a stream. A stream is playing if it’s not paused or being faded out.

do_playing_stream(stream_data) virtual¶

Parameters:: stream_data (object or None) –

do_redirect(stream_data, uri) virtual¶

Parameters:

stream_data (object or None) –
uri (str) –

do_seekable() virtual¶

Returns:: True if the current stream is seekable
Return type:: bool

Determines whether seeking is supported for the current stream.

do_set_time(newtime) virtual¶

Parameters:: newtime (int) – seek target position in seconds

Attempts to seek in the current stream. The player may ignore this if the stream is not seekable. The seek may take place asynchronously.

do_set_volume(volume) virtual¶

Parameters:: volume (float) – new output volume level

Adjusts the output volume level. This affects all streams. The player may use a hardware volume control to implement this volume adjustment.

do_tick(stream_data, elapsed, duration) virtual¶

Parameters:

stream_data (object or None) –
elapsed (int) –
duration (int) –

do_volume_changed(volume) virtual¶

Parameters:: volume (float) –

Signal Details¶

RB.Player.signals.buffering(player, stream_data, progress)¶

Signal Name:

buffering

Flags:

RUN_LAST

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – the data associated with the buffering stream
progress (int) – buffering percentage

The ‘buffering’ signal is emitted while a stream is paused so that a buffer can be filled. The progress value typically varies from 0 to 100, and once it reaches 100, playback resumes.

RB.Player.signals.eos(player, stream_data, early)¶

Signal Name:

eos

Flags:

RUN_LAST, NO_RECURSE

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – the data associated with the stream that finished
early (bool) – if True, the EOS notification should only be used for track changes.

The ‘eos’ signal is emitted when a stream finishes, or in some cases, when it is about to finish (with early set to True) to allow for a new track to be played immediately afterwards.

RB.Player.signals.error(player, stream_data, error)¶

Signal Name:

error

Flags:

RUN_LAST, NO_RECURSE

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – the data associated with the stream
error (object or None) – description of the error

The ‘error’ signal is emitted when an error is encountered while opening or playing a stream.

RB.Player.signals.event(player, stream_data, data)¶

Signal Name:

event

Flags:

RUN_LAST, DETAILED

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – data associated with the stream
data (object or None) – event data

The ‘event’ signal provides a means for custom GStreamer elements to communicate events back to the rest of the application. The GStreamer element posts an application message on the GStreamer bus, which is translated into an event signal with the detail of the signal set to the name of the structure found in the message.

RB.Player.signals.image(player, stream_data, image)¶

Signal Name:

image

Flags:

RUN_LAST

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – data associated with the stream
image (GdkPixbuf.Pixbuf) – the image extracted from the stream

The ‘image’ signal is emitted to provide access to images extracted from the stream.

RB.Player.signals.info(player, stream_data, field, value)¶

Signal Name:

info

Flags:

RUN_LAST

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – the data associated with the stream
field (int) – the RB.MetaDataField corresponding to the stream info
value (GObject.Value) – the value of the stream info field

The ‘info’ signal is emitted when a metadata value is found in the stream.

RB.Player.signals.playing_stream(player, stream_data)¶

Signal Name:

playing-stream

Flags:

RUN_LAST

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – data associated with the stream

The ‘playing-stream’ signal is emitted when the main playing stream changes. It should be used to update the UI to show the new stream. It can either be emitted before or after RB.Player.play returns, depending on the player backend.

RB.Player.signals.redirect(player, stream_data, uri)¶

Signal Name:

redirect

Flags:

RUN_LAST

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – data associated with the stream
uri (str) – URI to redirect to

The ‘redirect’ signal is emitted to indicate when a stream has change URI.

RB.Player.signals.tick(player, stream_data, elapsed, duration)¶

Signal Name:

tick

Flags:

RUN_LAST

Parameters:

player (RB.Player) – The object which received the signal
stream_data (object or None) – the data associated with the stream
elapsed (int) – playback position in the stream (in nanoseconds)
duration (int) – current estimate of the duration of the stream (in nanoseconds)

The ‘tick’ signal is emitted repeatedly while the stream is playing. Signal handlers can use this to update UI and to prepare new streams for crossfade or gapless playback.

RB.Player.signals.volume_changed(player, volume)¶

Signal Name:

volume-changed

Flags:

RUN_LAST

Parameters:

player (RB.Player) – The object which received the signal
volume (float) – the new volume level

The ‘volume-changed’ signal is emitted when the output stream volume is changed externally.