名称： apple-media
描述： 通过 pyatv 控制 Apple TV、HomePod 和 AirPlay 设备（扫描、串流、播放控制、音量、导航）。
主页： https://github.com/aaronn/clawd-apple-media-skill
元数据： {"clawdbot":{"emoji":"🎛️","requires":{"bins":["atvremote"]},"install":[{"id":"pipx","kind":"shell","command":"pipx install pyatv --python python3.13","bins":["atvremote"],"label":"通过 pipx 安装 pyatv (Python 3.13)"}]}}

Apple 媒体遥控器

使用 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 <命令>

扫描设备

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 <IP>（地址）或 -i <标识符> 来指定目标设备：

atvremote -n "厨房" <命令>
atvremote -s 10.0.0.50 <命令>
atvremote -i AA:BB:CC:DD:EE:FF <命令>

播放控制

atvremote -n "厨房" playing           # 获取当前播放信息（标题、艺术家、专辑、播放位置等）
atvremote -n "厨房" play              # 恢复播放
atvremote -n "厨房" pause             # 暂停播放（可通过 play 恢复）
atvremote -n "厨房" play_pause        # 切换播放/暂停状态
atvremote -n "厨房" stop              # 停止播放（结束会话，无法恢复）
atvremote -n "厨房" next              # 下一曲
atvremote -n "厨房" previous          # 上一曲
atvremote -n "厨房" skip_forward      # 快进（约 10-30 秒，取决于应用）
atvremote -n "厨房" skip_backward     # 快退（约 10-30 秒，取决于应用）
atvremote -n "厨房" skip_forward=30   # 快进指定秒数
atvremote -n "厨房" set_position=120  # 跳转到指定位置（秒）
atvremote -n "厨房" set_shuffle=Songs # 设置随机播放模式：Off, Songs, Albums
atvremote -n "厨房" set_repeat=All    # 设置重复模式：Off, Track, All

音量控制

atvremote -n "厨房" volume            # 获取当前音量 (0-100)
atvremote -n "厨房" set_volume=50     # 设置音量 (0-100)
atvremote -n "厨房" volume_up         # 调高音量（约 2.5%）
atvremote -n "厨房" volume_down       # 调低音量（约 2.5%）

串流播放

将本地文件或远程 URL 串流到设备：

atvremote -n "厨房" stream_file=/path/to/audio.mp3   # 本地文件
atvremote -n "厨房" play_url=http://example.com/stream.mp3  # 远程 URL

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

电源管理

atvremote -n "Apple TV" power_state      # 检查电源状态
atvremote -n "Apple TV" turn_on          # 唤醒设备
atvremote -n "Apple TV" turn_off         # 使设备进入睡眠

导航控制（Apple TV）

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             # Home 键
atvremote -n "Apple TV" home_hold        # 长按 Home 键（应用切换器）
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）

当文本输入框获得焦点时：

atvremote -n "Apple TV" text_get                 # 获取当前文本
atvremote -n "Apple TV" text_set="搜索内容"      # 替换文本
atvremote -n "Apple TV" text_append=" 更多"      # 追加文本
atvremote -n "Apple TV" text_clear               # 清空文本

应用控制（Apple TV）

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

输出设备（多房间音频）

管理连接的音频输出设备（例如组合 HomePod）：

atvremote -n "Apple TV" output_devices                    # 列出当前输出设备 ID
atvremote -n "Apple TV" add_output_devices=<设备ID>       # 将扬声器添加到组合
atvremote -n "Apple TV" remove_output_devices=<设备ID>    # 从组合中移除扬声器
atvremote -n "Apple TV" set_output_devices=<设备ID>       # 设置特定的输出设备

推送更新（实时监控）

实时监控播放状态变化：

atvremote -n "厨房" push_updates   # 实时打印更新（按 ENTER 键停止）

配对

部分设备（尤其是 Apple TV）在控制前需要配对：

atvremote -n "客厅" pair                   # 配对（按提示输入 PIN 码）
atvremote -n "客厅" --protocol airplay pair  # 为特定协议配对
atvremote wizard                                  # 交互式引导设置

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

设备信息

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

使用技巧

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