Module: MPD::Plugins::Queue

Included in:
MPD
Defined in:
lib/ruby-mpd/plugins/queue.rb

Overview

These commands manipulate the current playlist, what’s playing now. For a distinction between this and other playlists, this is called queue.

Instance Method Summary collapse

Instance Method Details

#add(path) ⇒ Boolean

Add the file path to the queue. If path is a directory, it will be added recursively.

Returns:

  • (Boolean) —

    returns true if successful.



21
22
23
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 21

def add(path)
  send_command :add, path
end

#addid(path, pos = nil) ⇒ Integer

Adds a song to the queue (non-recursive) and returns the song id. Optionally, one can specify the position on which to add the song (since MPD 0.14).

Returns:

  • (Integer) —

    id of the song that was added.



28
29
30
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 28

def addid(path, pos=nil)
  send_command :addid, path, pos
end

#clear ⇒ Boolean

Clears the current queue.

Returns:

  • (Boolean) —

    returns true if successful.



34
35
36
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 34

def clear
  send_command :clear
end

#delete(pos) ⇒ Boolean

Deletes the song from the queue.

Since MPD 0.15 a range can also be passed. Songs with positions within range will be deleted. if range is passed, songs with positions within range will be deleted.

Parameters:

  • pos (Integer, Range) —

    Song with position in the queue will be deleted,

  • pos (Hash) —

    :id to specify the song ID to delete instead of position.

Returns:

  • (Boolean) —

    returns true if successful.



45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 45

def delete(pos)
  if pos.is_a?(Hash)
    if pos[:id]
      send_command :deleteid, pos[:id]
    else
      raise ArgumentError, 'Only :id key is allowed!'
    end
  else
    send_command :delete, pos
  end
end

#move(from, to) ⇒ Boolean

Move the song at from to to in the queue.

  • Since 0.14, to can be a negative number, which is the offset of the song from the currently playing (or to-be-played) song. So -1 would mean the song would be moved to be the next song in the queue. Moving a song to -queue.length will move it to the song before the current song on the queue; so this will work for repeating playlists, too.

  • Since 0.15, from can be a range of songs to move.

Parameters:

  • from (Hash) —

    :id to specify the song ID to move instead of position.

Returns:

  • (Boolean) —

    returns true if successful.



66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 66

def move(from, to)
  if from.is_a?(Hash)
    if from[:id]
      send_command :moveid, from[:id], to
    else
      raise ArgumentError, 'Only :id key is allowed!'
    end
  else
    send_command :move, from, to
  end
end

#queue(limit = nil) ⇒ Array<MPD::Song>

List the current playlist/queue. An Integer or Range can be used to limit the information returned to a specific subset.

or a single song.

Returns:

  • (Array<MPD::Song>) —

    Array of songs in the queue



14
15
16
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 14

def queue(limit=nil)
  build_songs_list send_command(:playlistinfo, limit)
end

#queue_changes(version) ⇒ Array<MPD::Song>

List the changes since the specified version in the queue.

Returns:



128
129
130
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 128

def queue_changes(version)
  build_songs_list send_command(:plchanges, version)
end

#queue_search(type, what, options = {}) ⇒ Array<MPD::Song>

Deprecated.

Use #queue_where instead.

Searches for songs in the queue matched by the what argument. Case insensitive by default.

Parameters:

  • type (Symbol) —

    Can be any tag supported by MPD, or one of the two special parameters: :file to search by full path (relative to database root), and :any to match against all available tags.

  • options (Hash) (defaults to: {}) —

    Use :case_sensitive to make the query case sensitive.

Returns:



95
96
97
98
99
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 95

def queue_search(type, what, options = {})
  warn "MPD#queue_search is deprecated! Use MPD#where instead."
  options[:strict] = options[:case_sensitive] # transparently upgrade renamed option
  queue_where({type => what}, options)
end

#queue_where(params, options = {}) ⇒ Array<MPD::Song>

Searches the queue for any songs that match the specified parameters. Searching is loose (case insensitive and allow partial matching) by default.

The search keys can be any of the tags supported by MPD, or one of the two special parameters: :file to search by full path (relative to database root), and :any to match against all available tags.

mpd.queue_where(artist: "DJ Shadow", album: "Endtroducing.....")

A hash of options can be passed as a last parameter:

mpd.queue_where({artist: "Nujabes", album: "Modal Soul"}, {add: true})

Options:

  • strict: Search will be *case sensitive* and allow only *full matches*.

Parameters:

  • params (Hash) —

    A hash of search parameters.

  • options (Hash) (defaults to: {}) —

    A hash of options.

Returns:



121
122
123
124
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 121

def queue_where(params, options = {})
  command = options[:strict] ? :playlistfind : :playlistsearch
  build_songs_list send_command(command, params)
end

#save(playlist) ⇒ Boolean

Saves the current playlist/queue to playlist.m3u in the playlist directory.

Returns:

  • (Boolean) —

    returns true if successful.



183
184
185
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 183

def save(playlist)
  send_command :save, playlist
end

#shuffle(range = nil) ⇒ Boolean

Shuffles the queue. Optionally, a Range can be used to shuffle a specific subset.

Returns:

  • (Boolean) —

    returns true if successful.



162
163
164
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 162

def shuffle(range=nil)
  send_command :shuffle, range
end

#song_priority(priority, pos) ⇒ Object

Set the priority of the specified songs. A higher priority means that it will be played first when “random” mode is enabled.

Several ranges or ID’s can be specified at once:

mpd.song_priority(10, [5..7, 9..10]) # songs 5 to 10, excluding 8

mpd.song_priority(10, {id: [5, 8, 12]}) # songs with ID's 5, 8 and 12

Parameters:

  • priority (Integer) —

    An integer between 0 and 255. The default priority of new songs is 0.

  • pos (Integer) —

    A specific position.

  • pos (Range) —

    A range of positions.

  • pos (Hash) —

    :id to specify the song ID to move instead of position.



147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 147

def song_priority(priority, pos)
  if pos.is_a?(Hash)
    if pos[:id]
      send_command :prioid, priority, *pos[:id]
    else
      raise ArgumentError, 'Only :id key is allowed!'
    end
  else
    send_command :prio, priority, *pos
  end
end

#song_with_id(songid) ⇒ MPD::Song

Returns the song with the songid in the playlist,

Returns:



80
81
82
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 80

def song_with_id(songid)
  Song.new send_command(:playlistid, songid)
end

#swap(posA, posB) ⇒ Boolean

Swaps the song at position posA with the song as position posB in the queue.

Returns:

  • (Boolean) —

    returns true if successful.



169
170
171
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 169

def swap(posA, posB)
  send_command :swap, posA, posB
end

#swapid(songidA, songidB) ⇒ Boolean

Swaps the positions of the song with the id songidA with the song with the id songidB in the queue.

Returns:

  • (Boolean) —

    returns true if successful.



176
177
178
 
# File 'lib/ruby-mpd/plugins/queue.rb', line 176

def swapid(songidA, songidB)
  send_command :swapid, songidA, songidB
end