RB.Player

g GObject.GInterface GObject.GInterface RB.Player RB.Player GObject.GInterface->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

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:
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:
do_error(stream_data, error) virtual
Parameters:
do_event(stream_data, data) virtual
Parameters:
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:
do_info(stream_data, field, value) virtual
Parameters:
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:
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:
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.