Introduction
# Apple TV Control
Control Apple TV via the pyatv library.
## Requirements
```bash pipx install pyatv --python python3.11 ```
> **Note:** pyatv requires Python ≤3.13. Python 3.14+ has breaking asyncio changes. Use `--python python3.11` or `python3.13` with pipx.
## Configuration
Config file at `~/clawd/config/appletv.json`:
```json { "name": "Living Room", "id": "DEVICE_ID", "ip": "192.168.x.x", "credentials": { "companion": "...", "airplay": "..." } } ```
### First-Time Pairing
```bash # Find your Apple TV atvremote scan
# Pair Companion protocol (required) atvremote --id <DEVICE_ID> --protocol companion pair
# Pair AirPlay protocol (for media) atvremote --id <DEVICE_ID> --protocol airplay pair ```
Save the credentials to the config file.
## Quick Commands
### Status & Playing ```bash scripts/appletv.py status # Full status with now playing scripts/appletv.py playing # What's currently playing ```
### Playback Control ```bash scripts/appletv.py play # Play/resume scripts/appletv.py pause # Pause scripts/appletv.py stop # Stop scripts/appletv.py next # Next track/chapter scripts/appletv.py prev # Previous ```
### Navigation ```bash scripts/appletv.py up # Navigate up scripts/appletv.py down # Navigate down scripts/appletv.py left # Navigate left scripts/appletv.py right # Navigate right scripts/appletv.py select # Press select/OK scripts/appletv.py menu # Menu button scripts/appletv.py home # Home screen ```
### Volume ```bash scripts/appletv.py volume_up scripts/appletv.py volume_down ```
### Power ```bash scripts/appletv.py turn_on # Wake from sleep scripts/appletv.py turn_off # Put to sleep scripts/appletv.py power # Toggle ```
### Apps ```bash scripts/appletv.py apps # List installed apps scripts/appletv.py app Netflix scripts/appletv.py app YouTube scripts/appletv.py app "Disney+" ```
### Discovery ```bash scripts/appletv.py scan # Find Apple TVs on network ```
## Example Interactions
- "What's playing on the TV?" → `scripts/appletv.py status` - "Pause the TV" → `scripts/appletv.py pause` - "Turn off the Apple TV" → `scripts/appletv.py turn_off` - "Open Netflix on TV" → `scripts/appletv.py app Netflix`