介绍
# 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 <command>`
## 扫描设备
```bash atvremote scan atvremote --scan-hosts 10.0.0.50 scan # Scan specific IP (faster) atvremote --scan-hosts 10.0.0.50,10.0.0.51 scan # Multiple IPs ```
返回本地网络上所有可发现的 Apple TV、HomePod 和 AirPlay 设备及其名称、地址、协议和配对状态。
## 指定设备
使用 `-n <name>`（设备名称）、`-s <ip>`（地址）或 `-i <id>`（标识符）来指定： ```bash atvremote -n "Kitchen" <command> atvremote -s 10.0.0.50 <command> atvremote -i AA:BB:CC:DD:EE:FF <command> ```
## 播放控制
```bash atvremote -n "Kitchen" playing # Now playing info (title, artist, album, position, etc.) atvremote -n "Kitchen" play # Resume playback atvremote -n "Kitchen" pause # Pause playback (resumable with play) atvremote -n "Kitchen" play_pause # Toggle play/pause atvremote -n "Kitchen" stop # Stop playback (ends session, cannot resume) atvremote -n "Kitchen" next # Next track atvremote -n "Kitchen" previous # Previous track atvremote -n "Kitchen" skip_forward # Skip forward (~10-30s, app-dependent) atvremote -n "Kitchen" skip_backward # Skip backward (~10-30s, app-dependent) atvremote -n "Kitchen" skip_forward=30 # Skip forward specific seconds atvremote -n "Kitchen" set_position=120 # Seek to position (seconds) atvremote -n "Kitchen" set_shuffle=Songs # Shuffle: Off, Songs, Albums atvremote -n "Kitchen" set_repeat=All # Repeat: Off, Track, All ```
## 音量
```bash atvremote -n "Kitchen" volume # Get current volume (0-100) atvremote -n "Kitchen" set_volume=50 # Set volume (0-100) atvremote -n "Kitchen" volume_up # Step up (~2.5%) atvremote -n "Kitchen" volume_down # Step down (~2.5%) ```
## 投屏
将本地文件或 URL 投屏到设备： ```bash atvremote -n "Kitchen" stream_file=/path/to/audio.mp3 # Local file atvremote -n "Kitchen" play_url=http://example.com/stream.mp3 # Remote URL ```
支持常见的音频格式（MP3, WAV, AAC, FLAC 等）。
## 电源管理
```bash atvremote -n "Apple TV" power_state # Check power state atvremote -n "Apple TV" turn_on # Wake device atvremote -n "Apple TV" turn_off # Sleep device ```
## 导航（Apple TV）
```bash atvremote -n "Apple TV" up # D-pad up atvremote -n "Apple TV" down # D-pad down atvremote -n "Apple TV" left # D-pad left atvremote -n "Apple TV" right # D-pad right atvremote -n "Apple TV" select # Press select/enter atvremote -n "Apple TV" menu # Back/menu button atvremote -n "Apple TV" home # Home button atvremote -n "Apple TV" home_hold # Long press home (app switcher) atvremote -n "Apple TV" top_menu # Go to main menu atvremote -n "Apple TV" control_center # Open control center atvremote -n "Apple TV" guide # Show EPG/guide atvremote -n "Apple TV" channel_up # Next channel atvremote -n "Apple TV" channel_down # Previous channel atvremote -n "Apple TV" screensaver # Activate screensaver ```
## 键盘输入（Apple TV）
当文本字段处于焦点时： ```bash atvremote -n "Apple TV" text_get # Get current text atvremote -n "Apple TV" text_set="search query" # Replace text atvremote -n "Apple TV" text_append=" more" # Append text atvremote -n "Apple TV" text_clear # Clear text ```
## 应用控制（Apple TV）
```bash atvremote -n "Apple TV" app_list # List installed apps atvremote -n "Apple TV" launch_app=com.apple.TVMusic # Launch by bundle ID or URL ```
## 输出设备（多房间）
管理连接的音频输出（例如 HomePod 组）： ```bash atvremote -n "Apple TV" output_devices # List current output device IDs atvremote -n "Apple TV" add_output_devices=<device_id> # Add speaker to group atvremote -n "Apple TV" remove_output_devices=<device_id> # Remove from group atvremote -n "Apple TV" set_output_devices=<device_id> # Set specific output(s) ```
## 推送更新（实时监控）
监听实时播放变化： ```bash atvremote -n "Kitchen" push_updates # Prints updates as they occur (ENTER to stop) ```
## 配对
某些设备（尤其是 Apple TV）在控制前需要配对： ```bash atvremote -n "Living Room" pair # Pair (follow PIN prompt) atvremote -n "Living Room" --protocol airplay pair # Pair specific protocol atvremote wizard # Interactive guided setup ```
配对后，凭据会自动存储在 `~/.pyatv.conf` 中。
## 设备信息
```bash atvremote -n "Kitchen" device_info # Model, OS version, MAC atvremote -n "Kitchen" features # List all supported features atvremote -n "Kitchen" app # Current app playing media ```
## 提示
- **暂停与停止：** 使用 `pause`/`play` 来暂停和恢复。`stop` 会完全结束会话 —— 必须从源头（Siri、家庭 App 等）重新开始播放。 - 显示“配对: NotNeeded (不需要)”的 HomePod 可以直接向其投屏。 - Apple TV 通常需要先配对（针对该设备支持的所有协议）。 - `playing` 命令会显示媒体类型、标题、艺术家、位置、随机/重复状态。 - 对于立体声 HomePod 组，可以通过名称指定其中任意一个单元。 - 如果已知设备 IP，使用 `--scan-hosts` 可以更快地指定目标。 - 导航和键盘命令主要用于 Apple TV（不适用于 HomePod）。