REQUIREMENTS.md

Requirements

These are helpers for exposing Apple¹ AirPlay® metadata. All the helper utilities rely on shairport-sync built/configured with MQTT and metadata support.

Hardware and Network Requirements

Before we begin, first, some requirements for your home network. Requirements 2., 3., and 4. can all be hosted on the same computer, including a single Raspberry Pi®

1. AirPlay® source²

2. shairport-sync as AirPlay® receiver

   • shairport-sync needs to be built with MQTT support.
   • shairport-sync needs to be built with metadata support.
   • It also needs to properly configured to connect to MQTT broker.
   • See wiki - Build shairport-sync with MQTT support on Raspberry Pi

3. MQTT broker

   • An MQTT broker, such as mosquitto, available on same network.
   • See wiki - Configure MQTT broker

4. Renderer

   • Webserver for python-flask-socketio-server

     • Any computer that can run this Python 3-based Flask app (tested on macOS™ and Raspberry Pi OS)

   • Character LCD Display for circuitpython_char_lcd

     • A Raspberry Pi for running the CircuitPython script with a Character LCD display attached. A keypad for performing as a remote control is optional, but a nice feature.

   • HUB75 RGB LED Matrix Panel(s) for python-flaschen-taschen -- and something to drive them

     • A Raspberry Pi 3 B with a Adafruit RGB Matrix HAT + RTC was used to develop, attached to a powered 32x32 RGB LED Matrix Panel - 6mm pitch from Adafruit.

MQTT and shairport-sync config

For our purposes, these instructions assume or were tested with:

• a Raspberry Pi running Raspberry Pi OS buster
• AirPlay receiver (shairport-sync) and MQTT broker (mosquitto) running on same Raspberry Pi as the helper utilities.

See wiki for additional pointers.

IMPORTANT: Validate your MQTT broker config. See Configure MQTT broker - wiki for one way to set up a broker.

Test something like the following, done by using two separate shell sessions:

sudo apt install mosquitto-clients
# .. mosquitto_sub ...
mosquitto_sub -v -d -h mqttbrokerhost -t test/topic1
# .. mosquitto_pub ...
mosquitto_pub    -d -h mqttbrokerhost -t test/topic1 -m "helo"

As mentioned above, shairport-sync will need to be built with MQTT and metadata support. See wiki - Build shairport-sync with MQTT support on Raspberry Pi

Quickstart

Install python dependencies and clone this repository

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

# place a clone of this repo in ~/projects/
mkdir ~/projects
cd ~/projects
git clone https://github.com/idcrook/shairport-sync-mqtt-display.git
cd shairport-sync-mqtt-display

now go back to the "install" section:

• circuitpython_char_lcd install
• python-flaschen-taschen install
• python-flask-socketio-server install

Development setup

Original development setup:

• iTunes® and Airfoil Airplay-ing to Raspberry Pi(s).
• Raspberry Pi Model 3 B
  • running mosquitto MQTT broker
  • running shairport-sync, configured with MQTT to send cover artwork and parsed metadata

python-flask-socketio-server

Since both python and web technologies are very cross-platform, development was done on both a Mac running macOS and a Raspberry Pi Model 3 B running Raspberry Pi OS (buster)

circuitpython_char_lcd

Adafruit's Adafruit RGB Negative 16x2 LCD+Keypad Kit for Raspberry Pi LCD Pi Plate was used.

Useful docs:

• Character LCDs - Python & CircuitPython Usage
• Adafruit 16x2 Character LCD + Keypad for Raspberry Pi - Python Usage

python-flaschen-taschen

• A Raspberry Pi 3 B with a Adafruit RGB Matrix HAT + RTC was used to develop, attached to a powered 32x32 RGB LED Matrix Panel - 6mm pitch from Adafruit.

Useful docs:

• Adafruit RGB Matrix + Real Time Clock HAT for Raspberry Pi | Adafruit Learning System
• hzeller/rpi-rgb-led-matrix: Controlling up to three chains of 64x64, 32x32, 16x32 or similar RGB LED displays using Raspberry Pi GPIO
• hzeller/flaschen-taschen: Noisebridge Flaschen Taschen display - a network UDP client/server system for panel displaying.

---

1: Trademarks are the respective property of their owners.⤸

2: AirPlay® source could be

• iTunes® or Music app in iOS™/macOS™
• Rogue Amoeba's Airfoil app (which can even send Spotify artwork from macOS app)

⤸