基于 pyatv 库通过命令行控制 Apple TV、HomePod 及 AirPlay 设备的媒体播放、音量调节、导航与流媒体推送，适合本地网络智能家居自动化场景。
说明：
## 核心用法
`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 上游更新
