RBPlayer

RBPlayer — playback backend interface

Types and Values

Object Hierarchy

    GEnum
    ╰── RBPlayerError
    GInterface
    ╰── RBPlayer

Includes

#include <rb-player.h>

Description

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.

Functions

rb_player_new ()

RBPlayer *
rb_player_new (gboolean want_crossfade,
               GError **error);

Creates a new player object.

Parameters

want_crossfade

if TRUE, try to use a backend that supports crossfading and other track transitions.

 

error

returns error information

 

Returns

new player object.

[transfer full]


rb_player_open ()

gboolean
rb_player_open (RBPlayer *player,
                const char *uri,
                gpointer stream_data,
                GDestroyNotify stream_data_destroy,
                GError **error);

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.

Parameters

player

a RBPlayer

 

uri

URI to open

 

stream_data

arbitrary data to associate with the stream

 

stream_data_destroy

function to call to destroy the stream data

 

error

returns error information

 

Returns

TRUE if the stream preparation was not unsuccessful


rb_player_opened ()

gboolean
rb_player_opened (RBPlayer *player);

Determines whether a stream has been prepared for playback.

Parameters

player

a RBPlayer

 

Returns

TRUE if a stream is prepared for playback


rb_player_close ()

gboolean
rb_player_close (RBPlayer *player,
                 const char *uri,
                 GError **error);

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

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

Parameters

player

a RBPlayer

 

uri

optionally, the URI of the stream to close

 

error

returns error information

 

Returns

TRUE if a stream was found and closed


rb_player_play ()

gboolean
rb_player_play (RBPlayer *player,
                RBPlayerPlayType play_type,
                gint64 crossfade,
                GError **error);

Starts playback of the most recently opened stream. if play_type is RB_PLAYER_PLAY_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_PLAYER_PLAY_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_PLAYER_PLAY_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.

Parameters

player

a RBPlayer

 

play_type

requested playback start type

 

crossfade

requested crossfade duration (nanoseconds)

 

error

returns error information

 

Returns

TRUE if playback started successfully


rb_player_pause ()

void
rb_player_pause (RBPlayer *player);

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

Parameters

player

a RBPlayer

 

rb_player_playing ()

gboolean
rb_player_playing (RBPlayer *player);

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

Parameters

player

a RBPlayer.

 

Returns

TRUE if playing


rb_player_set_volume ()

void
rb_player_set_volume (RBPlayer *player,
                      float volume);

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

Parameters

player

a RBPlayer

 

volume

new output volume level

 

rb_player_get_volume ()

float
rb_player_get_volume (RBPlayer *player);

Returns the current volume level, between 0.0 and 1.0.

Parameters

player

a RBPlayer

 

Returns

current output volume level


rb_player_seekable ()

gboolean
rb_player_seekable (RBPlayer *player);

Determines whether seeking is supported for the current stream.

Parameters

player

a RBPlayer

 

Returns

TRUE if the current stream is seekable


rb_player_set_time ()

void
rb_player_set_time (RBPlayer *player,
                    gint64 newtime);

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

Parameters

player

a RBPlayer

 

newtime

seek target position in seconds

 

rb_player_get_time ()

gint64
rb_player_get_time (RBPlayer *player);

Returns the current playback for the current stream in nanoseconds.

Parameters

player

a RBPlayer

 

Returns

playback position


rb_player_multiple_open ()

gboolean
rb_player_multiple_open (RBPlayer *player);

Determines whether the player supports multiple open streams.

Parameters

player

a RBPlayer

 

Returns

TRUE if multiple open is supported

Types and Values

RBPlayer

typedef struct _RBPlayer RBPlayer;


struct RBPlayerIface

struct RBPlayerIface {
	GTypeInterface g_iface;

	/* virtual functions */
	gboolean        (*open)			(RBPlayer *player,
						 const char *uri,
						 gpointer stream_data,
						 GDestroyNotify stream_data_destroy,
						 GError **error);
	gboolean (*opened)		(RBPlayer *player);
	gboolean        (*close)		(RBPlayer *player,
						 const char *uri,
						 GError **error);

	gboolean (*play)			(RBPlayer *player,
						 RBPlayerPlayType play_type,
						 gint64 crossfade,
						 GError **error);
	void		(*pause)		(RBPlayer *player);
	gboolean (*playing)		(RBPlayer *player);

	void		(*set_volume)		(RBPlayer *player,
						 float volume);
	float		(*get_volume)		(RBPlayer *player);

	gboolean (*seekable)		(RBPlayer *player);
	void		(*set_time)		(RBPlayer *player,
						 gint64 newtime);
	gint64		(*get_time)		(RBPlayer *player);
	gboolean (*multiple_open) (RBPlayer *player);


	/* signals */
	void		(*playing_stream) (RBPlayer *player,
						 gpointer stream_data);
	void		(*eos)			(RBPlayer *player,
						 gpointer stream_data,
						 gboolean early);
	void		(*info)			(RBPlayer *player,
						 gpointer stream_data,
						 RBMetaDataField field,
						 GValue *value);
	void		(*buffering)		(RBPlayer *player,
						 gpointer stream_data,
						 guint progress);
	void		(*error)           	(RBPlayer *player,
						 gpointer stream_data,
						 GError *error);
	void		(*tick)            	(RBPlayer *player,
						 gpointer stream_data,
						 gint64 elapsed,
						 gint64 duration);
	void		(*event)		(RBPlayer *player,
						 gpointer stream_data,
						 gpointer data);
	void		(*volume_changed) (RBPlayer *player,
						 float volume);
	void		(*image)		(RBPlayer *player,
						 gpointer stream_data,
						 GdkPixbuf *image);
	void		(*redirect)		(RBPlayer *player,
						 gpointer stream_data,
						 const gchar *uri);
};


enum RBPlayerPlayType

Members

RB_PLAYER_PLAY_REPLACE

Replace the existing stream

 

RB_PLAYER_PLAY_AFTER_EOS

Start the new stream after the current stream ends

 

RB_PLAYER_PLAY_CROSSFADE

Crossfade between the existing stream and the new stream

 

enum RBPlayerError

Members

RB_PLAYER_ERROR_NO_AUDIO

Audio playback not available

 

RB_PLAYER_ERROR_GENERAL

Nonspecific error

 

RB_PLAYER_ERROR_INTERNAL

Internal error

 

RB_PLAYER_ERROR_NOT_FOUND

The resource could not be found

 

Signal Details

The “buffering” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               guint     progress,
               gpointer  user_data)

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.

Parameters

player

the RBPlayer

 

stream_data

the data associated with the buffering stream

 

progress

buffering percentage

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “eos” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               gboolean  early,
               gpointer  user_data)

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.

Parameters

player

the RBPlayer

 

stream_data

the data associated with the stream that finished

 

early

if TRUE, the EOS notification should only be used for track changes.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion


The “error” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               gpointer  error,
               gpointer  user_data)

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

Parameters

player

the RBPlayer

 

stream_data

the data associated with the stream

 

error

description of the error

 

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion


The “event” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               gpointer  data,
               gpointer  user_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.

Parameters

player

the RBPlayer

 

stream_data

data associated with the stream

 

data

event data

 

user_data

user data set when the signal handler was connected.

 

Flags: Has Details


The “image” signal

void
user_function (RBPlayer  *player,
               gpointer   stream_data,
               GdkPixbuf *image,
               gpointer   user_data)

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

Parameters

player

the RBPlayer

 

stream_data

data associated with the stream

 

image

the image extracted from the stream

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “info” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               gint      field,
               GValue   *value,
               gpointer  user_data)

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

Parameters

player

the RBPlayer

 

stream_data

the data associated with the stream

 

field

the RBMetaDataField corresponding to the stream info

 

value

the value of the stream info field

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “playing-stream” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               gpointer  user_data)

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.

Parameters

player

the RBPlayer

 

stream_data

data associated with the stream

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “redirect” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               gchar    *uri,
               gpointer  user_data)

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

Parameters

player

the RBPlayer

 

stream_data

data associated with the stream

 

uri

URI to redirect to

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “tick” signal

void
user_function (RBPlayer *player,
               gpointer  stream_data,
               gint64    elapsed,
               gint64    duration,
               gpointer  user_data)

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.

Parameters

player

the RBPlayer

 

stream_data

the data associated with the stream

 

elapsed

playback position in the stream (in nanoseconds)

 

duration

current estimate of the duration of the stream (in nanoseconds)

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “volume-changed” signal

void
user_function (RBPlayer *player,
               gfloat    volume,
               gpointer  user_data)

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

Parameters

player

the RBPlayer

 

volume

the new volume level

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last