Apple 媒体（AirPlay + Apple TV 控制）

作者：Parth Maniar — @officialpm

该技能是一个轻量级工作流封装，整合了以下两个工具：

• pyatv（通过 atvremote）：用于发现 Apple TV / HomePod 设备，并在支持且已配对的情况下执行远程控制类指令。
• Airfoil（复用现有 airfoil 技能）：提供跨 AirPlay 音响（包括 HomePod）的可靠音响连接/断开 + 音量控制能力。

安装配置

本技能依赖通过 pipx 安装的 pyatv。

安装或修复（固定使用 Python 3.12，以规避 Python 3.14 中 asyncio 的兼容性问题）：

pipx install pyatv || pipx upgrade pyatv
pipx reinstall pyatv --python python3.12

验证安装是否成功：

atvremote --help | head

快速上手

1) 扫描局域网中的设备

# 快速扫描（5 秒）
./scripts/scan.sh 5

# 已知目标 IP 时可更快扫描
./scripts/scan-hosts.sh "10.0.0.28,10.0.0.111" 3

# 或输出 JSON 格式结果
node ./scripts/scan-json.js 5

你将看到如下设备：

• HomePod（例如：“Living Room”、“Bedroom”）
• Apple TV
• 支持 AirPlay 的电视

2) 控制 HomePod / 音响音量（推荐路径）

使用 Airfoil 进行音响控制（对 HomePod 更稳定可靠）：

# 列出 Airfoil 可识别的所有音响
../airfoil/airfoil.sh list

# 连接并设置音量
./scripts/connect.sh "Living Room"
./scripts/volume.sh "Living Room" 35

# 直接断开连接
../airfoil/airfoil.sh disconnect "Living Room"

3) Apple TV 远程控制指令（基于 pyatv）

首先扫描获取 Apple TV 的名称或 ID，再执行具体命令：

# 示例（设备名可以是 “TV”，或其他目标名称）
atvremote -n "TV" playing
atvremote -n "TV" play_pause
atvremote -n "TV" turn_on
atvremote -n "TV" turn_off

若出现认证或协议错误，则需进行配对或提供凭据（取决于具体设备）。

注意事项 / 常见陷阱

• pyatv 对 HomePod 的控制通常需要身份认证，且开箱即用时未必支持全部远程控制指令。
  • 当 pyatv 在 HomePod 播放或音量控制上失败时，请优先使用 Airfoil 来管理音量及音响路由。
• atvremote scan 是获取设备 IP 地址与 ID 的权威来源。

附带脚本说明

scripts/scan.sh

调用 atvremote scan 并支持自定义超时时间。

./scripts/scan.sh 5

scripts/scan-json.js

将 atvremote scan 的原始输出解析为紧凑的 JSON 汇总格式（包含 name、address、model、services 字段）。

node ./scripts/scan-json.js