Tutorial: Raspberry Pi Streaming & Rendering Audio Media Center

In the following I am going to show a quick and well tested way of transforming a Raspberry Pi to a sound streaming media device capable of playing music from local disks, network shares and streaming services, like Spotify. The official documentation of the hand picked software components used is mostly outdated/not working (for me anyway), so I gathered all the steps necessary here in one page so that in the future I don’t have to figure it out again and in the hope it will be useful to some other enthusiasts creating their own multimedia solutions at home.

It is possible to simply download and flash a pre-packaged operating system already customized for the Pi, but these package deals come with their own set of problems, and that’s why I decided to build a custom system. It is a bit more work, but it will do exactly what I want/need and won’t have anything else slowing down the tiny Pi. Also, it was a great learning experience.

One of several available web interfaces for controlling mopidy

Hardware requirements

The only and most difficult part to source for this project is a Raspberry Pi micro computer (complete with power supply, speakers, cables). Probably any model will do. In my experiments I have successfully set up an actual media player/streamer on a Raspberry Pi Model B Rev 2 and a Raspberry Pi 3 Model B Rev 1.2. These are the only models I have tried to setup, but I’m fairly confident that most other models will work too. The only difference I noticed between my two setups is that the Raspberry Pi Model B took more time to show a web page and it took more time to start playback/streaming. The difference is not big (a few seconds), and once the playback/streaming starts they both played steadily for days at a time (testing).

There is no need for keyboard, mouse or monitor – we are using the Raspberry Pi in “headless” mode.


This tutorial starts with a fresh install of Raspbian operation system. (Doing this is outside of the scope of this tutorial, but there are many excellent tutorials on it elsewhere. Hint: using the Raspberry Pi Imager is probably the easiest way.) In this tutorial I am using the latest version available at the time of writing, which is Debian version: 11 (bullseye). I use Raspberry Pi OS Lite version, which can be downloaded here, but any OS should be OK.

To operate (pretty much any kind of) a server requires that computer to have a fixed IP address. This is also outside of the scope of this article. Hint: I usually set up my DHCP server to assign static IP addresses to my servers, this way I don’t have to set anything on the individual devices.

As we are using the Pi in “headless” mode, we will need ssh access to it. This can be enabled, for example, using the Raspberry Pi Imager mentioned earlier.

Finally, we need a computer to work on. This can be any computer as long as it has a terminal program that can ssh into the Pi. I am using a Windows 11 PC, and my terminal program is Windows Terminal which can be installed from Microsoft Store or from GitHub. Once the installation and the initial configuration id done there is no need for the computer – media can be managed even from a mobile phone.

Once you have all of the above ready, powered up and connected, we can start the installation and configuration of all the software packages that turn the humble Pi into a media center.


We are going to use upmpdcli as the audio media renderer because it is open source and it works very well on the Pi. To be able to install it, we need to add its repository key to apt:

As the music server, we will use mopidy. Similarly, we need to import its key too:

It is now time to update package information and bring the Pi up to date:

This may take a while, depending on how many new updates there are for your Pi since the installation image was created.

Once it finished we can install all the necessary software packages with a single command:

Here is the breakdown of the packages:
[optional] cifs-utils samba samba-common-bin: Allows the Pi to access my music collection on a Windows share.
[optional] curl, lm-sensors, gawk: I use them in some scripts I constantly run on my Pis to report its health to my home automation system.
[required] upmpdcli: The audio renderer.
[required] mopidy: The music server.
[required] python3-venv, python3-pip, build-essential, python-dev, python3-dev, libffi-dev, libspotify-dev: These packages allow mopidy and upmpdcli to be installed.

This step takes a while to complete. When all the software packages are installed, we can configure a share on the Pi and mount the Windows share with all my music:

Add the following to the end of /etc/samba/smb.conf:

Then create a password for user pi so that you can access the share from Windows:

Now let’s create a directory where we will mount the Windows share:

Edit the file /etc/fstab:

Add the following to the end of /etc/fstab:

In the above line is the IP address of my Windows PC, you should change it to whatever address your PC has. (Hint: On a Windows PC you can issue ipconfig in a Command Prompt to find out the IP address of the local computer. In the output of this command, look for a line that says IPv4 Address.)

We also need to create a credentials file as referenced above, so edit/create the file /etc/win-credentials:

Paste the following into the /etc/win-credentials:

Make sure to use a username and a password that corresponds to a user account on the Windows PC.

At this stage it may be a good idea to reboot the Pi:

You can also check if the Pi has access to the Windows share:

This should result in a full list of files and folders on that Windows share.

You should also check if sound is configured properly on the Pi:

If all works out, we can now move on to installing a number of extensions for mopidy to make it useful. In this tutorial I will only install a couple of extensions to show how it is done, the rest can be installed the same way. Installing an extension takes a number of steps:

  1. Picking the right extension for your need. Do not install extensions you need – they will slow down the Pi.
  2. Installing the extension. Most of the time the installation is straightforward, just follow its documentation (usually on GitHub).
  3. Configuring the extension. This is usually done in mopidy‘s own /etc/mopidy/mopidy.conf file.
  4. Restarting mopidy.

I am now going to show the installation and configuration of only two extensions: the MusicBox web client and the Spotify extensions.
Let’s start with installing the web client:

The Spotify extension needs a bit of extra work:

Now that we have everything installed, we have to configure both mopidy and upmpdcli. Let’s start with mopidy!
Edit the file /etc/upmpdcli.conf:

For a basic configuration to work, uncomment and edit the following lines (according to your own preferences):

All other lines can be left commented out (for this tutorial).
The last file to edit is mopidy‘s config file, /etc/mopidy/mopidy.conf:

Add the following to the end of the file (which should be empty with a few lines of comments only):

The different sections in the above config file refer to the various extensions installed for mopidy. You will recognize [http], [spotify] and [mpd] which we installed a few steps back. The one called [file] refers to an extension that came bundled with mopidy. You will need to change some of the fields to match your own settings, paths, names, passwords, etc. They are all self explanatory except for client_id and client_secret. To find these, have your Spotify user name and password ready and click here to retrieve the missing items.

Roughly halfway down the page there is a big green button. Click it to authenticate you. After a few seconds, you will get your client_id and client_secret:

Copy and paste those values into your config file.

We are now finished with the configuration of mopidy, its extensions and upmpdcli. The only thing left to do is start both services and make sure they will start automatically the next time you re/start your Pi:

Reboot the Pi:

Finished! Your old Raspberry Pi is now configured for use by the whole family! 🙂

  1. You can stream music from Spotify.
  2. You can stream music from a local drive or Windows share.
  3. You can cast music from any device on your network to it.
Clicking Cast to Device in Windows Media Player allows you to select where I want to hear the music.

Hints, best practices

1. You have seen above that to configure mopidy you need to edit the file /etc/upmpdcli.conf. However, the content of the file is not always an exact match of the actual configuration. Each parameter has a default value and in /etc/upmpdcli.conf you only need to list those that (should) have a different value. Furthermore, when some parameters are set incorrectly, mopidy can decide to disable the extension altogether. The best way to find out what the current settings are is to use this command:

This will display the current and actual configuration with any sensitive details (like passwords) redacted, so that you can post it in online forums should you need help. This is also useful when the documentation is not clear – you can simply copy and paste full sections from the output of this command to /etc/mopidy/mopidy.conf and customize it to your needs.

2. Every time you change your configuration (by editing /etc/mopidy/mopidy.conf) you also need to restart the mopidy service using this command:

3. You can check the status of the mopidy service like this:

4. In case something is not working you can have a look at the log:

5. Finally, here is a video walking you through the full installation process, containing all the commands and expected responses:


Where to go from here

The configuration shown in this tutorial is barely the first steps in creating a multi room multi media experience using the inexpensive Raspberry Pi. There are many ways you can customize your setup, many extensions to add and probably many more to come. All this with the power of free and open source programs!
If you have a cool setup or just an idea for one, please leave a comment for others to learn!


Your thoughts?

This site uses Akismet to reduce spam. Learn how your comment data is processed.