rb-player

rb-player — playback backend interface

Synopsis


#include <rb-player.h>

                    RBPlayer;
                    RBPlayerIface;
enum                RBPlayerError;
RBPlayer*           rb_player_new                       (gboolean want_crossfade,
                                                         GError **error);
gboolean            rb_player_open                      (RBPlayer *player,
                                                         const char *uri,
                                                         gpointer stream_data,
                                                         GDestroyNotify stream_data_destroy,
                                                         GError **error);
gboolean            rb_player_opened                    (RBPlayer *player);
gboolean            rb_player_close                     (RBPlayer *player,
                                                         const char *uri,
                                                         GError **error);
gboolean            rb_player_play                      (RBPlayer *player,
                                                         gint crossfade,
                                                         GError **error);
void                rb_player_pause                     (RBPlayer *player);
gboolean            rb_player_playing                   (RBPlayer *player);
void                rb_player_set_volume                (RBPlayer *player,
                                                         float volume);
float               rb_player_get_volume                (RBPlayer *player);
void                rb_player_set_replaygain            (RBPlayer *player,
                                                         const char *uri,
                                                         double track_gain,
                                                         double track_peak,
                                                         double album_gain,
                                                         double album_peak);
gboolean            rb_player_seekable                  (RBPlayer *player);
void                rb_player_set_time                  (RBPlayer *player,
                                                         long newtime );
long                rb_player_get_time                  (RBPlayer *player);
gboolean            rb_player_multiple_open             (RBPlayer *player);

Object Hierarchy

  GInterface
   +----RBPlayer

Signals

  "buffering"                                      : Run Last
  "eos"                                            : Run Last / No Recursion
  "error"                                          : Run Last / No Recursion
  "event"                                          : Run Last / Has Details
  "info"                                           : Run Last
  "playing-stream"                                 : Run Last
  "tick"                                           : Run Last

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, set_replaygain) 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.

Details

RBPlayer

typedef struct _RBPlayer RBPlayer;


RBPlayerIface

typedef struct {
	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,
						 gint crossfade,
						 GError **error);
	void		(*pause)		(RBPlayer *player);
	gboolean	(*playing)		(RBPlayer *player);

	void		(*set_volume)		(RBPlayer *player,
						 float volume);
	float		(*get_volume)		(RBPlayer *player);
	void		(*set_replaygain)	(RBPlayer *player,
						 const char *uri,
						 double track_gain,
						 double track_peak,
						 double album_gain,
						 double album_peak);

	gboolean	(*seekable)		(RBPlayer *player);
	void		(*set_time)		(RBPlayer *player,
						 long time);
	long		(*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);
	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,
						 long elapsed,
						 long duration);
	void		(*event)		(RBPlayer *player,
						 gpointer stream_data,
						 gpointer data);
} RBPlayerIface;


enum RBPlayerError

typedef enum
{
	RB_PLAYER_ERROR_NO_AUDIO,
	RB_PLAYER_ERROR_GENERAL,
	RB_PLAYER_ERROR_INTERNAL
} RBPlayerError;


rb_player_new ()

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

Creates a new player object.

want_crossfade :

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

error :

returns error information

Returns :

new player object.

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.

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);

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.

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,
                                                         gint crossfade,
                                                         GError **error);

Starts playback of the most recently opened stream. If crossfade is greater than zero, the player may attempt to crossfade the new stream with any existing streams.

If crossfade is zero, 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 crossfade is less than zero, the player will stop any existing stream before starting the new stream. It may do this anyway, regardless of the value of crossfade.

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.

player :

a RBPlayer

crossfade :

requested crossfade duration

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.

player :

a RBPlayer

rb_player_playing ()

gboolean            rb_player_playing                   (RBPlayer *player);

player :

a RBPlayer.

Returns :

TRUE if a stream is currently being played (not paused or being faded out).

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.

player :

a RBPlayer

volume :

new output volume level

rb_player_get_volume ()

float               rb_player_get_volume                (RBPlayer *player);

player :

a RBPlayer

Returns :

current output volume level

rb_player_set_replaygain ()

void                rb_player_set_replaygain            (RBPlayer *player,
                                                         const char *uri,
                                                         double track_gain,
                                                         double track_peak,
                                                         double album_gain,
                                                         double album_peak);

Sets ReplayGain values for a stream

player :

a RBPlayer

uri :

URI of stream to adjust

track_gain :

ReplayGain track gain level

track_peak :

ReplayGain track peak level

album_gain :

ReplayGain album gain level

album_peak :

ReplayGain album peak level

rb_player_seekable ()

gboolean            rb_player_seekable                  (RBPlayer *player);

player :

a RBPlayer

Returns :

TRUE if the current stream is seekable

rb_player_set_time ()

void                rb_player_set_time                  (RBPlayer *player,
                                                         long 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.

player :

a RBPlayer

Param2 :


rb_player_get_time ()

long                rb_player_get_time                  (RBPlayer *player);

player :

a RBPlayer

Returns :

the current playback position in the current stream

rb_player_multiple_open ()

gboolean            rb_player_multiple_open             (RBPlayer *player);

player :

a RBPlayer

Returns :

TRUE if the player supports multiple open streams (not necessarily multiple playing streams, though)

Signal Details

The "buffering" signal

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

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.

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.

The "eos" signal

void                user_function                      (RBPlayer *player,
                                                        gpointer  stream_data,
                                                        gpointer  user_data)        : Run Last / No Recursion

The 'eos' signal is emitted when a stream finishes.

player :

the RBPlayer

stream_data :

the data associated with the stream that finished

user_data :

user data set when the signal handler was connected.

The "error" signal

void                user_function                      (RBPlayer *player,
                                                        gpointer  stream_data,
                                                        gpointer  error,
                                                        gpointer  user_data)        : Run Last / No Recursion

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

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.

The "event" signal

void                user_function                      (RBPlayer *player,
                                                        gpointer  stream_data,
                                                        gpointer  data,
                                                        gpointer  user_data)        : Run Last / Has Details

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.

player :

the RBPlayer

stream_data :

data associated with the stream

data :

event data

user_data :

user data set when the signal handler was connected.

The "info" signal

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

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

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.

The "playing-stream" signal

void                user_function                      (RBPlayer *player,
                                                        gpointer  stream_data,
                                                        gpointer  user_data)        : Run Last

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.

player :

the RBPlayer

stream_data :

data associated with the stream

user_data :

user data set when the signal handler was connected.

The "tick" signal

void                user_function                      (RBPlayer *player,
                                                        gpointer  stream_data,
                                                        glong     elapsed,
                                                        glong     duration,
                                                        gpointer  user_data)        : Run Last

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.

player :

the RBPlayer

stream_data :

the data associated with the stream

elapsed :

playback position in the stream

duration :

current estimate of the duration of the stream

user_data :

user data set when the signal handler was connected.