@ciphore/radiocli 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.7] - 2026-06-29
+
+### Changed
+
+- Search results can now be navigated with `Up` / `Down` while editing the
+  search query; search-history recall remains available with
+  `Ctrl+Up` / `Ctrl+Down`.
+- The listening stats activity heatmap now renders day cells as square markers
+  and uses a capped contribution scale so one unusually long listening day does
+  not flatten the rest of the Less/More color range.
+
+## [0.1.6] - 2026-06-17
+
+### Added
+
+- Added VLC (`cvlc`/`vlc`) as a third playback-only backend so installs without
+  `mpv` or `ffplay` still play audio.
+- Added a Help screen (`?`) listing every keybinding and `:` command, plus
+  command-name tab completion in the command palette.
+- Added persisted ICY track history shown on Now Playing (`d`) and up/down
+  recall of recent search queries in the search box.
+- Added opt-in resume of the most recent station on launch.
+- Added `O` to open the station homepage and `y` to copy its stream URL.
+- Added ASCII-safe display, transparent background (also honoring `NO_COLOR`),
+  and reduce-motion settings for terminal and low-power compatibility.
+- Added a best-effort Radio Browser upvote when favoriting a station.
+- Added a `radiocli version` command (and `--version` / `-v`).
+- Added `:doctor`, `:help`, `:resume`, `:ascii`, `:motion`, and `:background`
+  command-palette entries.
+
+### Changed
+
+- Playback binary detection now probes common install locations (Homebrew,
+  Scoop, WinGet, Chocolatey, and the VLC app bundle) when a tool is not on
+  `PATH`, so GUI-launched terminals still find `mpv`/`ffplay`/VLC.
+- The Radio Browser `User-Agent` now reports the installed package version.
+
 ## [0.1.5] - 2026-05-31
 
 ### Fixed
@@ -119,6 +156,8 @@ Initial public release.
   rows go to the visualizer.
 
 [0.1.5]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.5
+[0.1.6]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.6
+[0.1.7]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.7
 [0.1.4]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.4
 [0.1.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.3
 [0.1.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.2

package/README.md

@@ -13,8 +13,10 @@ It is built with [Ink](https://github.com/vadimdemedes/ink), [React](https://rea
 ## Features
 
 - Explore public radio from around the world through a cosmo-style braille world map beside the station list, with click-to-place mouse support and WASD keyboard movement backed by a cached geotagged station atlas. Country lists, global station search, a country-density map, and opt-in nearby discovery round out the discovery surface.
-- Tune stations with `mpv` first for full playback controls, with `ffplay` as a playback-only fallback when available.
-- Use a receiver-style Now Playing screen with 50 selectable receiver visualizers, backend status, cleaned ICY track metadata, stream diagnostics, sleep timer, favorite state, `mpv`-backed volume, pause, mute, station skipping, and zero-signal graphics whenever playback is idle, paused, stopped, or not backend-ready.
+- Tune stations with `mpv` first for full playback controls, with `ffplay` and VLC (`cvlc`/`vlc`) as playback-only fallbacks. RadioCLI also probes common install locations (Homebrew, Scoop, WinGet, Chocolatey, VLC app bundle) when a backend is not on `PATH`, so GUI-launched terminals still find it.
+- Use a receiver-style Now Playing screen with 50 selectable receiver visualizers, backend status, cleaned ICY track metadata and persisted track history, stream diagnostics, sleep timer, favorite state, `mpv`-backed volume, pause, mute, station skipping, and zero-signal graphics whenever playback is idle, paused, stopped, or not backend-ready.
+- Open the in-app Help screen (`?`) for every keybinding and `:` command, with command-name tab completion and search-history recall. Open a station homepage (`O`) or copy its stream URL (`y`).
+- Adapt to any terminal: ASCII-safe display, transparent background (and `NO_COLOR`) for light terminals, reduce-motion for SSH and low-power devices, and opt-in resume of the last station on launch.
 - Keep shortcuts in a fixed adaptive footer: a compact live station and track row appears above page-specific and global controls while playback is active.
 - Move previous/next through the exact station list you tuned from, even after navigating to another screen.
 - Browse dense station lists with inline location/codec metadata and yellow favorite stars next to station names.
@@ -75,7 +77,7 @@ Live public radio from around the world
 3 recent · 2 favorites · 1 imported
 
 ↑/↓ move · Enter open · number jump · : command
-←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · q quit
+←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · ? help · q quit
 ```
 
 The Now Playing screen is a framed receiver panel with **50 selectable receiver styles**. The sample below shows the default pulse-grid display; press `v` to cycle through the catalog, which spans several families:
@@ -106,7 +108,7 @@ Now playing ──────────────────────
 
 Playing: KEXP 90.3 FM · Now: Artist - Track · Seattle, Washington, United States · MP3 / 128 kbps / english · mpv · playing · vol 70 · Nearby 4/90
 space/F8 pause · f favorite · m mute · s sleep · d diagnostics · b home
-←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · q quit
+←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · ? help · q quit
 ```
 
 For the exact non-interactive demo transcript:
@@ -277,7 +279,7 @@ Page-specific footer controls:
 | Screen | Controls |
 | --- | --- |
 | Home | `↑` / `↓` move, `Enter` open, number jump, `:` command |
-| Search input | type query, `Backspace` edit, `Enter` search or tune, `Esc` finish |
+| Search input | type query, `Backspace` edit, `Up` / `Down` move results, `Ctrl+Up` / `Ctrl+Down` recall search history, `Enter` search or tune, `Esc` finish |
 | Search results | `/` edit query, `↑` / `↓` or `n` / `p` move, `Enter` tune, `f` favorite, `b` home |
 | Explore | click map, `WASD` fine move, `Shift+WASD` jump, `↑` / `↓` station, `Enter` tune, `f` favorite, `[` / `]` page, `b` home |
 | Countries | `/` filter, `↑` / `↓` move, `Enter` open stations, `w` map, `b` home |

package/dist/cli.js

@@ -8,6 +8,7 @@ import { PlayerController } from './player/player-controller.js';
 import { JsonLibraryStore } from './storage/store.js';
 import { parsePlaylistFile, stationFromUrl, writeM3u } from './playlists/playlist.js';
 import { detectPlaybackBackends, playbackBackendStatusLines } from './player/backend-install.js';
+import { appVersion } from './version.js';
 if (isDirectRun(process.argv[1], import.meta.url)) {
     const args = process.argv.slice(2);
     if (args.length > 0) {
@@ -33,6 +34,10 @@ export async function runCommand(args) {
         printHelp();
         return;
     }
+    if (command === 'version' || command === '--version' || command === '-v') {
+        console.log(appVersion());
+        return;
+    }
     if (!isKnownCommand(command)) {
         throw new Error(`Unknown command: ${command}\nRun radiocli help.`);
     }
@@ -113,6 +118,7 @@ export function printHelp() {
 
 Usage:
   radiocli                 Start the TUI
+  radiocli version         Print the installed version
   radiocli check           Show provider/backend health
   radiocli doctor          Show local playback setup guidance
   radiocli countries       Print top countries

package/dist/player/backend-install.js

@@ -2,8 +2,12 @@ import { existsSync, readFileSync } from 'node:fs';
 import { commandExists } from './command.js';
 import { airPlaySenderHealth } from './airplay-sender-health.js';
 export const ffplayLimitedControlsMessage = 'ffplay fallback has limited controls. Install mpv for pause, mute, volume, and media keys.';
+export const vlcLimitedControlsMessage = 'VLC fallback has limited controls. Install mpv for pause, mute, volume, and media keys.';
 export function detectPlaybackBackends({ platform = process.platform, hasCommand = commandExists, hasAirPlaySender = hasAirPlaySenderPackage } = {}) {
     const backends = ['mpv', 'ffplay'].filter(hasCommand);
+    if (hasCommand('cvlc') || hasCommand('vlc')) {
+        backends.push('vlc');
+    }
     if (platform === 'darwin' && hasCommand('ffmpeg') && hasCommand('dns-sd') && hasAirPlaySender()) {
         backends.push('airplay');
     }
@@ -33,6 +37,16 @@ export function playbackBackendCapabilities(backend) {
             supportsMediaKeys: false
         };
     }
+    if (backend === 'vlc') {
+        return {
+            backend,
+            label: 'VLC fallback',
+            supportsPause: false,
+            supportsMute: false,
+            supportsVolume: false,
+            supportsMediaKeys: false
+        };
+    }
     if (backend === 'airplay') {
         return {
             backend,
@@ -82,6 +96,15 @@ export function playbackBackendStatusLines(backends, platform = process.platform
             ...lines
         ];
     }
+    if (backendSet.has('vlc')) {
+        return [
+            'playback=fallback-only',
+            'playback_backend=vlc',
+            'controls=limited',
+            'controls_hint=install mpv for pause, mute, volume, and media keys',
+            ...lines
+        ];
+    }
     if (backendSet.has('airplay')) {
         return [
             'playback=airplay-only',

package/dist/player/command.js

@@ -1,8 +1,96 @@
 import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 export function commandExists(command) {
+    return resolveCommand(command) !== null;
+}
+// Resolve a runnable path for a command. GUI-launched terminals (macOS .app
+// terminals, some Linux desktop launchers) frequently do not inherit the login
+// shell PATH, so a perfectly installed binary in /opt/homebrew/bin or a Windows
+// package-manager shim looks "missing" to a bare PATH lookup. We therefore fall
+// back to probing well-known install locations before giving up.
+export function resolveCommand(command) {
+    return lookupOnPath(command) ?? probeKnownLocations(command);
+}
+function lookupOnPath(command) {
     const lookup = process.platform === 'win32' ? 'where' : 'which';
-    const result = spawnSync(lookup, [command], {
-        stdio: 'ignore'
-    });
-    return result.status === 0;
+    const result = spawnSync(lookup, [command], { encoding: 'utf8' });
+    if (result.status !== 0 || typeof result.stdout !== 'string') {
+        return null;
+    }
+    const first = result.stdout
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .find(Boolean);
+    return first ?? null;
+}
+function probeKnownLocations(command) {
+    for (const candidate of candidatePaths(command)) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function candidatePaths(command) {
+    const paths = [];
+    const names = candidateNames(command);
+    for (const dir of knownBinaryDirs()) {
+        for (const name of names) {
+            paths.push(join(dir, name));
+        }
+    }
+    paths.push(...appBundlePaths(command));
+    return paths;
+}
+function candidateNames(command) {
+    if (process.platform === 'win32' && !/\.[a-z0-9]+$/i.test(command)) {
+        return [`${command}.exe`, `${command}.com`, `${command}.bat`, `${command}.cmd`, command];
+    }
+    return [command];
+}
+function knownBinaryDirs() {
+    const home = homedir();
+    if (process.platform === 'darwin') {
+        return ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/opt/local/bin', '/sw/bin', join(home, '.local', 'bin')];
+    }
+    if (process.platform === 'win32') {
+        const dirs = [];
+        if (process.env.LOCALAPPDATA) {
+            dirs.push(join(process.env.LOCALAPPDATA, 'Microsoft', 'WinGet', 'Links'));
+        }
+        dirs.push(join(home, 'scoop', 'shims'));
+        if (process.env.ProgramData) {
+            dirs.push(join(process.env.ProgramData, 'chocolatey', 'bin'));
+        }
+        return dirs;
+    }
+    return [
+        '/usr/bin',
+        '/usr/local/bin',
+        '/bin',
+        '/usr/local/sbin',
+        '/snap/bin',
+        '/var/lib/flatpak/exports/bin',
+        join(home, '.local', 'bin')
+    ];
+}
+// Some media players (notably VLC) commonly install without putting a CLI entry
+// on PATH, so probe their standard application directories directly.
+function appBundlePaths(command) {
+    if (command !== 'vlc' && command !== 'cvlc') {
+        return [];
+    }
+    if (process.platform === 'darwin') {
+        return [
+            '/Applications/VLC.app/Contents/MacOS/VLC',
+            join(homedir(), 'Applications', 'VLC.app', 'Contents', 'MacOS', 'VLC')
+        ];
+    }
+    if (process.platform === 'win32') {
+        const roots = [process.env.ProgramFiles, process.env['ProgramFiles(x86)']].filter(Boolean);
+        return roots.map(root => join(root, 'VideoLAN', 'VLC', 'vlc.exe'));
+    }
+    return [];
 }

package/dist/player/player-controller.js

@@ -4,7 +4,8 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Socket } from 'node:net';
-import { detectPlaybackBackends, ffplayLimitedControlsMessage, playbackBackendInstallHint } from './backend-install.js';
+import { detectPlaybackBackends, ffplayLimitedControlsMessage, playbackBackendInstallHint, vlcLimitedControlsMessage } from './backend-install.js';
+import { resolveCommand } from './command.js';
 import { discoverAirPlayDevices } from './airplay-discovery.js';
 import { airPlaySenderHealth } from './airplay-sender-health.js';
 import { encodeWorkerStart, parseWorkerMessage, serializeWorkerMessage } from './airplay-worker-protocol.js';
@@ -167,6 +168,10 @@ export class PlayerController {
             this.playWithFfplay(url);
             await this.waitForReady(backend);
         }
+        else if (backend === 'vlc') {
+            this.playWithVlc(url);
+            await this.waitForReady(backend);
+        }
         this.setState({
             backend,
             state: 'playing',
@@ -300,6 +305,9 @@ export class PlayerController {
         if (preferred === 'ffplay') {
             return backends.includes('ffplay') ? 'ffplay' : null;
         }
+        if (preferred === 'vlc') {
+            return backends.includes('vlc') ? 'vlc' : null;
+        }
         if (preferred === 'airplay') {
             return backends.includes('airplay') ? 'airplay' : null;
         }
@@ -309,6 +317,9 @@ export class PlayerController {
         if (backends.includes('ffplay')) {
             return 'ffplay';
         }
+        if (backends.includes('vlc')) {
+            return 'vlc';
+        }
         return null;
     }
     playbackUnavailableMessage() {
@@ -324,7 +335,7 @@ export class PlayerController {
     playWithMpv(url, initialTitle) {
         this.ipcPath = createMpvIpcPath();
         this.currentMpvMediaTitle = cleanMediaTitle(initialTitle) ?? 'RadioCLI';
-        this.process = spawn('mpv', [
+        this.process = spawn(resolveCommand('mpv') ?? 'mpv', [
             '--no-video',
             '--really-quiet',
             '--force-window=no',
@@ -338,11 +349,19 @@ export class PlayerController {
         this.wireProcess();
     }
     playWithFfplay(url) {
-        this.process = spawn('ffplay', ['-nodisp', '-hide_banner', '-loglevel', 'error', '-volume', String(this.getSettings().volume), '-autoexit', url], {
+        this.process = spawn(resolveCommand('ffplay') ?? 'ffplay', ['-nodisp', '-hide_banner', '-loglevel', 'error', '-volume', String(this.getSettings().volume), '-autoexit', url], {
             stdio: ['pipe', 'pipe', 'pipe']
         });
         this.wireProcess();
     }
+    playWithVlc(url) {
+        // VLC ships a `cvlc` shim for headless playback; fall back to the main `vlc`
+        // binary (resolved from app bundles when off PATH) with a dummy interface.
+        const binary = resolveCommand('cvlc') ?? resolveCommand('vlc') ?? 'cvlc';
+        const gain = (clampVolume(this.getSettings().volume) / 100).toFixed(2);
+        this.process = spawn(binary, ['--intf', 'dummy', '--no-video', '--quiet', '--play-and-exit', `--gain=${gain}`, url], { stdio: ['pipe', 'pipe', 'pipe'] });
+        this.wireProcess();
+    }
     canRetuneAirPlay(device) {
         return Boolean(this.backend === 'airplay' &&
             this.process &&
@@ -555,6 +574,9 @@ export class PlayerController {
         if (this.backend === 'ffplay' && this.process) {
             return { ok: false, message: ffplayLimitedControlsMessage };
         }
+        if (this.backend === 'vlc' && this.process) {
+            return { ok: false, message: vlcLimitedControlsMessage };
+        }
         return null;
     }
     wireProcess() {
@@ -708,7 +730,7 @@ export class PlayerController {
             if (!this.process) {
                 throw new Error('Player exited before the stream became ready.');
             }
-            if (backend === 'ffplay') {
+            if (backend === 'ffplay' || backend === 'vlc') {
                 await waitForStartupWindow(() => this.process, Math.min(500, timeoutMs));
                 return;
             }

package/dist/providers/provider-manager.js

@@ -37,6 +37,9 @@ export class ProviderManager {
         }
         return this.radioBrowser.resolve(station);
     }
+    vote(station) {
+        return this.radioBrowser.vote(station);
+    }
     async health(settings) {
         const radioBrowser = await this.radioBrowser.health().catch(error => error instanceof Error ? error.message : 'unavailable');
         const radioGarden = settings.enableRadioGarden

package/dist/providers/radio-browser.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { ProviderCache } from './cache.js';
+import { userAgent } from '../version.js';
 const stationSchema = z.object({
     stationuuid: z.string(),
     name: z.string().default('Untitled station'),
@@ -164,13 +165,28 @@ export class RadioBrowserProvider {
         }
         return { url: result.url, name: result.name };
     }
+    // Give back to the directory: an upvote on favorite helps surface good
+    // stations for everyone. Radio Browser rate-limits votes per IP, so this is
+    // best-effort and never blocks the favorite action.
+    async vote(station) {
+        if (station.provider !== this.id) {
+            return false;
+        }
+        try {
+            const result = clickResolveSchema.parse(await this.request(`/json/vote/${encodeURIComponent(station.id)}`, {}, { timeoutMs: 5000 }));
+            return result.ok;
+        }
+        catch {
+            return false;
+        }
+    }
     async detectLocation() {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 5000);
         try {
             const response = await fetch('https://ipapi.co/json/', {
                 signal: controller.signal,
-                headers: { 'User-Agent': 'radiocli/0.1' }
+                headers: { 'User-Agent': userAgent() }
             });
             if (!response.ok) {
                 return null;
@@ -306,7 +322,7 @@ async function fetchWithTimeout(url, timeoutMs) {
         return await fetch(url, {
             signal: controller.signal,
             headers: {
-                'User-Agent': 'radiocli/0.1 (+https://radio-browser.info)',
+                'User-Agent': userAgent(' (+https://radio-browser.info)'),
                 Accept: 'application/json'
             }
         });

package/dist/storage/store.js

@@ -136,7 +136,7 @@ const settingsSchema = z.object({
     volume: z.number().min(0).max(100).default(70),
     enableRadioGarden: z.boolean().default(false),
     enableNearbyLocation: z.boolean().default(false),
-    preferredBackend: z.enum(['auto', 'mpv', 'ffplay', 'airplay']).default('auto'),
+    preferredBackend: z.enum(['auto', 'mpv', 'ffplay', 'vlc', 'airplay']).default('auto'),
     preferredAirPlayDevice: z.string().min(1).optional(),
     tuneTimeoutSeconds: z.number().min(3).max(45).default(12),
     skipBrokenStreams: z.boolean().default(true),
@@ -146,7 +146,11 @@ const settingsSchema = z.object({
         playPause: z.array(z.string()).default([]),
         next: z.array(z.string()).default([])
     })
-        .default(defaultMediaKeys)
+        .default(defaultMediaKeys),
+    resumeOnLaunch: z.boolean().default(false),
+    transparentBackground: z.boolean().default(false),
+    asciiMode: z.boolean().default(false),
+    reduceMotion: z.boolean().default(false)
 });
 const librarySchema = z.object({
     recent: z
@@ -157,6 +161,15 @@ const librarySchema = z.object({
         .default([]),
     favorites: z.array(stationSchema).default([]),
     imported: z.array(stationSchema).default([]),
+    trackHistory: z
+        .array(z.object({
+        title: z.string(),
+        stationKey: z.string(),
+        stationName: z.string(),
+        at: z.string()
+    }))
+        .default([]),
+    searchHistory: z.array(z.string()).default([]),
     activity: z
         .object({
         sessions: z
@@ -215,6 +228,39 @@ export class JsonLibraryStore {
         this.write();
         return this.snapshot();
     }
+    // Persist the ICY track titles a station announces so "what was that song?"
+    // is answerable later. Consecutive duplicates on the same station are skipped.
+    recordTrack(station, title) {
+        const cleaned = title.trim();
+        if (!cleaned) {
+            return this.snapshot();
+        }
+        const key = stationKey(station);
+        const last = this.state.trackHistory[0];
+        if (last && last.title === cleaned && last.stationKey === key) {
+            return this.snapshot();
+        }
+        const entry = {
+            title: cleaned,
+            stationKey: key,
+            stationName: station.name,
+            at: new Date().toISOString()
+        };
+        this.state = { ...this.state, trackHistory: [entry, ...this.state.trackHistory].slice(0, 100) };
+        this.write();
+        return this.snapshot();
+    }
+    // Most-recent-first search queries for up-arrow recall in the search box.
+    addSearch(query) {
+        const cleaned = query.trim();
+        if (!cleaned) {
+            return this.snapshot();
+        }
+        const searchHistory = [cleaned, ...this.state.searchHistory.filter(item => item !== cleaned)].slice(0, 30);
+        this.state = { ...this.state, searchHistory };
+        this.write();
+        return this.snapshot();
+    }
     startListeningSession(station, startedAt = new Date()) {
         this.finishActiveListeningSession(startedAt);
         const session = {
@@ -329,6 +375,8 @@ function defaultState() {
         recent: [],
         favorites: [],
         imported: [],
+        trackHistory: [],
+        searchHistory: [],
         activity: { sessions: [] },
         settings: {
             theme: 'green',