Apple TV integration for Gladys Assistant
Control your Apple TV: power, remote, playback, volume and applications.
Published by valentinhttr
- Devices
- Version 1.0.0
- Requires Gladys >=4.85.0
- ★ 1
Control your Apple TV from Gladys Assistant: power, remote, playback, volume and applications. The integration talks to your Apple TV directly on your local network, using pyatv — the reference implementation of Apple's AirPlay and Companion protocols, and the same library Home Assistant uses. Nothing goes through Apple's servers, and no Apple ID is required.
Requirements
- An Apple TV (HD, 4K, any generation running tvOS 15 or later).
- Gladys 4.85.0 or later.
- The Apple TV and your Gladys server on the same network. If they are on different VLANs or subnets, see "Different subnets" below.
- Physical access to the television during pairing: Apple displays a code on the screen that you have to read and type into Gladys.
Setting it up
Three steps, in this order. An Apple TV has to be added and then paired before a single command works — adding it alone gets you a device that obeys nothing.
1. Find your Apple TV
Open the Discovery tab of the integration and press Scan. Gladys listens for the AirPlay announcements on your network, and the integration checks every candidate address directly with pyatv. Your Apple TV appears with its name and its model.
Press Add to Gladys to create the device. An Apple TV is usually named after the room it sits in ("Living room"), so the device is created as "Apple TV Living room" — clear in a device list, and it is also what makes its selector readable in scenes. You can rename it afterwards in the Devices tab.
2. Pair it
Pairing is what authorizes Gladys to control the device. It happens in the Configuration tab, with the first two buttons:
- 1. Pair an Apple TV — pick your Apple TV in the dropdown and press Run. The list holds the Apple TVs you added at step 1, so there is no IP address to look up. A code appears on your television.
- 2. Enter the code — type the code you see on screen, then press Run.
Apple asks for one code per protocol: after the first code is accepted, a second one appears on the television. Two codes is normal.
The second code goes in the same field as the first one. The form keeps what you typed, so you have to clear the field and type the new code in its place, then press the button again. Pressing it a second time without clearing does nothing useful — the integration recognizes the old code and says so rather than wasting the new one.
Codes expire fast, and the connection carrying them closes on its own after a short while. If that happens, the integration says so and immediately puts a new code on your television: read the message, clear the field, enter the new code, and carry on. There is no need to start over from step 1.
Once pairing is complete, run a scan again (or accept the Update that Gladys offers in the Discovery tab): the integration now knows what your Apple TV can actually do, and adds the volume control and the application shortcuts.
3. Use it
The device exposes:
- Power — on/off. "Off" means standby, in Apple's sense: the box stays on the network, the screen and the HDMI output go away.
- Remote — directional pad, OK, Back, Home, Control Center.
- Playback — play, pause, stop, previous, next, rewind, fast forward.
- Volume — a slider, plus volume up/down buttons. The slider only appears when your setup exposes a readable volume level. An Apple TV controlling a soundbar over HDMI-CEC usually only supports the up/down buttons.
- Now playing and Application — text sensors showing what is on screen.
- Application shortcuts — one button per installed application, so a scene can open Netflix or Disney+ directly. Disable them, or lower the maximum, in the configuration.
On a dashboard
Two boxes, two ways to use the same Apple TV:
- Devices in a room — every remote key is a real button you can press: the directional pad, OK, Back, Home, Control Center, play, pause, the transport keys, the volume slider and the application shortcuts. This is the remote.
- Music box — the transport bar of a media player. Add the Apple TV to it and drive it like a Sonos.
The device list shows both sets, which is why some keys appear twice: the ones prefixed with "Media" are what the Music box uses, the short ones are the remote buttons. Each box only offers the features it can actually use, so you never have to choose between them.
Configuration
| Setting | What it does |
|---|---|
| Discovery duration | How long Gladys listens for AirPlay announcements. Increase it on a busy or slow network. |
| Manual IPv4 addresses | Only needed when announcements do not reach Gladys (routed networks, VLANs). Added to the automatic discovery. |
| Refresh interval | How often the integration reconciles what the Apple TV does not push by itself, typically the power state on some models. |
| Application shortcuts | Whether to expose one button per installed application. |
| Maximum number of shortcuts | An Apple TV can have a hundred applications; this bound keeps the device readable. |
Other actions
Each one acts on an Apple TV you pick in a dropdown — the same list as the pairing buttons, filled with the devices you added from the Discovery tab.
- Reconnect and refresh — reopen the session and read the device again. The first thing to try when something looks stale.
- List the installed applications — shows the bundle identifier of every application, which is what "Launch an application" expects.
- Launch an application — opens an application by bundle identifier, e.g.
com.netflix.Netflix. - Play a URL — sends a video URL or a deep link to the Apple TV over AirPlay.
- Delete the pairing — forgets the stored credentials. Use it when pairing has to be redone, for example after a factory reset of the Apple TV.
Troubleshooting
The scan finds nothing. Gladys captures AirPlay announcements from the host network. Check that your Apple TV is powered on, that AirPlay is enabled (Settings → AirPlay and HomeKit), and that Gladys is on the same network. If your Gladys server is on a different subnet, fill in the manual IPv4 address.
The integration log names what it saw: if it reports announcements that "carried no IPv4 address", your Apple TV was announced but its address never reached Gladys — go straight to the manual address.
You run Gladys in Docker on a Mac or on Windows. Discovery cannot work
there, and it is not a misconfiguration on your side. Docker Desktop, OrbStack
and Colima run containers inside a Linux virtual machine, so network_mode: host means the virtual machine's network, not your Wi-Fi. Multicast from
your Apple TV never reaches Gladys. Unicast does, so everything else works:
put the IP address of your Apple TV in "Manual IPv4 addresses" and the
integration discovers, pairs and controls it normally. A Gladys running on
Linux (Raspberry Pi, NAS, server) is on the network for real and does not need
this.
Every command fails with "not paired yet". The device was added but never paired. Run the two pairing buttons in the Configuration tab.
The pairing dropdown is empty. It only lists Apple TVs already added to Gladys, so step 1 has not happened yet: go to the Discovery tab, press Scan, then Add to Gladys.
Pairing fails or the code is refused. The code expires quickly — start again and enter it right away. If it keeps failing, remove Gladys from the Apple TV (Settings → General → AirPlay and HomeKit → Allow Access), run "Delete the pairing" in Gladys, then pair again.
The device shows as unreachable. Check that the Apple TV is powered on and still has the same IP address. A scan refreshes the address the integration uses; a static lease on your router avoids the problem entirely.
There is no volume slider. Your setup does not expose a readable volume level — a common case with HDMI-CEC. Use the volume up and volume down buttons instead.
Different subnets. mDNS announcements do not cross subnets. Fill in the IPv4 address of each Apple TV in "Manual IPv4 addresses"; the integration queries them directly, which works as long as the traffic is routed.
Privacy and storage
The pairing credentials are stored in the integration's own writable volume
(/data/pyatv.json), never in the Gladys configuration, and never leave your
network. Deleting the integration deletes them with it.
Configuration settings
These are the settings Apple TV asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Setting up your Apple TV, step by step | section | No | An Apple TV has to be added AND paired before a single command works. Three steps, in this order. 1) Discovery tab: press "Scan", wait, then press "Add to Gladys" on your Apple TV. It now exists in Gladys, but obeys nothing yet. 2) Back on this page, at the bottom: run "1. Pair an Apple TV" and pick it from the list — no IP address to look up. A code appears on your television; type it in "2. Enter the code". Apple asks for one code per protocol, so a second code follows: clear the field and type the new one in its place. 3) Discovery tab again: press "Update" on your Apple TV to pick up the volume control and the application shortcuts that the pairing revealed. |
| Finding your Apple TV | section | No | These two settings only affect the scan of the Discovery tab. The defaults work on a normal home network: leave them alone unless a scan comes back empty. |
| Discovery duration (seconds) | number | No | How long Gladys listens for AirPlay announcements. Increase it on a busy or slow network. |
| Manual IPv4 addresses | string | No | Optional, comma separated. Needed only when Gladys and your Apple TV are on different subnets or VLANs, where mDNS announcements do not travel. They are added to the automatic discovery, so the Apple TV still shows up in the Discovery tab like any other. |
| What the device exposes | section | No | These settings shape the Gladys device itself. Changing one takes effect on the next "Update" you accept in the Discovery tab. |
| Refresh interval | select | No | The Apple TV pushes what it can in real time. This interval reconciles what it does not push, typically the power state on some models. |
| Application shortcuts | boolean | No | Add one button per installed application to the device, so scenes can open Netflix or Disney+ directly. Read from the Apple TV after pairing. |
| Maximum number of shortcuts | number | No | An Apple TV can have a hundred applications. This bound keeps the device readable. |
| Pairing and tools, with the buttons below | section | No | Everything below this line acts on an Apple TV you already added from the Discovery tab: pick it in the list, then press "Run". The first two buttons are the pairing itself and they go together — start with "1. Pair an Apple TV". The others are troubleshooting tools you will rarely need. |
How to install Apple TV in Gladys
- In Gladys, open Integrations: Apple TV appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/valentinhttr/gladys-apple-tv:1.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/valentinhttr/gladys-apple-tv.
Apple TV requires Gladys >=4.85.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
Apple TV 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 valentinhttr, not by the Gladys core team.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation