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

  • 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 and remotely access the Raspberry.

  • You have some familiarity with the command line.

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…).
August 2015: this page is almost 2 years old, and there are now much simpler ways to set up an MPD/upmpdcli-based Raspberry Pi music player: download one of the dedicated distributions (Moode Audio, Volumio, Rune Audio, Archphile, Pi MusicBox and others), copy it to an SD card, boot up the Pi and be up and running. 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, I think that you will 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. In any case, I have made a few notes about setting up WIFI, one of which can save you some time (don’t plug the dongle in the Pi, use an extension cable).

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.

This is still true for the RPI2 even with claims of improved audio. I have bad ears, and I can easily make the difference between the native audio and a cheap USB DAC.

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)


Preparing the SD card

Download the Raspbian “Jessie Lite” Raspbian Linux image from the Raspberry Pi download page.

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

unzip 2016-09-23-raspbian-jessie-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.

dd will destroy all data on the target disk

sudo dd if=2016-09-23-raspbian-jessie-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 this:

As of the November 2016 release, Raspbian has the SSH server disabled by default. You will have to enable it manually. For headless setup, SSH can be enabled by placing a file named ssh, without any extension, onto the boot partition of the SD card.

So, if the partitions were mounted, just create the ssh file. Check where /dev/sdZ1 was mounted (probably /media/yourlogin/boot, but check and replace below), then:

sudo touch /media/yourlogin/boot/ssh

If the partitions were not mounted, you need to mount the first one, then create the file:

sudo mount /dev/sdZ1 /mnt
sudo touch /mnt/ssh
sudo umount /mnt

Then 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.

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 for jessie 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.

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.

ssh into the Raspberry Pi (the default login and password are listed on the image download page listed above, last time I looked it was pi/raspberry). Example:

ssh -l pi

Initial Raspberry Pi configuration

When logged-in, execute:

sudo raspi-config


  • Resize the filesystem to use the whole SD card (Expand Filesystem entry).

  • With older 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.


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:1a:2b:3c:4d).

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


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 Wheezy, you should install the MPD package from the following alternate place: the standard one is ancient. The newer version is less buggy and supports the direct SMB access method.

Raspbian Jessie has a package for MPD 0.19.1, which is reasonably recent but does have some issues. There is also an official Debian jessie-backports repository which has MPD 0.19.12 (as of 2016-10). Or use the one from the following alternate site.

I maintain an alternate repository for a reasonably up to date MPD version with additional tweaks (mostly: suppressing a buggy library). You’ll have to trust that I did not introduce a Trojan in the MPD source. If you don’t, you could also rebuild from the debian source package, also available there, which would be reasonably safe as you would check the MPD source tarfile against the official depot.

Also these packages were built on Raspbian: beware if you are running Debian, I have heard of incompatibilities: some library versions differ, which can cause dependancies issues. If you hit this, you can still use the source package.

If the leap of faith is not too much for you, here how the simple approach goes:

cd /etc/apt/sources.list.d
sudo nano mpd.list

Insert the following lines:

deb http://www.lesbonscomptes.com/upmpdcli/downloads/mpd-debian/ jessie main
deb-src http://www.lesbonscomptes.com/upmpdcli/downloads/mpd-debian/ jessie main

(Use wheezy instead of jessie if appropriate).

Then save and exit.

Install MPD:

sudo apt-get update
sudo apt-get install mpd

This should list the MPD version as 0.19.x and will probably display a few ipv6-related and other errors when starting up, ignore them.

Configure MPD by editing mpd.conf

sudo nano /etc/mpd.conf

If you chose to have MPD access the files directly (which would be my default choice now), 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"

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

(Wheezy: use: sudo service mpd restart).

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, and you should be good to go ! 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.

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 and here.


comments powered by Disqus