功能描述

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

使用说明 (SKILL.md)

Apple Media Remote

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

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 \x3Ccommand>

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

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

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=\x3Cdevice_id>    # Add speaker to group
atvremote -n "Apple TV" remove_output_devices=\x3Cdevice_id> # Remove from group
atvremote -n "Apple TV" set_output_devices=\x3Cdevice_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)

安全使用建议

This skill appears to be what it says: a wrapper for pyatv/atvremote to control local Apple devices. Before installing, verify the pyatv package source (use official PyPI), and prefer installing via pipx as recommended. Be aware that pairing will create ~/.pyatv.conf containing credentials that allow device control — review and protect that file. Because the skill can scan your local network and control devices, only enable autonomous invocation if you trust the agent; otherwise keep it user-invocable and run commands yourself. If you want extra assurance, inspect the upstream repository (homepage) and run atvremote manually once to confirm behavior before giving the skill regular use.

功能分析

Type: OpenClaw Skill Name: apple-media Version: 1.0.0 The skill provides capabilities that, while aligned with its stated purpose of controlling Apple media devices, present significant security risks if the AI agent were to be compromised via prompt injection. Specifically, the `atvremote stream_file=/path/to/audio.mp3` command documented in SKILL.md allows the agent to read and stream arbitrary local files, which could be abused for data exfiltration. Additionally, `atvremote play_url=http://example.com/stream.mp3` enables outbound network connections to arbitrary URLs, potentially for beaconing or fetching malicious content. These powerful capabilities, even without explicit malicious intent in the skill's instructions, warrant a 'suspicious' classification due to their high potential for abuse.

能力评估

✓ Purpose & Capability

Name/description (control Apple TV/HomePod/AirPlay via pyatv) match the declared requirements (atvremote binary) and the runtime instructions. No unrelated binaries, environment variables, or config paths are requested.

✓ Instruction Scope

SKILL.md only instructs use of atvremote commands (scan, play, volume, pairing, streaming local files/URLs). It explicitly performs local network discovery and pairing; it does not instruct reading unrelated system files or exporting data externally. Note: pairing credentials are stored in ~/.pyatv.conf after pairing (expected for this tool).

ℹ Install Mechanism

The registry showed no formal install spec, but SKILL.md contains metadata recommending 'pipx install pyatv --python python3.13' (a reasonable installation method). Installing from PyPI via pipx is moderate-risk compared with no install; there are no arbitrary URL downloads or extract steps.

✓ Credentials

No environment variables or external credentials are requested. The only persisted credential-like artifact is the local pairing configuration (~/.pyatv.conf), which is proportional to the skill's purpose (paired control of devices).

ℹ Persistence & Privilege

Skill is not always:true and is user-invocable (defaults). The agent can invoke the skill autonomously (disable-model-invocation=false) — this is the platform default. Because the skill controls local devices and stores pairing tokens locally, consider the implications of allowing autonomous invocation, but this configuration is not inherently incoherent.

版本历史

v1.0.0

Initial public release — control Apple TV, HomePod, and AirPlay speakers from the command line. - Full documentation for scanning, pairing, playback, volume, streaming, navigation, app, and output device control - Recipes for setup, fast device targeting, and Power Management - Compatible with Python 3.13 and below (notes for 3.14+) - Includes real-time playback updates and multi-room audio support via pyatv/atvremote - Troubleshooting tips and common usage guidance

元数据

Slug apple-media

版本 1.0.0

许可证 —

累计安装 17

当前安装数 17

历史版本数 1

常见问题