Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

python-flask-socketio-server is a Flask webapp which uses MQTT and to serve shairport-sync-provided metadata. It has remote-control support and works great with Apple Music®1

If you use shairport-sync, you should be able to get this webapp working.

Safari screencap


First, some requirements for your home network.

  1. AirPlay®
    • iTunes® on a computer. Music* app in iOS™. Rogue Amoeba's Airfoil app too (which works with Spotify, e.g.)
  2. shairport-sync as AirPlay® receiver
  3. MQTT broker
  4. Webserver
    • Any computer that can run this Python 3-based webserver app (tested on macOS™ and Raspbian)

2., 3., and 4. can all be on the same computer, for example, a Raspberry Pi®

Oh, and of course, any number of browser "clients", to display the served webpage.

let's go

For our purposes, we are assuming a Raspberry Pi running Raspbian stretch. And the rest of this "quickstart" depends on the above requirements 1.) 2.) and 3.) being met, with 2.) and 3.) being on the same Raspberry Pi where we are installing the webserver app (4.).

See wiki for additional pointers.

# Install a python3 dev setup and other libraries
sudo apt install -y python3-pip python3-venv \
python3-setuptools python3-wheel git mosquitto-clients

# Validate MQTT broker config. E.g., from two different bash sessions:
# .. mosquitto_sub ...
# .. mosquitto_pub ...

# grab a copy of this repo
git clone
cd shairport-sync-mqtt-display
# now proceed to the next section: "install"


Steps to run on computer for webserver (in a git clone of this repo). We rely on python3's built-in venv module for dependencies.

cd python-flask-socketio-server
python3 -m venv env
source env/bin/activate
pip install flask
pip install flask-socketio
pip install paho-mqtt
pip install wheel # not required; avoids a pyyaml benign build error
pip install pyyaml


Copy the example config file and customize.

cp config.example.yaml config.secrets.yaml
$EDITOR config.secrets.yaml # $EDITOR would be nano, vi, etc.
  1. Configure the MQTT section (mqtt:) to reflect your environment.

    • For the topic, I use something like shairport-sync/SSHOSTNAME
      • this topic needs to match the mqtt.topic string in your /etc/shairport-sync.conf file
      • SSHOSTNAME is the name of where shairport-sync is running
      • Note, there is no leading slash ('/') in the topic string
    • Use the same mqtt broker for host that you did in your MQTT broker config testing and shairport-sync.conf
  2. Customize the webpage UI section (webui:) if desired.


Assumed music playing using AirPlay® (e.g. iTunes®), an MQTT broker, and shairport-sync with MQTT support are already online. Also assumes that config.yaml has been configured to match your home network environment.

# this is the python virtual environment we installed into
source env/bin/activate
# open it in your web browser, e.g.: open

Use IP address (in place of to connect from other devices on your network

Automatically start on boot

There's a systemd service file at python-flask-socketio-server/etc/shairport-sync_web.service in this git repository.

It includes instructions in its header that can be used to install the python webserver as a system service., so it will run automatically at boot-up.


Plan to gather here any troubleshooting guidance that comes up.

troubleshooting running

If you get an error like

socket.gaierror: [Errno -2] Name or service not known

you should add the mqtt broker host that you are using to /etc/hosts, for example something like. rpi

connecting across home network

To connect from across your home network, you will need to use the LAN IP address of your webserver computer. Placed in an URL, it might be something like

The commands ifconfig or ip addr show can reveal host IP addresses.

future ideas

Moved to issues and managed there.

inspired by


Original development setup:

  • iTunes® streaming to Raspberry Pi(s)
  • Raspberry Pi Model 3 B
    • configured to connect to MQTT broker
    • developed in python3.7 installed from Homebrew on macOS Mojave
    • also tested on a Raspberry Pi running Raspbian stretch/python3.5
  • Client app in Safari browser on macOS™, Mobile Safari on iOS™ 9 and iOS™ 12. Chrome.

1: Trademarks are the respective property of their owners.

You can’t perform that action at this time.