Apple Media Remote

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

设置说明

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

扫描设备

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 <名称>（设备名称）、-s <IP地址>(address)，或-i <id>（标识符）来指定目标设备：

atvremote -n "Kitchen" <command>
atvremote -s 10.0.0.50 <command>
atvremote -i AA:BB:CC:DD:EE:FF <command>

播放控制

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

音量

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流式传输到设备：

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等）。

电源管理

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）

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）

当文本字段获得焦点时：

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）

atvremote -n "Apple TV" app_list                          # List installed apps
atvremote -n "Apple TV" launch_app=com.apple.TVMusic      # Launch by bundle ID or URL

输出设备（多房间音频）

管理已连接的音频输出设备（例如，将HomePods分组）：

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)

推送更新（实时监控）

监听实时播放变化：

atvremote -n "Kitchen" push_updates   # Prints updates as they occur (ENTER to stop)

配对

某些设备（特别是Apple TV）在控制前需要配对：

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中。

设备信息

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

提示

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