class MPD::Client

Overview

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

Defined in:

crystal_mpd/client.cr

Constant Summary

ERROR_PREFIX = "ACK "
EVENTS_LIST = [:volume, :repeat, :random, :single, :consume, :playlist, :playlistlength, :mixrampdb, :state, :song, :songid, :time, :elapsed, :bitrate, :duration, :audio, :nextsong, :nextsongid]
HELLO_PREFIX = "OK MPD "
NEXT = "list_OK\n"
SUCCESS = "OK\n"

Constructors

Instance Method Summary

Constructor Detail

def self.new(host : String = "localhost", port : Int32 = 6600, *, with_callbacks : Bool = false, password : String | Nil = nil) #

Creates a new MPD client. Parses the #host, #port.

This constructor will raise an exception if could not connect to MPD


[View source]

Instance Method Detail

def add(uri : String, position : Int32 | String | Nil = nil) #

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.


[View source]
def addid(uri : String, position : Int32 | String | Nil = nil) #

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).


[View source]
def albumart(uri : String) #

Locate album art for the given song


[View source]
def callbacks_timeout : Time::Span #

[View source]
def callbacks_timeout=(callbacks_timeout : Time::Span) #

[View source]
def channels #

Obtain a list of all channels. The response is a list of channel: lines.


[View source]
def clear #

Clears the current playlist.


[View source]
def close #

Closes the connection to MPD.


[View source]
def command_list_end #

[View source]
def command_list_ok_begin #

https://mpd.readthedocs.io/en/latest/protocol.html#command-lists


[View source]
def commands #

Shows which commands the current user has access to.


[View source]
def config #

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.

[View source]
def connect #

Connect to the MPD daemon unless conected.

Connect using the #reconnect method.


[View source]
def connected? #

Check if the client is connected.


[View source]
def consume(state : Bool) #

Sets consume state to state, state should be false or true.

When consume is activated, each song played is removed from playlist.


[View source]
def count(filter : String, *, group : String | Nil = nil) #

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"}]

[View source]
def crop #

Delete all playlist entries except the one currently playing


[View source]
def currentsong #

Displays the song info of the current song (same song that is identified in #status).


[View source]
def decoders #

Print a list of decoder plugins, followed by their supported suffixes and MIME types.


[View source]
def delete(songpos : Int32 | MPD::Range) #

Deletes a song from the playlist.


[View source]
def deleteid(songid : Int32) #

Deletes the song singid from the playlist.


[View source]
def disconnect #

Disconnect from the MPD daemon.


[View source]
def find(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil) #

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 contains 'Rock')")

[View source]
def findadd(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil, position : Int32 | String | Nil = nil) #

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')")

[View source]
def getvol #

Read the volume. The result is a {"volume" => "100"} like in #status.


[View source]
def host : String #

[View source]
def list(type : String, filter : String | Nil = nil) #

Lists unique tags values of the specified type.

type can be any tag supported by MPD or file.

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'))")

[View source]
def listall(uri : String | Nil = nil) #

Lists all songs and directories in uri.


[View source]
def listallinfo(uri : String | Nil = nil) #

Same as #listall, except it also returns metadata info in the same format as #lsinfo.


[View source]
def listfiles(uri : String | Nil = nil) #

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.


[View source]
def listplaylist(name : String) #

Lists the songs in the playlist name.

Playlist plugins are supported.


[View source]
def listplaylistinfo(name : String) #

Lists the songs with metadata in the playlist.

Playlist plugins are supported.


[View source]
def listplaylists #

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.


[View source]
def load(name : String, songpos : Int32 | MPD::Range | Nil = nil, position : Int32 | String | Nil = nil) #

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.)


[View source]
def lsinfo(uri : String | Nil = nil) #

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:///).


[View source]
def move(from : Int32 | MPD::Range, to : Int32) #

Moves the song at from or range of songs at from to to in the playlist.


[View source]
def moveid(from : Int32, to : Int32 | String) #

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).


[View source]
def next #

Plays next song in the playlist.


[View source]
def nextsong : Object | Nil #

Show the currently queued (next) song.


[View source]
def notcommands #

Shows which commands the current user does not have access to.


[View source]
def on(event : Symbol, &block : String -> _) #

This will register a block callback that will trigger whenever that specific event happens.

mpd.on :state do |state|
  puts "State was change to #{state}"
end

[View source]
def outputs #

Shows information about all outputs.


[View source]
def pause(state : Bool | Nil = nil) #

Pause or resume playback. Pass state true to pause playback or false to resume playback. Without the parameter, the pause state is toggled.


[View source]
def play(songpos : Int32 | Nil = nil) #

Begins playing the playlist at song number songpos.


[View source]
def playid(songnid : Int32 | Nil = nil) #

Begins playing the playlist at song songid.


[View source]
def playlistadd(name : String, uri : String, position : Int32 | String | Nil = nil) #

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.


[View source]
def playlistclear(name : String) #

Clears the playlist name.m3u.


[View source]
def playlistdelete(name : String, songpos : Int32 | MPD::Range) #

Deletes songpos from the playlist name.m3u.

The songpos parameter can be a range.


[View source]
def playlistfind(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil) #

Search the queue for songs matching filter.


[View source]
def playlistid(songid : Int32 | Nil = nil) #

Displays a list of songs in the playlist.

songid is optional and specifies a single song to display info for.


[View source]
def playlistinfo(songpos : Int32 | MPD::Range | Nil = nil) #

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)

[View source]
def playlistmove(name : String, from : Int32 | MPD::Range, to : Int32) #

Moves the song at position from in the playlist name.m3u to the position to.


[View source]
def playlistsearch(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil) #

Search the queue for songs matching filter. Parameters have the same meaning as for #find, except that search is not case sensitive.


[View source]
def port : Int32 #

[View source]
def previous #

Plays previous song in the playlist.


[View source]
def random(state : Bool) #

Sets random state to state, state should be false or true.


[View source]
def readmessages #

Reads messages for this client. The response is a list of channel: and message: lines.


[View source]
def readpicture(uri : String) #

Locate a picture for the given song


[View source]
def reconnect #

Attempts to reconnect to the MPD daemon.


[View source]
def rename(name : String, new_name : String) #

Renames the playlist name.m3u to new_name.m3u.


[View source]
def repeat(state : Bool) #

Sets repeat state to state, state should be false or true.


[View source]
def replay_gain_mode(mode : String) #

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.


[View source]
def replay_gain_status #

Prints replay gain options.

Currently, only the variable #replay_gain_mode is returned.


[View source]
def rescan(uri : String | Nil = nil) #

Same as #update, but also rescans unmodified files.


[View source]
def rm(name : String) #

Removes the playlist name.m3u from the playlist directory.


[View source]
def save(name : String) #

Saves the current playlist to name.m3u in the playlist directory.


[View source]
def search(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil) #

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')")

[View source]
def searchadd(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil, position : Int32 | String | Nil = nil) #

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.


[View source]
def searchaddpl(name : String, filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil, position : Int32 | String | Nil = nil) #

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.


[View source]
def searchcount(filter : String, *, group : String | Nil = nil) #

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.


[View source]
def seek(songid : Int32, time : Int32) #

Seeks to the position time (in seconds) of entry songpos in the playlist.


[View source]
def seekcur(time : String | Int32) #

Seeks to the position time within the current song.

If prefixed by + or -, then the time is relative to the current playing position.


[View source]
def seekid(songid : Int32, time : String | Int32) #

Seeks to the position time (in seconds) of song songid.


[View source]
def sendmessage(channel : String, message : String) #

Send a message to the specified channel.


[View source]
def setvol(vol : Int) #

Sets volume to vol, the range of volume is 0-100.


[View source]
def shuffle(range : MPD::Range | Nil = nil) #

Shuffles the current playlist. range is optional and specifies a range of songs.


[View source]
def single(state : Bool) #

Sets single state to state, state should be false or true.

When single is activated, playback is stopped after current song, or song is repeated if the #repeat mode is enabled.


[View source]
def stats #

Displays statistics.

Response:

  • artists: number of artists
  • songs: number of albums
  • uptime: daemon uptime in seconds
  • db_playtime: sum of all song times in the db
  • db_update: last db update in UNIX time
  • playtime: time length of music played

[View source]
def status #

Reports the current status of the player and the volume level.

Response:

  • #volume: 0-100
  • #repeat: 0 or 1
  • #random: 0 or 1
  • #single: 0 or 1
  • #consume: 0 or 1
  • playlist: 31-bit unsigned integer, the playlist version number
  • playlistlength: integer, the length of the playlist
  • state: play, stop, or pause
  • song: playlist song number of the current song stopped on or playing
  • songid: playlist songid of the current song stopped on or playing
  • #nextsong: playlist song number of the next song to be played
  • nextsongid: playlist songid of the next song to be played
  • time: total time elapsed (of current playing/paused song)
  • elapsed: Total time elapsed within the current song, but with higher resolution.
  • bitrate: instantaneous bitrate in kbps
  • xfade: crossfade in seconds
  • mixrampdb: mixramp threshold in dB
  • mixrampdelay: mixrampdelay in seconds
  • audio: sampleRate:bits:channels
  • updating_db: job id
  • error: if there is an error, returns message here

[View source]
def stop #

Stops playing.


[View source]
def subscribe(name : String) #

Subscribe to a channel name.

The channel is created if it does not exist already. The name may consist of alphanumeric ASCII characters plus underscore, dash, dot and colon.


[View source]
def tagtypes #

Shows a list of available tag types.


[View source]
def unsubscribe(name : String) #

Unsubscribe from a channel name.


[View source]
def update(uri : String | Nil = nil) #

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.


[View source]
def urlhandlers #

Gets a list of available URL handlers.


[View source]
def version : String? #

[View source]
def volume(change : Int) #

Changes volume by amount change.


[View source]
def with_command_list(&) #

[View source]