AirPlay community integration, free and open source
Voice notifications, chimes and audio on your AirPlay speakers (HomePod, Apple TV…).
Published by gboulvin
- Devices
- Version 2.0.0
- Requires Gladys >=5.3.0
- ★ 0
Play voice notifications, chimes and audio files on your AirPlay speakers from Gladys: HomePod and HomePod mini, Apple TV, AirPort Express, and the third-party speakers and receivers that support AirPlay or AirPlay 2 (Sonos, Bose, Denon/Marantz, Yamaha, Bang & Olufsen, Libratone…).
This integration replaces the AirPlay service built into Gladys, and adds a volume per speaker, built-in chimes, scene actions and triggers, and a dashboard widget.
Where it works
- Countries: everywhere. The integration talks to the speakers on your local network only; it does not depend on a country, a vendor account or an online service.
- Network: the speakers must be on the same local network (same subnet) as the Gladys server. Speakers on a guest Wi-Fi, a separate VLAN or behind a VPN are not found.
- Internet: not needed to play a chime, a file or a stream of your local network. The voice notifications use the text-to-speech voice selected in Gladys: Gladys Plus by default (internet required), or a local text-to-speech integration.
- Languages: English, French, German and Spanish.
Requirements
- Gladys Assistant 5.3.0 or later.
- In the Home app of your iPhone (Home settings > Speakers & TV), Allow speaker & TV access must be set to Everyone or Anyone on the same network. "Only people sharing this home" blocks Gladys.
- If you set a password for AirPlay, enter it in the configuration.
Installation
- Install AirPlay from the integration catalog of Gladys.
- Open the Discovery tab: your speakers are listed after a few seconds. Click Create on each speaker you want in Gladys.
- Use the Test a speaker button of the Configuration tab: the chosen speaker plays a two-tone chime.
Coming from the built-in AirPlay service
The speakers of the built-in service and those of this integration are different devices. Once your speakers are created here:
- Edit your scenes using Play a notification and pick the new speakers.
- Delete the old speakers from the built-in AirPlay integration.
Configuration
| Setting | Default | Effect |
|---|---|---|
| Default volume (%) | 70 | Volume of a speaker whose volume was never set in Gladys. |
| Maximum duration (s) | 300 | Any playback is stopped after this time (10 to 1,800 s). |
| Availability check (s) | 300 | How often the speakers are checked (60 to 3,600 s). Drives the offline/online triggers. |
| AirPlay protocol | Automatic | Automatic reads what each speaker announces. Force AirPlay 1 for an old silent receiver. |
| Sender name | Gladys | Name shown by the speakers that display who is playing. |
| AirPlay password | (empty) | Only for password-protected speakers. |
Your speakers in Gladys
Each speaker is a device with four features:
- Notification — what the Play a notification scene action of Gladys uses: the text is turned into speech and played on the speaker.
- Volume — the volume Gladys plays at (0 to 100 %). AirPlay cannot read the volume of a speaker at rest, so this is Gladys' own setting, kept per speaker; changing it during a playback applies it immediately.
- Playback state — playing or idle.
- Now playing — what Gladys is playing.
The device card shows a local badge when the speaker answers, and unreachable when it does not.
Scenes
Actions
- Play a notification (built into Gladys) — speaks a text on a speaker.
- Play an audio URL on AirPlay — plays a sound file or a stream
(MP3, AAC, WAV, OGG, FLAC, internet radio…) from an
http://orhttps://address, at an optional volume. With Wait until the end, the scene waits for the end of the audio (100 s at most). Outputs: Playback started and Duration played. - Play a chime on AirPlay — a built-in sound: Doorbell, Notification or Alert. It needs neither internet nor text-to-speech: ideal for a doorbell or an alarm.
- Stop AirPlay playback — stops what Gladys is playing on a speaker.
A speaker that does not answer does not stop the scene: Playback started is then false, use it in a condition to send a message instead.
Triggers
- AirPlay speaker went offline — a speaker stopped answering (unplugged, Wi-Fi lost…).
- AirPlay speaker back online — a speaker answers again.
Leave the speaker empty to react to any speaker. The name of the speaker is
available as {{triggerEvent.data.name}}. The detection follows the
Availability check interval.
Dashboard
Add the AirPlay speakers widget:
- without a speaker chosen, it lists your speakers with their state (reachable, unreachable, playing) and a Check now button;
- with a speaker chosen, it shows its volume, its state, its address and protocol, and Chime, Play a URL and Stop buttons.
Limitations
- Audio only: no video, no screen mirroring.
- One speaker per playback: no synchronized multi-room.
- Gladys does not pass the volume chosen in Play a notification to external integrations: the notification plays at the speaker's Volume. To speak louder or softer in a scene, set the volume with a Control a device action first.
- Gladys streams through its own AirPlay session: a playback interrupts what the speaker was playing (Apple Music, Spotify…), which does not resume afterwards.
- HomePod and Apple TV only play AirPlay 2 (since their OS 27 they accept an AirPlay 1 session and stay silent), and only with a PTP clock served by Gladys on UDP ports 319 and 320. The integration runs in a Docker container on its own network: if the speaker cannot reach that clock, it accepts the session and stays silent, or the integration reports that the PTP clock cannot be served. Third-party AirPlay 2 speakers fall back to an NTP clock, and AirPlay 1 receivers need none.
- The AirPlay password only applies to AirPlay 2 speakers.
- An Apple TV or HomePod set to "Only people sharing this home" refuses Gladys (see the requirements).
Troubleshooting
| Symptom | What to do |
|---|---|
| No speaker in the Discovery tab | Check that the speaker is on and on the same network as Gladys, then reopen the tab. |
| "The speaker does not answer" | Wake the speaker up (play something from your phone), check its IP address has not changed. |
| "The speaker asks for a password" | Enter the AirPlay password in the configuration. |
| "The speaker refused the pairing" | Home app > Home settings > Speakers & TV > allow everyone on the same network. |
| The notification plays without a voice | Check the voice selected in Gladys (Artificial intelligence settings) and its subscription. |
| The test chime plays but stays silent | Third-party speaker: set the protocol to AirPlay 1 (RAOP), or AirPlay 2, and test again. HomePod and Apple TV: see the limitations. |
| "needs a PTP clock" | The UDP ports 319/320 are taken or forbidden on the Gladys server: see the limitations. |
The integration logs each playback (speaker, address, protocol, reason of a failure) in its Logs tab.
Configuration settings
These are the settings AirPlay asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Before you start | section | No | Everything stays on your local network: no account, no cloud. Your speakers must be on the same network as Gladys and allow AirPlay from "Everyone on the same network" (Home app > Home settings > Speakers & TV). Open the Discovery tab to add them. Voice notifications use the text-to-speech voice of Gladys (Gladys Plus by default). |
| Default volume (%) | number | No | Volume of a speaker whose volume was never set in Gladys. |
| Maximum duration (s) | number | No | Any playback is stopped after this time, in seconds. |
| Availability check (s) | number | No | How often the speakers are checked, in seconds. Drives the offline/online scene triggers. |
| AirPlay protocol | select | No | Automatic reads what each speaker announces. Force AirPlay 1 for an older receiver that stays silent. |
| Sender name | string | No | Name shown by the speakers that display who is playing. |
| AirPlay password | secret | No | Only for AirPlay 2 speakers protected by a password (leave empty otherwise). |
How to install AirPlay in Gladys
- In Gladys, open Integrations: AirPlay appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/gboulvin/gladys-airplay:2.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/gboulvin/Gladys-Airplay.
AirPlay requires Gladys >=5.3.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
AirPlay is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by gboulvin, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation