4.2 Generalized Commands ¶

The idea of executing arbitrary commands proved useful enough that mpdpopm generalized it: the user can configure arbitrary server-side commands in response to messages received on the mppopmd commands channel. As an example, an entry in the configuration file like this:

  (gen_cmds .
            (((name . "set-genre")
              (formal_parameters . (Literal Track))
              (default_after . 1)
              (cmd . "/home/sp1ff/bin/scribbu")
              (args . ("genre" "-a" "-C" "-g" "%1" "%full-file"))
              (update . TrackOnly)))

will define a new command “set-genre”, with two parameters, the second of which can be omitted (it will default to the current track). When =mppopmd= receives this command (i.e. when a client says something like:

sendmessage unwoundstack.com:commands "set-genre Rock"

mppopmd will invoke scribbu like so:

/home/sp1ff/scribbu genre -a -C -g Rock "${music-dir}/${song URI}"

where the "psuedo-variables" music-dir and song URI above will be replaced with the configured music directory and the current song’s URI.

The configuration is perforce more complex because we have to, at configuration-time, define a mapping between the actual parameters supplied by a client in the message to “unwoundstack.com:commands” and the replacement parameters used in the command arguments. The command’s replacement parameters are defined by a simple list, given in formal_parameters, of parameter types. At this time, there are only two formal parameter types:

1. Literal: the actual parameter shall be copied verbatim into the replacement parameters, under the name “%i” where i is the one-based index of this formal parameter, expressed in base ten
2. Track: the actual parameter will be interpreted as a song URI; it again may be referred in the replacement parameters as “%i”. Only one Track argument may appear in the list of formal parameters.

Actual parameters after index default_after (counting from one) are optional; if not specified the replacement parameter will take the default value for its type (the empty string for literals, the currently playing song’s URI for tracks).

Two additional parameters are available:

1. current-file:: the absolute path to the currently playing track (if any)
2. full-file :: if the list of formal parameters contains a Track argument in slot i, the actual parameter will be interpreted as a song URI, “%i” will return the absolute path to that file (i.e. with music_dir prepended to the actual argument), as will %full-file

Finally, some commands (such as set-genre, above) may change your music collection in such a way as to necessitate an MPD database update after they complete. The update configuration item governs that: it may be set to "NoUpdate", "TrackOnly", or "FullDatabase" to indicate that this command will require no update, an update to the song named by the Track parameter only, or the full database, respectively.