Rhythmbox Development Reference Manual: RBShellPlayer

## RBShellPlayer RBShellPlayer — playback state management |

## Functions

GQuark | rb_shell_player_error_quark ()
RBShellPlayer * | rb_shell_player_new ()
void | rb_shell_player_set_selected_source ()
void | rb_shell_player_set_playing_source ()
RBSource * | rb_shell_player_get_playing_source ()
RBSource * | rb_shell_player_get_active_source ()
void | rb_shell_player_jump_to_current ()
void | rb_shell_player_play_entry ()
gboolean | rb_shell_player_play ()
gboolean | rb_shell_player_pause ()
gboolean | rb_shell_player_playpause ()
void | rb_shell_player_stop ()
gboolean | rb_shell_player_do_previous ()
gboolean | rb_shell_player_do_next ()
char * | rb_shell_player_get_playing_time_string ()
gboolean | rb_shell_player_get_playing_time ()
gboolean | rb_shell_player_set_playing_time ()
gboolean | rb_shell_player_seek ()
long | rb_shell_player_get_playing_song_duration ()
gboolean | rb_shell_player_get_playing ()
gboolean | rb_shell_player_get_playing_path ()
void | rb_shell_player_set_playback_state ()
gboolean | rb_shell_player_get_playback_state ()
RhythmDBEntry * | rb_shell_player_get_playing_entry ()
gboolean | rb_shell_player_set_volume ()
gboolean | rb_shell_player_get_volume ()
gboolean | rb_shell_player_set_volume_relative ()
gboolean | rb_shell_player_set_mute ()
gboolean | rb_shell_player_get_mute ()
void | rb_shell_player_add_play_order ()
void | rb_shell_player_remove_play_order ()

## Properties

RhythmDB * | db | Read / Write / Construct Only
gboolean | has-next | Read
gboolean | has-prev | Read
RBHeader * | header | Read / Write
gboolean | mute | Read / Write
gchar * | play-order | Read
GObject * | player | Read
gboolean | playing | Read
gboolean | playing-from-queue | Read
gboolean | queue-only | Read / Write
RBPlaylistSource * | queue-source | Read / Write
RBSource * | source | Read / Write
gfloat | volume | Read / Write

## Signals

void | elapsed-changed | Run Last
void | elapsed-nano-changed | Run Last
void | playing-changed | Run Last
void | playing-song-changed | Run Last
void | playing-song-property-changed | Run Last
void | playing-source-changed | Run Last
void | playing-uri-changed | Run Last
void | window-title-changed | Run Last

## Types and Values

enum | RBShellPlayerError
struct | RBShellPlayer
struct | RBShellPlayerClass

## Object Hierarchy

        GEnum
        ╰── RBShellPlayerError
        GObject
        ╰── RBShellPlayer

## 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 stream 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.

## Functions

### rb_shell_player_error_quark ()

    GQuark
    rb_shell_player_error_quark (void);

#### Returns

### rb_shell_player_new ()

    RBShellPlayer *
    rb_shell_player_new (RhythmDB *db);

Creates the RBShellPlayer

#### Parameters

db | the RhythmDB |

#### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

player | the RBShellPlayer |

#### Returns

the current playing RBSource.

[transfer none]

### 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.

#### Parameters

player | the RBShellPlayer |

#### Returns

the active RBSource.

[transfer none]

### rb_shell_player_jump_to_current ()

    void
    rb_shell_player_jump_to_current (RBShellPlayer *player);

### rb_shell_player_play_entry ()

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

Plays a specified entry.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

player | the RBShellPlayer |
time | returns the current playback position. | [out]
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.

#### Parameters

player | the RBShellPlayer |
time | the target playback position (in seconds) |
error | returns error information |

#### Returns

`TRUE` if successful

### rb_shell_player_seek ()

    gboolean
    rb_shell_player_seek (RBShellPlayer *player,
                          gint32 offset,
                          GError **error);

Seeks forwards or backwards in the current playing song. Fails if the current song is not seekable.

#### Parameters

player | the RBShellPlayer |
offset | relative seek target (in seconds) |
error | returns error information |

#### Returns

`TRUE` if successful

### 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.

#### Parameters

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.

#### Parameters

player | a RBShellPlayer |
playing | playback state return. | [out]
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.

#### Parameters

player | the RBShellPlayer |
path | returns the URI of the current playing entry. | [out callee-allocates][transfer full]
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.

#### Parameters

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.

#### Parameters

player | the RBShellPlayer |
shuffle | returns the current shuffle setting. | [out]
repeat | returns the current repeat setting. | [out]

#### 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.

#### Parameters

player | the RBShellPlayer |

#### Returns

the currently playing RhythmDBEntry, or NULL.

[transfer full][allow-none]

### rb_shell_player_set_volume ()

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

Sets the playback volume level.

#### Parameters

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

#### Parameters

player | the RBShellPlayer |
volume | returns the volume level. | [out]
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.

#### Parameters

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.

#### Parameters

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

#### Parameters

player | the RBShellPlayer |
mute | returns the current mute setting. | [out]
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.

#### Parameters

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.

#### Parameters

player | the RBShellPlayer |
name | name of the play order to remove |

## Types and Values

### enum RBShellPlayerError

#### Members

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

### struct RBShellPlayer

    struct RBShellPlayer;

### struct RBShellPlayerClass

    struct RBShellPlayerClass {
    	GObjectClass 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);
    };

## Property Details

### The `“db”` property

      “db”                       RhythmDB *

The RhythmDB

Flags: Read / Write / Construct Only

### The `“has-next”` property

      “has-next”                 gboolean

Whether there is a track to play after the current track.

Flags: Read

Default value: FALSE

### The `“has-prev”` property

      “has-prev”                 gboolean

Whether there was a previous track before the current track.

Flags: Read

Default value: FALSE

### The `“header”` property

      “header”                   RBHeader *

The RBHeader object

Flags: Read / Write

### The `“mute”` property

      “mute”                     gboolean

Whether playback is currently muted.

Flags: Read / Write

Default value: FALSE

### The `“play-order”` property

      “play-order”               gchar *

The current play order object.

Flags: Read

Default value: "linear"

### The `“player”` property

      “player”                   GObject *

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

Flags: Read

### The `“playing”` property

      “playing”                  gboolean

Whether Rhythmbox is currently playing something

Flags: Read

Default value: FALSE

### The `“playing-from-queue”` property

      “playing-from-queue”       gboolean

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

Flags: Read

Default value: FALSE

### The `“queue-only”` property

      “queue-only”               gboolean

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

Flags: Read / Write

Default value: FALSE

### The `“queue-source”` property

      “queue-source”             RBPlaylistSource *

The play queue source

Flags: Read / Write

### The `“source”` property

      “source”                   RBSource *

The current source that is selected for playback.

Flags: Read / Write

### The `“volume”` property

      “volume”                   gfloat

The current playback volume (between 0.0 and 1.0)

Flags: Read / Write

Allowed values: [0,1]

Default value: 1

## Signal Details

### The `“elapsed-changed”` signal

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

Emitted when the playback position changes.

#### Parameters

player | the RBShellPlayer |
elapsed | the new playback position in seconds |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“elapsed-nano-changed”` signal

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

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.

#### Parameters

player | the RBShellPlayer |
elapsed | the new playback position in nanoseconds |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“playing-changed”` signal

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

Emitted when playback either stops or starts.

#### Parameters

player | the RBShellPlayer |
playing | flag indicating playback state |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“playing-song-changed”` signal

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

Emitted when the playing database entry changes

#### Parameters

player | the RBShellPlayer |
entry | the new playing RhythmDBEntry |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“playing-song-property-changed”` signal

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

Emitted when a property of the playing database entry changes.

#### Parameters

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. |

Flags: Run Last

### The `“playing-source-changed”` signal

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

Emitted when a new RBSource instance starts playing

#### Parameters

player | the RBShellPlayer |
source | the RBSource that is now playing |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“playing-uri-changed”` signal

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

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

#### Parameters

player | the RBShellPlayer |
uri | the URI of the new playing entry |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“window-title-changed”` signal

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

Emitted when the main window title text should be changed

#### Parameters

player | the RBShellPlayer |
title | the new window title |
user_data | user data set when the signal handler was connected. |

Flags: Run Last