Apple TV Control

Control Apple TV via the pyatv library.

Requirements

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:

{
  "name": "Living Room",
  "id": "DEVICE_ID",
  "ip": "192.168.x.x",
  "credentials": {
    "companion": "...",
    "airplay": "..."
  }
}

First-Time Pairing

# 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

scripts/appletv.py status     # Full status with now playing
scripts/appletv.py playing    # What's currently playing

Playback Control

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

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

scripts/appletv.py volume_up
scripts/appletv.py volume_down

Power

scripts/appletv.py turn_on    # Wake from sleep
scripts/appletv.py turn_off   # Put to sleep
scripts/appletv.py power      # Toggle

Apps

scripts/appletv.py apps       # List installed apps
scripts/appletv.py app Netflix
scripts/appletv.py app YouTube
scripts/appletv.py app "Disney+"

Discovery

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