RBShellPlayer

RBShellPlayer — playback state management

Synopsis

                    RBShellPlayer;
                    RBShellPlayerClass;
enum                RBShellPlayerError;
RBShellPlayer *     rb_shell_player_new                 (RhythmDB *db,
                                                         GtkUIManager *mgr,
                                                         GtkActionGroup *actiongroup);
void                rb_shell_player_set_selected_source (RBShellPlayer *player,
                                                         RBSource *source);
void                rb_shell_player_set_playing_source  (RBShellPlayer *player,
                                                         RBSource *source);
RBSource *          rb_shell_player_get_playing_source  (RBShellPlayer *player);
RBSource *          rb_shell_player_get_active_source   (RBShellPlayer *player);
void                rb_shell_player_jump_to_current     (RBShellPlayer *player);
void                rb_shell_player_play_entry          (RBShellPlayer *player,
                                                         RhythmDBEntry *entry,
                                                         RBSource *source);
gboolean            rb_shell_player_play                (RBShellPlayer *player,
                                                         GError **error);
gboolean            rb_shell_player_pause               (RBShellPlayer *player,
                                                         GError **error);
gboolean            rb_shell_player_playpause           (RBShellPlayer *player,
                                                         gboolean unused,
                                                         GError **error);
void                rb_shell_player_stop                (RBShellPlayer *player);
gboolean            rb_shell_player_do_previous         (RBShellPlayer *player,
                                                         GError **error);
gboolean            rb_shell_player_do_next             (RBShellPlayer *player,
                                                         GError **error);
char *              rb_shell_player_get_playing_time_string
                                                        (RBShellPlayer *player);
gboolean            rb_shell_player_get_playing_time    (RBShellPlayer *player,
                                                         guint *time,
                                                         GError **error);
gboolean            rb_shell_player_set_playing_time    (RBShellPlayer *player,
                                                         guint time,
                                                         GError **error);
void                rb_shell_player_seek                (RBShellPlayer *player,
                                                         glong offset);
long                rb_shell_player_get_playing_song_duration
                                                        (RBShellPlayer *player);
gboolean            rb_shell_player_get_playing         (RBShellPlayer *player,
                                                         gboolean *playing,
                                                         GError **error);
gboolean            rb_shell_player_get_playing_path    (RBShellPlayer *player,
                                                         const gchar **path,
                                                         GError **error);
void                rb_shell_player_set_playback_state  (RBShellPlayer *player,
                                                         gboolean shuffle,
                                                         gboolean repeat);
gboolean            rb_shell_player_get_playback_state  (RBShellPlayer *player,
                                                         gboolean *shuffle,
                                                         gboolean *repeat);
RhythmDBEntry *     rb_shell_player_get_playing_entry   (RBShellPlayer *player);
void                rb_shell_player_toggle_mute         (RBShellPlayer *player);
gboolean            rb_shell_player_set_volume          (RBShellPlayer *player,
                                                         gdouble volume,
                                                         GError **error);
gboolean            rb_shell_player_get_volume          (RBShellPlayer *player,
                                                         gdouble *volume,
                                                         GError **error);
gboolean            rb_shell_player_set_volume_relative (RBShellPlayer *player,
                                                         gdouble delta,
                                                         GError **error);
gboolean            rb_shell_player_set_mute            (RBShellPlayer *player,
                                                         gboolean mute,
                                                         GError **error);
gboolean            rb_shell_player_get_mute            (RBShellPlayer *player,
                                                         gboolean *mute,
                                                         GError **error);
void                rb_shell_player_add_play_order      (RBShellPlayer *player,
                                                         const char *name,
                                                         const char *description,
                                                         GType order_type,
                                                         gboolean hidden);
void                rb_shell_player_remove_play_order   (RBShellPlayer *player,
                                                         const char *name);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBox
                                 +----GtkHBox
                                       +----RBShellPlayer

Implemented Interfaces

RBShellPlayer implements AtkImplementorIface, GtkBuildable and GtkOrientable.

Properties

  "action-group"             GtkActionGroup*       : Read / Write / Construct Only
  "db"                       RhythmDB*             : Read / Write / Construct Only
  "play-order"               gchar*                : Read
  "player"                   GObject*              : Read
  "playing"                  gboolean              : Read
  "playing-from-queue"       gboolean              : Read
  "queue-only"               gboolean              : Read / Write
  "queue-source"             RBPlaylistSource*     : Read / Write
  "source"                   RBSource*             : Read / Write
  "statusbar"                RBStatusbar*          : Read / Write
  "ui-manager"               GtkUIManager*         : Read / Write / Construct Only
  "volume"                   gfloat                : Read / Write

Signals

  "elapsed-changed"                                : Run Last
  "elapsed-nano-changed"                           : Run Last
  "missing-plugins"                                : Run Last
  "playing-changed"                                : Run Last
  "playing-song-changed"                           : Run Last
  "playing-song-property-changed"                  : Run Last
  "playing-source-changed"                         : Run Last
  "playing-uri-changed"                            : Run Last
  "window-title-changed"                           : Run Last

Description

The shell player (or player shell, depending on who you're talking to) manages the RBPlayer instance, tracks the current playing RhythmDBEntry, and manages the various RBPlayOrder instances. It provides simple operations such as next, previous, play/pause, and seek.

When playing internet radio streams, it first attempts to read the straem URL as a playlist. If this succeeds, the URLs from the playlist are stored in a list and tried in turn in case of errors. If the playlist parsing fails, the stream URL is played directly.

The mapping from the separate shuffle and repeat settings to an RBPlayOrder instance occurs in here. The play order logic can also support a number of additional play orders not accessible via the shuffle and repeat buttons.

If the player backend supports multiple streams, the shell player crossfades between streams by watching the elapsed time of the current stream and simulating an end-of-stream event when it gets within the crossfade duration of the actual end.

Details

RBShellPlayer

typedef struct _RBShellPlayer RBShellPlayer;

RBShellPlayerClass

typedef struct {
	GtkHBoxClass parent_class;

	void (*window_title_changed) (RBShellPlayer *player, const char *window_title);
	void (*elapsed_changed) (RBShellPlayer *player, guint elapsed);
	void (*elapsed_nano_changed) (RBShellPlayer *player, gint64 elapsed);
	void (*playing_changed) (RBShellPlayer *player, gboolean playing);
	void (*playing_source_changed) (RBShellPlayer *player, RBSource *source);
	void (*playing_uri_changed) (RBShellPlayer *player, const char *uri);
	void (*playing_song_changed) (RBShellPlayer *player, RhythmDBEntry *entry);
	void (*playing_song_property_changed) (RBShellPlayer *player,
					       const char *uri,
					       const char *property,
					       GValue *old,
					       GValue *newValue);
} RBShellPlayerClass;

enum RBShellPlayerError

typedef enum
{
	RB_SHELL_PLAYER_ERROR_PLAYLIST_PARSE_ERROR,
	RB_SHELL_PLAYER_ERROR_END_OF_PLAYLIST,
	RB_SHELL_PLAYER_ERROR_NOT_PLAYING,
	RB_SHELL_PLAYER_ERROR_NOT_SEEKABLE,
	RB_SHELL_PLAYER_ERROR_POSITION_NOT_AVAILABLE,
} RBShellPlayerError;

rb_shell_player_new ()

RBShellPlayer *     rb_shell_player_new                 (RhythmDB *db,
                                                         GtkUIManager *mgr,
                                                         GtkActionGroup *actiongroup);

Creates the RBShellPlayer

db :

 the RhythmDB

mgr :

 the GtkUIManager

actiongroup :

 the GtkActionGroup to use

Returns :

 the RBShellPlayer instance

rb_shell_player_set_selected_source ()

void                rb_shell_player_set_selected_source (RBShellPlayer *player,
                                                         RBSource *source);

Updates the player to reflect a new source being selected.

player :

 the RBShellPlayer

source :

 the RBSource to select

rb_shell_player_set_playing_source ()

void                rb_shell_player_set_playing_source  (RBShellPlayer *player,
                                                         RBSource *source);

Replaces the current playing source.

player :

 the RBShellPlayer

source :

 the new playing RBSource

rb_shell_player_get_playing_source ()

RBSource *          rb_shell_player_get_playing_source  (RBShellPlayer *player);

Retrieves the current playing source. That is, the source from which the current song was drawn. This differs from rb_shell_player_get_active_source when the current song came from the play queue.

player :

 the RBShellPlayer

Returns :

 the current playing RBSource

rb_shell_player_get_active_source ()

RBSource *          rb_shell_player_get_active_source   (RBShellPlayer *player);

Retrieves the active source. This is the source that the user selected for playback.

player :

 the RBShellPlayer

Returns :

 the active RBSource

rb_shell_player_jump_to_current ()

void                rb_shell_player_jump_to_current     (RBShellPlayer *player);

Scrolls the RBEntryView for the current playing source so that the current playing entry is visible and selects the row for the entry. If there is no current playing entry, the selection is cleared instead.

player :

 the RBShellPlayer

rb_shell_player_play_entry ()

void                rb_shell_player_play_entry          (RBShellPlayer *player,
                                                         RhythmDBEntry *entry,
                                                         RBSource *source);

Plays a specified entry.

player :

 the RBShellPlayer

entry :

 the RhythmDBEntry to play

source :

 the new RBSource to set as playing (or NULL to use the selected source)

rb_shell_player_play ()

gboolean            rb_shell_player_play                (RBShellPlayer *player,
                                                         GError **error);

Starts playback, if it is not already playing.

player :

 a RBShellPlayer

error :

 error return

Returns :

 whether playback is now occurring (TRUE when successfully started or already playing).

rb_shell_player_pause ()

gboolean            rb_shell_player_pause               (RBShellPlayer *player,
                                                         GError **error);

Pauses playback if possible, completely stopping if not.

player :

 a RBShellPlayer

error :

 error return

Returns :

 whether playback is not occurring (TRUE when successfully paused/stopped or playback was not occurring).

rb_shell_player_playpause ()

gboolean            rb_shell_player_playpause           (RBShellPlayer *player,
                                                         gboolean unused,
                                                         GError **error);

Toggles between playing and paused state. If there is no playing entry, chooses an entry from (in order of preference) the play queue, the selection in the current source, or the play order.

player :

 the RBShellPlayer

unused :

 nothing

error :

 returns error information

Returns :

 TRUE if successful

rb_shell_player_stop ()

void                rb_shell_player_stop                (RBShellPlayer *player);

Completely stops playback, freeing resources and unloading the file.

In general rb_shell_player_pause() should be used instead, as it stops the audio, but does not completely free resources.

player :

 a RBShellPlayer.

rb_shell_player_do_previous ()

gboolean            rb_shell_player_do_previous         (RBShellPlayer *player,
                                                         GError **error);

If the current song has been playing for more than 3 seconds, restarts it, otherwise, goes back to the previous song. Fails if there is no current song, or if inside the first 3 seconds of the first song in the play order.

player :

 the RBShellPlayer

error :

 returns any error information

Returns :

 TRUE if successful

rb_shell_player_do_next ()

gboolean            rb_shell_player_do_next             (RBShellPlayer *player,
                                                         GError **error);

Skips to the next song. Consults the play queue and handles transitions between the play queue and the active source. Fails if there is no entry to play after the current one.

player :

 the RBShellPlayer

error :

 returns error information

Returns :

 TRUE if successful

rb_shell_player_get_playing_time_string ()

char *              rb_shell_player_get_playing_time_string
                                                        (RBShellPlayer *player);

Constructs a string showing the current playback position, taking the time display settings into account.

player :

 the RBShellPlayer

Returns :

 allocated playing time string

rb_shell_player_get_playing_time ()

gboolean            rb_shell_player_get_playing_time    (RBShellPlayer *player,
                                                         guint *time,
                                                         GError **error);

Retrieves the current playback position. Fails if the player currently cannot provide the playback position.

player :

 the RBShellPlayer

time :

 returns the current playback position

error :

 returns error information

Returns :

 TRUE if successful

rb_shell_player_set_playing_time ()

gboolean            rb_shell_player_set_playing_time    (RBShellPlayer *player,
                                                         guint time,
                                                         GError **error);

Attempts to set the playback position. Fails if the current song is not seekable.

player :

 the RBShellPlayer

time :

 the target playback position (in seconds)

error :

 returns error information

Returns :

 TRUE if successful

rb_shell_player_seek ()

void                rb_shell_player_seek                (RBShellPlayer *player,
                                                         glong offset);

Seeks forwards or backwards in the current playing song. Does not return error information.

player :

 the RBShellPlayer

offset :

 relative seek target (in seconds)

rb_shell_player_get_playing_song_duration ()

long                rb_shell_player_get_playing_song_duration
                                                        (RBShellPlayer *player);

Retrieves the duration of the current playing song.

player :

 the RBShellPlayer

Returns :

 duration, or -1 if not playing

rb_shell_player_get_playing ()

gboolean            rb_shell_player_get_playing         (RBShellPlayer *player,
                                                         gboolean *playing,
                                                         GError **error);

Reports whether playback is occuring by setting playing.

player :

 a RBShellPlayer

playing :

 playback state return

error :

 error return

Returns :

 TRUE if successful

rb_shell_player_get_playing_path ()

gboolean            rb_shell_player_get_playing_path    (RBShellPlayer *player,
                                                         const gchar **path,
                                                         GError **error);

Retrieves the URI of the current playing entry. The caller must not free the returned string.

player :

 the RBShellPlayer

path :

 returns the URI of the current playing entry

error :

 returns error information

Returns :

 TRUE if successful

rb_shell_player_set_playback_state ()

void                rb_shell_player_set_playback_state  (RBShellPlayer *player,
                                                         gboolean shuffle,
                                                         gboolean repeat);

Sets the state of the shuffle and repeat settings.

player :

 the RBShellPlayer

shuffle :

 whether to enable the shuffle setting

repeat :

 whether to enable the repeat setting

rb_shell_player_get_playback_state ()

gboolean            rb_shell_player_get_playback_state  (RBShellPlayer *player,
                                                         gboolean *shuffle,
                                                         gboolean *repeat);

Retrieves the current state of the shuffle and repeat settings.

player :

 the RBShellPlayer

shuffle :

 returns the current shuffle setting

repeat :

 returns the current repeat setting

Returns :

 TRUE if successful.

rb_shell_player_get_playing_entry ()

RhythmDBEntry *     rb_shell_player_get_playing_entry   (RBShellPlayer *player);

Retrieves the currently playing RhythmDBEntry, or NULL if nothing is playing. The caller must unref the entry (using rhythmdb_entry_unref) when it is no longer needed.

player :

 the RBShellPlayer

Returns :

 the currently playing RhythmDBEntry, or NULL

rb_shell_player_toggle_mute ()

void                rb_shell_player_toggle_mute         (RBShellPlayer *player);

Toggles the mute setting on the player.

player :

 the RBShellPlayer

rb_shell_player_set_volume ()

gboolean            rb_shell_player_set_volume          (RBShellPlayer *player,
                                                         gdouble volume,
                                                         GError **error);

Sets the playback volume level.

player :

 the RBShellPlayer

volume :

 the volume level (between 0 and 1)

error :

 returns the error information

Returns :

 TRUE on success

rb_shell_player_get_volume ()

gboolean            rb_shell_player_get_volume          (RBShellPlayer *player,
                                                         gdouble *volume,
                                                         GError **error);

Returns the current volume level

player :

 the RBShellPlayer

volume :

 returns the volume level

error :

 returns error information

Returns :

 the current volume level.

rb_shell_player_set_volume_relative ()

gboolean            rb_shell_player_set_volume_relative (RBShellPlayer *player,
                                                         gdouble delta,
                                                         GError **error);

Adds the specified value to the current volume level.

player :

 the RBShellPlayer

delta :

 difference to apply to the volume level (between -1 and 1)

error :

 returns error information

Returns :

 TRUE on success

rb_shell_player_set_mute ()

gboolean            rb_shell_player_set_mute            (RBShellPlayer *player,
                                                         gboolean mute,
                                                         GError **error);

Updates the mute setting on the player.

player :

 the RBShellPlayer

mute :

 TRUE to mute playback

error :

 returns error information

Returns :

 TRUE if successful

rb_shell_player_get_mute ()

gboolean            rb_shell_player_get_mute            (RBShellPlayer *player,
                                                         gboolean *mute,
                                                         GError **error);

Returns TRUE if currently muted

player :

 the RBShellPlayer

mute :

 returns the current mute setting

error :

 returns error information

Returns :

 TRUE if currently muted

rb_shell_player_add_play_order ()

void                rb_shell_player_add_play_order      (RBShellPlayer *player,
                                                         const char *name,
                                                         const char *description,
                                                         GType order_type,
                                                         gboolean hidden);

Adds a new play order to the set of available play orders.

player :

 the RBShellPlayer

name :

 name of the new play order

description :

 description of the new play order

order_type :

 the GType of the play order class

hidden :

 if TRUE, don't display the play order in the UI

rb_shell_player_remove_play_order ()

void                rb_shell_player_remove_play_order   (RBShellPlayer *player,
                                                         const char *name);

Removes a play order previously added with rb_shell_player_add_play_order from the set of available play orders.

player :

 the RBShellPlayer

name :

 name of the play order to remove

Property Details

The "action-group" property

  "action-group"             GtkActionGroup*       : Read / Write / Construct Only

The GtkActionGroup to use for player actions

The "db" property

  "db"                       RhythmDB*             : Read / Write / Construct Only

The RhythmDB

The "play-order" property

  "play-order"               gchar*                : Read

The current play order object.

Default value: "linear"

The "player" property

  "player"                   GObject*              : Read

The player backend object (an object implementing the RBPlayer interface).

The "playing" property

  "playing"                  gboolean              : Read

Whether Rhythmbox is currently playing something

Default value: FALSE

The "playing-from-queue" property

  "playing-from-queue"       gboolean              : Read

If TRUE, the current playing entry came from the play queue.

Default value: FALSE

The "queue-only" property

  "queue-only"               gboolean              : Read / Write

If TRUE, activating an entry should only add it to the play queue.

Default value: FALSE

The "queue-source" property

  "queue-source"             RBPlaylistSource*     : Read / Write

The play queue source

The "source" property

  "source"                   RBSource*             : Read / Write

The current source that is selected for playback.

The "statusbar" property

  "statusbar"                RBStatusbar*          : Read / Write

The RBStatusbar object

The "ui-manager" property

  "ui-manager"               GtkUIManager*         : Read / Write / Construct Only

The GtkUIManager

The "volume" property

  "volume"                   gfloat                : Read / Write

The current playback volume (between 0.0 and 1.0)

Allowed values: [0,1]

Default value: 1

Signal Details

The "elapsed-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        guint          elapsed,
                                                        gpointer       user_data)      : Run Last

Emitted when the playback position changes.

player :

 the RBShellPlayer

elapsed :

 the new playback position in seconds

user_data :

 user data set when the signal handler was connected.

The "elapsed-nano-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        gint64         elapsed,
                                                        gpointer       user_data)      : Run Last

Emitted when the playback position changes. Only use this (as opposed to elapsed-changed) when you require subsecond precision. This signal will be emitted multiple times per second.

player :

 the RBShellPlayer

elapsed :

 the new playback position in nanoseconds

user_data :

 user data set when the signal handler was connected.

The "missing-plugins" signal

gboolean            user_function                      (RBShellPlayer *player,
                                                        GStrv         *details,
                                                        GStrv         *descriptions,
                                                        GClosure      *closure,
                                                        gpointer       user_data)         : Run Last

Emitted when the player backend requires some plugins to be installed in order to play the current playing song. When the closure included in the signal args is called, playback will be attempted again.

player :

 the RBShellPlayer

details :

 the list of plugin detail strings describing the missing plugins

descriptions :

 the list of descriptions for the missing plugins

closure :

 a GClosure to be called when the plugin installation is complete

user_data :

 user data set when the signal handler was connected.

The "playing-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        gboolean       playing,
                                                        gpointer       user_data)      : Run Last

Emitted when playback either stops or starts.

player :

 the RBShellPlayer

playing :

 flag indicating playback state

user_data :

 user data set when the signal handler was connected.

The "playing-song-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        RhythmDBEntry *entry,
                                                        gpointer       user_data)      : Run Last

Emitted when the playing database entry changes

player :

 the RBShellPlayer

entry :

 the new playing RhythmDBEntry

user_data :

 user data set when the signal handler was connected.

The "playing-song-property-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        gchar         *uri,
                                                        gchar         *property,
                                                        GValue        *old,
                                                        GValue        *newvalue,
                                                        gpointer       user_data)      : Run Last

Emitted when a property of the playing database entry changes.

player :

 the RBShellPlayer

uri :

 the URI of the playing entry

property :

 the name of the property that changed

old :

 the previous value for the property

newvalue :

 the new value of the property

user_data :

 user data set when the signal handler was connected.

The "playing-source-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        RBSource      *source,
                                                        gpointer       user_data)      : Run Last

Emitted when a new RBSource instance starts playing

player :

 the RBShellPlayer

source :

 the RBSource that is now playing

user_data :

 user data set when the signal handler was connected.

The "playing-uri-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        gchar         *uri,
                                                        gpointer       user_data)      : Run Last

Emitted when the playing database entry changes, providing the URI of the entry.

player :

 the RBShellPlayer

uri :

 the URI of the new playing entry

user_data :

 user data set when the signal handler was connected.

The "window-title-changed" signal

void                user_function                      (RBShellPlayer *player,
                                                        gchar         *title,
                                                        gpointer       user_data)      : Run Last

Emitted when the main window title text should be changed

player :

 the RBShellPlayer

title :

 the new window title

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.13