Skip to content

mpdev.1

Jump to bottom
Manvendra Bhangui edited this page Oct 22, 2024 · 3 revisions

NAME

mpdev - mpd Event Watcher

SYNOPSIS

mpdev [options]

DESCRIPTION

mpdev(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 MPD_HOST and MPD_PORT environment variables. MPD_PASSWORD environment variable can be set to make mpdev(1) connect to a password-protected mpd. If these environment variables aren't set, mpdev(1) connects to localhost on port 6600.

OPTIONS

-v
Set verbose output. You can increase verbosity by specifying it multiple times

-h host / IP
Host or IP address of mpd host if different from localhost

-p port
port on which mpd(1) is listening if different from 6600

-s unix_socket
Unix domain socket in case you don't want to use IP and port

-r retry_interval
Retry interval in seconds in case mpd(1) is down

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

  • 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

  • updates play counts in the sqlite stats.db. All db updates get disabled if you set NO_DB_UPDATE environment variable.

  • 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 NO_DB_UPDATE environment variable.

You can put your own script named `player` in this directory. In fact mpdev(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 player script, the default installation will put the following scripts

playpause - This gets executed when you pause or play a song
mixer     - This gets executed when you change the mixer volume
output    - This gets executed when you enable or disable any output

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

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

The hooks are passed the following arguments

  • mpd-event - Passed when the above events listed, apart from SONG_CHANGE happen.

  • player-event - Passed to ~/.mpdev/playpause when you play/pause player

  • playlist-event - Passed to ~/.mpdev/playlist when the playlist changes

  • now-playing - Passed to ~/.mpdev/player when a song starts playing

  • end-song - Passed to ~/.mpdev/player when a song finishes playing

  • output-event - Passed to ~/.mpdev/output script when any device outputs are enabled or disabled

Environment Variables

mpdev(1) sets the following environment variables

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.

if $HOME/.config/lastfm-scrobbler & $HOME/.config/librefm-scrobbler are present, mpdev(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.

mpdev(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 mpd.conf(5). If any output changes, the environment variable OUTPUT_CHANGED is set in the form

"DEVNO - state"
Where DEVNO is the ID of the device in mpd.conf (0, 1, 2, etc) and state is either the word "enabled" or "disabled".

So, in the below example, if you disable the headphone, OUTPUT_CHANGED environment variable will be set as "3 - disabled"

All devices are maintained in the environment variables OUTPUT_DEVNO_ID, OUTPUT_DEVNO_NAME, OUTPUT_DEVNO_STATE, OUTPUT_DEVNO_TYPE, OUTPUT_DEVNO_EXTRA1, OUTPUT_DEVNO_EXTRA2, OUTPUT_DEVNO_EXTRA... OUTPUT_DEVNO_EXTRAn

Here DEVNO 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).

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

SEE ALSO

mpd(1) mpd.conf(5) sqlite3(1) lastfm-scrobbler(1), librefm-scrobbler(1), karma(1), mpdev_cleanup(1), mpdev_rename(1), mpdev_update(1), mpdplaylist(1), transfer_play(1)

https://github.com/mbhangui/mpdev/

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

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

AUTHOR Manvendra Bhangui <manvendra@indimail.org>

Clone this wiki locally