modbender 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/binisn'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/playto suspend and resume.stopends 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
playingcommand shows media type, title, artist, position, shuffle/repeat state - For stereo HomePod pairs, target either unit by name
- Use
--scan-hostsfor faster targeting when you know the device IP - Navigation and keyboard commands are primarily for Apple TV (not HomePod)