Apple 设备命令行全能遥控器 - Apple Media Remote (for HomePod, Apple TV, etc)

基于 pyatv 库通过命令行控制 Apple TV、HomePod 及 AirPlay 设备的媒体播放、音量调节、导航与流媒体推送，适合本地网络智能家居自动化场景。

基本信息

• 技能名称?Apple Media Remote (for HomePod, Apple TV, etc)
• 中文名称?Apple 设备命令行全能遥控器
• 作者?aaronn
• 分类?专业技能
• 版本?1.0.0
• 标签?apple-tv, homepod, airplay, pyatv, media-remote, streaming, home-automation, cli, mDNS

使用方法

使用说明
核心用法
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 上游更新