mpdev.1

.\" vim: tw=75
.TH mpdev 1 "December 23, 2009" "manual"
.SH NAME
.PP
mpdev - mpd Event Watcher
.SH SYNOPSIS
.PP
mpdev [\f[I]options\f[]]

.SH DESCRIPTION

\fBmpdev\fR(1) is a mpd event watcher. It connects to mpd, waits for idle
events. By default it will get the host name and port for mpd from
\f[B]MPD_HOST\f[] and \f[B]MPD_PORT\f[] environment variables.
\f[B]MPD_PASSWORD\f[] environment variable can be set to make
\fBmpdev\fR(1) connect to a password-protected mpd. If these environment
variables aren't set, \fBmpdev\fR(1) connects to localhost on port 6600.

.SH OPTIONS
.TP 3
.B -v
Set verbose output. You can increase verbosity by specifying it multiple
times
.RS
.RE

.TP
\fB-h\fR \fIhost\fR / \fIIP\fR
Host or IP address of mpd host if different from localhost
.RS
.RE

.TP
\fB-p\fR \fIport\fR
port on which mpd(1) is listening if different from 6600
.RS
.RE

.TP
\fB-s\fR \fIunix_socket\fR
Unix domain socket in case you don't want to use \fIIP\fR and \fIport\fR
.RS
.RE

.TP
\fB-r\fR \fIretry_interval\fR
Retry interval in seconds in case \fBmpd\fR(1) is down
.RS
.RE

.SH HOOKS
You can create scripts in $HOME/.mpdev directory. The default installation
installs a script named $HOME/.mpdev/player for the uid 1000. The script
does the following

.IP \[bu] 4
scrobbles titles to last.fm and libre.fm. You have to create API keys by
running lastfm-scrobbler and librefm-scrobbler one time. You can disable
scrobbling by setting DISABLE_SCROBBLE environment variable
.sp -1
.IP \[bu]
updates play counts in the sqlite stats.db. All db updates get disabled if
you set \fBNO_DB_UPDATE\fR environment variable.
.sp -1
.IP \[bu]
Synchronizes the ratings in the sticker (sqlite). It also initializes the
rating to 3 when you play an unrated song. All db updates get disabled if
you set \fBNO_DB_UPDATE\fR environment variable.
.PP

You can put your own script named `player` in this directory. In fact
\fBmpdev\fR(1) can run specific hooks for specific types of mpd events. A
hook can be any executable program or script. It will be passed arguments
and have certain environment variables related to the song playing,
available to it. Apart from the \fBplayer\fR script, the default
installation will put the following scripts

.EX
\fBplaypause\fR - This gets executed when you pause or play a song
\fBmixer\fR     - This gets executed when you change the mixer volume
\fBoutput\fR    - This gets executed when you enable or disable any output
.EE

Below is a list of of events and corresponding hooks that will be executed
if available.

.TS
l l.
MPD EVENT             | Hook script
_
SONG_CHANGE           | ~/.mpdev/player
PLAY/PAUSE            | ~/.mpdev/playpause
STICKER_EVENT         | ~/.mpdev/sticker
MIXER_EVENT           | ~/.mpdev/mixer
OUTPUT_EVENT          | ~/.mpdev/output
OPTIONS_EVENT         | ~/.mpdev/options
UPDATE_EVENT          | ~/.mpdev/update
DATABASE_EVENT        | ~/.mpdev/database
PLAYLIST_EVENT        | ~/.mpdev/playlist
STORED_PLAYLIST_EVENT | ~/.mpdev/stored_playlist
PARTITION_EVENT       | ~/.mpdev/partition
SUBSCRIPTION_EVENT    | ~/.mpdev/subscription
MESSAGE_EVENT         | ~/.mpdev/message
MOUNT_EVENT           | ~/.mpdev/mount
NEIGHBOUR_EVENT       | ~/.mpdev/neighbour
CUSTOM_EVENT          | ~/.mpdev/custom
.TE

The hooks are passed the following arguments

.IP \[bu] 4
mpd-event      - Passed when the above events listed, apart from
SONG_CHANGE happen.
.sp -1
.IP \[bu]
player-event   - Passed to ~/.mpdev/playpause when you play/pause player
.sp -1
.IP \[bu]
playlist-event - Passed to ~/.mpdev/playlist when the playlist changes
.sp -1
.IP \[bu]
now-playing    - Passed to ~/.mpdev/player when a song starts playing
.sp -1
.IP \[bu]
end-song       - Passed to ~/.mpdev/player when a song finishes playing
.sp -1
.IP \[bu]
output-event   - Passed to ~/.mpdev/output script when any device outputs
are enabled or disabled

.SH Environment Variables

\fBmpdev\fR(1) sets the following environment variables

.EX
SONG_ID            - Set to the ID from mpd database
SONG_URI           - Set to the full path of the music file
SONG_TITLE         - Set to the title of the song
SONG_ARTIST        - Set to the song artist
SONG_ALBUM         - Set to the song album
SONG_DATE          - Set to the Date tag of the song
SONG_GENRE         - Set to the Genre tag of the song
SONG_TRACK         - Set to the track number of the song
SONG_DURATION      - Set to the song duration
ELAPSED_TIME       - Total time elapsed within the current song in seconds,
                     but with higher resolution
SONG_PLAYED        - Set to the duration for which the song was played
SONG_LAST_MODIFIED - Set to the last modified time of the song
START_TIME         - Time at which the song play started
END_TIME           - Time at which the song ended
PLAYER_STATE       - Set when you pause/resume player
VERBOSE            - Set to the verbose field
OUTPUT_CHANGED     - Set when you enable or disable any output devices.
                     This indicates the new state of an output device.
VOLUME             - Set during startup and when you change mixer volume.
                     This indicates the volume level as a percentage.
.EE

if \fI$HOME/.config/lastfm-scrobbler\fR &
\fI$HOME/.config/librefm-scrobbler\fR are present, \fBmpdev\fR(1) sets
SCROBBLER_LASTFM and SCROBBLER_LIBREFM environment variables respectively.
These get created when you create API keys for lastfm, librefm by running
lastfm-scrobbler and librefm-scrobbler one time with --connect argument.

\fBmpdev\fR(1) also runs OUTPUT_EVENT on startup ($HOME/.mpdev/output),
with the argument output-initialize. This allows you to store information
for devices configured in your \fBmpd.conf\fR(5). If any output changes,
the environment variable OUTPUT_CHANGED is set in the form

.TP 2
"\fIDEVNO\fR - \fIstate\fR"

Where \fIDEVNO\fR is the ID of the device in mpd.conf (0, 1, 2, etc) and
\fIstate\fR is either the word "enabled" or "disabled".

.PP
So, in the below example, if you disable the headphone,
\fBOUTPUT_CHANGED\fR environment variable will be set as "3 - disabled"

All devices are maintained in the environment variables
\fBOUTPUT_\fR\fIDEVNO\fR\fB_ID\fR, \fBOUTPUT_\fR\fIDEVNO\fR\fB_NAME\fR,
\fBOUTPUT_\fR\fIDEVNO\fR\fB_STATE\fR, \fBOUTPUT_\fR\fIDEVNO\fR\fB_TYPE\fR,
\fBOUTPUT_\fR\fIDEVNO\fR\fB_EXTRA1\fR,
\fBOUTPUT_\fR\fIDEVNO\fR\fB_EXTRA2\fR,
\fBOUTPUT_\fR\fIDEVNO\fR\fB_EXTRA...\fR
\fBOUTPUT_\fR\fIDEVNO\fR\fB_EXTRAn\fR

Here \fIDEVNO\fR is the device id of the audio device in mpd.conf.

Below is an example of the state of environment variables where mpd.conf
have 3 devices configured (Piano DAC Plus 2.1, Xonar EssenceOne, Scarlet 2i2 USB).

.EX
OUTPUT_0_ID=0
OUTPUT_0_NAME=Piano DAC Plus 2.1
OUTPUT_0_STATE=enabled
OUTPUT_1_ID=1
OUTPUT_1_NAME=Xonar EssenceOne
OUTPUT_1_STATE=disabled
OUTPUT_2_ID=2
OUTPUT_2_NAME=Scarlett 2i2 USB
OUTPUT_2_STATE=disabled
.EE

.SH SEE ALSO
.IP \[bu] 2
\f[B]mpd\f[](1),
\f[B]mpd.conf\f[](5),
\f[B]sqlite3\f[](1),
\f[B]lastfm-scrobbler\f[](1),
\f[B]librefm-scrobbler\f[](1),
\f[B]karma\f[](1),
\f[B]mpdev_cleanup\f[](1),
\f[B]mpdev_rename\f[](1),
\f[B]mpdev_update\f[](1),
\f[B]mpdplaylist\f[](1),
\f[B]transfer_play\f[](1)
.IP \[bu] 2
https://github.com/mbhangui/mpdev/

.SH REPORTING BUGS
.PP
If you find a bug, please report it at https://github.com/mbhangui/mpdev/issues

.SH COPYRIGHT
.PP
Copyright (c) 2020 Manvendra Bhangui <mpdev@indimail.org>
.PD 0
.P
.PD
Free
use of this software is granted under the terms of the GNU General
Public License (GPLv2).
.SH AUTHOR
Manvendra Bhangui <manvendra@indimail.org>