✓ Verified ✍️ Content Creation ✓ Enhanced Data

Apple Media

Control Apple TV, HomePod, and AirPlay devices via pyatv.

Rating
4.9 (194 reviews)
Downloads
5,060 downloads
Version
1.0.0

Overview

Control Apple TV, HomePod, and AirPlay devices via pyatv.

Complete Documentation

View Source →

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

Scan for Devices

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

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 (device name), -s (address), or -i (identifier) to target:

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

Playback Control

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

Volume

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

Streaming

Stream local files or URLs to a device:

bash
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

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

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

Keyboard Input (Apple TV)

When a text field is focused:

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

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

Output Devices (Multi-room)

Manage connected audio outputs (e.g. grouping HomePods):

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)

Push Updates (Live Monitoring)

Watch for real-time playback changes:

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

Pairing

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

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

Credentials are stored automatically in ~/.pyatv.conf after pairing.

Device Info

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

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)

Installation

Terminal bash

openclaw install apple-media
    
Copied!

💻Code Examples

atvremote --scan-hosts 10.0.0.50,10.0.0.51 scan # Multiple IPs

atvremote---scan-hosts-100050100051-scan--multiple-ips.txt
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" volume_down # Step down (~2.5%)

atvremote--n-kitchen-volumedown--step-down-25.txt
## Streaming

Stream local files or URLs to a device:

atvremote -n "Kitchen" play_url=http://example.com/stream.mp3 # Remote URL

atvremote--n-kitchen-playurlhttpexamplecomstreammp3--remote-url.txt
Supports common audio formats (MP3, WAV, AAC, FLAC, etc.).

## Power Management

atvremote -n "Apple TV" screensaver # Activate screensaver

atvremote--n-apple-tv-screensaver--activate-screensaver.txt
## Keyboard Input (Apple TV)

When a text field is focused:

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

atvremote--n-apple-tv-launchappcomappletvmusic--launch-by-bundle-id-or-url.txt
## Output Devices (Multi-room)

Manage connected audio outputs (e.g. grouping HomePods):

atvremote -n "Apple TV" set_output_devices=<device_id> # Set specific output(s)

atvremote--n-apple-tv-setoutputdevicesdeviceid--set-specific-outputs.txt
## Push Updates (Live Monitoring)

Watch for real-time playback changes:

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

atvremote--n-kitchen-pushupdates--prints-updates-as-they-occur-enter-to-stop.txt
## Pairing

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

atvremote wizard # Interactive guided setup

atvremote-wizard--interactive-guided-setup.txt
Credentials are stored automatically in `~/.pyatv.conf` after pairing.

## Device Info
example.sh
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
example.sh
atvremote -n "Kitchen" <command>
atvremote -s 10.0.0.50 <command>
atvremote -i AA:BB:CC:DD:EE:FF <command>

Tags

#media_and-streaming

Quick Info

Category Content Creation
Model Claude 3.5
Complexity One-Click
Author aaronn
Last Updated 3/10/2026
🚀
Optimized for
Claude 3.5
🧠

Ready to Install?

Get started with this skill in seconds

openclaw install apple-media