MPD

MPD (Music Player Daemon) is the local music player on your odio node. It handles audio CD, USB flash drive playback, and can also serve a full music library from a NAS.

No library management by default

odio is designed as a streamer, not a library manager. A large music database on a Pi (especially older models like the B+) causes long scan times, high CPU usage, and corrupted database files — particularly over NFS.

By default, MPD only maintains a lightweight local database for CD and USB playback via go-mpd-discplayer.

If you want library browsing, two options are available: an NFS mount, or MPD running on the NAS.

Playback controls

MPD exposes itself as an MPRIS player via mpDris2. This is what allows the odio API to discover and control MPD playback alongside all other sources. Playback is controllable from the embedded UI, the odio application, Home Assistant, or any MPD client.

The mpDris2 fork shipped by odio walks an ordered cover-art pipeline: the embedded picture inside the audio file (MPD’s readpicture), a regex-matched image in the song’s directory, MPD’s albumart resolver, a CUE/cdda fallback that looks next to the loaded .cue playlist when the current song is a virtual reference like cdda://Disc/Track01 or sheet.cue/trackNNNN, and an XDG cover cache at $XDG_CACHE_HOME/mpDris2/ for downloaded covers.

The CUE fallback is what makes cover art work for audio CD playback: MPD’s CUE plugin is configured with as_directory "true", which exposes the CUE sheet as a virtual directory, and the cover.jpg cached by go-disc-cuer sits next to it where the fallback finds it.

odio embedded UI playing an audio CD via MPD: Retroaction - A Noisy Blast - Son of Light, with album cover art and full transport controls — CD playback in the embedded UI, cover art via mpDris2

odio embedded UI playing a USB flash drive via MPD: Dooz Kawa - Sans pluie pas d'arc-en-ciel from Vol de Nuit, with album cover art and transport controls — USB stick playback, cover art served by odio-api v0.11.0+

odio embedded UI showing MPD playing Dub Incorporation - Dario's Dub from La Grosse Radio Reggae, with transport controls and the Built-in Audio Stereo output active — Webradio playback via the upmpdcli built-in sources

myMPD web UI

myMPD ships as a sub-feature of the mpd role since 2026.4.2b2, running as a user systemd service themed in the odio palette and pointed at the local MPD. It tags along whenever MPD is installed (opt out with INSTALL_MYMPD=N), and the package itself comes from odio-mympd, the build-only pipeline that tracks upstream and publishes .deb to apt.odio.love.

Open it from any browser on the network:

http://<ip>:8080

Or via Zeroconf (mDNS):

http://<hostname>.local:8080

Since 2026.5.0b1, the odio API also publishes the myMPD URL alongside mpd.service, so the embedded UI and odio application link to it directly from their services list.

It covers the MPD-side use cases the embedded UI doesn’t: queue editing, library browsing, tag-aware search.

myMPD playback queue showing a USB-loaded album, current track highlighted, transport controls in the footer

USB drives — browse and queue from any stick go-mpd-discplayer has indexed. The stick’s content stays browsable as long as it’s plugged in.
CD library — every CD that’s been inserted before shows up as a virtual directory (CUE sheets cached in MPD’s music directory by go-disc-cuer, exposed via MPD’s CUE plugin with as_directory "true"). Browsing works offline, but playback still needs the matching physical disc in the drive — the audio comes from the cdda:// URI, not from the cached metadata.
Your own library — for anyone wanting to manage their own collection through odio (NAS mount, files on the node, etc.), it’s a real MPD client with playlists, queue, and tag editing.

Web radios get their own dedicated treatment. See Webradios → Via myMPD on the odio node.

Using a NAS library

The two options from above each carry a tradeoff.

odio’s MPD watches /media/USB, so mount your NAS export as a subfolder there. Install the NFS client and mount it:

sudo apt install nfs-common
sudo mount -t nfs 192.168.1.21:/export/Music /media/USB/Music

To survive reboots, add an /etc/fstab entry (_netdev waits for the network):

192.168.1.21:/export/Music  /media/USB/Music  nfs  defaults,_netdev  0  0

Then trigger a database update:

mpc update

The files are browsable from any MPD client. Simple, but the scan runs on the Pi and gets slow over NFS for large collections, the exact problem odio sidesteps by default.

Run MPD on the NAS

For a large library, run MPD on the NAS itself. The full NAS-side setup lives in the NAS use case.

MPD clients

For library browsing and queue management, you can also use any external MPD client:

mpc — CLI client, shipped with odios, handy for scripting and SSH sessions
M.A.L.P. — Android MPD client with cover art support

MPD