foo_rpc API methods

This section contains a thorough description of each method that foo_rpc accepts. The parameters of the methods are expected to be packed with msgpack.

CoreVersion.get_name()

Returns:string

Return the name of the program, e.g. “foobar2000”.

CoreVersion.get_version_as_text()

Returns:string

Return the version string of the program, in the form “N.N.N.N”

PlaylistLoader.load_playlist(string playlist)

Returns:bool

Attempts to load a playlist file from specified filesystem path.

PlaylistLoader.save_playlist(string playlist_path, vector<string> files)

Returns:bool

Saves specified list of locations into a playlist file.

PlaybackControl.get_now_playing()

Returns:tuple<bool, optional<Track>>

Retrieves now playing item handle. Returns true on success, false on failure (not playing).

PlaybackControl.start(tuple<play_control::t_track_command, bool>)

Starts playback. If playback is already active, existing process is stopped first.

The first parameter specifies what track to start playback from. See t_track_Command enum from foobar2000’s SDK for more info.

The second parameter specifies whether playback should be started as paused.

PlaybackControl.stop()

Stops playback.

PlaybackControl.is_playing()

Returns:bool

Returns whether playback is active.

PlaybackControl.is_paused()

Returns:bool

Returns whether playback is active and in paused state.

PlaybackControl.pause(bool p_state)

Toggles pause state if playback is active.

Parameters:p_state – set to true when pausing or to false when unpausing.

PlaybackControl.get_stop_after_current()

Returns:bool

Retrieves stop-after-current-track option state.

PlaybackControl.set_stop_after_current(bool p_state)

Alters stop-after-current-track option state.

PlaybackControl.set_volume(float p_value)

Alters playback volume level. :param p_value: volume in dB; 0 for full volume.

PlaybackControl.get_volume()

Returns:float

Retrieves playback volume level. Returns current playback volume level, in dB; 0 for full volume.

PlaybackControl.volume_up()

Alters playback volume level one step up.

PlaybackControl.volume_down()

Alters playback volume level one step down.

PlaybackControl.volume_mute_toggle()

Toggles playback mute state.

PlaybackControl.playback_seek(double p_time)

Seeks in currenly played track to specified time. :param p_time: target time in seconds.

PlaybackControl.playback_seek_delta(double p_delta)

Seeks in currently played track by specified time forward or back. :param p_delta: time in seconds to seek by; can be positive to seek forward or negative to seek back.

PlaybackControl.playback_can_seek()

Returns:bool

Returns whether currently played track is seekable. If it’s not, playback_seek/playback_seek_delta calls will be ignored.

PlaybackControl.playback_get_position()

Returns:double

Returns current playback position within currently played track, in seconds.

PlaybackControl.playback_format_title(string script)

Returns:string

Renders information about currently playing item. The script represents the query to use for formatting the current playing item.

PlaybackControl.playback_format_title_complete()

Returns:string

Similar to PlaybackControl.playback_format_title(), with the caveat that this function has the script hardcoded.

PlaybackControl.playback_get_length()

Returns:double

Retrieves length of currently playing item.

PlaybackControl.playback_get_length_ex()

Returns:double

Extended version: queries dynamic track info for the rare cases where that is different from static info.

PlaybackControl.toggle_stop_after_current()

Toggles stop-after-current state.

PlaybackControl.toggle_pause()

Toggles pause state.

PlaybackControl.play_or_pause()

Starts playback if playback is inactive, otherwise toggles pause.

PlaybackControl.play_or_unpause()

PlaybackControl.next()

PlaybackControl.previous()

PlaybackControl.is_muted()

Returns:bool

Check if the volume is muted.

PlaybackControl.get_volume_step()

Returns:double

Returns user-specified the step dB value for volume decrement/increment.

Playlist.get_playlist_count()

Returns:t_size

Returns number of playlists.

Playlist.get_active_playlist()

Returns:t_size

Retrieves index of active playlist; infinite if no playlist is active.

Playlist.set_active_playlist(t_size)

Sets active playlist (infinite to set no active playlist)

Playlist.get_playing_playlist()

Returns:t_size

Retrieves playlist from which items to be played are taken from.

Playlist.set_playing_playlist(t_size)

Sets playlist from which items to be played are taken from.

Playlist.remove_playlists(vector<t_size>)

Removes playlists with the ids from the given list.

Playlist.create_playlist(string name, t_size length, t_size index)

Returns:size_t

Creates a playlist with the given name. Do note that the API needs the length of the name. For instance, this might be useful in case the name is UTF-8, in which case the actual length might be double than what is expected.

Playlist.create_playlist_ex(string name, t_size length, t_size index, vector<string> files)

Returns:size_t

Creates a playlist with the given name. Similar notes to Playlist.create_playlist() applies. The files parameter contains the files that are added to the initial content of the playlist.

Playlist.reorder(vector<int> permutations)

Returns:bool

Reorder the playlists according to the given permutations.

Playlist.playlist_get_item_count(t_size playlist)

Returns:size_t

Get the number of items from the given playlist.

Playlist.activeplaylist_get_item_count()

Returns:size_t

Get the number of items from the active playlist.

Playlist.playlist_get_name(t_size playlist)

Returns:string

Get the playlist’s name.

Playlist.activeplaylist_get_name()

Returns:string

Get the name of the active playlist.

Playlist.playlist_reorder_items(t_size playlist, vector<int> permutation)

Returns:bool

Reorder the items in the specified playlist according to the specified permutation.

Playlist.activeplaylist_reorder_items(vector<int> permutation)

Returns:bool

Reorder the items in the active playlist according to the specified permutation.

Playlist.playlist_remove_items(t_size playlist, vector<t_size> items)

Returns:bool

Remove the specified items from the given playlist.

Playlist.activeplaylist_remove_items(vector<t_size> items)

Returns:bool

Remove the specified items from the active playlist.

Playlist.playlist_replace_item(t_size playlist, t_size item, t_size replacee)

Returns:bool

Replace the given item with the one specified by the replacee parameter, in the given playlist.

Playlist.activeplaylist_replace_item(t_size item, t_size replacee)

Returns:bool

Replace the given item with the one specified by the replacee parameter, in the active playlist.

Playlist.playlist_insert_items(t_size playlist, t_size base, vector<string> files)

Returns:t_size

Insert the given files at the specified position, in the given playlist.

Playlist.activeplaylist_insert_items(t_size base, vector<string> files)

Returns:t_size

Insert the given files at the specified position, in the active playlist.

Playlist.playlist_rename(t_size playlist, std::string name, t_size length)

Returns:bool

Change the name of the given playlist.

Playlist.activeplaylist_rename(std::string name, t_size length)

Returns:bool

Change the name of the active playlist.

Playlist.playlist_activate_next()

Activate the next playlist.

Playlist.playlist_activate_previous()

Activate the previous playlist.

Playlist.playlist_add_items(t_size playlist, vector<string> files)

Returns:t_size

Add the given files in the given playlist.

Playlist.activeplaylist_add_items(vector<string> files)

Returns:t_size

Add the given files in the active playlist.

Playlist.playlist_item_format_title(t_size playlist, t_size item, string format)

Returns:string

Format the given item with the given format string. The item is retrieved from the given playlist.

Playlist.activeplaylist_item_format_title(t_size item, string format)

Returns:string

Format the given item with the given format string. The item is retrieved from the active playlist.

Playlist.get_playing_item_location()

Returns:std::tuple<bool, t_size, t_size>

Get the playing item location. It returns a tuple of three elements, where the first element is a bool representing if there is a playing item or not, the second item represents the playlist where the playing item is located and the last element is the playing item’s position in the given playlist.

Playlist.playlist_sort_by_format(t_size playlist, string format, bool sel_only)

Returns:bool

Sort the given playlist by the given format string. The last parameter controls if the sorting should be done on the selection only or not.

Playlist.activeplaylist_sort_by_format(string format, bool sel_only)

Returns:bool

Sort the active playlist by the given format string. The last parameter controls if the sorting should be done on the selection only or not.

Playlist.playback_order_get_count()

Returns:t_size

Get the number of the playback items.

Playlist.playback_order_get_name(t_size item)

Returns:string

Get the name of the given playback item.

Playlist.playback_order_get_active()

Returns:t_size

Get the index of the active playback order item.

Playlist.playback_order_set_active(t_size item)

Set the given playback order item as active.

Playlist.queue_add_item_playlist(t_size playlist, t_size p_item)

Add the given item, from the given playlist, into the playback queue.

Playlist.queue_get_count()

Returns:t_size

Get the number of items in the playback queue.

Playlist.queue_get_contents()

Returns:std::vector<std::map<std::string, t_size>>

Return the list of playback queue’s items. A playback queue’s item is represented as a dictionary, containing the song’s position and its playlist.

Playlist.queue_remove_mask(vector<t_size> items)

Remove the given items from the playback queue.

Playlist.queue_flush()

Remove all the items from the playback queue.

Playlist.queue_is_active()

Returns:bool

Check if the playback queue is active.

Playlist.remove_playlist(t_size playlist)

Returns:bool

Remove the given playlist.

Playlist.remove_playlist_switch(t_size playlist)

Returns:bool

Remove the given playlist and the switch to the next one.

Playlist.playlist_clear(t_size playlist)

Clear the given playlist.

Playlist.activeplaylist_clear()

Clear the active playlist.

Playlist.create_playlist_autoname(t_size position.)

Returns:t_size

Create a playlist with a default name at the specified position.

Playlist.reset_playlist_playlist()

Playlist.find_playlist(string name, t_size length)

Returns:t_size

Find the playlist with the given name.

Playlist.find_or_create_playlist(string name, t_size length)

Returns:t_size

Find the playlist with the given name. If it does not exist, it is going to be created with the given name.

Playlist.get_all_items(t_size playlist)

Returns:std::vector<Track>

Get all the items from the given playlist. Returns a list of tracks, where a track is a tuple of pairs, as in:

(
    ("index", song_index),
    ("path", song_path),
    ("selected", is_song_selected),
    ("subsong_index", subsong_index)
)

Playlist.activeplaylist_get_all_items()

Returns:std::vector<Track>

See the documentation of Playlist.get_all_items()

Playlist.playlist_get_item_handle(t_size playlist, t_size item)

Returns:optional<Track>

Get the handle of the given item, from the given playlist. If the item does not exist, this function will return a null. Otherwise, it will return a Track object, which is a tuple of pairs, with the format:

(
    ("index", song_index),
    ("path", song_path),
    ("selected", is_song_selected),
    ("subsong_index", subsong_index)
)

Playlist.activeplaylist_get_item_handle(t_size item)

Returns:optional<Track>

Get the handle of the given item, from the active playlist.

Playlist.playlist_get_items(t_size playlist, vector<t_size> masks)

Returns:std::vector<Track>

Get the items specified by masks from the given playlist.

Playlist.activeplaylist_get_items(vector<t_size> masks)

Returns:std::vector<Track>

Get the items specified by masks from the active playlist.