apple-media

Control Apple TV, HomePod, and AirPlay devices via pyatv (scan, stream, playback, volume, navigation).

Install with Tessl CLI

npx tessl i github:Demerzels-lab/elsamultiskillagent --skill apple-media

What are skills?

Quality

68%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Optimize this skill with Tessl

npx tessl skill review --optimize ./public/skills/aaronn/apple-media/SKILL.md

SKILL.md

Review

Evals

Apple Media Remote

Name: apple-media
Rating: 0.75 (1 reviews)
Author: Demerzels-lab

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)

Repository: Demerzels-lab/elsamultiskillagent
Commit: 45f9fac
Last updated: 15 days ago
Created: 15 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.