appletv

通过 pyatv 控制 Apple TV。用于播放/暂停、导航、音量、启动应用程序、电源控制以及检查正在播放的内容。在“Apple TV”、“电视”、“正在播放的内容”、“暂停电视”、“播放电视”、“关闭电视”上触发。

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

---

## 中文说明

# Apple TV 控制

通过 pyatv 库控制 Apple TV。

## 环境要求

```bash
pipx install pyatv --python python3.11
```

> **注意：** pyatv 需要 Python ≤3.13。Python 3.14+ 包含破坏性的 asyncio 变更。请在 pipx 中使用 `--python python3.11` 或 `python3.13`。

## 配置

配置文件位于 `~/clawd/config/appletv.json`：

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

### 首次配对

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

将凭据保存到配置文件中。

## 快速命令

### 状态与播放
```bash
scripts/appletv.py status     # Full status with now playing
scripts/appletv.py playing    # What's currently playing
```

### 播放控制
```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
```

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

### 音量
```bash
scripts/appletv.py volume_up
scripts/appletv.py volume_down
```

### 电源
```bash
scripts/appletv.py turn_on    # Wake from sleep
scripts/appletv.py turn_off   # Put to sleep
scripts/appletv.py power      # Toggle
```

### 应用程序
```bash
scripts/appletv.py apps       # List installed apps
scripts/appletv.py app Netflix
scripts/appletv.py app YouTube
scripts/appletv.py app "Disney+"
```

### 设备发现
```bash
scripts/appletv.py scan       # Find Apple TVs on network
```

## 交互示例

- “电视上正在播放什么？” → `scripts/appletv.py status`
- “暂停电视” → `scripts/appletv.py pause`
- “关闭 Apple TV” → `scripts/appletv.py turn_off`
- “在电视上打开 Netflix” → `scripts/appletv.py app Netflix`