The main idea is to stream audio to the HomePod or Apple TV using the pyatv AirPlay library.

• Automatically stops streaming when HomePod is used by another app
• Sometimes audio streaming stops, so plugin automatically restarts it

• NodeJS (>=8.9.3) with NPM (>=6.4.1)
• pyatv (>=0.13) which require python (>= 3.8)

For the HomePod you can specify device MAC address or device name.

Config example:

{
    "platform": "HomepodRadioPlatform",
    "serialNumber": "20020105:00",
    "homepodId": "<homepod id or name>",
    "httpPort": 7654,
    "mediaPath": "/media/homepod",
    "enableVolumeControl": true,
    "radios": [
        {
            "name": "BBC - Radio 1",
            "radioUrl": "http://stream.live.vc.bbcmedia.co.uk/bbc_radio_one",
            "artworkUrl": "https://ichef.bbci.co.uk/images/ic/1920x1080/p05d68tx.jpg",
            "autoResume": true,
            "onSwitch": true
        }
    ],
    "audioFiles": [
        {
            "name": "Alert",
            "fileName": "police.mp3",
            "volume": 85
        }
    ]
}

Some radios provide metadata about currently played tracks. The plugin supports an optional metadataUrl parameter and tries to fetch JSON in the following format (example: https://o.tavrmedia.ua/rokscla):

[
      {
            "stime": "15:29:21",
            "time": "15:29",
            "singer": "Billy Joel",
            "song": "Honesty",
            "cover": "https://www.radioroks.ua/static/img/content/cover/0/38/500x500.jpg"
      },
      {
            "stime": "15:25:38",
            "time": "15:25",
            "singer": "Fleetwood Mac",
            "song": "Everywhere",
            "cover": ""
      },
      ...
  ]

The plugin then

• Enriches the radio stream with singer and song values from the retrieved metadata
• Enriches the radio artwork with the image downloaded using the cover metadata URL

The plugin allows to start file playback either through a add switch accessory (see below) or it can be triggered from a webhook.

Make sure your audio files are available to the Homebridge server, for example by downloading them to the server:

$ mkdir -r /home/pi/media
$ <downlaod files to /home/pi/media>
$ ls /home/pi/media
-rw-r--r-- 1 pi   pi     94622 Jan 10 16:46 hello.wav

Configure the plugin to play files from /home/pi/media by setting the mediaPath property:

  "mediaPath": "/home/pi/media",

This feature adds a switch accessory in the audioFiles section for each audio file you want to stream

    "audioFiles": [
        {
            "name": "Alert",
            "fileName": "police.mp3",
            "volume": 85
        }
    ]

Supported audio file formats are mp3, wav, flac, and ogg.

You can also specify an .m3u playlist file to stream multiple files:

    "audioFiles": [
        {
            "name": "Relaxing Mood",
            "fileName": "death_metal.m3u",
            "volume": 85
        }
    ]

The .m3u file format is just a list of audio files:

# My playlist

# Metallica, 1991
Nothing Else Matters.mp3

# Master Of Puppets, 1986
Master Of Puppets.mp3

# Ride The Lightning, 1984
For Whom The Bell Tolls.mp3

You should use the Homebridge server name (default for Homebridge server is homebridge.local) or IP to invoke playback via URL

Example:

• Homebridge is running on host "homebridge.local"
• hello.mp3 file is on the same server on /var/www/media
• Plugin's "httpPort" is set to 4567
• Plugin's "mediaPath" is set to /var/www/media

Then you can trigger playback of hello.mp3 even from browser by navigating to: http://homebridge.local:4567/play/hello.mp3

You can specify the playback volume level, by adding it to the end of the playback URL: http://homebridge.local:4567/play/hello.mp3/75

• Configure automation to play file
  • Select/Create automation in Home app
  • Tap "Select Accessories and Scenes..."
  • At the botton tap "Convert to Shortcut"
  • Create shortcut:
  • Test shortcut

In the Home app settings:

• Tap the Homes and Home Settings button.
• Tap Home Settings > Allow Speaker & TV Access, then choose "allow everyone"
• Important! Reboot the HomePod

• Create shortcut with name (for example) "Start Radio"
• Select "Control Home" action, check corresponding speaker and in "Media" section select "Resume Audio")
• Say "Hey Siri, start radio" on iPhone/iPad (on HomePod Mini Siri does not run it properly)

For streaming to the HomePod the plugin uses pyatv (https://pyatv.dev). Follow these setup instructions for RaspberryPi/Linux. If installing on a different platform, adjust as needed.

Install python3:

sudo apt-get install python3

Install pip3:

sudo apt-get install python3-pip

Install pyatv:

pip3 install pyatv

If the installation fails with this error:

error: externally-managed-environment

× This environment is externally managed

Then install pyatv with the break-system-packages option:

pip3 install --break-system-packages

Make atvremote available for homebridge:

sudo ln -s /home/pi/.local/bin/atvremote /usr/local/bin/atvremote

The Homebridge Docker image comes with the latest version of python pre-installed. At the time of writing, the image is based on Ubuntu 22.04, with Python 3.10.12 included.

To avoid having to reinstall pyatv every time the container is recreated (for example when updating the Homebridge image), Homebridge provides the startup.sh script, which is executed after the Docker container is finished starting up. Add the following line to the end of startup.sh:

pip3 install --break-system-packages

You can do this from the command line (using your favorite editor) and finding the script in the Homebridge config folder. Alternatively you can edit it from the Homebridge UI, by going to Settings, Startup & Environment, Startup Script. If you edit the script from the UI or after the container has started, you will need to restart the container.

Starting with various OS versions, Apple devices have started generating, by default, a new random MAC address for each wireless network they connect to. The HomePod Identifiers are based on the MAC address and while it will not change every time the HomePod reconnects to your home wifi, resetting a HomePod will indeed generate a new randomized MAC address and therefore new HomePod Identifiers. If this happens, you will have to update the plugin configuration.

Due to Apple's use of MAC address randomization and simply to make it easier to setup and read the plugin configuration, you can use the HomePod name (as displayed in the Home app) in the HomePod Id field, as well as any of the HomePod Identifiers. If you use the HomePod name, you will have to update the plugin configuration if you change it in the Home app.

Scan for devices:

atvremote scan

Select one of Identifiers values from the chosen device (or the Name value):

       Name: HomePod
   Model/SW: HomePod Mini, tvOS 15.2
    Address: 192.168.1.7
        MAC: F4:22:F0:10:33:71
 Deep Sleep: False
Identifiers:
 - F4:22:F0:10:33:71
 - F422F0103371

The easieast path would be to get the streaming url from your favorite radio playlist (usually .m3u file). Example for BBC Radio: https://gist.github.com/bpsib/67089b959e4fa898af69fea59ad74bc3

Make sure your HomePod has Pairing: NotNeeded set for RAOP protocol.

Scan for devices:

atvremote scan

Select for your device:

Services:
 - Protocol: Companion, Port: 49152, Credentials: None, Requires Password: False, Password: None, Pairing: Unsupported
 - Protocol: AirPlay, Port: 7000, Credentials: None, Requires Password: False, Password: None, Pairing: NotNeeded
 - Protocol: RAOP, Port: 7000, Credentials: None, Requires Password: False, Password: None, Pairing: NotNeeded

Sometimes (quite rarely) playback fails and in the logs there are errors like:

  pyatv.exceptions.HttpError: RTSP/1.0 method SETUP failed with code 500: Internal Server Error

Typically this error disappears after HomePod restart.

Looks like this is not supported at the moment by pyatv

With iOS 15 Homekit does not support volume control and start/stop for speaker accessory (at least for speakers exposed by Homebridge). So I'd suggest to enable switch accessory for each radio.