Apple Media Remote

使用atvremote从命令行控制Apple TV、HomePod和AirPlay设备。

设置说明

• - pyatv与Python 3.14+存在兼容性问题。安装时请使用--python python3.13（或任何≤3.13的版本）。
• 如果安装后~/.local/bin不在PATH中，请运行：pipx ensurepath
• 如果默认Python版本为3.14+，也可以直接调用：python3.13 -m pyatv.scripts.atvremote

扫描设备

bash
atvremote scan
atvremote --scan-hosts 10.0.0.50 scan # 扫描特定IP（更快）
atvremote --scan-hosts 10.0.0.50,10.0.0.51 scan # 多个IP

返回本地网络中所有可发现的Apple TV、HomePod和AirPlay设备，包括名称、地址、协议和配对状态。

指定目标设备

使用-n （设备名称）、-s （地址）或-i （标识符）指定目标：
bash
atvremote -n Kitchen
atvremote -s 10.0.0.50
atvremote -i AA:BB:CC:DD:EE:FF

播放控制

bash
atvremote -n Kitchen playing # 当前播放信息（标题、艺术家、专辑、进度等）
atvremote -n Kitchen play # 恢复播放
atvremote -n Kitchen pause # 暂停播放（可用play恢复）
atvremote -n Kitchen play_pause # 切换播放/暂停
atvremote -n Kitchen stop # 停止播放（结束会话，无法恢复）
atvremote -n Kitchen next # 下一曲
atvremote -n Kitchen previous # 上一曲
atvremote -n Kitchen skip_forward # 快进（约10-30秒，取决于应用）
atvremote -n Kitchen skip_backward # 快退（约10-30秒，取决于应用）
atvremote -n Kitchen skip_forward=30 # 快进指定秒数
atvremote -n Kitchen set_position=120 # 跳转到指定位置（秒）
atvremote -n Kitchen set_shuffle=Songs # 随机播放：关闭、歌曲、专辑
atvremote -n Kitchen set_repeat=All # 重复模式：关闭、单曲、全部

音量控制

bash
atvremote -n Kitchen volume # 获取当前音量（0-100）
atvremote -n Kitchen set_volume=50 # 设置音量（0-100）
atvremote -n Kitchen volume_up # 增加音量（约2.5%）
atvremote -n Kitchen volume_down # 减小音量（约2.5%）

流媒体播放

将本地文件或URL流式传输到设备：
bash
atvremote -n Kitchen stream_file=/path/to/audio.mp3 # 本地文件
atvremote -n Kitchen play_url=http://example.com/stream.mp3 # 远程URL

支持常见音频格式（MP3、WAV、AAC、FLAC等）。

电源管理

bash
atvremote -n Apple TV power_state # 检查电源状态
atvremote -n Apple TV turn_on # 唤醒设备
atvremote -n Apple TV turn_off # 使设备休眠

导航（Apple TV）

bash
atvremote -n Apple TV up # 方向键上
atvremote -n Apple TV down # 方向键下
atvremote -n Apple TV left # 方向键左
atvremote -n Apple TV right # 方向键右
atvremote -n Apple TV select # 按下选择/确认
atvremote -n Apple TV menu # 返回/菜单按钮
atvremote -n Apple TV home # 主页按钮
atvremote -n Apple TV home_hold # 长按主页（应用切换器）
atvremote -n Apple TV top_menu # 前往主菜单
atvremote -n Apple TV control_center # 打开控制中心
atvremote -n Apple TV guide # 显示EPG/节目指南
atvremote -n Apple TV channel_up # 下一个频道
atvremote -n Apple TV channel_down # 上一个频道
atvremote -n Apple TV screensaver # 启动屏幕保护

键盘输入（Apple TV）

当文本输入框获得焦点时：
bash
atvremote -n Apple TV text_get # 获取当前文本
atvremote -n Apple TV text_set=search query # 替换文本
atvremote -n Apple TV text_append= more # 追加文本
atvremote -n Apple TV text_clear # 清除文本

应用控制（Apple TV）

bash
atvremote -n Apple TV app_list # 列出已安装应用
atvremote -n Apple TV launch_app=com.apple.TVMusic # 通过Bundle ID或URL启动应用

输出设备（多房间）

管理连接的音频输出（例如，组合HomePod）：
bash
atvremote -n Apple TV output_devices # 列出当前输出设备ID
atvremote -n Apple TV addoutputdevices= # 将扬声器添加到组
atvremote -n Apple TV removeoutputdevices= # 从组中移除
atvremote -n Apple TV setoutputdevices= # 设置指定输出设备

推送更新（实时监控）

实时监控播放变化：
bash
atvremote -n Kitchen push_updates # 实时打印更新（按ENTER停止）

配对

某些设备（尤其是Apple TV）在控制前需要配对：
bash
atvremote -n Living Room pair # 配对（按照PIN码提示操作）
atvremote -n Living Room --protocol airplay pair # 配对特定协议
atvremote wizard # 交互式引导设置

配对后，凭据会自动存储在~/.pyatv.conf中。

设备信息

bash
atvremote -n Kitchen device_info # 型号、操作系统版本、MAC地址
atvremote -n Kitchen features # 列出所有支持的功能
atvremote -n Kitchen app # 当前播放媒体的应用

提示

• - 暂停 vs 停止： 使用pause/play暂停和恢复。stop完全结束会话——必须从源设备（Siri、家庭应用等）重新开始播放。
• 标记为Pairing: NotNeeded的HomePod可以立即进行流媒体播放。
• Apple TV通常需要先配对（设备支持的所有协议）。
• playing命令显示媒体类型、标题、艺术家、进度、随机/重复状态。
• 对于立体声HomePod对，按名称指定任一单元。
• 如果知道设备IP，使用--scan-hosts可以更快地定位目标。
• 导航和键盘命令主要适用于Apple TV（不适用于HomePod）。