核心用法
apple-media 是 pyatv 命令行工具 atvremote 的封装技能，提供对 Apple TV、HomePod 及兼容 AirPlay 设备的完整控制。核心工作流为：扫描发现设备 → 配对（如需）→ 执行控制指令。
设备发现：atvremote scan 可发现局域网内所有 Apple 媒体设备，返回名称、IP、协议及配对状态。支持限定 IP 范围加速扫描（--scan-hosts）。
设备定位：通过 -n（名称）、-s（IP）或 -i（标识符）三选一指定目标设备。
媒体控制：完整覆盖播放控制（play/pause/stop/next/previous）、进度跳转（skip_forward/backward、set_position）、播放模式（shuffle/repeat）及音量调节（0-100 或步进）。
流媒体推送：支持将本地音频文件（MP3、WAV、AAC、FLAC 等）或远程 URL 直接推送到设备播放，实现非 Apple 生态内容的 AirPlay 投射。
Apple TV 专属：提供 D-pad 导航（上下左右/select/menu/home）、键盘文本输入（get/set/append/clear）、应用列表与启动（bundle ID）、电源管理（turn_on/off）及多房间音频输出管理（add/remove/set_output_devices）。
实时监听：push_updates 可持续监听播放状态变更，便于脚本触发自动化。
显著优点
- 协议完整：基于 pyatv 逆向工程实现，支持 MRP（Media Remote Protocol）、AirPlay、RAOP 等私有协议，功能覆盖度远超通用 DLNA/UPnP 方案
- 零硬件依赖：纯软件方案，无需 HomeKit 中枢或额外硬件
- 脚本友好：命令行接口适合 Shell/Python 自动化、Cron 定时任务、家庭助理集成
- 跨平台：pyatv 本身支持多平台，技能通过 pipx 隔离安装避免依赖冲突
- 多设备协同：支持输出设备分组管理，可实现 Apple TV + HomePod 立体声组合或全屋同步播放
潜在缺点与局限性
- Python 版本锁死：明确不兼容 Python 3.14+，必须用 ≤3.13 版本安装，增加环境维护成本
- 本地网络限制：依赖 mDNS/Bonjour 发现，跨 VLAN、VPN 或复杂网络拓扑下设备发现可能失败
- 配对摩擦：Apple TV 通常需首次手动配对并存储凭证，无人值守场景需预置
~/.pyatv.conf - 功能不对称：导航、键盘、应用控制仅限 Apple TV；HomePod 仅支持媒体流与基础播放控制
- 无官方支持：基于逆向工程，iOS/tvOS 更新可能破坏兼容性，存在协议变更风险
- 音频格式限制：流媒体推送虽支持常见格式，但无损/空间音频的端到端保真度未经官方验证
适合人群
- 智能家居极客：已将 Apple 设备纳入家庭自动化体系，需突破 HomeKit/Siri 限制的高级用户
- 跨平台开发者：需在 Linux/Windows 服务器或 Docker 环境中远程控制 Apple 媒体的工程师
- 多房间音频方案集成者：希望用统一脚本管理 Apple TV + HomePod 组合输出的全屋音频系统搭建者
常规风险
- 网络暴露风险：pyatv 协议未加密传输控制信令，不建议在不受信任网络（公共 WiFi、访客网络）使用
- 凭证泄露：
~/.pyatv.conf存储配对凭证，需确保文件权限（建议 600）并避免纳入版本控制 - 误操作停机：
turn_off与stop指令会终止播放会话，自动化脚本需区分pause与stop语义 - 协议兼容性：tvOS 大版本升级后可能出现功能失效，需关注 pyatv 上游更新