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

Last change on this file since 20728 was 20728, checked in by Ivan Raikov, 10 years ago

initial wiki doc for mpd-client

File size: 13.4 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>(mpd: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
20<procedure>(mpd:reconnect CONN)</procedure>
21Reconnects the given MPD connection object.  This function should normally not be needed as the library automatically reconnects if needed.
22
23
24<procedure>(mpd-conn? CONN)</procedure>
25Returns {{#t}} if {{CONN}} is an MPD connection object, {{#f}} otherwise.
26
27
28<procedure>(mpd:host CONN)</procedure>
29Returns the hostname field of the MPD connection object {{CONN}}.
30
31
32<procedure>(mpd:port CONN)</procedure>
33Returns the port field of the MPD connection object {{CONN}}.
34
35
36<procedure>(mpd:password CONN)</procedure>
37Returns 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.
38
39
40<procedure>(mpd:version CONN)</procedure>
41Returns the version field of the MPD connection object {{CONN}} which contains the version number received by the MPD server.
42
43
44<procedure>(mpd:close CONN)</procedure>
45Closes the connection to MPD.  {{CONN}} should not be used anymore after calling this function.
46
47
48<procedure>(mpd:ping CONN)</procedure>
49Sends a {{ping}} command to the MPD server, reconnecting if necessary.
50
51
52<procedure>(mpd:clear-error CONN)</procedure>
53Clears the current error message (which is returned by {{(mpd:status)}}). This is also done by any command that starts playback.
54
55
56<procedure>(mpd:stats CONN)</procedure>
57
58Returns an alist containing various stats:
59
60 #;6> (pp (mpd:stats m))
61 ((artists . 183)
62  (albums . 429)
63  (songs . 6200)
64  (uptime . 130260)
65  (playtime . 49958)
66  (db_playtime . 1773229)
67  (db_update . 1152376960.0))
68 #;7>
69
70
71
72<procedure>(mpd:status CONN)</procedure>
73
74Return an alist describing the current status of MPD:
75
76 #;9> (pp (mpd:status m))
77 ((volume . 78)
78  (repeat . #f)
79  (random . #f)
80  (playlist . 78)
81  (playlistlength . 77)
82  (xfade . 0)
83  (state . play)
84  (song . 12)
85  (songid . 12)
86  (time 31 623)
87  (bitrate . 128)
88  (audio 44100 16 2))
89 #;10>
90
91
92
93<procedure>(mpd:kill CONN)</procedure>
94Kill MPD.
95
96
97<procedure>(mpd:send-password CONN PASSWORD)</procedure>
98Sends {{PASSWORD}} (a string containing the plain text password) to the server for authentication.  Normally, this not needed as the password can be specified when creating the connection which has the advantage that it's automatically sent after having reconnected.
99
100
101<procedure>(mpd:commands CONN)</procedure>
102Returns a list of commands the current user has access to.
103
104
105<procedure>(mpd:not-commands CONN)</procedure>
106Returns a list of commands the current user doesn't have access to.
107
108
109=== Controlling playback
110
111
112<procedure>(mpd:play/pos CONN POS)</procedure>
113Start playing at position {{POS}}.
114
115
116<procedure>(mpd:play/id CONN ID)</procedure>
117Start playing at song with id {{ID}}.
118
119
120<procedure>(mpd:seek/pos CONN POS SECS)</procedure>
121Seeks to {{SECS}} in the song at position {{POSITION}}.
122
123
124<procedure>(mpd:seek/id CONN ID SECS)</procedure>
125Seeks to {{SECS}} in the song with id {{ID}}.
126
127
128<procedure>(mpd:next CONN)</procedure>
129Play the next song in the playlist.
130
131
132<procedure>(mpd:previous CONN)</procedure>
133Play the previous song in the playlist.
134
135
136<procedure>(mpd:stop CONN)</procedure>
137Stop playback.
138
139
140<procedure>(mpd:pause CONN PAUSE?)</procedure>
141Pause if {{PAUSE?}} is true, resume playing otherwise.
142
143
144<procedure>(mpd:random CONN RANDOM?)</procedure>
145Enable or disable random.
146
147
148<procedure>(mpd:repeat CONN REPEAT?)</procedure>
149Enable or disable repeat.
150
151
152<procedure>(mpd:crossfade CONN SECS)</procedure>
153Sets the cross fading setting to {{SECS}} seconds (0 = disabled).
154
155
156<procedure>(mpd:set-vol CONN VOLUME)</procedure>
157Sets the volume to {{VOLUME}} (a fixnum in the range 0-100).
158
159
160=== Managing output devices
161
162
163<procedure>(mpd:outputs CONN)</procedure>
164Returns a list of alists describing the available output devices.
165
166
167<procedure>(mpd:enable-output CONN ID)</procedure>
168Enables the output device with id {{ID}}.
169
170
171<procedure>(mpd:disable-output CONN ID)</procedure>
172Disables the output device with id {{ID}}.
173
174
175=== Querying and modifying the current playlist
176
177
178<procedure>(mpd:playlist/pos CONN [POS])</procedure>
179
180Return a list of alists describing the songs in the current playlist. (Optionally only the song at position {{POS}}).  See below for an example of the result format.
181
182
183
184<procedure>(mpd:playlist/id CONN [ID])</procedure>
185
186Return a list of alists describing the songs in the current playlist. (Optionally only the song with id {{ID}}):
187
188 #;10>  (pp (mpd:playlist/id m 12))
189 (((Id . 12)
190   (Pos . 12)
191   (Time . 623)
192   (Title . "the leper affinity")
193   (Track . 1)
194   (Album . "blackwater park")
195   (Artist . "opeth")
196   (file . "metal/opeth/blackwater park/01 the leper affinity.mp3")))
197 #;11>
198
199
200
201<procedure>(mpd:current-song CONN)</procedure>
202Returns an alist with information about the current song (the same information that {{(mpd:playlist/id)}} returns).
203
204
205<procedure>(mpd:pl-changes CONN VERSION)</procedure>
206Return 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 {{(mpd:status)}}.
207
208
209<procedure>(mpd:pl-changes/pos+id CONN VERSION)</procedure>
210Similar to {{mpd:pl-changes}} but only returns the position and id of each song.
211
212
213<procedure>(mpd:add CONN PATH)</procedure>
214Adds {{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.
215
216
217<procedure>(mpd:add/id CONN PATH)</procedure>
218Similar to {{mpd:add}} but returns a list of ids of the newly added songs.
219
220
221<procedure>(mpd:move/pos CONN FROM TO)</procedure>
222Move song at position {{FROM}} to {{TO}}.  The playlist version is incremented by 1.
223
224
225<procedure>(mpd:move/id CONN ID TO)</procedure>
226Move song with id {{ID}} to {{TO}}.  The playlist version is incremented by 1.
227
228
229<procedure>(mpd:swap/pos CONN POS1 POS2)</procedure>
230Swap position of the two songs given by playlist positions {{POS1}} and {{POS2}}.
231
232
233<procedure>(mpd:swap/id CONN ID1 ID2)</procedure>
234Swap position of the two songs given by ids {{ID1}} and {{ID2}}.
235
236
237<procedure>(mpd:delete/pos CONN POS)</procedure>
238Remove the song at position {{POS}} from playlist.  The playlist version is incremented by 1.
239
240
241<procedure>(mpd:delete/id CONN ID)</procedure>
242Remove the song with id {{ID}} from playlist.  The playlist version is incremented by 1.
243
244
245<procedure>(mpd:shuffle CONN)</procedure>
246Shuffles the current playlist and increments the playlist version by 1.
247
248
249<procedure>(mpd:clear CONN)</procedure>
250Clears the current playlist, incrementing playlist version by 1.
251
252
253=== Managing stored playlist
254
255
256<procedure>(mpd:load-playlist CONN PLAYLIST)</procedure>
257Loads the playlist named {{"PLAYLIST.m3u"}} from the playlist directory. The playlist version is incremented by the number of songs added.
258
259
260<procedure>(mpd:rm-playlist CONN PLAYLIST)</procedure>
261Removes the playlist named {{"PLAYLIST.m3u"}} from the playlist directory.
262
263
264<procedure>(mpd:save-playlist CONN PLAYLIST)</procedure>
265Saves the current playlist to {{"PLAYLIST.m3u"}} in the playlist directory.
266
267
268=== Querying/Updating song database
269
270
271<procedure>(mpd:find CONN TYPE STRING)</procedure>
272Searches 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).
273
274
275<procedure>(mpd:find/album CONN ALBUM)</procedure>
276
277Returns a list of alists describing songs on album {{ALBUM}} (a string).
278
279 #;13> (pp (mpd:find/album m "catch 33"))
280 (((Time . 101)
281   (Title . "autonomy lost")
282   (Track . 1)
283   (Album . "catch 33")
284   (Artist . "meshuggah")
285   (file . "metal/meshuggah/catch 33/01 autonomy lost.mp3"))
286  ((Time . 96)
287   (Title . "imprint of the un-saved")
288   (Track . 2)
289   (Album . "catch 33")
290   (Artist . "meshuggah")
291   (file . "metal/meshuggah/catch 33/02 imprint of the un-saved.mp3"))
292 ...
293 #;14>
294
295
296
297<procedure>(mpd:find/artist CONN ARTIST)</procedure>
298Returns a list of alists describing songs from {{ARTIST}} (a string).
299
300
301<procedure>(mpd:find/title CONN TITLE)</procedure>
302Returns a list of alists describing songs with title {{TITLE}} (a string).
303
304
305<procedure>(mpd:search CONN TYPE SEARCHSTRING)</procedure>
306Returns 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).
307
308
309<procedure>(mpd:search/album CONN SEARCHSTRING)</procedure>
310Returns a list of alists describing songs whose album names contain {{SEARCHSTRING}} (not case sensitive).
311
312
313<procedure>(mpd:search/artist CONN SEARCHSTRING)</procedure>
314Returns a list of alists describing songs whose artist names contain {{SEARCHSTRING}} (not case sensitive).
315
316
317<procedure>(mpd:search/title CONN SEARCHSTRING)</procedure>
318Returns a list of alists describing songs whose titles contain {{SEARCHSTRING}} (not case sensitive).
319
320
321<procedure>(mpd:search/filename CONN SEARCHSTRING)</procedure>
322Returns a list of alists describing songs whose filenames contain {{SEARCHSTRING}} (not case sensitive).
323
324
325<procedure>(mpd:list CONN TYPE [LIMIT STRING])</procedure>
326Return a list of values of metadata {{TYPE}} (e.g. {{'title}}, {{'album}} or {{'artist}}), optionally limited by {{LIMIT}} and {{STRING}}.
327E.g. {{(mpd:list m 'album 'artist "nevermore")}} to get a list of all albums by Nevermore.
328
329
330<procedure>(mpd:list-artists CONN)</procedure>
331Returns a list of all known artists.
332
333
334<procedure>(mpd:list-albums CONN [ARTIST])</procedure>
335Returns a list of all known albums, optionally limited by {{ARTIST}}.
336
337
338<procedure>(mpd:list-all CONN [PATH])</procedure>
339Returns a list of filenames of all songs (below {{PATH}}, if given).
340
341
342<procedure>(mpd:list-all/info CONN [PATH])</procedure>
343Like {{(mpd:list-all)}}, but also returns metadata.  The data is returned as a list of alists.
344
345
346<procedure>(mpd:ls/info CONN [DIR])</procedure>
347Returns a list of alists describing the contents of {{DIR}} (a string). This function is like {{(mpd:list-all/info)}}, but doesn't operate recursively.
348
349
350<procedure>(mpd:update CONN [PATH])</procedure>
351Updates 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).
352
353
354== Examples
355
356
357 #!/usr/local/bin/csi -script
358 
359 (require-extension mpd-client srfi-18 utils)
360 
361 (define mpd (mpd:connect))
362 
363 (define (get-mpd-status)
364   (let ((status (mpd:status mpd)))
365     (list (alist-ref 'songid status)
366           (alist-ref 'state status))))
367 
368 (define (get-songname id)
369   (let ((info (car (mpd:playlist/id mpd id))))
370     (or (alist-ref 'Title info)
371         (pathname-strip-directory
372          (alist-ref 'file info)))))
373 
374 (let loop ((status (get-mpd-status)) (old-status #f))
375   (unless (equal? status old-status)
376     (let ((song (car status))
377           (state (cadr status)))
378       (cond
379        ((eq? state 'play)
380         (printf "Now playing: ~a\n"
381                 (if song
382                     (get-songname song)
383                     "(unknown song)")))
384 
385        ((eq? state 'stop)
386         (printf "STOP\n")))))
387   (thread-sleep! 1)
388   (loop (get-mpd-status) status))
389
390== About this egg
391
392
393=== Author
394
395[[http://www.nil.at/|Hans Bulfone]]
396
397=== Version history
398
399; 1.12 : Added regex as a dependency; converted eggdoc documentation to wiki format [Ivan Raikov]
400; 1.1 : Added new commands supported by recent versions of MPD
401; 1.02 : Fixed a bug that caused playlists to be returned incorrectly by {{mpd:ls/info}} et al.
402; 1.01 : Fixed typo in documentation
403; 1.0 : Initial release
404
405=== License
406
407
408 Copyright (c) 2006-2007, Hans Bulfone
409 All rights reserved.
410 
411 Redistribution and use in source and binary forms, with or without
412 modification, are permitted provided that the following conditions are met:
413 
414     * Redistributions of source code must retain the above copyright notice,
415       this list of conditions and the following disclaimer.
416     * Redistributions in binary form must reproduce the above copyright
417       notice, this list of conditions and the following disclaimer in the
418       documentation and/or other materials provided with the distribution.
419     * Neither the name of the author nor the names of his contributors may
420       be used to endorse or promote products derived from this software
421       without specific prior written permission.
422 
423 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
424 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
425 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
426 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
427 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
428 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
429 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
430 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
431 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
432 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
433 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
434
Note: See TracBrowser for help on using the repository browser.