I’d love to improve this document: if you have trouble with something in the following, or any idea to improve it, please drop me an email: jf at dockes.org, or use the new comments system.

This recipy sets up a Raspberry Pi as a music player, connected to your stereo and pulling music files from your home network.

It uses MPD, the Music Player Daemon, which can be remotely controlled by almost any device with network access (IOS, Android, PC, WEB interface). You can also use an UPnP control point. If you’re a bit lost among the different possibilities, I have written an overview of what I’ve learned about the home music network.

No screen, keyboard or mouse is needed at any point for the Raspberry Pi. This will save scrambling for cables and adapters, and eliminate additional sources of trouble.

Everything is done inside a command window, either on your main machine, or, through ssh on the Raspberry Pi.

The following describes precisely the steps I took from receiving the Pi to playing music, in the simplest possible way, without exploring too many alternatives. The more complete (and complicated) pages from which I got the information are referenced and can provide other approaches.

As this text is simple-minded it will only be useful to you if you work in the same context:

  • The music stored on the home network (either on an appliance or on a Linux or BSD server), or directly on a disk connected to the Rasberry PI.

  • If the music is remote, you will be using either NFS or SMB/Windows network file sharing.

  • You will be using a Linux (or BSD) computer to prepare the SD card.

  • You have some familiarity with the command line.

Note
 I make the assumption everywhere that your environment is relatively simple. If it is much more sophisticated than what I assume, you should be able to extrapolate the appropriate extensions (if you need this text at all…​).
Note
 Dec 2023: this page is very old, and there are now simpler ways to set up an MPD/upmpdcli-based Raspberry Pi music player: download and install one of the dedicated distributions (Moode Audio, Volumio, hifiberry OS, maybe others). I have not re-tested these recently, and one of my old favorites (Archphile) has been discontinued unfortunately. My quick impressions anyway: Volumio has become quite commercial and is based on a very stale OS version (Debian Buster at the moment). Moode has always been nice and would be my first choice for a graphical interface. Hifiberry OS is closer to a bare system, but comes with preinstalled mpd and upmpdcli (and more). You will have to tweak the audio configuration if your audio hardware is not from Hifiberry.
The procedure which follows still works though, and, because it is based on age-old command line steps and standard knowledge, it will hopefully continue to. If you are not an old Linux/Unix hand, you may learn a few things while following it, especially if you have the curiosity to research a bit around the more unfamiliar steps (and I’ll be glad to answer questions as well as I can).

What you need:

  • A Raspberry Pi

  • Its power supply

  • Its SD card (4 GB min)

  • An Ethernet connection close to the stereo.

This also works over WIFI, but, if you need to set up WIFI, you may be better off using a screen, keyboard and mouse, at least temporarily until the network link works. This page is more or less dedicated to a headless config, else some things could be done in a simpler way. Nevertheless, especially on the newer Pis with integrated WIFI, it is quite possible to configure WIFI for a headless Pi and I have made a few notes about setting up WIFI

Audio hardware

As the Raspberry native audio does not have a great reputation sounds like crap, you will probably want to use external audio hardware. If this is not chosen yet, my notes on the subject.

Reference pages

Raspberry Pi quick start guide: http://www.raspberrypi.org/quick-start-guide

Raspberry Pi images download page: http://www.raspberrypi.org/downloads

Raspberry Pi headless installation: http://www.penguintutor.com/linux/raspberrypi-headless

Raspbian FAQ: http://www.raspbian.org/RaspbianFAQ (esp. for information about remote volume mounts)

Procedure

Preparing the SD card

Download the Raspbian Linux (now named 'Raspberry Pi OS') image from the Raspberry Pi download page.

The OS Lite image is fine, except if you need a desktop for other purposes.

Unzip the image (update the name for what you downloaded):

unzip 2021-01-11-raspios-buster-armhf-lite.zip

Copy the unzipped image (name ends in '.img') to the SD card. You’ll need at least a 4 GB one. You may have to change the name of the image if the version changed since I wrote this, and use an appropriate drive name in place of the sdZ I chose as example.

You should probably take some care to be very sure that the value used is not your hard disk…​ Use the df command to display your mounted volumes.

Note
 Inserting the card on the PC, finding the right device name, unmounting the volumes.

dd will destroy all data on the target disk

sudo dd if=2021-01-11-raspios-buster-armhf-lite.img bs=1M of=/dev/sdZ

(replace Z with the carefully determined drive letter…​).

At this point, if you are running this on a desktop, the automounter may mount the two newly created partitions. You will need to unmount them (press the eject button) before ejecting the card. But before you do this, we want to enable ssh for the future system.

Creating a user and enabling sshd

As of april 2022 the good Raspbian developers have decided to make our life more difficult for ??reasons.

The OS images now come without the pre-configured "pi" user. You need to create a user on the disk image before starting up the PI.

Recipee, copied from the above page:

Check where /dev/sdZ1 was mounted (probably '/media/[yourlogin]/boot'). If the partitions were not mounted, you need to mount the first one yourself:

sudo mount /dev/sdZ1 /mnt

Then create a file called userconf or userconf.txt in the boot partition (now /media/[yourlogin]/boot or /mnt/). This file should contain a single line of text, consisting of:

username:encrypted-password

To generate the encrypted password, use OpenSSL on any Linux/BSD/MacOS machine. Open a terminal window and enter:

echo 'mypassword' | openssl passwd -6 -stdin

Replace mypassword with a suitable value, of course, then copy/paste the gibberish into the userconf file, which should look like the following:

yourusername:$6$...

If you have no appropriate machine around, you will need to use the Raspberry PI GUI imager, refer to the explanations on their page.

Also, Raspbian now has the SSH server disabled by default. You need to enable it manually, which is done by placing an empty file named 'ssh' (without any extension) onto the boot partition of the SD card. Mount it as above (or use the existing mount), then:

sudo touch /media/[yourlogin]/boot/ssh

Once the user is created and sshd enabled, unmount the partition, using the desktop or an unmount command.

Done with the card initialisation

Then, unmount the still mounted card partitions, physically eject the card, insert it in the unpowered Raspberry Pi.

Accessing the Raspberry Pi on the network

As you are going to connect by ssh to the Rasberry PI when it is up on the network, you need a way to find its IP address.

Note
 There is a slightly brutal way to solve this, which is to set a static IP address by editing the PI system files with the SD card mounted on the PC. Editing the interfaces file is described in the page about headless setup linked above, but the right method is now to set the static address in '/etc/dhcpcd.conf'. In any case, I don’t like this method too much because, later on, either you are stuck with using the numeric IP, or you will need to record the hostname-to-address correspondence somewhere else (either DNS or host file), so that it will be stored in two places (the PI and DNS/hosts). My preferred approach is to let the initial setup use DHCP, and have to find/guess the IP address for the PI.
Note
 Recent versions of the Raspberry Pi OS advertise themselves as raspberrypi.local on the mDNS local resolver. So, after starting the pi, you should be able to ssh to raspberrypi.local, and either just keep using the approach, or retrieve the IP address through 'ip addr'. You can also change the host name from raspberrypi to whatever you would fancy by editing '/etc/hostname' and rebooting. The method next described, based on retrieving DHCP information will still work though.

Have a look at the host table on your DHCP server (on your ISP-provided WIFI router for most home setups, the section might be called Attached Devices for example). If DHCP is provided by a Linux machine you might want to tail '/var/lib/dhcp/dhcpd.leases'. After we power up the Raspberry, it will appear as a new entry.

Insert the SD card in the Raspberry, connect the Ethernet cable, and power up.

Wait a minute and have another look at your DHCP table to find the Raspberry IP address: it is the new guy, and it is probably called raspberrypi - but not necessarily, on my buggy router, it is named UNKNOWN :-). Jessie update: I don’t see a raspberrypi name in the dhcpd leases during the Jessie boot. The device could be identified by a vendor-class-identifier of dhcpcd-6.7.1:Linux-4.4.21-v7+:armv7l:BCM2709. Curiously, it did come up with a client-hostname of "raspberrypi" a bit later.

Initial Login

Rasbian does not have a default user anymore (versions prior to april 2022 used to have a user named pi with password raspberry). See above for the method to choose and set your login/password combination.

Now ssh into the Raspberry Pi. Example:

ssh 192.168.1.105 -l myusername

Initial Raspberry Pi configuration

When logged-in, depending on the Raspbian version, you may need to execute:

sudo raspi-config

to:

  • Resize the filesystem to use the whole SD card (Expand Filesystem entry). As far as I can see, this is now done automatically by the first boot (Debian Buster and later), so not needed any more.

  • With old Pis, maybe change the memory split between processor and video (memory_split). The above page recommends 32 Mb for VideoCore, I only left 16 as I won’t be using video, and I plan other uses for this machine, so I don’t want to waste memory. You can also leave the default of 64MB, especially if this is a 512MB Pi. On recent images, this option found under the Advanced Options entry of the top raspi-config menu, and may be less useful.

Note

If raspi-config exits without doing anything, maybe your TERM variable is not set correctly. Try to set it, e.g. from the command line:

export TERM=vt100

Then retrieve the Raspberry Ethernet address. You can get it by typing ifconfig on the command line and noting the HWaddr field for eth0 (it is 6 hex bytes looking like: b8:27:eb:xx:xx:xx).

File sharing

The initial version of this document explained how to mount the server volume on the PI, so that MPD could see the server music files as it would local ones.

I have moved the instructions for doing this to the annexes, because there is now a much simpler method, which is to let MPD access the remote volume all by itself (new in MPD 0.19).

Also, this section explained how to set up DHCP and DNS so that the PI would have a fixed address and network name. The fixed address part at least is almost necessary for NFS. The DNS host name is convenient to avoid having to remember and type IP addresses.

However, if you finally decide to install an UPnP/DLNA front-end on the PI, all this is unnecessary, so I moved it to the annexes too.

MPD installation

Note

I have been told that alsa-utils was not always pre- or auto-installed, and is needed. (In my experience it’s always already there). In any case, requesting it again won’t hurt:

sudo apt-get install alsa-utils

If you are using Raspbian 10 Buster or newer (11 bullseye, 12 bookworm…​), just install mpd from the standard repositories.

For older releases (but why run these?), have a look at the annex section about MPD backports.

Install MPD:

sudo apt-get update
sudo apt-get install mpd

Configure MPD by editing 'mpd.conf'

sudo nano /etc/mpd.conf

In the following, you can skip the 'music_directory' setup if you are going to use an UPnP client (because the music catalog will be managed by the UPnP server).

If you chose to have MPD access the files directly, (simpler than mounting a volume), change the following lines. You will need to substitute the IP address or DNS name for your samba/NAS server, and the volume name and path to where your music is stored.

 music_directory	"smb://MyServerNameOrAddress/path/to/Music"
 bind_to_address         "any"
 audio_output {
     device          "hw:1,0"    # optional usb output. Keep 0,0 if using the Pi audio
 }
 mixer_type                      "software"
Note
Alsa device names

The aplay utility can be used to retrieve Alsa device names (the value after the "device" tag above).

aplay -l will list hardware devices by card and device number (the 1,0 above means card 1, device 0). Example (here the audio card is card 0 because I got rid of the rpi audio):

card 0: sndrpihifiberry [snd_rpi_hifiberry_dacplus], device 0: HiFiBerry ...

aplay -L will list more explicit descriptions names:

hw:CARD=sndrpihifiberry,DEV=0
  snd_rpi_hifiberry_dacplus, HiFiBerry DAC+ Pro HiFi pcm512x-hifi-0
  Direct hardware device without any conversions

You can use "hw:CARD=sndrpihifiberry,DEV=0" in place of "hw:1,0" above.

You will also see "plughw:" entries in the aplay -L output. These are interfaces which can perform audio format conversions. Use "hw:" except if you need to play formats which your DAC can’t process.

If you chose to mount the server volume instead, the music_directory line will look something like the following (NFS case):

 music_directory         "/net/servername/path/to/music"

If you have a doubt about your card number, use the aplay -l command to list the cards. The internal audio is bcm2835.

Restart mpd:

sudo systemctl restart mpd

Install any of the music play daemon clients (ipad/Android/phpmp whatever…​) on your remote, use it to tell mpd to update its tags database (Example: mpc update), and you should be good to go !

Note
 Don’t forget to tell mpd to update its database, else you will see no music !

I quite like MPDroid on my Nook tablet as a client …​ If you did not perform the DNS dance linked above, you will need to use the IP address to connect, and if you also skipped the fixed address part, it might change one day (unlikely in most circumstances in fact).

One approach to avoid these names and addresses issues is to use an UPnP front-end to MPD instead. The main purpose of UPnP is to free you from these trivial matters.

Using an UPnP controller with MPD

If your music network is primarily based on UPnP, you may prefer to use an UPnP control point application, such as BubbleUPnP or Audionet, instead of an MPD client to control the player.

upmpdcli is an UPnP Media Renderer front-end to MPD, and will allow such a configuration.

Installing upmpdcli on the Raspberry Pi.

Setting up MPD to let the storage server manage the database

If you did not chose the UPnP approach above, one of the (small) problems with MPD on a Raspberry Pi, especially if the files are stored somewhere else, is that updating the songs database is slow. Also, if you have multiple devices on the network (the one in the kitchen, for the bedroom, etc.), it’s a source of waste and inconsistency to have them all compute the tag database.

Happily enough, you just installed MPD 0.19, and this has two possible workarounds for these problems, the new database plugins:

  • The Proxy database plugin lets you use the tags database from another MPD instance (for example one running on the server).

  • The UPnP database plugin lets you access the directory from an UPnP Media Server (for example the one running on your NAS), while still using an MPD client for control. I wrote the initial version for this, but it has been modified and integrated in MPD 0.19.

More details here.

Comments

comments powered by Disqus