davis.1

.\" Generated by scdoc  1.11.1
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "davis" "1" "2021-12-02"
.P
.SH NAME
davis - a command line interface for MPD.\&
.P
.SH SYNOPSIS
\fBdavis\fR [--verbose] [--host <host>] <command> [<args>]
.P
.SH DESCRIPTION
Davis is a command line interface for MPD.\&
.P
.SH OPTIONS
--help
.RS 4
Prints help information.\&
.RE
-v, --verbose
.RS 4
Enable verbose output.\&
.RE
-h, --host <host>
.RS 4
The MPD server to connect to, can be specified using IP/hostname, or a
label defined in the config file.\&
.RE
-p, --plain
.RS 4
Disable decorations in output, useful for scripting.\&
.P
.RE
.SH ENVIRONMENT VARIABLES
MPD_HOST
.RS 4
The MPD server to connect to.\& Can also be set with \fB--host\fR.\&
.P
.RE
.SH DAVIS COMMANDS:
add <path>
.RS 4
Add items in path to queue.\&
.P
.RE
albumart -o <output> [path]
.RS 4
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
.P
.RE
clear
.RS 4
Clear the current queue.\&
.P
.RE
current
.RS 4
Display metadata about the currently playing song.\&
.P
.RE
del <index>
.RS 4
Remove song at index from queue.\&
.P
.RE
help
.RS 4
Prints a brief help text.\&
.P
.RE
list <tag> [query]
.RS 4
List all values for tag, for songs matching query.\& See \fBQUERY\fR
for details on the query format.\&
.P
.RE
load <path>
.RS 4
Load playlist at path to queue                    
.P
.RE
ls [path]
.RS 4
List items in path, or the root if omitted.\&
.P
.RE
mv <from> <to>
.RS 4
Move song in queue by index.\&
.P
.RE
next
.RS 4
Skip to next song in queue.\&
.P
.RE
pause
.RS 4
Pause playback.\&
.P
.RE
play
.RS 4
Continue playback from current state.\&
.P
.RE
play [index]
.RS 4
Start playback from index in queue.\&
.P
.RE
prev
.RS 4
Go back to previous song in queue.\&
.P
.RE
queue
.RS 4
Display the current queue.\&
.P
.RE
read-comments <file>
.RS 4
Read raw metadata for file.\& The format will depend on the format of the
file.\&
.P
.RE
search <query>
.RS 4
Search the MPD database for files matching query.\& See \fBQUERY\fR for details on
the format.\&
.P
.RE
seek <position>             
.RS 4
Seek to position.\& The position is expressed in [+-][[hh:]:mm]:ss format.\& If
+ or - is used, the seek is done relative to the current position.\&
.P
.RE
status
.RS 4
Display MPD status.\&
.P
.RE
stop
.RS 4
Stop playback.\&
.P
.RE
toggle
.RS 4
Toggle between play/pause.\&
.P
.RE
update
.RS 4
Update the MPD database.\&
.P
.RE
.SH 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:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`/etc/davis/bin/`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`~/.\&config/davis/bin/`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
A directory in `$PATH`

.RE
.P
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.\&
.P
.SH QUERY
A query can either be a single argument in the MPD filter syntax, such as:     
.RS 4
davis search '((artist == "Miles Davis") AND (album == "Kind Of Blue"))'
.RE
Or a list of arguments-pairs, each pair corresponding to a filter, such as:    
.RS 4
davis search artist 'Miles Davis' album 'Kind Of Blue'         
.RE
More information on the MPD filter syntax is available at:         
.RS 4
https://mpd.\&readthedocs.\&io/en/latest/protocol.\&html#filters  
.P
.RE
.SH CONFIGURATION
Davis will read a configuration file from one of these locations:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
~/.\&config/davis/davis.\&conf
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
/etc/davis/davis.\&conf

.RE
.P
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:
.nf
.RS 4
[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
.fi
.RE
.P
.SH AUTHORS
Simon Persson <simon@flaskpost.\&me>