Apple TV 控制

通过 pyatv 库控制 Apple TV。

要求

pipx install pyatv --python python3.11

注意：pyatv 要求 Python ≤3.13。Python 3.14+ 有破坏性的 asyncio 变更。请使用--python python3.11或python3.13配合 pipx 使用。

配置

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

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

首次配对

# 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

将凭据保存到配置文件。

快捷命令

状态与播放

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

播放控制

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

导航

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

音量

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

电源

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

应用程序

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

发现

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