![]() |
![]() |
![]() |
Rhythmbox Development Reference Manual | ![]() |
---|---|---|---|---|
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, long 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);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBox +----GtkHBox +----RBShellPlayer
"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
"elapsed-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
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.
typedef struct { GtkHBoxClass parent_class; void (*window_title_changed) (RBShellPlayer *player, const char *window_title); void (*elapsed_changed) (RBShellPlayer *player, guint 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;
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;
RBShellPlayer* rb_shell_player_new (RhythmDB *db, GtkUIManager *mgr, GtkActionGroup *actiongroup);
Creates the RBShellPlayer
|
the RhythmDB |
|
the GtkUIManager |
|
the GtkActionGroup to use |
Returns : |
the RBShellPlayer instance |
void rb_shell_player_set_selected_source (RBShellPlayer *player, RBSource *source);
Updates the player to reflect a new source being selected.
|
the RBShellPlayer |
|
the RBSource to select |
void rb_shell_player_set_playing_source (RBShellPlayer *player, RBSource *source);
Replaces the current playing source.
|
the RBShellPlayer |
|
the new playing RBSource |
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.
|
the RBShellPlayer |
Returns : |
the current playing RBSource |
RBSource* rb_shell_player_get_active_source (RBShellPlayer *player);
Retrieves the active source. This is the source that the user selected for playback.
|
the RBShellPlayer |
Returns : |
the active RBSource |
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.
|
the RBShellPlayer |
void rb_shell_player_play_entry (RBShellPlayer *player, RhythmDBEntry *entry, RBSource *source);
Plays a specified entry.
|
the RBShellPlayer |
|
the RhythmDBEntry to play |
|
the new RBSource to set as playing (or NULL to use the selected source) |
gboolean rb_shell_player_play (RBShellPlayer *player, GError **error);
Starts playback, if it is not already playing.
|
a RBShellPlayer |
|
error return |
Returns : |
whether playback is now occurring (TRUE when successfully started or already playing). |
gboolean rb_shell_player_pause (RBShellPlayer *player, GError **error);
Pauses playback if possible, completely stopping if not.
|
a RBShellPlayer |
|
error return |
Returns : |
whether playback is not occurring (TRUE when successfully paused/stopped or playback was not occurring). |
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.
|
the RBShellPlayer |
|
nothing |
|
returns error information |
Returns : |
TRUE if successful
|
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.
|
a RBShellPlayer. |
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.
|
the RBShellPlayer |
|
returns any error information |
Returns : |
TRUE if successful
|
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.
|
the RBShellPlayer |
|
returns error information |
Returns : |
TRUE if successful
|
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.
|
the RBShellPlayer |
Returns : |
allocated playing time string |
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.
|
the RBShellPlayer |
|
returns the current playback position |
|
returns error information |
Returns : |
TRUE if successful
|
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.
|
the RBShellPlayer |
|
the target playback position (in seconds) |
|
returns error information |
Returns : |
TRUE if successful
|
void rb_shell_player_seek (RBShellPlayer *player, long offset );
Seeks forwards or backwards in the current playing song. Does not return error information.
|
the RBShellPlayer |
|
long rb_shell_player_get_playing_song_duration (RBShellPlayer *player);
Retrieves the duration of the current playing song.
|
the RBShellPlayer |
Returns : |
duration, or -1 if not playing |
gboolean rb_shell_player_get_playing (RBShellPlayer *player, gboolean *playing, GError **error);
Reports whether playback is occuring by setting playing.
|
a RBShellPlayer |
|
playback state return |
|
error return |
Returns : |
TRUE if successful
|
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.
|
the RBShellPlayer |
|
returns the URI of the current playing entry |
|
returns error information |
Returns : |
TRUE if successful
|
void rb_shell_player_set_playback_state (RBShellPlayer *player, gboolean shuffle, gboolean repeat);
Sets the state of the shuffle and repeat settings.
|
the RBShellPlayer |
|
whether to enable the shuffle setting |
|
whether to enable the repeat setting |
gboolean rb_shell_player_get_playback_state (RBShellPlayer *player, gboolean *shuffle, gboolean *repeat);
Retrieves the current state of the shuffle and repeat settings.
|
the RBShellPlayer |
|
returns the current shuffle setting |
|
returns the current repeat setting |
Returns : |
TRUE if successful.
|
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.
|
the RBShellPlayer |
Returns : |
the currently playing RhythmDBEntry, or NULL |
void rb_shell_player_toggle_mute (RBShellPlayer *player);
Toggles the mute setting on the player.
|
the RBShellPlayer |
gboolean rb_shell_player_set_volume (RBShellPlayer *player, gdouble volume, GError **error);
Sets the playback volume level.
|
the RBShellPlayer |
|
the volume level (between 0 and 1) |
|
returns the error information |
Returns : |
TRUE on success
|
gboolean rb_shell_player_get_volume (RBShellPlayer *player, gdouble *volume, GError **error);
|
the RBShellPlayer |
|
returns the volume level |
|
returns error information |
Returns : |
the current volume level. |
gboolean rb_shell_player_set_volume_relative (RBShellPlayer *player, gdouble delta, GError **error);
Adds the specified value to the current volume level.
|
the RBShellPlayer |
|
difference to apply to the volume level (between -1 and 1) |
|
returns error information |
Returns : |
TRUE on success
|
gboolean rb_shell_player_set_mute (RBShellPlayer *player, gboolean mute, GError **error);
Updates the mute setting on the player.
|
the RBShellPlayer |
|
TRUE to mute playback
|
|
returns error information |
Returns : |
TRUE if successful
|
gboolean rb_shell_player_get_mute (RBShellPlayer *player, gboolean *mute, GError **error);
|
the RBShellPlayer |
|
returns the current mute setting |
|
returns error information |
Returns : |
TRUE if currently muted
|
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.
|
the RBShellPlayer |
|
name of the new play order |
|
description of the new play order |
|
the GType of the play order class |
|
if TRUE , don't display the play order in the UI
|
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.
|
the RBShellPlayer |
|
name of the play order to remove |
"action-group"
property"action-group" GtkActionGroup* : Read / Write / Construct Only
GtkActionGroup object.
"play-order"
property"play-order" gchar* : Read
What play order to use.
Default value: "linear"
"playing"
property"playing" gboolean : Read
Whether Rhythmbox is currently playing.
Default value: FALSE
"playing-from-queue"
property"playing-from-queue" gboolean : Read
Whether playing from the play queue or not.
Default value: FALSE
"queue-only"
property"queue-only" gboolean : Read / Write
Activation only adds to queue.
Default value: FALSE
"queue-source"
property"queue-source" RBPlaylistSource* : Read / Write
RBPlaylistSource object.
"ui-manager"
property"ui-manager" GtkUIManager* : Read / Write / Construct Only
GtkUIManager object.
"volume"
property"volume" gfloat : Read / Write
Current playback volume.
Allowed values: [0,1]
Default value: 1
"elapsed-changed"
signalvoid user_function (RBShellPlayer *player, guint elapsed, gpointer user_data) : Run Last
Emitted when the playback position changes.
|
the RBShellPlayer |
|
the new playback position in seconds |
|
user data set when the signal handler was connected. |
"missing-plugins"
signalgboolean 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.
|
the RBShellPlayer |
|
the list of plugin detail strings describing the missing plugins |
|
the list of descriptions for the missing plugins |
|
a GClosure to be called when the plugin installation is complete |
|
user data set when the signal handler was connected. |
"playing-changed"
signalvoid user_function (RBShellPlayer *player, gboolean playing, gpointer user_data) : Run Last
Emitted when playback either stops or starts.
|
the RBShellPlayer |
|
flag indicating playback state |
|
user data set when the signal handler was connected. |
"playing-song-changed"
signalvoid user_function (RBShellPlayer *player, RhythmDBEntry *entry, gpointer user_data) : Run Last
Emitted when the playing database entry changes
|
the RBShellPlayer |
|
the new playing RhythmDBEntry |
|
user data set when the signal handler was connected. |
"playing-song-property-changed"
signalvoid 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.
|
the RBShellPlayer |
|
the URI of the playing entry |
|
the name of the property that changed |
|
the previous value for the property |
|
the new value of the property |
|
user data set when the signal handler was connected. |
"playing-source-changed"
signalvoid user_function (RBShellPlayer *player, RBSource *source, gpointer user_data) : Run Last
Emitted when a new RBSource instance starts playing
|
the RBShellPlayer |
|
the RBSource that is now playing |
|
user data set when the signal handler was connected. |
"playing-uri-changed"
signalvoid user_function (RBShellPlayer *player, gchar *uri, gpointer user_data) : Run Last
Emitted when the playing database entry changes, providing the URI of the entry.
|
the RBShellPlayer |
|
the URI of the new playing entry |
|
user data set when the signal handler was connected. |
"window-title-changed"
signalvoid user_function (RBShellPlayer *player, gchar *title, gpointer user_data) : Run Last
Emitted when the main window title text should be changed
|
the RBShellPlayer |
|
the new window title |
|
user data set when the signal handler was connected. |