paracusia

v0.2.11

paracusia v0.2.11 Paracusia.MpdClient.Queue

Functions related to the current playlist / queue.

See also: https://musicpd.org/doc/protocol/queue.html

Note that, unlike the official specification, we use the term "queue" rather than "playlist" in order to distinguish MPD playlists saved in the playlists directory in m3u format from the current playlist. Furthermore, we use the term id when referring to the unique identifier of a song in the entire database, and the term position when referring to a zero-based index inside the queue. According to the authors of MPD, "Using song ids [instead of positions] is a safer method when multiple clients are interacting with MPD."

Link to this section Summary

Functions

add(uri)

Adds the file uri to the queue

add_id(uri)

Adds the uri to the end of the queue (non-recursively) and returns the song id

add_id(uri, pos)

Adds the uri at the given position to the queue (non-recursively) and returns the song id

add_tag_id(id, tag, value)

Adds a tag to the song with the given id

changed_since(version)

Returns a list of maps containing all songs from the queue that changed since version

changed_since_pos_id(version)

Similar to changes/1 but the songs contain only the position and the id instead of the complete metadata

clear()

Clears the queue

clear_all_tags(id)

Removes all tags from the song with the given id

clear_tag_id(id, tag)

Removes the given tag from the song with the given id

delete_id(id)

Deletes the song with the given id from the queue

delete_pos(position)

Deletes the song at position from the queue

delete_range(arg)

Deletes songs from the given range from the queue

find(filters)

Same as Paracusia.MpdClient.Database.find/1, except that it searches for songs from the queue

move(from, to)

Moves the song/songs from the given position/range to to in the queue

move_id(from, to)

Moves the song with id from to position to in the queue

range_id(id, start, until)

Specifies the portion of the song that shall be played

remove_range(id)

Removes the range that was previously set by calling range_id/3

search(filters)

Searches case-insensitively for partial matches in the queue

set_priority(prio, arg)

Sets the priority of the songs in the given range to prio

set_priority_from_id(prio, ids)

Same as set_priority/2, except songs are addressed with their id

shuffle()

Shuffles the queue

shuffle(arg)

Shuffles the queue in the given range

song_info_from_id(id)

Returns a map containing info about the songs with the given id

song_info_from_pos(songpos)

Returns a map containing info about the song at position songpos

songs_info()

Returns a list of maps containing info about the songs currently in the queue

songs_info_from_range(arg)

Returns a list of maps containing info about the songs in the given range

swap(pos1, pos2)

Swaps the positions of the songs at the given positions pos1 and pos2

swap_id(id1, id2)

Swaps the positions of the songs with ids id1 and id2

Link to this section Functions

Link to this function

add(uri) 
add(String.t()) :: :ok | Paracusia.MpdTypes.mpd_error()

Adds the file uri to the queue.

Directories are added recursively. uri can also be a single file.

Link to this function

add_id(uri) 
add_id(String.t()) ::
  {:ok, Paracusia.MpdTypes.id()} | Paracusia.MpdTypes.mpd_error()

Adds the uri to the end of the queue (non-recursively) and returns the song id.

Link to this function

add_id(uri, pos) 
add_id(String.t(), Paracusia.MpdTypes.position()) ::
  {:ok, Paracusia.MpdTypes.id()} | Paracusia.MpdTypes.mpd_error()

Adds the uri at the given position to the queue (non-recursively) and returns the song id.

Link to this function

add_tag_id(id, tag, value) 
add_tag_id(Paracusia.MpdTypes.id(), Paracusia.MpdTypes.tag(), String.t()) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Adds a tag to the song with the given id.

Editing song tags is only possible for remote songs. This change is volatile: it may be overwritten by tags received from the server, and the data is gone when the song gets removed from the queue.

Link to this function

changed_since(version) 
changed_since(integer()) :: {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Returns a list of maps containing all songs from the queue that changed since version.

To detect songs that were deleted at the end of the queue, use the playlist_length key inside the map returned by Paracusia.MpdClient.Status.status/0.

Link to this function

changed_since_pos_id(version) 
changed_since_pos_id(integer()) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Similar to changes/1 but the songs contain only the position and the id instead of the complete metadata.

This is more bandwith efficient than changes/1. To detect songs that were deleted at the end of the queue, use the playlist_length key inside the map returned by Paracusia.MpdClient.Status.status/0.

Link to this function

clear() 
clear() :: :ok | Paracusia.MpdTypes.mpd_error()

Clears the queue.

Link to this function

clear_all_tags(id) 
clear_all_tags(Paracusia.MpdTypes.id()) :: :ok | Paracusia.MpdTypes.mpd_error()

Removes all tags from the song with the given id.

Link to this function

clear_tag_id(id, tag) 
clear_tag_id(Paracusia.MpdTypes.id(), Paracusia.MpdTypes.tag()) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Removes the given tag from the song with the given id.

Link to this function

delete_id(id) 
delete_id(Paracusia.MpdTypes.id()) :: :ok | Paracusia.MpdTypes.mpd_error()

Deletes the song with the given id from the queue.

Link to this function

delete_pos(position) 
delete_pos(Paracusia.MpdTypes.position()) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Deletes the song at position from the queue.

Link to this function

delete_range(arg) 
delete_range(Paracusia.MpdTypes.range()) :: :ok | Paracusia.MpdTypes.mpd_error()

Deletes songs from the given range from the queue.

Link to this function

find(filters) 
find([{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Same as Paracusia.MpdClient.Database.find/1, except that it searches for songs from the queue.

Link to this function

move(from, to) 
move(
  Paracusia.MpdTypes.position() | Paracusia.MpdTypes.range(),
  Paracusia.MpdTypes.position()
) :: :ok | Paracusia.MpdTypes.mpd_error()

Moves the song/songs from the given position/range to to in the queue.

from can be either a position or a range.

Link to this function

move_id(from, to)

Moves the song with id from to position to in the queue.

If to is negative, it is relative to the current song in the queue (if there is one).

Link to this function

range_id(id, start, until) 
range_id(Paracusia.MpdTypes.id(), integer(), integer()) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Specifies the portion of the song that shall be played.

start and until are offsets in seconds (fractional seconds allowed). A song that is currently playing cannot be manipulated this way.

Link to this function

remove_range(id) 
remove_range(Paracusia.MpdTypes.id()) :: :ok | Paracusia.MpdTypes.mpd_error()

Removes the range that was previously set by calling range_id/3.

Link to this function

search(filters) 
search([{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Searches case-insensitively for partial matches in the queue.

See Paracusia.MpdClient.Database.find/1, for a usage example.

Link to this function

set_priority(prio, arg) 
set_priority(integer(), Paracusia.MpdTypes.range()) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Sets the priority of the songs in the given range to prio.

A higher priority means that it will be played first when "random" mode is enabled. A priority is an integer between 0 and 255. The default priority of new songs is 0.

Link to this function

set_priority_from_id(prio, ids) 
set_priority_from_id(
  integer(),
  Paracusia.MpdTypes.id() | [Paracusia.MpdTypes.id()]
) :: :ok | Paracusia.MpdTypes.mpd_error()

Same as set_priority/2, except songs are addressed with their id.

Link to this function

shuffle() 
shuffle() :: :ok | Paracusia.MpdTypes.mpd_error()

Shuffles the queue.

Link to this function

shuffle(arg) 
shuffle(Paracusia.MpdTypes.range()) :: :ok | Paracusia.MpdTypes.mpd_error()

Shuffles the queue in the given range.

Link to this function

song_info_from_id(id) 
song_info_from_id(Paracusia.MpdTypes.id()) ::
  {:ok, map()} | Paracusia.MpdTypes.mpd_error()

Returns a map containing info about the songs with the given id.

Link to this function

song_info_from_pos(songpos) 
song_info_from_pos(Paracusia.MpdTypes.position()) ::
  {:ok, map()} | Paracusia.MpdTypes.mpd_error()

Returns a map containing info about the song at position songpos.

Link to this function

songs_info() 
songs_info() :: {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Returns a list of maps containing info about the songs currently in the queue.

Link to this function

songs_info_from_range(arg) 
songs_info_from_range(Paracusia.MpdTypes.range()) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Returns a list of maps containing info about the songs in the given range.

Link to this function

swap(pos1, pos2) 
swap(Paracusia.MpdTypes.position(), Paracusia.MpdTypes.position()) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Swaps the positions of the songs at the given positions pos1 and pos2.

Link to this function

swap_id(id1, id2) 
swap_id(Paracusia.MpdTypes.id(), Paracusia.MpdTypes.id()) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Swaps the positions of the songs with ids id1 and id2.