mpc (1) Linux Manual Page
mpc – Program for controlling Music Player Daemon (MPD)
Synopsis
mpc [<command> <arguments>]Description
mpc is a client for MPD, the Music Player Daemon. mpc connects to a MPD and controls it according to commands and arguments passed to it. If no arguments are passed, current status is given.Options
- –format
- Configure the format of song display for status and the playlist. The metadata delimiters are "%name%", "%artist%", "%album%", "%title%", "%track%", "%time%", and "%file%". The [] operator is used to group output such that if no metadata delimiters are found or matched between ‘[‘ and ‘]’, then none of the characters between ‘[‘ and ‘]’ are output. ‘&’ and ‘|’ are logical operators for and and or. ‘#’ is used to escape characters. Some useful examples for format are: "%file%" and "[[%artist% – ]%title%]|[%file%]". This command also takes the following defined escape sequences:
\\ – backslash
\a – alert
\b – backspace
\t – tab
\n – newline
\v – vertical tab
\f – form-feed
\r – carriage return
- –no-status
- Prevents the current song status from being printed on completion of some of the commands.
Commands
- add <file>
- Adds a song from the music database to the playlist. Can also read input from pipes. Use "mpc ls | mpc add" to add all files to the playlist.
- clear
- Empties playlist.
- crop
- Remove all songs except for the currently playing song.
- current
- Show the currently playing song
- crossfade [<seconds>]
- Gets and sets the current amount of crossfading between songs (0 disables crossfading).
- del <songpos>
- Removes a playlist number from the playlist. Can also read input from pipes (0 deletes the current playing song).
- disable <output #>
- Disables the output, number is required.
- enable <output #>
- Enables the output, number is required.
- idle
- Waits until an event occurs. Prints a list of event names, one per line. See the MPD protocol documentation for further information.
- listall [<file>]
- Lists <file> from playlist. If no <file> is specified, lists all songs.
- load <file>
- Loads <file> as playlist.
- ls [<directory>]
- Lists all files/folders in <directory>. If no <directory> is specified, lists all files in music directory.
- lsplaylists
- Lists available playlists.
- move <from> <to>
- Moves song at position <from> to the position <to> in the playlist.
- next
- Starts playing next song on playlist.
- outputs
- Lists all available outputs
- pause
- Pauses playing.
- play <position>
- Starts playing the song-number specified. If none is specified, plays number 1.
- playlist
- Prints entire playlist.
- prev
- Starts playing previous song.
- random <on|off>
- Toggle random mode if state ("on" or "off") is not specified.
- repeat <on|off>
- Toggle repeat mode if state ("on" or "off") is not specified.
- single <on|off>
- Toggle single mode if state ("on" or "off") is not specified.
- consume <on|off>
- Toggle consume mode if state ("on" or "off") is not specified.
- rm <file>
- Deletes a specific playlist.
- save <file>
- Saves playlist as <file>.
- search <type> <query> [<type> <query>]…
- Searches for songs where all of the given tag <type>s match the given <query>s. Any number of tag type and query combinations can be specified. Possible tag types are: artist, album, title, track, name, genre, date, composer, performer, comment, disc, filename, or any (to match any tag).
- find <type> <query> [<type> <query>]…
- Same as search, but match <query>s exactly.
- list <type> [<type> <query>]…
- Return a list of all tags of given tag <type>. Optional search <type>s/<query>s limit results in a way similar to search.
- seek [+-][<HH:MM:SS>] or <[+-]<0-100>%>
- Seeks by hour, minute or seconds, hours or minutes can be omitted. If seeking by percentage, seeks within the current song in the specified manner. If a "+" or "-" is used, the seek is done relative to the current song position. Absolute seeking by default.
- shuffle
- Shuffles all songs on the playlist.
- stats
- Displays statistics about MPD.
- stop
- Stops playing.
- toggle
- Toggles between play and pause. If stopped starts playing. Does not support start playing at song number (use play).
- update [<path>]
- Scans music directory for updates if no <path> is specified. If one or more <path>’s are specified, scans only those path’s for updates. Can take input from a pipe.
- version
- Reports the version of MPD.
- volume [+-]<num>
- Sets the volume to <num> (0-100). If "+" or "-" is used, then it adjusts the volume relative to the current volume.
Environment
- This section describes some environment variables that affect how mpc operates.
MPD_HOST, MPD_PORT
- By default, mpc connects to localhost:6600. This can be changed either at compile-time, or by exporting the MPD_HOST and MPD_PORT environment variables.
If you specify an absolute path in MPD_HOST, mpc attempts a connection via Unix Domain Socket.
To use a password with MPD, set MPD_HOST to password [at] host.
Examples
- For useful examples of mpc use in playlist parsing, see mpd-m3u-playlist.sh and mpd-pls-playlist.sh.