class MPD::Client
- MPD::Client
- Reference
- Object
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.crConstant 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
-
.new(host : String = "localhost", port : Int32 = 6600, *, with_callbacks : Bool = false, password : String | Nil = nil)
Creates a new MPD client.
Instance Method Summary
-
#add(uri : String, position : Int32 | String | Nil = nil)
Adds the file
uri
to the playlist (directories add recursively). -
#addid(uri : String, position : Int32 | String | Nil = nil)
Adds a song to the playlist (non-recursive) and returns the song id.
-
#albumart(uri : String)
Locate album art for the given song
- #callbacks_timeout : Time::Span
- #callbacks_timeout=(callbacks_timeout : Time::Span)
-
#channels
Obtain a list of all channels.
-
#clear
Clears the current playlist.
-
#close
Closes the connection to MPD.
- #command_list_end
-
#command_list_ok_begin
https://mpd.readthedocs.io/en/latest/protocol.html#command-lists
-
#commands
Shows which commands the current user has access to.
-
#config
Dumps configuration values that may be interesting for the client.
-
#connect
Connect to the MPD daemon unless conected.
-
#connected?
Check if the client is connected.
-
#consume(state : Bool)
Sets consume state to
state
,state
should befalse
ortrue
. -
#count(filter : String, *, group : String | Nil = nil)
Count the number of songs and their total playtime in the database matching
filter
. -
#crop
Delete all playlist entries except the one currently playing
-
#currentsong
Displays the song info of the current song (same song that is identified in
#status
). -
#decoders
Print a list of decoder plugins, followed by their supported suffixes and MIME types.
-
#delete(songpos : Int32 | MPD::Range)
Deletes a song from the playlist.
-
#deleteid(songid : Int32)
Deletes the song
singid
from the playlist. -
#disconnect
Disconnect from the MPD daemon.
-
#find(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil)
Search the database for songs matching
filter
. -
#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. -
#getvol
Read the volume.
- #host : String
-
#list(type : String, filter : String | Nil = nil)
Lists unique tags values of the specified
type
. -
#listall(uri : String | Nil = nil)
Lists all songs and directories in
uri
. - #listallinfo(uri : String | Nil = nil)
-
#listfiles(uri : String | Nil = nil)
Lists the contents of the directory
URI
, including files are not recognized byMPD
. -
#listplaylist(name : String)
Lists the songs in the playlist
name
. -
#listplaylistinfo(name : String)
Lists the songs with metadata in the playlist.
-
#listplaylists
Prints a list of the playlist directory.
-
#load(name : String, songpos : Int32 | MPD::Range | Nil = nil, position : Int32 | String | Nil = nil)
Loads the playlist
name
into the current queue. -
#lsinfo(uri : String | Nil = nil)
Lists the contents of the directory
uri
. -
#move(from : Int32 | MPD::Range, to : Int32)
Moves the song at
from
or range of songs atfrom
toto
in the playlist. -
#moveid(from : Int32, to : Int32 | String)
Moves the song with
from
(songid) toto
(playlist index) in the playlist. -
#next
Plays next song in the playlist.
-
#nextsong : Object | Nil
Show the currently queued (next) song.
-
#notcommands
Shows which commands the current user does not have access to.
-
#on(event : Symbol, &block : String -> _)
This will register a block callback that will trigger whenever that specific event happens.
-
#outputs
Shows information about all outputs.
-
#pause(state : Bool | Nil = nil)
Pause or resume playback.
-
#play(songpos : Int32 | Nil = nil)
Begins playing the playlist at song number
songpos
. -
#playid(songnid : Int32 | Nil = nil)
Begins playing the playlist at song
songid
. -
#playlistadd(name : String, uri : String, position : Int32 | String | Nil = nil)
Adds
uri
to the playlistname
.m3u. -
#playlistclear(name : String)
Clears the playlist
name
.m3u. -
#playlistdelete(name : String, songpos : Int32 | MPD::Range)
Deletes
songpos
from the playlistname
.m3u. -
#playlistfind(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil)
Search the queue for songs matching
filter
. -
#playlistid(songid : Int32 | Nil = nil)
Displays a list of songs in the playlist.
-
#playlistinfo(songpos : Int32 | MPD::Range | Nil = nil)
Displays a list of all songs in the playlist,
-
#playlistmove(name : String, from : Int32 | MPD::Range, to : Int32)
Moves the song at position
from
in the playlistname
.m3u to the positionto
. -
#playlistsearch(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil)
Search the queue for songs matching
filter
. - #port : Int32
-
#previous
Plays previous song in the playlist.
-
#random(state : Bool)
Sets random state to
state
,state
should befalse
ortrue
. -
#readmessages
Reads messages for this client.
-
#readpicture(uri : String)
Locate a picture for the given song
-
#reconnect
Attempts to reconnect to the MPD daemon.
-
#rename(name : String, new_name : String)
Renames the playlist
name
.m3u tonew_name
.m3u. -
#repeat(state : Bool)
Sets repeat state to
state
,state
should befalse
ortrue
. -
#replay_gain_mode(mode : String)
Sets the replay gain mode.
-
#replay_gain_status
Prints replay gain options.
-
#rescan(uri : String | Nil = nil)
Same as
#update
, but also rescans unmodified files. -
#rm(name : String)
Removes the playlist
name
.m3u from the playlist directory. -
#save(name : String)
Saves the current playlist to
name
.m3u in the playlist directory. -
#search(filter : String, *, sort : String | Nil = nil, window : MPD::Range | Nil = nil)
Search the database for songs matching
filter
. -
#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. -
#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. -
#searchcount(filter : String, *, group : String | Nil = nil)
Count the number of songs and their total playtime in the database matching
filter
. -
#seek(songid : Int32, time : Int32)
Seeks to the position
time
(in seconds) of entrysongpos
in the playlist. -
#seekcur(time : String | Int32)
Seeks to the position
time
within the current song. -
#seekid(songid : Int32, time : String | Int32)
Seeks to the position
time
(in seconds) of songsongid
. -
#sendmessage(channel : String, message : String)
Send a
message
to the specifiedchannel
. -
#setvol(vol : Int)
Sets volume to
vol
, the range of volume is 0-100. -
#shuffle(range : MPD::Range | Nil = nil)
Shuffles the current playlist.
-
#single(state : Bool)
Sets single state to
state
,state
should befalse
ortrue
. -
#stats
Displays statistics.
-
#status
Reports the current status of the player and the volume level.
-
#stop
Stops playing.
-
#subscribe(name : String)
Subscribe to a channel
name
. -
#tagtypes
Shows a list of available tag types.
-
#unsubscribe(name : String)
Unsubscribe from a channel
name
. -
#update(uri : String | Nil = nil)
Updates the music database: find new files, remove deleted files, update modified files.
-
#urlhandlers
Gets a list of available URL handlers.
- #version : String?
-
#volume(change : Int)
Changes volume by amount
change
. - #with_command_list(&)
Constructor Detail
Creates a new MPD client. Parses the #host
, #port
.
This constructor will raise an exception if could not connect to MPD
Instance Method Detail
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
or true
.
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"}]
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 contains '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')")
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'))")
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.
Lists the songs with metadata in the playlist.
Playlist plugins are supported.
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).
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
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
.
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)
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.
Reads messages for this client. The response is a list of channel:
and message:
lines.
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.
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.
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.
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
or true
.
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:
#volume
: 0-100#repeat
: 0 or 1#random
: 0 or 1#single
: 0 or 1#consume
: 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 playing#nextsong
: 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 resolution.bitrate
: instantaneous bitrate in kbpsxfade
: crossfade in secondsmixrampdb
: mixramp threshold in dBmixrampdelay
: mixrampdelay in secondsaudio
: sampleRate:bits:channelsupdating_db
: job iderror
: if there is an error, returns message here
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.
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.