核心用法
apple-media 是一个纯文档型 Skill，通过封装 pyatv 项目的 atvremote 命令行工具，提供对 Apple TV、HomePod 及 AirPlay 设备的完整控制能力。用户需先通过 pipx install pyatv 安装依赖，随后即可使用 atvremote scan 发现局域网内的苹果设备，并通过设备名称、IP 地址或标识符进行精准控制。
该 Skill 覆盖五大核心场景：设备发现与配对（scan/pair/wizard）、播放控制（play/pause/seek/shuffle/repeat）、音量管理（set_volume/volume_up/down）、内容投流（stream_file/play_url）以及 Apple TV 专属交互（方向键导航、键盘输入、应用启动、电源管理）。特别值得一提的是其多房间音频管理能力，支持通过 add_output_devices 等命令将多个 HomePod 组成立体声或全屋播放组。
显著优点
1. 协议完整度高：基于 pyatv 逆向工程实现，支持 MRP（Media Remote Protocol）、AirPlay、Companion 等多种协议，功能覆盖度远超普通遥控器 App。
2. 局域网自动化友好：纯命令行交互，易于集成到 Home Assistant、Shell 脚本或定时任务中，实现"到家自动播放音乐"等场景。
3. 跨平台兼容：pyatv 本身支持 Linux/macOS/Windows，配合 Python 3.13 环境即可运行，打破苹果生态的封闭性。
4. 实时状态推送：push_updates 命令可监听播放状态变化，为开发状态面板或自动化触发提供数据基础。
潜在缺点与局限性
- Python 版本锁死：明确不兼容 Python 3.14+，安装时需显式指定
--python python3.13，对新手有一定门槛。 - 配对流程繁琐：Apple TV 通常需要多协议配对，首次配置需交互式 PIN 码验证，无法完全无人值守。
- 网络环境敏感：设备发现依赖 mDNS/Bonjour，跨 VLAN 或复杂网络拓扑下可能出现扫描失败。
- 功能边界模糊：导航和键盘命令仅适用于 Apple TV，对 HomePod 无效，文档虽注明但易误用。
适合的目标群体
- 智能家居极客：希望将 Apple TV/HomePod 接入非 HomeKit 自动化体系的技术用户
- 多平台开发者：需要在 Linux 服务器或 Windows 环境中远程调试 Apple 设备的工程师
- 家庭影音集成商：为客户部署全屋音频方案，需批量配置多房间音频分组的专业人员
- CLI 爱好者：偏好终端操作效率，反感频繁切换遥控器 App 的进阶用户
使用风险
- 依赖项维护：
pyatv作为社区逆向项目，可能随 tvOS 更新出现协议兼容性问题，需关注版本更新。 - 凭证安全：配对凭证明文存储于
~/.pyatv.conf，多用户系统需注意文件权限（建议 600）。 - 网络暴露风险：
play_url功能可接受任意远程流地址，若脚本参数未做校验，可能存在 SSRF 隐患。 - 设备误操作：
turn_off与stop命令不可逆，自动化脚本中需谨慎使用，避免中断重要播放会话。