cliamp-plugin-yt-radio

Endless YouTube radio for cliamp — auto-fills the queue with the current track's YouTube Mix.

---

⚠️ Vibecoded

This plugin was written with an AI assistant (Claude) and has only been lightly reviewed by a human. It is ~180 lines of Lua with no external dependencies beyond yt-dlp.

Read yt-radio.lua before you approve it. cliamp will ask you to grant it the control (modify the play queue) and exec (run yt-dlp) permissions, and you should only do that if you are comfortable with the source. No warranty; use at your own risk.

---

What it does

yt-radio listens to cliamp's track.change / queue.change events. When fewer than min_ahead tracks remain ahead in the queue, it takes the video ID of the track currently playing, asks yt-dlp for that video's YouTube Mix (RD<videoID> — the auto-generated radio YouTube builds for any video), and appends up to batch fresh tracks to the queue.

Because every refill re-seeds from whatever is playing at that moment, the result is an endless radio that keeps drifting instead of a fixed playlist. It works for any YouTube / YouTube Music track played in cliamp.

Requirements

• cliamp with the Lua plugin runtime. Plugins run in the TUI, not in --daemon mode.
• yt-dlp on your PATH — it is already in cliamp's cliamp.exec allowlist by default, so no extra config is needed.
• A working YouTube provider in cliamp so the queued tracks actually play: ytmusic (run cliamp setup) or the yt provider.
• Permissions granted on trust: control (modify the queue) and exec (run yt-dlp).

Installation

Recommended: manual (directory) install — works on every cliamp version

mkdir -p ~/.config/cliamp/plugins/yt-radio
curl -fsSL https://raw.githubusercontent.com/Cache21/cliamp-plugin-yt-radio/main/yt-radio.lua \
  -o ~/.config/cliamp/plugins/yt-radio/init.lua
cliamp plugins trust yt-radio          # answer "y" at the prompt

Then start the cliamp TUI. cliamp plugins list should show yt-radio as trusted.

Why a directory and not a single file? cliamp 1.63.x has a bug where single-file plugins (plugins/yt-radio.lua) can never be trusted — they stay untrusted and never load. Installing as plugins/yt-radio/init.lua works around it. The bug is fixed in cliamp 2.0.0.

On cliamp ≥ 2.0.0: cliamp plugins install

cliamp plugins install Cache21/cliamp-plugin-yt-radio
# or pin a version:
cliamp plugins install Cache21/cliamp-plugin-yt-radio@v0.2.0

Accept the trust prompt (permissions control, exec), then restart the TUI.

Trust model: cliamp pins a hash of the approved contents in ~/.config/cliamp/plugins/.trust.json. If you edit the plugin afterwards you must re-run cliamp plugins trust yt-radio.

Configuration

All keys are optional. Put them under [plugins.yt-radio] in ~/.config/cliamp/config.toml:

Key	Default	Purpose
start_on	true	Whether auto-refill is active when the plugin loads. Toggle at runtime with cliamp plugins call yt-radio toggle (the runtime state is remembered and overrides this).
min_ahead	3	Refill when fewer than N tracks remain ahead of the current one.
batch	10	How many tracks to add per refill.
cooldown_secs	20	Minimum seconds between automatic refills (guards against event storms). The start command ignores it.
fetch_max	batch * 3	How many Mix entries to request from yt-dlp (headroom for de-duplication).
history_max	300	How many recently-added video IDs to remember, to avoid repeats across refills and restarts.
use_cookies	false	Pass --cookies-from-browser to yt-dlp (only needed for Mixes that require a signed-in session).
cookie_browser	chromium	Which browser yt-dlp reads cookies from when use_cookies = true.

enabled = false under [plugins.yt-radio] is cliamp's own switch to disable the whole plugin — different from start_on.

Example:

[plugins.yt-radio]
min_ahead = 3
batch     = 10

Usage

Automatic: just play any YouTube / YouTube Music track in cliamp. As the queue drains it tops itself up — you'll see YT radio +N flash in the status bar.

Manual: cliamp plugins call yt-radio <command>

Command	Effect
start	Force a refill right now, ignoring cooldown_secs, min_ahead and the on/off state.
on / off	Enable / disable automatic refills (persisted).
toggle	Flip the on/off state.
status	Print current state and settings.
clear	Reset the anti-repeat history.

How it works

RD<videoID> is the "Mix" playlist YouTube auto-generates for any video. yt-dlp --flat-playlist --dump-json lists that playlist cheaply (metadata only, no per-video extraction). The plugin then:

1. reads the current queue via cliamp.queue.list() / cliamp.queue.current();
2. extracts the seed video ID from the current track's path;
3. runs yt-dlp on https://www.youtube.com/watch?v=<seed>&list=RD<seed>;
4. filters out the seed itself, IDs already in the queue, and IDs in the recent history;
5. appends up to batch of the remainder with cliamp.queue.add(...).

yt-dlp runs asynchronously off cliamp's UI thread; the queue is only touched in the process's exit callback. A single-flight guard plus cooldown_secs keep the track.change / queue.change event stream (including the plugin's own queue.add calls) from triggering overlapping refills.

Troubleshooting

• Nothing gets added — tail the plugin log: tail -f ~/.config/cliamp/plugins.log and look for [yt-radio] lines.
• cliamp plugins list shows untrusted and it never runs — you installed it as a single file on cliamp 1.63.x. Remove it (cliamp plugins remove yt-radio) and use the directory install above.
• plugins not enabled — you ran cliamp --daemon. Plugins only run in the TUI.
• current track is not a YouTube id — you're playing internet radio, Navidrome, or a local file. The plugin only acts on YouTube tracks.
• yt-dlp exited with code N — try use_cookies = false, or update yt-dlp.
• It circles the same songs — raise history_max, and run cliamp plugins call yt-radio clear to reset the history.

Limits & notes

• The queue length stays around min_ahead + batch; already-played tracks remain in the queue history (normal cliamp behavior).
• cliamp sandbox constraints: exec is limited to the allowlist (yt-dlp, ffmpeg), 4 MiB combined output, 4 concurrent processes per plugin. This plugin does not use cliamp.http.
• No data is collected or sent anywhere. The video-ID history is stored locally at ~/.local/share/cliamp/plugins/yt-radio/store.json (mode 0600).

License

MIT © 2026 Manuel Artía. See LICENSE.