davis(1)

# NAME
davis - a command line interface for MPD.

# SYNOPSIS
*davis* [--verbose] [--host <host>] <command> [<args>]

# DESCRIPTION
Davis is a command line interface for MPD.

# OPTIONS
\--help
	Prints help information.
\-v, --verbose
	Enable verbose output.
\-h, --host <host>
	The MPD server to connect to, can be specified using IP/hostname, or a
	label defined in the config file.
\-p, --plain
	Disable decorations in output, useful for scripting.

# ENVIRONMENT VARIABLES
MPD_HOST
	The MPD server to connect to. Can also be set with *--host*.

# DAVIS COMMANDS:
add <path>
	Add items in path to queue.

albumart -o <output> [path]
	Download album art from MPD to file specified by <output>. Davis will
	fetch the album art for the track at [path] if specified, and the currently
	playing track otherwise. If dash ('-') is specified as output, davis will
	write the album art to stdout. MPD requires the cover file to be named
	cover.jpg, cover.png, cover.tiff, or cover.bmp at the time of writing, this
	is documented in the MPD protocol documentation:
	https://mpd.readthedocs.io/en/latest/protocol.html#the-music-database

clear
	Clear the current queue.

current
	Display metadata about the currently playing song.

del <index>
	Remove song at index from queue.

help
	Prints a brief help text.

list <tag> [query]
	List all values for tag, for songs matching query. See *QUERY*
	for details on the query format.

load <path>
	Load playlist at path to queue                    

ls [path]
	List items in path, or the root if omitted.

mv <from> <to>
	Move song in queue by index.

next
	Skip to next song in queue.

pause
	Pause playback.

play
	Continue playback from current state.

play [index]
	Start playback from index in queue.

prev
	Go back to previous song in queue.

queue
	Display the current queue.

read-comments <file>
	Read raw metadata for file. The format will depend on the format of the
	file.

search <query>
	Search the MPD database for files matching query. See *QUERY* for details on
	the format.

seek <position>             
	Seek to position. The position is expressed in [+-][[hh:]:mm]:ss format. If
	+ or - is used, the seek is done relative to the current positon.

status
	Display MPD status.

stop
	Stop playback.

toggle
	Toggle between play/pause.

update
	Update the MPD database.

# Plugins
Davis can be extended with external sub-commands. An external sub-command is
created by placing an executable file named `davis-$name` in one of the
following locations:

- `/etc/davis/bin/`
- `~/.config/davis/bin/`
- A directory in `$PATH`

An external command `davis-foo` is executed by calling `davis foo [args]`. Davis
will find the external sub command, and pass along any arguments. External sub
commands can read the `$MPD_HOST` environment variable to know which MPD server
davis is expected to speak to.

# QUERY
A query can either be a single argument in the MPD filter syntax, such as:     
	davis search '((artist == "Miles Davis") AND (album == "Kind Of Blue"))'
Or a list of arguments-pairs, each pair corresponding to a filter, such as:    
	davis search artist 'Miles Davis' album 'Kind Of Blue'         
More information on the MPD filter syntax is available at:         
	https://mpd.readthedocs.io/en/latest/protocol.html#filters  

# CONFIGURATION
Davis will read a configuration file from one of these locations:

- ~/.config/davis/davis.conf
- /etc/davis/davis.conf

The configuration file has two sections, tags and hosts. The tags section
configures which tags davis should display when running the "current" command.
The host section defines a list of MPD hosts for davis to connect to. Example
file:

```
[tags]
# The list of enabled tags
enabled=Composer,Work,Conductor,Ensemble,Performer,Label,Opus,RecordingDate,Rating,Genre,Location
# Change the label of "RecordingDate" to "Recording Date"
RecordingDate=Recording Date
\[hosts]
# Connect to localhost by default
default=127.0.0.1
# Connect to another host using label rpi with the --host option.
rpi=192.168.0.16
```

# AUTHORS
Simon Persson <simon@flaskpost.me>