Apple Media (AirPlay + Apple TV control)#

Author: Parth Maniar — @officialpm

This skill is a thin workflow wrapper around two tools:

• pyatv ( atvremote) for discovering Apple TVs/HomePods and (when supported/paired) remote-control style commands.
• Airfoil (via the existing airfoil skill) for reliable speaker connect/disconnect + volume control across AirPlay speakers (including HomePods).

Setup#

This skill uses pyatv installed via pipx.

Install/repair (pinned to Python 3.12 to avoid Python 3.14 asyncio issues):

bash

pipx install pyatv || pipx upgrade pyatv
pipx reinstall pyatv --python python3.12

Verify:

bash

atvremote --help | head

Quick start#

1) Scan the network for devices#

bash

# Fast scan (5s)
./scripts/scan.sh 5

# Faster scan when you know IP(s)
./scripts/scan-hosts.sh "10.0.0.28,10.0.0.111" 3

# Or JSON output
node ./scripts/scan-json.js 5

You’ll see devices like:

• HomePods (e.g., "Living Room", "Bedroom")
• Apple TV
• AirPlay-capable TVs

2) Control HomePod / speaker volume (recommended path)#

Use Airfoil for speaker control (reliable for HomePods):

bash

# List speakers Airfoil can see
../airfoil/airfoil.sh list

# Connect and set volume
./scripts/connect.sh "Living Room"
./scripts/volume.sh "Living Room" 35

# Disconnect (direct)
../airfoil/airfoil.sh disconnect "Living Room"

3) Apple TV remote commands (pyatv)#

First, scan to find the Apple TV name or id, then run commands:

bash

# Examples (device name can be Apple TV or other targets)
atvremote -n "TV" playing
atvremote -n "TV" play_pause
atvremote -n "TV" turn_on
atvremote -n "TV" turn_off

If you get auth/protocol errors, pairing/credentials are needed (device-dependent).

Notes / gotchas#

• pyatv HomePod control often requires authentication and may not support all remote-control commands out of the box.

  • When pyatv fails for HomePod playback/volume, prefer Airfoil for volume + speaker routing.

• atvremote scan is the source of truth for IP/ID discovery.

Bundled scripts#

scripts/scan.sh#

Runs atvremote scan with a configurable timeout.

bash

./scripts/scan.sh 5

scripts/scan-json.js#

Parses atvremote scan output into a compact JSON summary (name, address, model, services).

bash

node ./scripts/scan-json.js