home / skills / openclaw / skills / appletv

appletv skill

This skill lets you control an Apple TV via pyatv, performing playback, navigation, volume, opening apps, and power actions.

npx playbooks add skill openclaw/skills --skill appletv

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.5 KB

---
name: appletv
version: 1.0.0
description: Control Apple TV via pyatv. Use for play/pause, navigation, volume, launching apps, power control, and checking what's playing. Triggers on "Apple TV", "TV", "what's playing", "pause TV", "play TV", "turn off TV".
license: MIT
---

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

Overview

This skill controls an Apple TV using the pyatv library to perform playback, navigation, volume, app launching, power, and status queries. It exposes simple voice and script triggers like "Apple TV", "pause TV", "what's playing", and supports discovery and first-time pairing. The skill relies on a local JSON config containing the device id, IP, and protocol credentials. Use it to integrate Apple TV control into automation or a chat/voice assistant workflow.

How this skill works

The skill talks to Apple TV devices over the network via pyatv, using the Companion and AirPlay protocols for control and media info. You must pair the device once (companion and airplay) and save credentials into ~/clawd/config/appletv.json. After pairing, commands map to pyatv actions (play, pause, navigation, volume, power, launch app, status) and discovery finds available Apple TVs on the LAN.

When to use it

Remote control Apple TV from a chat or voice assistant
Integrate Apple TV actions into home automation routines
Query what’s currently playing without using the physical remote
Launch streaming apps on the Apple TV from scripts or automations
Wake or sleep the Apple TV as part of energy-saving flows

Best practices

Install pyatv in an isolated Python environment (pipx recommended) and use Python ≤3.13
Pair Companion and AirPlay protocols and store credentials in the config file
Keep the device IP stable (static DHCP or reserved IP) to avoid rediscovery
Test discovery and pairing on the same network segment as the Apple TV
Limit automation to trusted hosts since credentials allow device control

Example use cases

Say "Pause TV" to pause current playback via the assistant
Run a bedtime routine that pauses playback and puts the Apple TV to sleep
Ask "What’s playing on the TV?" to get current media title and position
Trigger a script to launch Netflix or YouTube before guests arrive
Use discovery to find and add new Apple TVs to your config automatically

FAQ

How do I pair the Apple TV the first time?

Run atvremote scan to find devices, then pair with the companion and airplay protocols using atvremote --id <DEVICE_ID> --protocol companion pair and --protocol airplay pair, saving the returned credentials to the config file.

Which Python version should I use?

Use Python 3.11–3.13. pyatv is not compatible with Python 3.14+ due to asyncio changes; pipx install with --python python3.11 is recommended.

What goes in the config file?

The JSON file should include name, id, ip, and a credentials object containing companion and airplay credential strings for the paired Apple TV.