# AdHush box setup — Apple TV + HomePods

The plain-text version of <https://adhush.app/appletv/>, for reading in a
terminal or with an agent. The box watches the TV picture, finds the ad
breaks, and turns the volume down and up again. Nothing is installed on the
Apple TV itself.

Allow about 45 minutes. Most of it is the Pi installing software.

## Parts

- Raspberry Pi 4 (2 GB is enough) with a USB-C power supply
- microSD card, 16 GB or larger
- HDMI capture dongle (MS2130 class, USB 3.0)
- 1×2 HDMI splitter, plus 2 short HDMI cables
- The Apple TV and the TV that are already there

## 1. Flash the card

1. Install Raspberry Pi Imager on a computer.
2. Choose **Raspberry Pi OS Lite (64-bit)**.
3. Open the settings (the gear icon) and set:
   - hostname: `adhush`
   - username: `adhush`, and a password you keep
   - the home Wi-Fi name and password, and the Wi-Fi country
   - **Enable SSH** with password authentication
4. Write the card, then put it in the Pi.
5. Power the Pi on with no HDMI cable attached. Wait 90 seconds, then connect
   from your computer with `ssh adhush@adhush.local`. Do this before you wire
   the HDMI tap. It proves the Pi, the card and the Wi-Fi work, so any later
   picture problem can only be the splitter. If that name does not answer, use
   the Pi's IP address from your router's client list.

## 2. Cable the HDMI tap

CAUTION: The output port order is not optional. The dongle must sit on OUT 1.
The splitter copies the first output's capability to the source. A dongle on
OUT 1 makes the splitter report "no copy protection", which is what lets the
capture work. The TV on OUT 1 instead causes a black screen.

Connect in this order:

1. Apple TV HDMI out → splitter **IN**
2. Splitter **OUT 1** → capture dongle → a **blue** USB 3.0 port on the Pi
3. Splitter **OUT 2** → the TV input the Apple TV used before
4. Power the Pi last

The TV picture must look exactly as before. If the picture is black, swap
OUT 1 and OUT 2 and try again.

NOTE: Apple TV support is new. Every earlier AdHush box ran behind a Roku. If
the Apple TV refuses to send a picture through the splitter, and swapping the
outputs does not fix it, stop and email support@adhush.app — do not buy other
parts yet.

## 3. Install the software

Sign in at <https://adhush.app/account/> and open "Have an AdHush Box? Set it
up". The page shows a device ID and a device key. Then, from a computer on the
same network:

```bash
ssh adhush@adhush.local
```

On the Pi, run the installer. Use the ID and key from the account page, and
keep the word `appletv` at the end:

```bash
curl -fsSL https://adhush.app/beta/install-box.sh | bash -s -- <deviceId> <deviceKey> appletv
```

The installer does four things:

- installs the video libraries and pyatv (the Apple TV control library)
- downloads the box software to `~/adhush-box`
- writes the device credentials
- starts the box service, and starts it again at every boot

## 4. Pair the box with the Apple TV

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

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

The script scans for the Apple TV, then asks for a PIN. The Apple TV shows the
PIN on the TV screen. It usually asks twice, once for each protocol. Type each
PIN as it appears.

When it finishes, restart the box:

```bash
sudo systemctl restart adhush
```

The pairing is stored in `~/.adhush_appletv.json`. You do this once.

## 5. Check that it works

- The TV picture blinks black for about 2 seconds when the box first opens the
  capture. This happens once, at start.
- Watch the box think:

  ```bash
  tail -f ~/adhush.log
  ```

  Look for `[actuator] Apple TV at …` with a volume number. That line proves
  the box can read the Apple TV volume, which means it can also set it.
- Open <https://adhush.app/account/> on a phone. The box row goes live within a
  minute. It shows the channel, the current state, and volume controls.
- Watch live TV until an ad break. The volume must drop within a few seconds of
  the break, and come back when the show returns.

## What the box does with the volume

The box sets the Apple TV volume, the same value the Apple TV remote sets. The
Apple TV passes it to whatever plays the sound — the HomePods, in this setup.

- During a show, the box leaves the volume alone.
- During an ad break, it sets the volume to 0.
- After the break, it restores the level the user last chose.
- If the user changes the volume with the remote during a break, the box keeps
  that new level and restores it instead. The remote always wins.

The `/account` page can also duck instead of silencing. Set the ad volume above
0, and ads stay faint instead of silent.

## If something is wrong

| What you see | What to do |
|---|---|
| Black TV picture | Swap the splitter outputs. The dongle belongs on OUT 1. |
| `no Apple TV pairing` in the log | Run the pairing script again (step 4). |
| Pairing finds no Apple TV | Wake the Apple TV. Check that the Pi and the Apple TV use the same network. |
| Volume never changes | Check the log for `[actuator]` lines. A `set volume failed` line means the pairing no longer works — pair again. |
| The service is not running | `sudo systemctl status adhush` and `tail -50 ~/adhush.log`. Check the dongle is in a blue USB port. |
| The box mutes the show | Press "Audio IS playing" on the account page. That corrects the box without touching the TV. |

To stop the box at any time: `sudo systemctl stop adhush`. The TV keeps working
— the box only listens and changes the volume.