source: project/wiki/eggref/4/mpd-client @ 35391

Last change on this file since 35391 was 35391, checked in by svnwiki, 19 months ago

Anonymous wiki edit for IP [217.109.134.89]: play! instead of play-song!...

File size: 9.8 KB
Line 
1[[tags:egg]]
2
3== mpd-client
4
5Interface to the [[http://www.musicpd.org/|Music Player Daemon]].
6
7[[toc:]]
8
9== Documentation
10
11This extension allows convenient access to the tcp interface of [[http://www.musicpd.org/|MPD]].
12
13=== Connecting to MPD and obtaining connection/server information
14
15
16<procedure>(connect [HOST] [PORT] [PASSWORD])</procedure>
17Connects to the MPD instance running on {{HOST}} (defaults to {{localhost}}) at {{PORT}} (defaults to {{6600}}).  Optionally authenticates using {{PASSWORD}}. Returns an MPD connection object.
18
19<procedure>(disconnect CONN)</procedure>
20Closes the connection to MPD.  {{CONN}} should not be used anymore after calling this function.
21
22<procedure>(mpd-connection? CONN)</procedure>
23Returns {{#t}} if {{CONN}} is an MPD connection object, {{#f}} otherwise.
24
25
26<procedure>(mpd-host CONN)</procedure>
27Returns the hostname field of the MPD connection object {{CONN}}.
28
29
30<procedure>(mpd-port CONN)</procedure>
31Returns the port field of the MPD connection object {{CONN}}.
32
33
34<procedure>(mpd-password CONN)</procedure>
35Returns the password field of the MPD connection object {{CONN}}.  This is either a string containing the plain text password or {{#f}} if no authentication should be done.
36
37
38<procedure>(mpd-version CONN)</procedure>
39Returns the version field of the MPD connection object {{CONN}} which contains the version number received by the MPD server.
40
41<procedure>(ping CONN)</procedure>
42Sends a {{ping}} command to the MPD server, reconnecting if necessary.
43
44
45<procedure>(clear-error! CONN)</procedure>
46Clears the current error message (which is returned by {{(get-status)}}). This is also done by any command that starts playback.
47
48
49<procedure>(get-stats CONN)</procedure>
50
51Returns an alist containing various stats:
52
53 #;6> (pp (get-stats m))
54 ((artists . 183)
55  (albums . 429)
56  (songs . 6200)
57  (uptime . 130260)
58  (playtime . 49958)
59  (db_playtime . 1773229)
60  (db_update . 1152376960.0))
61 #;7>
62
63
64
65<procedure>(get-status CONN)</procedure>
66
67Return an alist describing the current status of MPD:
68
69 #;9> (pp (get-status m))
70 ((volume . 78)
71  (repeat . #f)
72  (random . #f)
73  (playlist . 78)
74  (playlistlength . 77)
75  (xfade . 0)
76  (state . play)
77  (song . 12)
78  (songid . 12)
79  (time 31 623)
80  (bitrate . 128)
81  (audio 44100 16 2))
82 #;10>
83
84
85
86<procedure>(shutdown-server! CONN)</procedure>
87Kill MPD.
88
89<procedure>(get-commands CONN)</procedure>
90Returns a list of commands the current user has access to.
91
92
93=== Controlling playback
94
95<procedure>(play! CONN #!optional SONG TIME)</procedure>
96Start playing at song {{SONG}} (or the first in playlist) at {{TIME}} (in seconds).
97
98
99<procedure>(next-song! CONN)</procedure>
100Play the next song in the playlist.
101
102
103<procedure>(previous-song! CONN)</procedure>
104Play the previous song in the playlist.
105
106
107<procedure>(stop! CONN)</procedure>
108Stop playback.
109
110
111<procedure>(pause! CONN PAUSE?)</procedure>
112Pause if {{PAUSE?}} is true, resume playing otherwise.
113
114
115<procedure>(set-options! CONN . OPTS)</procedure>
116Set playback options.  Options are: {{#:crossfade}}, {{#:random}},
117{{#:repeat}} and {{#:volume}} and they can be mapped to arguments.
118
119
120=== Managing output devices
121
122
123<procedure>(get-output-devices CONN)</procedure>
124Returns a list of alists describing the available output devices.
125
126
127<procedure>(enable-output-device! CONN ID)</procedure>
128Enables the output device with id {{ID}}.
129
130
131<procedure>(disable-output-device! CONN ID)</procedure>
132Disables the output device with id {{ID}}.
133
134
135=== Querying and modifying the current playlist
136
137<procedure>(get-playlist CONN [ID])</procedure>
138
139Return a list of alists describing the songs in the current playlist. (Optionally only the song with id {{ID}}):
140
141 #;10>  (pp (get-playlist m 12))
142 (((Id . 12)
143   (Pos . 12)
144   (Time . 623)
145   (Title . "the leper affinity")
146   (Track . 1)
147   (Album . "blackwater park")
148   (Artist . "opeth")
149   (file . "metal/opeth/blackwater park/01 the leper affinity.mp3")))
150 #;11>
151
152
153
154<procedure>(get-current-song CONN)</procedure>
155Returns an alist with information about the current song (the same information that {{(get-playlist)}} returns).
156
157
158<procedure>(get-playlist-changes CONN VERSION)</procedure>
159Return a list of alists describing new songs since playlist version {{VERSION}}. Note: to detect songs that were deleted at the end of the playlist, use the {{playlistlength}} returned by {{(get-status)}}.
160
161<procedure>(add-song! CONN PATH)</procedure>
162Adds {{PATH}} (a string naming a file or directory) to the end of the current playlist.  Directories are added recursively.  Increments playlist version by 1 for each added song.
163
164
165<procedure>(move-song! CONN FROM TO)</procedure>
166Move song at position {{FROM}} to {{TO}}.  The playlist version is incremented by 1.
167
168<procedure>(swap-songs! CONN SONG1 SONG2)</procedure>
169Swap position of the two songs.
170
171
172<procedure>(remove-song! CONN SONG)</procedure>
173Remove the song SONG (position or ID) from playlist.  The playlist version is incremented by 1.
174
175
176<procedure>(shuffle-playlist! CONN)</procedure>
177Shuffles the current playlist and increments the playlist version by 1.
178
179
180<procedure>(clear-playlist! CONN)</procedure>
181Clears the current playlist, incrementing playlist version by 1.
182
183
184=== Managing stored playlist
185
186
187<procedure>(load-playlist! CONN PLAYLIST)</procedure>
188Loads the playlist named {{"PLAYLIST.m3u"}} from the playlist directory. The playlist version is incremented by the number of songs added.
189
190
191<procedure>(remove-playlist! CONN PLAYLIST)</procedure>
192Removes the playlist named {{"PLAYLIST.m3u"}} from the playlist directory.
193
194
195<procedure>(save-playlist! CONN PLAYLIST)</procedure>
196Saves the current playlist to {{"PLAYLIST.m3u"}} in the playlist directory.
197
198
199=== Querying/Updating song database
200
201
202<procedure>(find-songs CONN TYPE STRING)</procedure>
203Searches for songs and returns a list of alists.  {{TYPE}} is e.g. {{'title}}, {{'album}} or {{'artist}}.  {{STRING}} is the search string (which must match exactly).
204
205<procedure>(search-songs CONN TYPE SEARCHSTRING)</procedure>
206Returns a list of alists describing the matching songs.  {{TYPE}} is e.g. {{'title}}, {{'album}} or {{'artist}}.  {{SEARCHSTRING}} is the string which is searched for (not case sensitive, doesn't need to be an exact match).
207
208
209<procedure>(list-metadata CONN TYPE [LIMIT STRING])</procedure>
210Return a list of values of metadata {{TYPE}} (e.g. {{'title}}, {{'album}} or {{'artist}}), optionally limited by {{LIMIT}} and {{STRING}}.
211E.g. {{(list-metadata m 'album 'artist "nevermore")}} to get a list of all albums by Nevermore.
212
213
214<procedure>(list-directory/r CONN [PATH] [FULL #t])</procedure>
215Returns a list of all songs (below {{PATH}}, if given). If {{FULL}} is
216{{#t}} (default), list all metadata.  If {{FULL}} is {{#f}}, return
217only filename metadata.
218
219
220<procedure>(list-directory CONN [PATH])</procedure>
221Like {{(list-directory/r)}}, with {{FULL}} as #t.  The data is returned as a list of alists.
222
223
224<procedure>(update-song-database! CONN [PATH])</procedure>
225Updates MPD's database, removing old songs and adding new songs.  Optionally, the update process can be limited to {{PATH}} (a string naming a file or directory).
226
227
228== Examples
229
230
231 #!/usr/local/bin/csi -script
232 
233 (require-extension mpd-client srfi-18 utils)
234 
235 (define mpd (connect))
236 
237 (define (get-mpd-status)
238   (let ((status (get-status mpd)))
239     (list (alist-ref 'songid status)
240           (alist-ref 'state status))))
241 
242 (define (get-songname id)
243   (let ((info (car (get-playlist mpd id))))
244     (or (alist-ref 'Title info)
245         (pathname-strip-directory
246          (alist-ref 'file info)))))
247 
248 (let loop ((status (get-mpd-status)) (old-status #f))
249   (unless (equal? status old-status)
250     (let ((song (car status))
251           (state (cadr status)))
252       (cond
253        ((eq? state 'play)
254         (printf "Now playing: ~a\n"
255                 (if song
256                     (get-songname song)
257                     "(unknown song)")))
258 
259        ((eq? state 'stop)
260         (printf "STOP\n")))))
261   (thread-sleep! 1)
262   (loop (get-mpd-status) status))
263
264== About this egg
265
266
267=== Author
268
269[[http://www.nil.at/|Hans Bulfone]]
270
271=== Version history
272
273; 1.12 : Added regex as a dependency; converted eggdoc documentation to wiki format [Ivan Raikov]
274; 1.1 : Added new commands supported by recent versions of MPD
275; 1.02 : Fixed a bug that caused playlists to be returned incorrectly by {{mpd:ls/info}} et al.
276; 1.01 : Fixed typo in documentation
277; 1.0 : Initial release
278
279=== License
280
281
282 Copyright (c) 2006-2007, Hans Bulfone
283 All rights reserved.
284 
285 Redistribution and use in source and binary forms, with or without
286 modification, are permitted provided that the following conditions are met:
287 
288     * Redistributions of source code must retain the above copyright notice,
289       this list of conditions and the following disclaimer.
290     * Redistributions in binary form must reproduce the above copyright
291       notice, this list of conditions and the following disclaimer in the
292       documentation and/or other materials provided with the distribution.
293     * Neither the name of the author nor the names of his contributors may
294       be used to endorse or promote products derived from this software
295       without specific prior written permission.
296 
297 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
298 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
299 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
300 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
301 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
302 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
303 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
304 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
305 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
306 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
307 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
308
Note: See TracBrowser for help on using the repository browser.