Deploying MPD (Music Player Daemon)

Introduction

MPD (Music Player Daemon) is a flexible, powerful server-side music player that has been the foundation of audio streaming solutions for over two decades. Running as a background service, MPD manages your music database, playlists, and audio playback while accepting commands from various client applications.

Unlike monolithic music players, MPD separates the music playing logic from the user interface, allowing you to control your music from any device using your preferred client application. This architecture makes it ideal for server deployments where you want centralized music management with distributed control.

Key highlights of MPD:

• Server-Side Architecture: Runs as a daemon, freeing your client devices from audio processing
• HTTP Streaming: Stream audio to any device with a web browser or compatible player
• Format Support: Plays FLAC, MP3, AAC, OGG, WAV, and virtually every audio format
• Gapless Playback: Seamless transitions between tracks for uninterrupted listening
• ReplayGain: Automatic volume normalization across your library
• Database Management: Maintains an indexed database of your music for fast searching
• Playlist Support: Create and manage multiple playlists with various formats
• Multiple Outputs: Stream to multiple destinations simultaneously
• Low Resource Usage: Efficient design suitable for minimal hardware
• Client Ecosystem: Dozens of clients available for every platform
• Crossfade Support: Smooth audio transitions between tracks
• Sticker Database: Store custom metadata and ratings per track

This guide walks through deploying MPD on Klutch.sh using Docker, configuring HTTP streaming for remote access, and setting up client connections.

Why Deploy MPD on Klutch.sh

Deploying MPD on Klutch.sh provides several advantages for music streaming:

Always-On Music Server: Your music daemon remains running 24/7, accessible from any client worldwide.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds MPD without complex configuration.

Persistent Storage: Attach persistent volumes for your music library, database, and playlists.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure client connections and web streaming.

GitHub Integration: Connect your configuration repository for automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your library size and streaming needs.

Custom Domains: Assign a custom domain for easy client configuration.

Prerequisites

Before deploying MPD on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• Your music library files ready to upload
• (Optional) A custom domain for your MPD instance

Understanding MPD Architecture

MPD operates with a client-server model:

MPD Daemon: The core server process that manages the music database, handles playback, and responds to client commands.

Music Database: An indexed catalog of your music library for fast searches and browsing.

Audio Outputs: Configurable destinations for audio, including HTTP streams, files, and null outputs.

Protocol Interface: A simple text-based protocol on port 6600 for client communication.

HTTP Stream Output: Built-in streaming server for browser and player access.

Preparing Your Repository

Create a GitHub repository with your MPD configuration.

Repository Structure

mpd-deploy/
├── Dockerfile
├── mpd.conf
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in your repository root:

FROM debian:bookworm-slim

# Install MPD and required codecs
RUN apt-get update && apt-get install -y \
    mpd \
    mpc \
    libflac-dev \
    libvorbis-dev \
    libopus-dev \
    libmp3lame-dev \
    libsndfile1 \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Create required directories
RUN mkdir -p /var/lib/mpd/music \
    /var/lib/mpd/playlists \
    /var/log/mpd \
    /var/run/mpd

# Set permissions
RUN chown -R mpd:audio /var/lib/mpd /var/log/mpd /var/run/mpd

# Copy configuration
COPY mpd.conf /etc/mpd.conf

# Expose ports
# 6600: MPD protocol
# 8000: HTTP streaming
EXPOSE 6600 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD mpc status || exit 1

# Run MPD in foreground
USER mpd
CMD ["mpd", "--no-daemon", "/etc/mpd.conf"]

Creating the MPD Configuration

Create mpd.conf with HTTP streaming enabled:

# MPD Configuration for Klutch.sh

# Directories
music_directory         "/var/lib/mpd/music"
playlist_directory      "/var/lib/mpd/playlists"
db_file                 "/var/lib/mpd/database"
log_file                "/var/log/mpd/mpd.log"
pid_file                "/var/run/mpd/pid"
state_file              "/var/lib/mpd/state"
sticker_file            "/var/lib/mpd/sticker.sql"

# Network binding
bind_to_address         "0.0.0.0"
port                    "6600"

# Connection settings
max_connections         "20"
connection_timeout      "60"

# Playback settings
auto_update             "yes"
auto_update_depth       "3"
follow_outside_symlinks "yes"
follow_inside_symlinks  "yes"

# Audio quality settings
replaygain              "auto"
replaygain_preamp       "0"
volume_normalization    "no"

# HTTP Streaming Output
audio_output {
    type        "httpd"
    name        "HTTP Stream"
    encoder     "vorbis"
    port        "8000"
    bind_to_address "0.0.0.0"
    quality     "8"
    format      "44100:16:2"
    always_on   "yes"
    tags        "yes"
}

# Null output for when no streaming client is connected
audio_output {
    type        "null"
    name        "Null Output"
    mixer_type  "none"
}

# Character set
filesystem_charset      "UTF-8"

# Logging
log_level               "default"

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Deploying MPD on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile and MPD configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project called “mpd” or similar.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8000 for HTTP streaming

Note: The MPD protocol port (6600) can be exposed for direct client connections if needed.

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/lib/mpd/music	50+ GB	Your music library
/var/lib/mpd/playlists	1 GB	Saved playlists
/var/lib/mpd	2 GB	Database and state files
/var/log/mpd	1 GB	Log files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build and start your MPD instance.

Upload Your Music

Transfer your music files to the /var/lib/mpd/music volume.

Update the Database

Trigger a database update to index your music:

mpc update

Access the HTTP Stream

Listen to your music at https://your-app-name.klutch.sh:8000/mpd.ogg using any compatible player.

Connecting Clients

Web-Based Players

Access the HTTP stream directly in a web browser or with web-based MPD clients:

• Stream URL: https://your-app-name.klutch.sh/mpd.ogg

Desktop Clients

Popular MPD clients for desktop:

• ncmpcpp: Terminal-based client with visualizations
• Cantata: Feature-rich Qt-based client
• GMPC: GTK-based client with extensive features
• Sonata: Lightweight GTK client

Configure clients with:

• Host: your-app-name.klutch.sh
• Port: 6600 (if exposed)

Mobile Clients

MPD clients for mobile devices:

• MPDroid (Android)
• M.A.L.P. (Android)
• MPDluxe (iOS)

Command Line Control

Use mpc for command-line control:

# Play/pause
mpc toggle

# Next track
mpc next

# View current playlist
mpc playlist

# Search library
mpc search artist "Artist Name"

# Add to playlist
mpc add "path/to/file.flac"

# Update database
mpc update

Advanced Configuration

Multiple Audio Outputs

Configure additional outputs for different streaming formats:

audio_output {
    type        "httpd"
    name        "MP3 Stream"
    encoder     "lame"
    port        "8001"
    bitrate     "320"
    format      "44100:16:2"
}

audio_output {
    type        "httpd"
    name        "FLAC Stream"
    encoder     "flac"
    port        "8002"
    format      "44100:16:2"
    compression "8"
}

Password Protection

Add authentication to MPD:

password "your_password@read,add,control,admin"
default_permissions "read"

ReplayGain Configuration

Enable volume normalization:

replaygain              "auto"
replaygain_preamp       "0"
replaygain_missing_preamp "0"
replaygain_limit        "yes"

Organizing Your Music Library

Recommended Structure

/var/lib/mpd/music/
├── Artist Name/
│   ├── Album Name (Year)/
│   │   ├── 01 - Track Title.flac
│   │   ├── 02 - Track Title.flac
│   │   └── cover.jpg
│   └── Another Album/
├── Compilations/
│   └── Various Artists - Collection/
└── Podcasts/
    └── Show Name/

Supported Formats

MPD supports virtually all audio formats:

• Lossless: FLAC, ALAC, WAV, AIFF, APE, WavPack
• Lossy: MP3, AAC, OGG Vorbis, Opus
• Other: MIDI, MOD, S3M, IT, XM

Troubleshooting

No Sound/Stream

• Verify audio output configuration in mpd.conf
• Check that the HTTP streaming port is accessible
• Ensure music files exist and are readable
• Review MPD logs for errors

Database Not Updating

• Check file permissions on the music directory
• Verify MPD has write access to the database file
• Run mpc update --wait to see progress

Client Cannot Connect

• Verify the correct port is exposed
• Check firewall rules
• Ensure password configuration matches client settings

High CPU Usage

• Consider reducing stream quality/bitrate
• Limit maximum connections
• Check for corrupt audio files causing decoder issues

Additional Resources

• MPD Official Website
• MPD Documentation
• MPD GitHub Repository
• MPD Community Wiki
• MPD Client List
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying MPD on Klutch.sh gives you a powerful, centralized music server with HTTP streaming capabilities. The client-server architecture means you can control your music from any device while keeping your library and playback engine in the cloud.

With support for high-quality audio formats, gapless playback, and a vast ecosystem of client applications, MPD on Klutch.sh provides the foundation for a flexible, always-available music streaming solution that you control.