Case 00367

Agent Radio Skill

Internet radio player for OpenClaw with station search, favorites, volume control, and playback management.

When to Use

Use when user wants to:

• Play an internet radio stream by URL
• Search for stations by name from the live Radio Browser directory
• Play a random built-in station when no target is provided
• Manage favorite stations (add, remove, list)
• Control volume, pause/resume, stop, skip to next
• Check what is currently playing
• Have a persistent radio experience across sessions

Tools

This skill provides the following CLI commands in scripts/:

play <url|station_name> [volume]

Play a stream by URL or by name from favorites or the built-in list.

If no target is provided, the skill chooses a random station from stations.json. Optional volume is 0-100 and defaults to the saved setting.

Examples:

• play https://stream.zeno.fm/0r0xa792kwzuv
• play BBC Radio 1
• play "Jazz 24 (KNKX)" 60

stop

Stop playback immediately.

pause

Pause or resume the current playback process.

next

Skip to the next favorite station in a cycle.

volume [level]

Show the current volume or set a new default volume from 0-100.

Examples:

• volume
• volume 75

now

Show the current station URL, volume, PID, and playback status.

favorite add <name> <url>

Add a station to favorites.

favorite remove <name>

Remove a station from favorites.

list

List all favorite and built-in stations.

find <query> [number]

Search the Radio Browser directory. When number is provided, play that result immediately.

Examples:

• find jazz
• find "lofi hip hop" 1

Configuration

Preferences are stored in: {baseDir}/preferences.json

{
  "last_station": "",
  "volume": 80,
  "favorites": [
    {"name": "BBC Radio 1", "url": "http://..."},
    {"name": "Jazz 24 (KNKX)", "url": "https://..."}
  ],
  "audio_device": "auto",
  "current_pid": null,
  "paused": false
}

Audio device auto-detection:

• macOS: coreaudio/BuiltInSpeakerDevice
• Linux: alsa/default
• Windows: directsound/default

Override locations when needed:

• AGENT_RADIO_BASE_DIR
• AGENT_RADIO_PREF_FILE
• AGENT_RADIO_STATIONS_FILE

Implementation Notes

• Primary player: mpv --no-video --audio-device=<device> --volume=<vol> --cache=yes <url>
• Fallback player: ffplay -nodisp -autoexit <url>
• Playback runs in the background and stores PID plus paused state in preferences.
• On play, any existing playback is stopped before starting the next stream.
• Station lookup is case-insensitive across favorites and built-in stations.
• next cycles favorite URLs instead of depending on station-name matching.

Error Handling

• If both mpv and ffplay are missing, return install guidance.
• If dependencies like jq or curl are missing, fail early with a clear message.
• If a stored PID is stale, clear it automatically.
• If station search returns no matches, explain how to retry with another query or a direct URL.

Examples for Users

/radio play https://stream.zeno.fm/0r0xa792kwzuv
/radio play "BBC Radio 1"
/radio volume 70
/radio now
/radio find jazz
/radio find "lofi hip hop" 1
/radio favorite add "Lounge Jazz" https://jazz.stream
/radio list
/radio next
/radio stop

Future Enhancements

• Built-in station directory with genres and countries
• Recording streams to file
• Equalizer presets
• Web interface control