MPD::Client
An MPD Client.
One-shot usage
require "crystal_mpd"
mpd = MPD::Client.new("localhost", 6600)
puts mpd.version
puts mpd.status
puts mpd.stats
mpd.disconnect
Constants
Constructors
Creates a new MPD client. Parses the host, port.
This constructor will raise an exception if could not connect to MPD
Instance methods
Adds the file uri to the playlist (directories add recursively).
uri can also be a single file.
The position parameter is the same as in addid.
Adds a song to the playlist (non-recursive) and returns the song id.
uri is always a single file or URL.
If the position is given, then the song is inserted at the specified position.
If the parameter is string and starts with "+" or "-", then it is relative to the current song;
e.g. "+0" inserts right after the current song
and "-0" inserts right before the current song (i.e. zero songs between the current song and the newly added song).
Dumps configuration values that may be interesting for the client.
This command is only permitted to local clients (connected via UNIX domain socket).
The following response attributes are available:
music_directory: The absolute path of the music directory.
Sets consume state to state, state should be false, true or "oneshot".
When consume is activated, each song played is removed from playlist.
Count the number of songs and their total playtime in the database matching filter.
mpd.count("(genre == 'Rock')")
=> {"songs" => "11", "playtime" => "2496"}
The group keyword may be used to group the results by a tag.
The first following example prints per-artist counts
while the next prints the number of songs whose title matches "Echoes" grouped by artist:
mpd.count("(genre != 'Pop')", group: "artist")
=> [{"Artist" => "Artist 1", "songs" => "11", "playtime" => "2388"}, {"Artist" => "Artist 2", "songs" => "12", "playtime" => "2762"}]
Count the number of songs and their total playtime in the database matching filter.
mpd.count("(genre == 'Rock')")
=> {"songs" => "11", "playtime" => "2496"}
The group keyword may be used to group the results by a tag.
The first following example prints per-artist counts
while the next prints the number of songs whose title matches "Echoes" grouped by artist:
mpd.count("(genre != 'Pop')", group: "artist")
=> [{"Artist" => "Artist 1", "songs" => "11", "playtime" => "2388"}, {"Artist" => "Artist 2", "songs" => "12", "playtime" => "2762"}]
Displays the song info of the current song (same song that is identified in #status).
Print a list of decoder plugins, followed by their supported suffixes and MIME types.
Search the database for songs matching filter.
sort sorts the result by the specified tag.
The sort is descending if the tag is prefixed with a minus (-).
Without sort, the order is undefined.
Only the first tag value will be used, if multiple of the same type exist.
To sort by "Artist", "Album" or "AlbumArtist", you should specify "ArtistSort", "AlbumSort" or "AlbumArtistSort" instead.
These will automatically fall back to the former if "*Sort" doesn't exist.
"AlbumArtist" falls back to just "Artist".
The type "Last-Modified" can sort by file modification time.
window can be used to query only a portion of the real response.
The parameter is two zero-based record numbers; a start number and an end number.
mpd.find("(genre != 'Pop')", sort: "-ArtistSort", window: (5..10))
mpd.find("(genre starts_with 'Indie')")
mpd.find("(genre starts_with_ci 'inDIE')")
mpd.find("(genre contains 'Rock')")
mpd.find("(genre contains_ci 'RocK')")
Search the database for songs matching filter.
sort sorts the result by the specified tag.
The sort is descending if the tag is prefixed with a minus (-).
Without sort, the order is undefined.
Only the first tag value will be used, if multiple of the same type exist.
To sort by "Artist", "Album" or "AlbumArtist", you should specify "ArtistSort", "AlbumSort" or "AlbumArtistSort" instead.
These will automatically fall back to the former if "*Sort" doesn't exist.
"AlbumArtist" falls back to just "Artist".
The type "Last-Modified" can sort by file modification time.
window can be used to query only a portion of the real response.
The parameter is two zero-based record numbers; a start number and an end number.
mpd.find("(genre != 'Pop')", sort: "-ArtistSort", window: (5..10))
mpd.find("(genre starts_with 'Indie')")
mpd.find("(genre starts_with_ci 'inDIE')")
mpd.find("(genre contains 'Rock')")
mpd.find("(genre contains_ci 'RocK')")
Search the database for songs matching filter and add them to the queue.
Parameters have the same meaning as for #find and #searchadd.
mpd.findadd("(genre == 'Alternative Rock')")
Search the database for songs matching filter and add them to the queue.
Parameters have the same meaning as for #find and #searchadd.
mpd.findadd("(genre == 'Alternative Rock')")
Waits until there is a noteworthy change in one or more of MPD’s subsystems.
As soon as there is one, it lists all changed systems, where subsystem is one of the following:
database- the song database has been modified after update.update- a database update has started or finished. If the database was modified during the update, the database event is also emitted.stored_playlist- a stored playlist has been modified, renamed, created or deletedplaylist- the queue (i.e. the current playlist) has been modifiedplayer- the player has been started, stopped or seeked or tags of the currently playing song have changed (e.g. received from stream)mixer- the volume has changedoutput- an audio output has been added, removed or modified (e.g. renamed, enabled or disabled)options- options like repeat, random, crossfade, replay gainpartition- a partition was added, removed or changedsticker- the sticker database has been modifiedsubscription- a client has subscribed or unsubscribed to a channelmessage- a message was received on a channel this client is subscribed to; this event is only emitted when the client’s message queue is emptyneighbor- a neighbor was found or lostmount- the mount list has changed
If the optional subsystems argument is used,
MPD will only send notifications when something changed in one of the specified subsytems.
Lists unique tags values of the specified type.
type can be any tag supported by MPD or file.
window works like in find. In this command, it affects only the top-most tag type.
group keyword may be used to group the results by tags.
mpd.list("Artist")
Additional arguments may specify a filter.
The following example lists all file names by their respective artist and date:
mpd.list("Artist")
mpd.list("filename", "((artist == 'Linkin Park') AND (date == '2003'))")
Lists unique tags values of the specified type.
type can be any tag supported by MPD or file.
window works like in find. In this command, it affects only the top-most tag type.
group keyword may be used to group the results by tags.
mpd.list("Artist")
Additional arguments may specify a filter.
The following example lists all file names by their respective artist and date:
mpd.list("Artist")
mpd.list("filename", "((artist == 'Linkin Park') AND (date == '2003'))")
Same as #listall, except it also returns metadata info in the same format as #lsinfo.
Lists the contents of the directory URI, including files are not recognized by MPD.
uri can be a path relative to the music directory or an uri understood by one of the storage plugins.
The response contains at least one line for each directory entry with the prefix file: or directory: ,
and may be followed by file attributes such as Last-Modified and size.
For example, smb://SERVER returns a list of all shares on the given SMB/CIFS server;
nfs://servername/path obtains a directory listing from the NFS server.
Lists the songs in the playlist name.
Playlist plugins are supported.
A range may be specified to list only a part of the playlist
Lists the songs with metadata in the playlist.
Playlist plugins are supported.
A range may be specified to list only a part of the playlist.
Prints a list of the playlist directory.
After each playlist name the server sends its last modification time
as attribute Last-Modified in ISO 8601 format.
To avoid problems due to clock differences between clients and the server,
clients should not compare this value with their local clock.
Loads the playlist name into the current queue.
Playlist plugins are supported.
A range songpos may be specified to load only a part of the playlist.
The position parameter specifies where the songs will be inserted into the queue;
it can be relative as described in addid.
(This requires specifying the range as well;
the special value 0: can be used if the whole playlist shall be loaded at a certain queue position.)
Lists the contents of the directory uri.
When listing the root directory, this currently returns the list of stored playlists.
This behavior is deprecated; use #listplaylists instead.
Clients that are connected via UNIX domain socket may use this command
to read the tags of an arbitrary local file (uri beginning with file:///).
Moves the song at from or range of songs at from to to in the playlist.
Moves the song with from (songid) to to (playlist index) in the playlist.
If to starts with "+" or "-", then it is relative to the current song;
e.g. "+0" moves to right after the current song
and "-0" moves to right before the current song (i.e. zero songs between the current song and the moved song).
Register a callback for a specific event (e.g., :state, :song, etc.)
mpd.on :state do |state|
puts "State was change to #{state}"
end
Register a callback for connection failures raised by callback or idle fibers.
Register a callback for MPD idle subsystem changes.
This starts a background fiber that repeatedly calls #idle and yields
the changed subsystem names to the block.
MPD's idle command blocks the connection while it waits for changes, so
use a dedicated client for idle listeners when the application also needs
to send regular commands.
listener = MPD::Client.new
listener.on_idle(["player", "playlist"]) do |events|
puts events
end
Pause or resume playback.
Pass state true to pause playback or false to resume playback.
Without the parameter, the pause state is toggled.
Adds uri to the playlist name.m3u.
name.m3u will be created if it does not exist.
The position parameter specifies where the songs will be inserted into the playlist.
Deletes songpos from the playlist name.m3u.
The songpos parameter can be a range.
Search the queue for songs matching filter.
sort sorts the result by the specified tag.
The sort is descending if the tag is prefixed with a minus ('-').
Only the first tag value will be used, if multiple of the same type exist.
To sort by "Title", "Artist", "Album", "AlbumArtist" or "Composer",
you should specify "TitleSort", "ArtistSort", "AlbumSort", "AlbumArtistSort" or "ComposerSort" instead.
These will automatically fall back to the former if "*Sort" doesn’t exist.
"AlbumArtist" falls back to just "Artist".
The type "Last-Modified" can sort by file modification time, and "prio" sorts by queue priority.
window can be used to query only a portion of the real response.
:ditto
Displays a list of songs in the playlist.
songid is optional and specifies a single song to display info for.
Displays a list of all songs in the playlist,
or if the optional argument is given, displays information only for
the song songpos or the range of songs START:END.
Range is done in by using MPD::Range.
Show info about the first three songs in the playlist:
mpd.playlistinfo
mpd.playlistinfo(1..3)
mpd.playlistinfo(..3)
mpd.playlistinfo(10..)
With negative range end MPD will assumes the biggest possible number then
mpd.playlistinfo(10..-1)
Count the number of songs and their total playtime (seconds) in the playlist.
Moves the song at position from in the playlist name.m3u to the position to.
Search the queue for songs matching filter.
Parameters have the same meaning as for find, except that search is not case sensitive.
Search the queue for songs matching filter.
Parameters have the same meaning as for find, except that search is not case sensitive.
Set the priority of the specified songs.
A higher priority means that it will be played first when “random” mode is enabled.
A priority is an integer between 0 and 255. The default priority of new songs is 0.
Shows a list of enabled protocol features.
Available features:
"hide_playlists_in_root": disables the listing of stored playlists for the lsinfo.
Reads messages for this client.
client.readmessages
[{"channel" => "notifications", "message" => "System update available"}]
Sets the replay gain mode.
One of off, track, album, auto.
Changing the mode during playback may take several seconds, because the new settings does not affect the buffered data.
This command triggers the options idle event.
Prints replay gain options.
Currently, only the variable replay_gain_mode is returned.
Saves the current playlist to name.m3u in the playlist directory.
mode is optional argument. One of "create", "append", or "replace".
- "create": The default. Create a new playlist. Fail if a playlist with name
namealready exists. - "append", "replace": Append or replace an existing playlist. Fail if a playlist with name
namedoesn't already exist.
Search the database for songs matching filter.
Parameters have the same meaning as for #find, except that search is not case sensitive.
mpd.search("(any =~ 'crystal')")
Search the database for songs matching filter.
Parameters have the same meaning as for #find, except that search is not case sensitive.
mpd.search("(any =~ 'crystal')")
Search the database for songs matching filter and add them to the queue.
Parameters have the same meaning as for #search.
The position parameter specifies where the songs will be inserted.
It can be relative to the current song as in #addid.
Search the database for songs matching filter and add them to the queue.
Parameters have the same meaning as for #search.
The position parameter specifies where the songs will be inserted.
It can be relative to the current song as in #addid.
Search the database for songs matching filter and add them to the queue.
If a playlist by that name doesn't exist it is created.
Parameters have the same meaning as for search.
The position parameter specifies where the songs will be inserted.
It can be relative to the current song as in addid.
Search the database for songs matching filter and add them to the queue.
If a playlist by that name doesn't exist it is created.
Parameters have the same meaning as for search.
The position parameter specifies where the songs will be inserted.
It can be relative to the current song as in addid.
Count the number of songs and their total playtime in the database matching filter.
Parameters have the same meaning as for count except the search is not case sensitive.
Count the number of songs and their total playtime in the database matching filter.
Parameters have the same meaning as for count except the search is not case sensitive.
Search the playlist for songs matching filter.
A range may be specified to list only a part of the playlist.
Search the playlist for songs matching filter.
A range may be specified to list only a part of the playlist.
Seeks to the position time (in seconds) of entry songpos in the playlist.
Seeks to the position time within the current song.
If prefixed by + or -, then the time is relative to the current playing position.
Seeks to the position time (in seconds) of song songid.
Shuffles the current playlist. range is optional and specifies a range of songs.
Sets single state to state, state should be false, true or "oneshot".
When single is activated, playback is stopped after current song,
or song is repeated if the repeat mode is enabled.
Displays statistics.
Response:
artists: number of artistssongs: number of albumsuptime: daemon uptime in secondsdb_playtime: sum of all song times in the dbdb_update: last db update in UNIX timeplaytime: time length of music played
Reports the current status of the player and the volume level.
Response:
partition: the name of the current partitionvolume: 0-100repeat: 0 or 1random: 0 or 1single: 0 or 1consume: 0 or 1playlist: 31-bit unsigned integer, the playlist version numberplaylistlength: integer, the length of the playliststate: play, stop, or pausesong: playlist song number of the current song stopped on or playingsongid: playlist songid of the current song stopped on or playingnextsong: playlist song number of the next song to be playednextsongid: playlist songid of the next song to be playedtime: total time elapsed (of current playing/paused song)elapsed: Total time elapsed within the current song, but with higher resolutionduration: Duration of the current song in secondsbitrate: instantaneous bitrate in kbpsxfade: crossfade in secondsmixrampdb: mixramp threshold in dBmixrampdelay: mixrampdelay in secondsaudio: sampleRate:bits:channelssamplerate:bits:channelsupdating_db: job iderror: if there is an error, returns message herelastloadedplaylist: last loaded stored playlist
Adds a sticker value to the specified object. If a sticker item with that name already exists, it is decremented by supplied value.
Deletes a sticker value from the specified object.
If you do not specify a sticker name, all sticker values are deleted.
Searches for stickers with the given value.
Other supported operators are: "<", ">", "contains", "starts_with" for strings and "eq", "lt", "gt" to cast the value to an integer.
Searches the sticker database for stickers with the specified name, below the specified directory (uri).
For each matching song, it prints the URI and that one sticker’s value.
sort sorts the result by "uri", "value" or "value_int" (casts the sticker value to an integer).
Returns:
client.sticker_find("song", "path/to/folder", "name1")
# => [{"file" => "path/to/folder/file1.ogg", "sticker" => "name1=value1"}, ...]
Reads a sticker value for the specified object.
Adds a sticker value to the specified object. If a sticker item with that name already exists, it is incremented by supplied value.
Lists the stickers for the specified object.
Adds a sticker value to the specified object. If a sticker item with that name already exists, it is replaced.
Subscribe to a channel.
The channel is created if it does not exist already.
The name may consist of alphanumeric ASCII characters plus underscore, dash, dot and colon.
Updates the music database: find new files, remove deleted files, update modified files.
uri is a particular directory or song/file to update.
If you do not specify it, everything is updated.