ruby-mpd 0.1.4 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/README.rdoc +54 -11
- data/lib/ruby-mpd.rb +3 -1
- data/lib/ruby-mpd/playlist.rb +12 -0
- data/lib/ruby-mpd/plugins/controls.rb +20 -25
- data/lib/ruby-mpd/plugins/database.rb +21 -22
- data/lib/ruby-mpd/plugins/queue.rb +53 -22
- data/ruby-mpd.gemspec +1 -1
- metadata +1 -1
data/README.rdoc
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
= ruby-mpd
|
2
2
|
|
3
3
|
ruby-mpd is a powerful object-oriented Music Player Daemon library, forked from librmpd.
|
4
|
-
librmpd is as of writing outdated by 6
|
4
|
+
librmpd is as of writing outdated by 6 years! This library tries to act as a successor,
|
5
5
|
originally using librmpd as a base, however almost all of the codebase was rewritten.
|
6
6
|
ruby-mpd supports all "modern" MPD features.
|
7
7
|
|
@@ -22,7 +22,7 @@ Require the library.
|
|
22
22
|
|
23
23
|
require 'ruby-mpd'
|
24
24
|
|
25
|
-
Then, make a new
|
25
|
+
Then, make a new MPD instance:
|
26
26
|
|
27
27
|
mpd = MPD.new 'localhost', 6600
|
28
28
|
|
@@ -31,8 +31,7 @@ You can also omit the host and/or port, and it will use the defaults.
|
|
31
31
|
mpd = MPD.new 'localhost'
|
32
32
|
mpd = MPD.new
|
33
33
|
|
34
|
-
|
35
|
-
Once you have an instance of the MPD class, connect to the server:
|
34
|
+
Once you have an instance of the MPD class, connect to the server.
|
36
35
|
|
37
36
|
mpd.connect
|
38
37
|
|
@@ -47,13 +46,57 @@ be fixed by enabling callbacks (see the Callbacks section) or by issuing a
|
|
47
46
|
Once connected, you can issue commands to talk to the server
|
48
47
|
|
49
48
|
mpd.connect
|
50
|
-
|
51
|
-
|
52
|
-
|
49
|
+
|
50
|
+
mpd.play if mpd.stopped?
|
51
|
+
|
53
52
|
song = mpd.current_song
|
54
53
|
puts "Current Song: #{song.artist} - #{song.title}"
|
55
54
|
|
56
|
-
You can find documentation for each command
|
55
|
+
You can find documentation for each command at http://www.rubydoc.info/github/archSeer/ruby-mpd/master/MPD
|
56
|
+
|
57
|
+
== Commands
|
58
|
+
|
59
|
+
Some commands accept "option hashes" besides their default values. For example, +#move+
|
60
|
+
accepts an ID key instead of the position:
|
61
|
+
|
62
|
+
mpd.move(1, 10) # => move first song to position 10.
|
63
|
+
|
64
|
+
mpd.move(:id => 1, 10) # => move the song with the ID of 1 to position 10.
|
65
|
+
|
66
|
+
Commands that accept ID's: +#move+, +#delete+, +#play+, +#song_priority+. +#seek+
|
67
|
+
accepts both +:pos+ and +:id+. *Note*: #swap and #swapid are still separate!
|
68
|
+
|
69
|
+
=== Ranges
|
70
|
+
|
71
|
+
Some commands also allow ranges instead of numbers, specifying a range of songs.
|
72
|
+
ruby-mpd correctly handles inclusive and exclusive ranges (1..10 vs 1...10).
|
73
|
+
For example, #queue allows us to return only a subset of the queue:
|
74
|
+
|
75
|
+
mpd.queue.count # => 20
|
76
|
+
|
77
|
+
mpd.queue(1..10).count # => 10
|
78
|
+
|
79
|
+
Move also allows this:
|
80
|
+
|
81
|
+
mpd.move 1, 10 # => move song 1 to position 10.
|
82
|
+
|
83
|
+
mpd.move 1..3, 10 # => move songs 1, 2 and 3 to position 10 (and 11 and 12).
|
84
|
+
|
85
|
+
Commands that support ranges: +#delete+, +#move+, +#queue+, +#song_priority+, +#shuffle+,
|
86
|
+
+MPD::Playlist#load+.
|
87
|
+
|
88
|
+
== Searching
|
89
|
+
|
90
|
+
Searching is case insensitive by default. To enable case sensitivity, pass a third
|
91
|
+
argument in as +:case_sensitive => true+. This does not work for Playlist#searchadd.
|
92
|
+
|
93
|
+
mpd.search(:artist, 'MyArtiSt', :case_sensitive => true)
|
94
|
+
|
95
|
+
While searching, one can also enable the +add+ option, which will automatically add
|
96
|
+
the songs the query returned to the queue. In that case, the response will only return
|
97
|
+
+true+, stating that the operation was successful (instead of returning an array).
|
98
|
+
|
99
|
+
mpd.search(:artist, 'MyArtiSt', {:case_sensitive => true, :add => true})
|
57
100
|
|
58
101
|
== Playlists
|
59
102
|
|
@@ -95,9 +138,8 @@ the server without having to worry about timeouts.
|
|
95
138
|
|
96
139
|
To make use of callbacks, we need to:
|
97
140
|
|
98
|
-
|
99
|
-
|
100
|
-
|
141
|
+
1. Setup a callback to be called when something happens.
|
142
|
+
2. Connect to the server with callbacks set as enabled.
|
101
143
|
|
102
144
|
Firstly, we need to create a callback block and subscribe it, so that will get
|
103
145
|
triggered whenever a specific event happens. When the callback is triggered,
|
@@ -158,6 +200,7 @@ in order to recieve those values:
|
|
158
200
|
puts bits
|
159
201
|
end
|
160
202
|
|
203
|
+
# or
|
161
204
|
mpd.on :audio do |*args|
|
162
205
|
puts args.join(',')
|
163
206
|
end
|
data/lib/ruby-mpd.rb
CHANGED
@@ -33,6 +33,8 @@ require 'ruby-mpd/plugins/channels'
|
|
33
33
|
|
34
34
|
# make it possible to use MPD::Song objects instead of filepath strings
|
35
35
|
|
36
|
+
# commands missing: #plchangeposid, #lsinfo, #listall.
|
37
|
+
|
36
38
|
# error codes stored in ack.h
|
37
39
|
|
38
40
|
# @!macro [new] error_raise
|
@@ -248,7 +250,7 @@ class MPD
|
|
248
250
|
#
|
249
251
|
# @return [Array<MPD::Song>]
|
250
252
|
def songs_by_artist(artist)
|
251
|
-
|
253
|
+
search :artist, artist
|
252
254
|
end
|
253
255
|
|
254
256
|
# Used to send a command to the server. This synchronizes
|
data/lib/ruby-mpd/playlist.rb
CHANGED
@@ -42,6 +42,18 @@ class MPD
|
|
42
42
|
@mpd.send_command :playlistadd, @name, uri
|
43
43
|
end
|
44
44
|
|
45
|
+
# Searches for any song that contains +what+ in the +type+ field
|
46
|
+
# and immediately adds them to the playlist.
|
47
|
+
# Searches are *NOT* case sensitive.
|
48
|
+
#
|
49
|
+
# @param [Symbol] type Can be any tag supported by MPD, or one of the two special
|
50
|
+
# parameters: +:file+ to search by full path (relative to database root),
|
51
|
+
# and +:any+ to match against all available tags.
|
52
|
+
# @macro returnraise
|
53
|
+
def searchadd(type, what)
|
54
|
+
send_command :searchaddpl, @name, type, what
|
55
|
+
end
|
56
|
+
|
45
57
|
# Clears the playlist.
|
46
58
|
# @macro returnraise
|
47
59
|
def clear
|
@@ -17,18 +17,20 @@ class MPD
|
|
17
17
|
send_command :pause, toggle
|
18
18
|
end
|
19
19
|
|
20
|
-
# Begin playing the
|
20
|
+
# Begin/resume playing the queue.
|
21
21
|
# @param [Integer] pos Position in the playlist to start playing.
|
22
|
+
# @param [Hash] pos :id of the song where to start playing.
|
22
23
|
# @macro returnraise
|
23
24
|
def play(pos = nil)
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
31
|
-
|
25
|
+
if pos.is_a?(Hash)
|
26
|
+
if pos[:id]
|
27
|
+
send_command :playid, priority, pos[:id]
|
28
|
+
else
|
29
|
+
raise ArgumentError, 'Only :id key is allowed!'
|
30
|
+
end
|
31
|
+
else
|
32
|
+
send_command :play, pos
|
33
|
+
end
|
32
34
|
end
|
33
35
|
|
34
36
|
# Plays the previous song in the playlist.
|
@@ -43,23 +45,16 @@ class MPD
|
|
43
45
|
#
|
44
46
|
# @since MPD 0.17
|
45
47
|
# @param [Integer, String] time Position within the current song.
|
48
|
+
# @param [Hash] options Either +:id+ or +:pos+ can be specified.
|
46
49
|
# Returns true if successful,
|
47
|
-
def seek(time)
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
send_command :seek, pos, time
|
56
|
-
end
|
57
|
-
|
58
|
-
# Seeks to the position +time+ (in seconds) of the song with
|
59
|
-
# the id of +songid+.
|
60
|
-
# @macro returnraise
|
61
|
-
def seekid(songid, time)
|
62
|
-
send_command :seekid, songid, time
|
50
|
+
def seek(time, options = {})
|
51
|
+
if options[:id]
|
52
|
+
send_command :seekid, options[:id], time
|
53
|
+
elsif options[:pos]
|
54
|
+
send_command :seek, options[:pos], time
|
55
|
+
else
|
56
|
+
send_command :seekcur, time
|
57
|
+
end
|
63
58
|
end
|
64
59
|
|
65
60
|
# Stop playing.
|
@@ -2,7 +2,8 @@ class MPD
|
|
2
2
|
module Plugins
|
3
3
|
# Commands for interacting with the music database.
|
4
4
|
#
|
5
|
-
# Changes: listallinfo -> songs
|
5
|
+
# Changes: listallinfo -> songs, searchaddpl in MPD::Playlist#searchadd.
|
6
|
+
# search merges search, find, searchadd and findadd
|
6
7
|
module Database
|
7
8
|
|
8
9
|
# Counts the number of songs and their total playtime
|
@@ -12,19 +13,6 @@ class MPD
|
|
12
13
|
send_command :count, type, what
|
13
14
|
end
|
14
15
|
|
15
|
-
# Finds songs in the database that are *EXACTLY* matched by the what
|
16
|
-
# argument.
|
17
|
-
#
|
18
|
-
# @param [Symbol] type Can be any tag supported by MPD, or one of the two special
|
19
|
-
# parameters: +:file+ to search by full path (relative to database root),
|
20
|
-
# and +:any+ to match against all available tags.
|
21
|
-
# @return [Array<MPD::Song>] Songs that matched.
|
22
|
-
def find(type, what)
|
23
|
-
build_songs_list send_command(:find, type, what)
|
24
|
-
end
|
25
|
-
|
26
|
-
# findadd
|
27
|
-
|
28
16
|
# List all tags of the specified type.
|
29
17
|
# Type can be any tag supported by MPD or +:file+.
|
30
18
|
# If type is 'album' then arg can be a specific artist to list the albums for
|
@@ -47,17 +35,28 @@ class MPD
|
|
47
35
|
# lsinfo
|
48
36
|
|
49
37
|
# Searches for any song that contains +what+ in the +type+ field.
|
50
|
-
# Searches are
|
38
|
+
# Searches are case insensitive by default, however you can enable
|
39
|
+
# it using the third argument.
|
51
40
|
#
|
52
|
-
#
|
41
|
+
# Options:
|
42
|
+
# * *add*: Add the search results to the queue.
|
43
|
+
# * *case_sensitive*: Make the query case sensitive.
|
44
|
+
#
|
45
|
+
# @param [Symbol] type Can be any tag supported by MPD, or one of the two special
|
46
|
+
# parameters: +:file+ to search by full path (relative to database root),
|
47
|
+
# and +:any+ to match against all available tags.
|
48
|
+
# @param [Hash] options A hash of options.
|
53
49
|
# @return [Array<MPD::Song>] Songs that matched.
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
50
|
+
# @return [true] if +:add+ is enabled.
|
51
|
+
def search(type, what, options = {})
|
52
|
+
if options[:add]
|
53
|
+
command = options[:case_sensitive] ? :findadd : :searchadd
|
54
|
+
else
|
55
|
+
command = options[:case_sensitive] ? :find : :search
|
56
|
+
end
|
59
57
|
|
60
|
-
|
58
|
+
build_songs_list send_command(command, type, what)
|
59
|
+
end
|
61
60
|
|
62
61
|
# Tell the server to update the database. Optionally,
|
63
62
|
# specify the path to update.
|
@@ -4,7 +4,8 @@ class MPD
|
|
4
4
|
# For a distinction between this and other playlists, this is called
|
5
5
|
# queue.
|
6
6
|
# Changes: playlistinfo -> queue, plchanges -> queue_changes,
|
7
|
-
# playlistid -> song_with_id
|
7
|
+
# playlistid -> song_with_id, playlistfind -> queue_find,
|
8
|
+
# playlistsearch -> queue_search, prio -> song_priority.
|
8
9
|
module Queue
|
9
10
|
|
10
11
|
# List the current playlist/queue.
|
@@ -41,15 +42,18 @@ class MPD
|
|
41
42
|
# Since MPD 0.15 a range can also be passed. Songs with positions within range will be deleted.
|
42
43
|
# @param [Integer, Range] pos Song with position in the queue will be deleted,
|
43
44
|
# if range is passed, songs with positions within range will be deleted.
|
45
|
+
# @param [Hash] pos :id to specify the song ID to delete instead of position.
|
44
46
|
# @macro returnraise
|
45
47
|
def delete(pos)
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
48
|
+
if pos.is_a?(Hash)
|
49
|
+
if pos[:id]
|
50
|
+
send_command :deleteid, pos[:id]
|
51
|
+
else
|
52
|
+
raise ArgumentError, 'Only :id key is allowed!'
|
53
|
+
end
|
54
|
+
else
|
55
|
+
send_command :delete, pos
|
56
|
+
end
|
53
57
|
end
|
54
58
|
|
55
59
|
# Move the song at +from+ to +to+ in the queue.
|
@@ -59,26 +63,39 @@ class MPD
|
|
59
63
|
# Moving a song to -queue.length will move it to the song _before_ the current
|
60
64
|
# song on the queue; so this will work for repeating playlists, too.
|
61
65
|
# * Since 0.15, +from+ can be a range of songs to move.
|
66
|
+
# @param [Hash] from :id to specify the song ID to move instead of position.
|
62
67
|
# @macro returnraise
|
63
68
|
def move(from, to)
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
69
|
+
if pos.is_a?(Hash)
|
70
|
+
if pos[:id]
|
71
|
+
send_command :moveid, pos[:id], to
|
72
|
+
else
|
73
|
+
raise ArgumentError, 'Only :id key is allowed!'
|
74
|
+
end
|
75
|
+
else
|
76
|
+
send_command :move, from, to
|
77
|
+
end
|
71
78
|
end
|
72
79
|
|
73
|
-
# playlistfind
|
74
|
-
|
75
80
|
# Returns the song with the +songid+ in the playlist,
|
76
81
|
# @return [MPD::Song]
|
77
82
|
def song_with_id(songid)
|
78
83
|
Song.new send_command(:playlistid, songid)
|
79
84
|
end
|
80
85
|
|
81
|
-
#
|
86
|
+
# Searches for songs in the queue matched by the what
|
87
|
+
# argument. Case insensitive by default.
|
88
|
+
#
|
89
|
+
# @param [Symbol] type Can be any tag supported by MPD, or one of the two special
|
90
|
+
# parameters: +:file+ to search by full path (relative to database root),
|
91
|
+
# and +:any+ to match against all available tags.
|
92
|
+
#
|
93
|
+
# @param [Hash] options Use +:case_sensitive+ to make the query case sensitive.
|
94
|
+
# @return [Array<MPD::Song>] Songs that matched.
|
95
|
+
def queue_search(type, what, options = {})
|
96
|
+
command = options[:case_sensitive] ? :playlistfind : :playlistsearch
|
97
|
+
build_songs_list send_command(command, type, what)
|
98
|
+
end
|
82
99
|
|
83
100
|
# List the changes since the specified version in the queue.
|
84
101
|
# @return [Array<MPD::Song>]
|
@@ -88,14 +105,28 @@ class MPD
|
|
88
105
|
|
89
106
|
# plchangesposid
|
90
107
|
|
91
|
-
#
|
92
|
-
|
93
|
-
#
|
108
|
+
# Set the priority of the specified songs. A higher priority means that it will be played
|
109
|
+
# first when "random" mode is enabled.
|
110
|
+
# @param [Integer] priority An integer between 0 and 255. The default priority of new songs is 0.
|
111
|
+
# @param [Integer] pos A specific position.
|
112
|
+
# @param [Range] pos A range of positions.
|
113
|
+
# @param [Hash] pos :id to specify the song ID to move instead of position.
|
114
|
+
def song_priority(priority, pos)
|
115
|
+
if pos.is_a?(Hash)
|
116
|
+
if pos[:id]
|
117
|
+
send_command :prioid, priority, pos[:id]
|
118
|
+
else
|
119
|
+
raise ArgumentError, 'Only :id key is allowed!'
|
120
|
+
end
|
121
|
+
else
|
122
|
+
send_command :prio, priority, pos
|
123
|
+
end
|
124
|
+
end
|
94
125
|
|
95
126
|
# Shuffles the queue.
|
96
127
|
# Optionally, a Range can be used to shuffle a specific subset.
|
97
128
|
# @macro returnraise
|
98
|
-
def shuffle(range)
|
129
|
+
def shuffle(range=nil)
|
99
130
|
send_command :shuffle, range
|
100
131
|
end
|
101
132
|
|
data/ruby-mpd.gemspec
CHANGED