Changeset 30884 in project


Ignore:
Timestamp:
05/16/14 20:30:01 (6 years ago)
Author:
Mario Domenech Goulart
Message:

mpd-client (wiki): update documentation for the new API

It probably contains a lot of mistakes, but is better than before.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/mpd-client

    r20728 r30884  
    1414
    1515
    16 <procedure>(mpd:connect [HOST] [PORT] [PASSWORD])</procedure>
     16<procedure>(connect [HOST] [PORT] [PASSWORD])</procedure>
    1717Connects to the MPD instance running on {{HOST}} (defaults to {{localhost}}) at {{PORT}} (defaults to {{6600}}).  Optionally authenticates using {{PASSWORD}}. Returns an MPD connection object.
    1818
    19 
    20 <procedure>(mpd:reconnect CONN)</procedure>
    21 Reconnects 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>
     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>
    2523Returns {{#t}} if {{CONN}} is an MPD connection object, {{#f}} otherwise.
    2624
    2725
    28 <procedure>(mpd:host CONN)</procedure>
     26<procedure>(mpd-host CONN)</procedure>
    2927Returns the hostname field of the MPD connection object {{CONN}}.
    3028
    3129
    32 <procedure>(mpd:port CONN)</procedure>
     30<procedure>(mpd-port CONN)</procedure>
    3331Returns the port field of the MPD connection object {{CONN}}.
    3432
    3533
    36 <procedure>(mpd:password CONN)</procedure>
     34<procedure>(mpd-password CONN)</procedure>
    3735Returns 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.
    3836
    3937
    40 <procedure>(mpd:version CONN)</procedure>
     38<procedure>(mpd-version CONN)</procedure>
    4139Returns the version field of the MPD connection object {{CONN}} which contains the version number received by the MPD server.
    4240
    43 
    44 <procedure>(mpd:close CONN)</procedure>
    45 Closes the connection to MPD.  {{CONN}} should not be used anymore after calling this function.
    46 
    47 
    48 <procedure>(mpd:ping CONN)</procedure>
     41<procedure>(ping CONN)</procedure>
    4942Sends a {{ping}} command to the MPD server, reconnecting if necessary.
    5043
    5144
    52 <procedure>(mpd:clear-error CONN)</procedure>
    53 Clears 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>
     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>
    5750
    5851Returns an alist containing various stats:
    5952
    60  #;6> (pp (mpd:stats m))
     53 #;6> (pp (get-stats m))
    6154 ((artists . 183)
    6255  (albums . 429)
     
    7063
    7164
    72 <procedure>(mpd:status CONN)</procedure>
     65<procedure>(get-status CONN)</procedure>
    7366
    7467Return an alist describing the current status of MPD:
    7568
    76  #;9> (pp (mpd:status m))
     69 #;9> (pp (get-status m))
    7770 ((volume . 78)
    7871  (repeat . #f)
     
    9184
    9285
    93 <procedure>(mpd:kill CONN)</procedure>
     86<procedure>(shutdown-server! CONN)</procedure>
    9487Kill MPD.
    9588
    96 
    97 <procedure>(mpd:send-password CONN PASSWORD)</procedure>
    98 Sends {{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>
     89<procedure>(get-commands CONN)</procedure>
    10290Returns a list of commands the current user has access to.
    10391
    10492
    105 <procedure>(mpd:not-commands CONN)</procedure>
    106 Returns a list of commands the current user doesn't have access to.
    107 
    108 
    10993=== Controlling playback
    11094
    111 
    112 <procedure>(mpd:play/pos CONN POS)</procedure>
    113 Start playing at position {{POS}}.
    114 
    115 
    116 <procedure>(mpd:play/id CONN ID)</procedure>
    117 Start playing at song with id {{ID}}.
    118 
    119 
    120 <procedure>(mpd:seek/pos CONN POS SECS)</procedure>
    121 Seeks to {{SECS}} in the song at position {{POSITION}}.
    122 
    123 
    124 <procedure>(mpd:seek/id CONN ID SECS)</procedure>
    125 Seeks to {{SECS}} in the song with id {{ID}}.
    126 
    127 
    128 <procedure>(mpd:next CONN)</procedure>
     95<procedure>(play-song! 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>
    129100Play the next song in the playlist.
    130101
    131102
    132 <procedure>(mpd:previous CONN)</procedure>
     103<procedure>(previous-song! CONN)</procedure>
    133104Play the previous song in the playlist.
    134105
    135106
    136 <procedure>(mpd:stop CONN)</procedure>
     107<procedure>(stop! CONN)</procedure>
    137108Stop playback.
    138109
    139110
    140 <procedure>(mpd:pause CONN PAUSE?)</procedure>
     111<procedure>(pause! CONN PAUSE?)</procedure>
    141112Pause if {{PAUSE?}} is true, resume playing otherwise.
    142113
    143114
    144 <procedure>(mpd:random CONN RANDOM?)</procedure>
    145 Enable or disable random.
    146 
    147 
    148 <procedure>(mpd:repeat CONN REPEAT?)</procedure>
    149 Enable or disable repeat.
    150 
    151 
    152 <procedure>(mpd:crossfade CONN SECS)</procedure>
    153 Sets the cross fading setting to {{SECS}} seconds (0 = disabled).
    154 
    155 
    156 <procedure>(mpd:set-vol CONN VOLUME)</procedure>
    157 Sets the volume to {{VOLUME}} (a fixnum in the range 0-100).
     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.
    158118
    159119
     
    161121
    162122
    163 <procedure>(mpd:outputs CONN)</procedure>
     123<procedure>(get-output-devices CONN)</procedure>
    164124Returns a list of alists describing the available output devices.
    165125
    166126
    167 <procedure>(mpd:enable-output CONN ID)</procedure>
     127<procedure>(enable-output-device! CONN ID)</procedure>
    168128Enables the output device with id {{ID}}.
    169129
    170130
    171 <procedure>(mpd:disable-output CONN ID)</procedure>
     131<procedure>(disable-output-device! CONN ID)</procedure>
    172132Disables the output device with id {{ID}}.
    173133
     
    175135=== Querying and modifying the current playlist
    176136
    177 
    178 <procedure>(mpd:playlist/pos CONN [POS])</procedure>
    179 
    180 Return 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>
     137<procedure>(get-playlist CONN [ID])</procedure>
    185138
    186139Return a list of alists describing the songs in the current playlist. (Optionally only the song with id {{ID}}):
    187140
    188  #;10>  (pp (mpd:playlist/id m 12))
     141 #;10>  (pp (get-playlist m 12))
    189142 (((Id . 12)
    190143   (Pos . 12)
     
    199152
    200153
    201 <procedure>(mpd:current-song CONN)</procedure>
    202 Returns 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>
    206 Return 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>
    210 Similar to {{mpd:pl-changes}} but only returns the position and id of each song.
    211 
    212 
    213 <procedure>(mpd:add CONN PATH)</procedure>
     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>
    214162Adds {{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.
    215163
    216164
    217 <procedure>(mpd:add/id CONN PATH)</procedure>
    218 Similar 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>
     165<procedure>(move-song! CONN FROM TO)</procedure>
    222166Move song at position {{FROM}} to {{TO}}.  The playlist version is incremented by 1.
    223167
    224 
    225 <procedure>(mpd:move/id CONN ID TO)</procedure>
    226 Move song with id {{ID}} to {{TO}}.  The playlist version is incremented by 1.
    227 
    228 
    229 <procedure>(mpd:swap/pos CONN POS1 POS2)</procedure>
    230 Swap position of the two songs given by playlist positions {{POS1}} and {{POS2}}.
    231 
    232 
    233 <procedure>(mpd:swap/id CONN ID1 ID2)</procedure>
    234 Swap position of the two songs given by ids {{ID1}} and {{ID2}}.
    235 
    236 
    237 <procedure>(mpd:delete/pos CONN POS)</procedure>
    238 Remove the song at position {{POS}} from playlist.  The playlist version is incremented by 1.
    239 
    240 
    241 <procedure>(mpd:delete/id CONN ID)</procedure>
    242 Remove the song with id {{ID}} from playlist.  The playlist version is incremented by 1.
    243 
    244 
    245 <procedure>(mpd:shuffle CONN)</procedure>
     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>
    246177Shuffles the current playlist and increments the playlist version by 1.
    247178
    248179
    249 <procedure>(mpd:clear CONN)</procedure>
     180<procedure>(clear-playlist! CONN)</procedure>
    250181Clears the current playlist, incrementing playlist version by 1.
    251182
     
    254185
    255186
    256 <procedure>(mpd:load-playlist CONN PLAYLIST)</procedure>
     187<procedure>(load-playlist! CONN PLAYLIST)</procedure>
    257188Loads the playlist named {{"PLAYLIST.m3u"}} from the playlist directory. The playlist version is incremented by the number of songs added.
    258189
    259190
    260 <procedure>(mpd:rm-playlist CONN PLAYLIST)</procedure>
     191<procedure>(remove-playlist! CONN PLAYLIST)</procedure>
    261192Removes the playlist named {{"PLAYLIST.m3u"}} from the playlist directory.
    262193
    263194
    264 <procedure>(mpd:save-playlist CONN PLAYLIST)</procedure>
     195<procedure>(save-playlist! CONN PLAYLIST)</procedure>
    265196Saves the current playlist to {{"PLAYLIST.m3u"}} in the playlist directory.
    266197
     
    269200
    270201
    271 <procedure>(mpd:find CONN TYPE STRING)</procedure>
     202<procedure>(find-songs CONN TYPE STRING)</procedure>
    272203Searches 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).
    273204
    274 
    275 <procedure>(mpd:find/album CONN ALBUM)</procedure>
    276 
    277 Returns 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>
    298 Returns a list of alists describing songs from {{ARTIST}} (a string).
    299 
    300 
    301 <procedure>(mpd:find/title CONN TITLE)</procedure>
    302 Returns a list of alists describing songs with title {{TITLE}} (a string).
    303 
    304 
    305 <procedure>(mpd:search CONN TYPE SEARCHSTRING)</procedure>
     205<procedure>(search-songs CONN TYPE SEARCHSTRING)</procedure>
    306206Returns 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).
    307207
    308208
    309 <procedure>(mpd:search/album CONN SEARCHSTRING)</procedure>
    310 Returns a list of alists describing songs whose album names contain {{SEARCHSTRING}} (not case sensitive).
    311 
    312 
    313 <procedure>(mpd:search/artist CONN SEARCHSTRING)</procedure>
    314 Returns a list of alists describing songs whose artist names contain {{SEARCHSTRING}} (not case sensitive).
    315 
    316 
    317 <procedure>(mpd:search/title CONN SEARCHSTRING)</procedure>
    318 Returns a list of alists describing songs whose titles contain {{SEARCHSTRING}} (not case sensitive).
    319 
    320 
    321 <procedure>(mpd:search/filename CONN SEARCHSTRING)</procedure>
    322 Returns a list of alists describing songs whose filenames contain {{SEARCHSTRING}} (not case sensitive).
    323 
    324 
    325 <procedure>(mpd:list CONN TYPE [LIMIT STRING])</procedure>
     209<procedure>(list-metadata CONN TYPE [LIMIT STRING])</procedure>
    326210Return a list of values of metadata {{TYPE}} (e.g. {{'title}}, {{'album}} or {{'artist}}), optionally limited by {{LIMIT}} and {{STRING}}.
    327 E.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>
    331 Returns a list of all known artists.
    332 
    333 
    334 <procedure>(mpd:list-albums CONN [ARTIST])</procedure>
    335 Returns a list of all known albums, optionally limited by {{ARTIST}}.
    336 
    337 
    338 <procedure>(mpd:list-all CONN [PATH])</procedure>
    339 Returns a list of filenames of all songs (below {{PATH}}, if given).
    340 
    341 
    342 <procedure>(mpd:list-all/info CONN [PATH])</procedure>
    343 Like {{(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>
    347 Returns 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>
     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>
    351225Updates 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).
    352226
     
    359233 (require-extension mpd-client srfi-18 utils)
    360234 
    361  (define mpd (mpd:connect))
     235 (define mpd (connect))
    362236 
    363237 (define (get-mpd-status)
    364    (let ((status (mpd:status mpd)))
     238   (let ((status (get-status mpd)))
    365239     (list (alist-ref 'songid status)
    366240           (alist-ref 'state status))))
    367241 
    368242 (define (get-songname id)
    369    (let ((info (car (mpd:playlist/id mpd id))))
     243   (let ((info (car (get-playlist mpd id))))
    370244     (or (alist-ref 'Title info)
    371245         (pathname-strip-directory
Note: See TracChangeset for help on using the changeset viewer.