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.
@@ -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(*!*) years. This library tries to act as a successor,
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 object:
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
- if mpd.stopped?
51
- mpd.play
52
- end
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 [here](TODO)
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
- (1) Setup a callback to be called when something happens.
99
- (2) Connect to the server with callbacks set as enabled.
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
@@ -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
- find :artist, artist
253
+ search :artist, artist
252
254
  end
253
255
 
254
256
  # Used to send a command to the server. This synchronizes
@@ -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 playist.
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
- send_command :play, pos
25
- end
26
-
27
- # Begin playing the playlist.
28
- # @param [Integer] songid ID of the song where to start playing.
29
- # @macro returnraise
30
- def playid(songid = nil)
31
- send_command :playid, songid
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
- send_command :seekcur, time
49
- end
50
-
51
- # Seeks to the position +time+ (in seconds) of the
52
- # song at +pos+ in the playlist.
53
- # @macro returnraise
54
- def seekpos(pos, time)
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 *NOT* case sensitive.
38
+ # Searches are case insensitive by default, however you can enable
39
+ # it using the third argument.
51
40
  #
52
- # @param (see #find)
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
- def search(type, what)
55
- build_songs_list(send_command(:search, type, what))
56
- end
57
-
58
- # searchadd
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
- # searchaddpl
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
- send_command :delete, pos
47
- end
48
-
49
- # Delete the song with the +songid+ from the queue.
50
- # @macro returnraise
51
- def deleteid(songid)
52
- send_command :deleteid, songid
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
- send_command :move, from, to
65
- end
66
-
67
- # Move the song with the +songid+ to +to+ in the queue.
68
- # @macro returnraise
69
- def moveid(songid, to)
70
- send_command :moveid, songid, to
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
- # playlistsearch
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
- # prio
92
-
93
- # prioid
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
 
@@ -3,7 +3,7 @@
3
3
  Gem::Specification.new do |s|
4
4
  s.platform = Gem::Platform::RUBY
5
5
  s.name = 'ruby-mpd'
6
- s.version = '0.1.4'
6
+ s.version = '0.1.5'
7
7
  s.homepage = 'https://github.com/archSeer/ruby-mpd'
8
8
  s.authors = ["Blaž Hrastnik"]
9
9
  s.email = ['speed.the.bboy@gmail.com']
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ruby-mpd
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.1.5
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors: