Name: Apple Media Remote (for HomePod, Apple TV, etc)
Availability: InStock
Author: aaronn

Apple Media Remote

Control Apple TV, HomePod, and AirPlay devices from the command line using

atvremote

Setup Notes

pyatv has a compatibility issue with Python 3.14+. Use
```
--python python3.13
```
(or any version ≤3.13) when installing.
If
```
~/.local/bin
```
isn't on your PATH after install, run:
```
pipx ensurepath
```
If your default Python is 3.14+, you can also call directly:
```
python3.13 -m pyatv.scripts.atvremote <command>
```

Scan for Devices

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

Returns all discoverable Apple TV, HomePod, and AirPlay devices on the local network with their names, addresses, protocols, and pairing status.

Target a Device

Use

-n <name>

(device name),

-s <ip>

(address), or

-i <id>

(identifier) to target:

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

Playback Control

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

Volume

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%)

Streaming

Stream local files or URLs to a device:

atvremote -n "Kitchen" stream_file=/path/to/audio.mp3   # Local file
atvremote -n "Kitchen" play_url=http://example.com/stream.mp3  # Remote URL

Supports common audio formats (MP3, WAV, AAC, FLAC, etc.).

Power Management

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

Navigation (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

Keyboard Input (Apple TV)

When a text field is focused:

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

App Control (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

Output Devices (Multi-room)

Manage connected audio outputs (e.g. grouping 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)

Push Updates (Live Monitoring)

Watch for real-time playback changes:

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

Pairing

Some devices (especially Apple TV) require pairing before control:

atvremote -n "Living Room" pair                   # Pair (follow PIN prompt)
atvremote -n "Living Room" --protocol airplay pair  # Pair specific protocol
atvremote wizard                                  # Interactive guided setup

Credentials are stored automatically in

~/.pyatv.conf

after pairing.

Device Info

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

Tips

Pause vs Stop: Use
```
pause
```
/
```
play
```
to suspend and resume.
```
stop
```
ends the session entirely — playback must be restarted from the source (Siri, Home app, etc.)
HomePods with "Pairing: NotNeeded" can be streamed to immediately
Apple TVs typically require pairing first (all protocols the device supports)
The
```
playing
```
command shows media type, title, artist, position, shuffle/repeat state
For stereo HomePod pairs, target either unit by name
Use
```
--scan-hosts
```
for faster targeting when you know the device IP
Navigation and keyboard commands are primarily for Apple TV (not HomePod)

Apple Media Remote (for HomePod, Apple TV, etc)

AI Skill Market Insights

Be Part of the 0+ Developer Community