Apple Media

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.

Security Scan

The skill's code, scripts, and instructions are coherent with its stated purpose (discovering AirPlay devices and controlling them via pyatv and Airfoil) and do not request unrelated credentials or install arbitrary remote code.

Purpose & Capability

The name/description match the behavior: scripts call atvremote (pyatv) to scan and provide wrappers that delegate speaker control to an Airfoil script. No unrelated services, credentials, or binaries are requested.

Instruction Scope

SKILL.md and the bundled scripts limit actions to local network discovery (atvremote scan), parsing that output, and delegating speaker connect/volume to a local Airfoil helper. They do expose discovered IPs and device identifiers (expected for a network scan) but do not transmit data to external endpoints.

Install Mechanism

This is instruction-only (no install spec). The README/SKILL.md recommend installing pyatv via pipx and using Airfoil (Homebrew cask). Nothing is downloaded from arbitrary URLs and no archive extraction is present.

Credentials

No environment variables or credentials are requested. The skill's runtime needs (pyatv/atvremote, Node for the JSON parser, and Airfoil tooling) are proportionate to the described functionality.

Persistence & Privilege

The skill does not request always:true, does not modify other skills or system-wide settings, and does not persist credentials. It runs only the supplied scripts when invoked.

Assessment

This skill appears to do what it says: scan the local network for AirPlay devices (showing IPs and identifiers) and control speakers by delegating to an Airfoil helper. Before installing/using it: 1) ensure you are comfortable with local network scanning (outputs include IP addresses) and avoid committing scan outputs; 2) install pyatv (atvremote) via pipx and have Node available for the JSON script; 3) ensure the expected airfoil helper (../../airfoil/airfoil.sh relative to the skill) exists and that you trust that helper—the skill delegates volume/connect to that script; 4) note the README recommends pinning pyatv to Python 3.12; 5) review the small scripts locally (they execute atvremote and spawn child processes) before running. There are no unexplained credential requests or remote downloads, so the skill is internally consistent.

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