AdHush Box setup: Apple TV

Every step, start to finish. The box watches your TV picture, finds the ad breaks, and turns the volume down and back up. Nothing is installed on the Apple TV itself.

Allow about 45 minutes. Most of that is the Pi installing software. Using a Roku instead? Use the Roku guide →

Apple TV support is brand new. Every AdHush Box before this one sat behind a Roku. The part we have not yet seen on real hardware is whether an Apple TV sends its picture through the HDMI splitter. If the TV stays black after Step 3 and swapping the outputs does not fix it, stop and email support rather than buying other parts.

Prefer plain text, or reading this with an agent? The same instructions as a text file →

Step 1: What you need

A Raspberry Pi 4 with its power supply. 2 GB of memory is enough.
A microSD card, 16 GB or larger, and a way to plug it into your computer.
A USB 3.0 HDMI capture card.
A 1×2 HDMI splitter and two short HDMI cables.
Your Apple TV and TV, already working.

The parts list on the Roku guide links the exact tested hardware. The parts are the same; only the streaming device differs.

Step 2: Write the SD card

Install the free Raspberry Pi Imager on your computer. It writes the card and pre-loads the settings that let the Pi join your WiFi with no monitor and no keyboard.

Choose Device: Raspberry Pi 4.
Choose OS: Raspberry Pi OS (other), then Raspberry Pi OS Lite (64-bit). Lite, not Desktop. 64-bit, not 32-bit.
Choose Storage: your SD card.
Click Next, then Edit Settings, and fill in:
- Hostname: adhush
- Username: adhush, with a password you will remember
- Your home WiFi name and password, and your WiFi country
- On the Services tab: Enable SSH, with password authentication
Save, then write the card and confirm the erase.

Step 3: Start the Pi and connect to it

Do this before any HDMI cable is attached. It proves the Pi, the card, and the WiFi all work, so a later picture problem can only be the splitter.

Put the card in the Pi and plug the Pi in. Wait about 90 seconds.
From your computer, open Terminal and connect:
ssh adhush@adhush.local
If that name does not answer, find the Pi in your router’s client list and use its IP address: ssh adhush@192.168.1.42

Step 4: Wire the HDMI tap

The output order is not optional. The capture card goes on OUTPUT 1 and the TV on OUTPUT 2. The splitter copies the first output’s capability back to the Apple TV, and only the capture card on OUTPUT 1 produces a feed AdHush can read. The other way round gives a black TV.

Unplug the HDMI cable from the back of the TV, leave it in the Apple TV, and plug it into the splitter’s INPUT.
Connect the splitter’s OUTPUT 1 to the capture card.
Connect the splitter’s OUTPUT 2 to the TV input the Apple TV used before.
Plug the capture card’s USB cable into one of the Pi’s blue USB 3.0 ports.
Turn the TV on. The picture must look exactly as it did before. If it is black, swap OUTPUT 1 and OUTPUT 2 and try again.

Step 5: Install the AdHush software

Sign in on your account page and open “Have an AdHush Box? Set it up”. It shows your device ID and device key.
In your SSH session on the Pi, run the command below. Replace the two placeholders with your own ID and key, and keep the word appletv at the end — that word is what installs Apple TV control.
curl -fsSL https://adhush.app/beta/install-box.sh | bash -s -- <deviceId> <deviceKey> appletv

The installer loads the video libraries and pyatv, downloads the box software to ~/adhush-box, saves your credentials, and starts the service. The service starts again on every boot. The TV blinks black for about two seconds the first time the box opens the capture card.

Step 6: Pair the box with the Apple TV

Turn the TV on and leave the Apple TV home screen showing. Then run this on the Pi:

python3 ~/adhush-box/box/pair_appletv.py

The script finds the Apple TV and asks for a PIN. The Apple TV shows the PIN on the TV screen. It usually asks twice, once for each connection it needs. Type each PIN as it appears. Then restart the box:

sudo systemctl restart adhush

You pair once. The box reconnects by itself after that.

Step 7: Check that it works

Watch the box think: tail -f ~/adhush.log. A line reading [actuator] Apple TV at … with a volume number proves the box can read the Apple TV volume, which means it can set it too.
Open your account page. Your box appears under Devices within a minute, with an Open controller button for the live view and the volume settings.
Watch live TV until an ad break. The volume drops within a few seconds of the break and returns when the show does.

What AdHush does with your volume

The box sets the Apple TV volume — the same volume its remote sets. The Apple TV passes that on to whatever plays the sound, including HomePods or any other AirPlay speaker.

During a show it leaves your volume alone.
During an ad break it sets the volume to zero.
After the break it restores the level you last chose.
If you change the volume with your remote during a break, the box keeps your new level and restores that instead. Your remote always wins.

On the controller you can also set the ad volume above zero. Ads then stay faint instead of silent.

If something is wrong

What you see	What to do
The TV picture is black after wiring the splitter	Swap the two splitter outputs. The capture card must be on OUTPUT 1 and the TV on OUTPUT 2.
ssh adhush@adhush.local does not answer	Find the Pi in your router's client list and use its IP address instead. Mesh WiFi systems often block .local names between nodes.
The log says: no Apple TV pairing	Run the pairing command in Step 5 again, then restart the service.
Pairing finds no Apple TV	Wake the Apple TV and leave its home screen on the TV. Check that the Pi and the Apple TV are on the same network.
The volume never changes during ads	Run tail -50 ~/adhush.log. A line reading 'set volume failed' means the pairing stopped working — pair again.
The service is not running	Run sudo systemctl status adhush and tail -50 ~/adhush.log. Check the capture card is in a blue USB 3.0 port.
AdHush mutes the show itself	Press 'Audio IS playing' on your account page. That corrects the box without touching the TV.

To stop the box at any time: sudo systemctl stop adhush. Your TV keeps working — the box only watches the picture and changes the volume.

Still stuck? Support →