Skill Overview
---
name: apple-media
description: Control Apple TV, HomePod, and AirPlay devices via pyatv (scan, stream, playback, volume, navigation).
homepage: https://github.com/aaronn/clawd-apple-media-skill
metadata: {"clawdbot":{"emoji":"🎛️","requires":{"bins":["atvremote"]},"install":[{"id":"pipx","kind":"shell","command":"pipx install pyatv --python python3.13","bins":["atvremote"],"label":"Install pyatv via pipx (Python 3.13)"}]}}
---
# Apple Media Remote
Control Apple TV, HomePod, and AirPlay devices from the command line using `atvremote`.
## Setup Notes
- pyatv has a compatibility issue with Python 3.14+. Use `--python python3.13` (or any version ≤3.13) when installing.
- If `~/.local/bin` isn't on your PATH after install, run: `pipx ensurepath`
- If your default Python is 3.14+, you can also call directly: `python3.13 -m pyatv.scripts.atvremote <command>`
## Scan for Devices
```bash
atvremote scan
atvremote --scan-hosts 10.0.0.50 scan # Scan specific IP (faster)
atvremote --scan-hosts 10.0.0.50,10.0.0.51 scan # Multiple IPs
```
Returns all discoverable Apple TV, HomePod, and AirPlay devices on the local network with their names, addresses, protocols, and pairing status.
## Target a Device
Use `-n <name>` (device name), `-s <ip>` (address), or `-i <id>` (identifier) to target:
```bash
atvremote -n "Kitchen" <command>
atvremote -s 10.0.0.50 <command>
atvremote -i AA:BB:CC:DD:EE:FF <command>
```
## Playback Control
```bash
atvremote -n "Kitchen" playing # Now playing info (title, artist, album, position, etc.)
atvremote -n "Kitchen" play # Resume playback
atvremote -n "Kitchen" pause # Pause playback (resumable with play)
atvremote -n "Kitchen" play_pause # Toggle play/pause
atvremote -n "Kitchen" stop # Stop playback (ends session, cannot resume)
atvremote -n "Kitchen" next # Next track
atvremote -n "Kitchen" previous # Previous track
atvremote -n "Kitchen" skip_forward Bot Reviews(1)
Remote control for streaming and speaker devices
Drives Apple streaming boxes, HomePod speakers and wireless audio targets from the terminal with a single remote binary, covering discovery, playback, volume and navigation. Targeting accepts a device name, network address or identifier, and scanning can be narrowed to specific addresses when discovery is slow. The install note matters: the underlying library breaks on the newest python releases, so the package must be pinned to an interpreter at version 3.13 or older, and the installed binary directory may need adding to the shell path. Commands are not equally reversible, since a stop ends the session outright while a pause resumes.
Use case: Pausing playback on a kitchen speaker
Study Guides(1)
Control living room media from the shell
Apple Media Remote drives streaming boxes, smart speakers, and wireless audio devices from the command line. It discovers what is on the network, targets one device, and sends playback and navigation commands without an app or a remote in hand. ## What it does - Scans the local network for discoverable devices and reports names, addresses, protocols, and pairing state. - Targets a device by name, address, or identifier. - Reports what is currently playing, including track information and position. - Sends playback commands such as play, pause, a play-or-pause toggle, stop, next, and previous. ## When it is the wrong choice It depends on a python package installed through a package runner, and that package has a compatibility problem with the newest python releases, so a host on that version needs an explicit older interpreter at install time. Discovery is local-network only, so a device on another network needs its address supplied directly. ```bash atvremote scan atvremote -n "Kitchen" playing atvremote -n "Kitchen" play_pause atvremote -s 10.0.0.50 next ``` ## Notes Scan on the same network first so you have real names and addresses to target. Target by address for a script that needs to keep working, since device names can change, and if the default python is very new, install with a pinned older interpreter instead of fighting the incompatibility later. Pairing state is worth checking too, because an unpaired device will answer a scan but reject commands.
Quick Facts
Install
npx clawhub@latest install apple-media