name: apple-media
description: Discover and control Apple media/AirPlay devices (HomePod, Apple TV, AirPlay speakers) from macOS. Use when you want to scan for AirPlay devices, map names→IPs/IDs, pair/connect, and control playback/volume using pyatv (atvremote) and Airfoil.

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):

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

Verify:

atvremote --help | head

Quick start

1) Scan the network for devices

# 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):

# 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:

# 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.

./scripts/scan.sh 5

scripts/scan-json.js

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

node ./scripts/scan-json.js