Command-line client for Music Player Daemon (MPD) with monitoring capabilities, GNTP/Growl notifications, and MPC-like functionality.
✨ Core Features:
- 🎵 Complete MPD control (play, pause, stop, next, previous)
- 📝 Playlist management (add, delete, clear, list)
- 🔊 Volume and playback mode control
- 📊 Beautiful colored terminal output
- 🔄 Automatic reconnection on connection loss
- 🖥️ Cross-platform support (Windows, Linux, macOS)
🎬 Monitor Mode:
- 👀 Real-time monitoring of MPD status
- 📢 Desktop notifications via GNTP/Growl
- 🎨 Album artwork support
- ⌨️ Keyboard shortcuts for quick control
- 🔔 Song change and state notifications
⚙️ Advanced:
- 📄 TOML configuration file support
- 🔧 MPD config file editing (local MPD)
- 🌍 Environment variable support
- 🔍 Debug mode for troubleshooting
- 🎯 MPC-compatible commands
git clone https://github.com/cumulus13/mpdl.git
cd mpdl
go build -o mpdlgo install github.com/cumulus13/mpdl@latestDownload the latest release from the releases page.
# Show help
mpdl --help
# Start playback
mpdl play
# Add a song to playlist
mpdl add ~/Music/song.mp3
# Show current playlist
mpdl list
# Monitor MPD with notifications
mpdl monitor
# Show current status
mpdl statusCreate a configuration file at ~/.config/mpdl/config.toml (Linux/macOS) or %APPDATA%\mpdl\config.toml (Windows):
[mpd]
host = "localhost"
port = "6600"
password = ""
timeout = 10
music_root = "/home/user/Music" # or "C:/Musics" on Windows
config_path = "/home/user/.config/mpd/mpd.conf"
[gntp]
host = "localhost"
port = 23053
password = ""
icon_mode = "binary" # binary, dataurl, fileurl, httpurl
enabled = true
[display]
show_album_art = true
use_color = trueexport MPD_HOST="localhost"
export MPD_PORT="6600"
export MPD_PASSWORD=""
export MPD_TIMEOUT="10"
export MPD_MUSIC_ROOT="/home/user/Music"
export DEBUG="1" # Enable debug modempdl play [POS] # Start playback (optionally at position)
mpdl pause # Toggle pause
mpdl stop # Stop playback
mpdl next # Next song (alias: n)
mpdl prev # Previous song (aliases: previous, p)
mpdl seek [+/-]TIME # Seek to position (e.g., 30, +10, -5)mpdl add PATH # Add song/directory to playlist
mpdl del PATH # Delete songs matching PATH (aliases: delete)
mpdl clear # Clear playlist
mpdl list # Show current playlist (aliases: ls, playlist)mpdl current # Show current song
mpdl status # Show player status (alias: st)mpdl volume [VOL] # Set volume (0-100) or show current
mpdl repeat [on|off] # Toggle or set repeat mode
mpdl random [on|off] # Toggle or set random mode
mpdl single [on|off] # Toggle or set single modempdl update [PATH] # Update music databasempdl get-config KEY # Get MPD config value
mpdl set-config KEY VALUE # Set MPD config valueExamples:
mpdl get-config music_directory
mpdl set-config volume_normalization yesmpdl monitor # Start monitoring mode (aliases: mon, m)Keyboard Shortcuts in Monitor Mode:
p- Play/Pauses- Stopn- Next songb- Previous song (back)q- Quit monitor
# Connect to MPD and show status
mpdl status
# Add all MP3 files from a directory
mpdl add ~/Music/Artist/Album
# Delete all songs from an artist
mpdl del "Artist Name"
# Set volume to 75%
mpdl volume 75
# Enable shuffle mode
mpdl random on# Start monitoring with default settings
mpdl monitor
# Start monitoring with custom config
mpdl --config ~/.config/mpdl/config.toml monitor
# Monitor with debug output
mpdl --debug monitor# Connect to remote MPD server
mpdl --mpd-host 192.168.1.100 --mpd-port 6600 status
# Or set environment variables
export MPD_HOST="192.168.1.100"
export MPD_PORT="6600"
mpdl play# View MPD music directory
mpdl get-config music_directory
# Enable audio normalization
mpdl set-config volume_normalization yes
# Set audio output
mpdl set-config audio_output_format "44100:16:2"mpdl supports desktop notifications via GNTP (Growl Notification Transport Protocol). To use this feature:
-
Install a GNTP-compatible notification system:
- Windows: Growl for Windows
- macOS: Growl
- Linux: go-gntp or similar
-
Enable GNTP in your config file:
[gntp]
host = "localhost"
port = 23053
enabled = true
icon_mode = "binary" # Recommended for Windows- Start monitor mode:
mpdl monitorNotifications will show:
- Album artwork (if available)
- Song title, artist, and album
- Playback time and bitrate
- Player state changes
- Default music root:
C:\Musics - Default MPD config:
%APPDATA%\mpd\mpd.conf - Use binary icon mode for GNTP notifications
- Default music root:
~/Music - Default MPD config:
~/.config/mpd/mpd.conf - May require
libmpdpackage
- Default music root:
~/Music - Default MPD config:
~/.config/mpd/mpd.conf - Growl notifications supported
# Enable debug mode
mpdl --debug status
# Check MPD is running
systemctl status mpd # Linux
# or
net start mpd # Windows
# Test connection manually
telnet localhost 6600The get-config and set-config commands only work with local MPD installations where you have read/write access to the MPD configuration file.
- Verify GNTP server is running
- Check firewall settings
- Try different icon modes:
mpdl --config config.toml monitor # Edit config.toml and change icon_mode
git clone https://github.com/cumulus13/mpdl.git
cd mpdl
go mod download
go build -o mpdlgo test ./...# Linux
GOOS=linux GOARCH=amd64 go build -o mpdl-linux-amd64
# Windows
GOOS=windows GOARCH=amd64 go build -o mpdl-windows-amd64.exe
# macOS
GOOS=darwin GOARCH=amd64 go build -o mpdl-darwin-amd64
GOOS=darwin GOARCH=arm64 go build -o mpdl-darwin-arm64- gompd - MPD client library
- go-gntp - GNTP notification library
- toml - TOML parser
- term - Terminal utilities
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- MPD developers for the excellent music player daemon
- gompd library maintainers
- All contributors to this project
See CHANGELOG.md for release history.