ClawHub

Agent Radio

Other

Control internet radio playback with stream/ station search, favorites, volume, pause/resume, stop, next, and show current playback using mpv or ffplay.

Install

openclaw skills install agent-radio

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