@ciphore/radiocli 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to RadioCLI are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2026-05-30
+## [0.1.1] - 2026-05-30
 
 Initial public release.
 
@@ -19,7 +19,7 @@ Initial public release.
   resolution, plus an experimental, opt-in Radio Garden provider.
 - `mpv` playback with `ffplay` fallback, readiness checks, ICY metadata polling,
   volume, pause, mute, sleep timer, tune timeouts, and skip-broken-stream
-  behavior.
+  behavior, using Unix sockets on macOS/Linux and named pipes on native Windows.
 - Receiver-style Now Playing screen with 50 selectable visualizers and
   zero-signal frames whenever playback is idle, paused, stopped, or not
   backend-ready.
@@ -34,7 +34,10 @@ Initial public release.
   streaks, active days, and total hours listened.
 - `radiocli doctor` to report local playback readiness and print OS-specific
   setup guidance.
-- Homebrew formula template for `brew install` distribution.
+- Published Homebrew tap formula for `brew install ciphore/tap/radiocli`.
+- Documented native Linux and Windows install paths, with `winget` guidance for
+  Node.js, `mpv`, and optional FFmpeg on Windows.
+- Documented pnpm and Bun as optional npm-package install clients.
 
 ### Changed
 
@@ -44,4 +47,4 @@ Initial public release.
   backend/volume that already appear in the header and footer. The reclaimed
   rows go to the visualizer.
 
-[0.1.0]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.0
+[0.1.1]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.1

package/CONTRIBUTING.md

@@ -18,7 +18,11 @@ Install `mpv` for the best playback experience:
 brew install mpv
 ```
 
-On Linux, use your package manager's `mpv` package.
+On Linux, use your package manager's `mpv` package. On Windows, use:
+
+```powershell
+winget install --id shinchiro.mpv -e
+```
 
 ## Verification
 

package/README.md

@@ -1,3 +1,5 @@
+![RadioCLI Now Playing visualizer demo](apps/docs/public/demo/radiocli-now-playing.gif)
+
 # RadioCLI
 
 [![CI](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml/badge.svg)](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml)
@@ -24,6 +26,32 @@ It is built with [Ink](https://github.com/vadimdemedes/ink), [React](https://rea
 - Survive ordinary internet-radio failure modes with provider mirror fallback, stale cache fallback, corrupt-file backups, tune timeouts, and skip-broken-stream behavior.
 - Resize with the terminal. The app listens for terminal resize events and recomputes list row counts, map density, receiver width, and compact-mode fallback from the current dimensions.
 
+## Visual Tour
+
+The GIFs below are recorded from the real built TUI with `npm run demo:assets`.
+The top GIF cycles multiple Now Playing receiver styles and display colors while
+a real stream is playing through `mpv`.
+
+### Library: Favorites And Recents
+
+![RadioCLI library showing favorites and recent stations](apps/docs/public/demo/radiocli-library.gif)
+
+### Explore: World Map Discovery
+
+![RadioCLI Explore world map with nearby station results](apps/docs/public/demo/radiocli-explore-map.gif)
+
+### Search: Query Public Station Directories
+
+![RadioCLI search results for tokyo jazz](apps/docs/public/demo/radiocli-search.gif)
+
+### Nearby: Opt-In Local Stations
+
+![RadioCLI Nearby station list](apps/docs/public/demo/radiocli-nearby.gif)
+
+### Stats: Listening History And Display Colors
+
+![RadioCLI stats screen cycling display colors](apps/docs/public/demo/radiocli-stats-colors.gif)
+
 ## Demo
 
 The interactive TUI opens directly into the product, not a marketing screen:
@@ -109,29 +137,34 @@ Set `NEXT_PUBLIC_SITE_URL` for the canonical public docs URL. Preview builds als
 
 Requirements:
 
-- Node.js 22 or newer
+- Homebrew on macOS: installs RadioCLI, Node.js, and `mpv`
+- npm on macOS, Linux, and Windows: Node.js 22 or newer
 - `mpv` for best playback; RadioCLI expects one local playback backend at runtime
 - `ffplay` from FFmpeg as an optional fallback
 
-NPM installs RadioCLI and its JavaScript dependencies. It does not install native
-system playback tools. Use `radiocli doctor` after installation to check local
-playback readiness and get the right setup command for your OS:
+Recommended macOS install:
 
 ```bash
-npm install -g @ciphore/radiocli
-radiocli doctor
+brew install ciphore/tap/radiocli
 radiocli
 ```
 
-macOS with npm:
+The Homebrew formula depends on `node` and `mpv`, so the native playback backend
+comes from the native package manager.
+
+Universal npm install:
 
 ```bash
-brew install mpv
 npm install -g @ciphore/radiocli
+radiocli doctor
 radiocli
 ```
 
-Linux with npm:
+The npm package is `@ciphore/radiocli`, and the installed executable is
+`radiocli`. npm installs RadioCLI and its JavaScript dependencies only; it does
+not install system playback tools.
+
+Debian/Ubuntu:
 
 ```bash
 sudo apt install mpv
@@ -139,25 +172,39 @@ npm install -g @ciphore/radiocli
 radiocli
 ```
 
-`ffplay` is optional fallback support. Install FFmpeg separately if you want it:
+Fedora, Arch, Alpine, and openSUSE users can install the distro `mpv` package
+first, then install `@ciphore/radiocli` with npm.
+
+Native Windows with Windows Terminal or PowerShell:
+
+```powershell
+winget install --id OpenJS.NodeJS.LTS -e
+winget install --id shinchiro.mpv -e
+npm install -g @ciphore/radiocli
+radiocli doctor
+radiocli
+```
+
+Scoop users can use `scoop bucket add extras` and `scoop install mpv` instead
+of the `winget` mpv command. WSL remains supported through the Linux path.
+
+Optional `ffplay` fallback support:
+
+macOS/Linux:
 
 ```bash
 brew install ffmpeg        # macOS
 sudo apt install ffmpeg    # Debian/Ubuntu
 ```
 
-The repo also includes a Homebrew formula template in `packaging/homebrew` for a
-native one-command macOS tap. Once the tap formula is published, the intended
-Homebrew install path is:
+Windows:
 
-```bash
-brew install ciphore/tap/radiocli
+```powershell
+winget install --id Gyan.FFmpeg -e
 ```
 
-That formula depends on `node` and `mpv`, keeping native dependencies in the
-native package manager instead of running system installs from npm.
-
-CI covers command-mode typecheck, tests, builds, and package checks on Ubuntu. Native Windows terminals are not release-tested yet; use WSL with Linux `mpv` / `ffplay` for the supported path.
+CI covers command-mode typecheck, tests, builds, package checks, and fresh
+install smoke checks on Ubuntu, macOS, and Windows.
 
 Local checkout:
 
@@ -288,9 +335,57 @@ RadioCLI is split around four seams:
 - playback lifecycle and metadata in `src/player`
 - local JSON persistence in `src/storage`
 
+### Audio Pipeline
+
+Station lists keep provider metadata and a resolvable stream URL. When you tune
+a station, `ProviderManager.resolve()` follows the provider-specific path, then
+`PlayerController` starts `mpv` with `--no-video`, `--force-window=no`, a local
+JSON IPC endpoint, and the configured volume. The endpoint is a Unix socket on
+macOS/Linux and a named pipe on native Windows. `ffplay` is available as a
+simpler fallback, but `mpv` is the intended backend because it handles
+redirects, HLS, codecs, metadata, pause, mute, volume, and readiness checks more
+reliably than a JavaScript stream client.
+
+RadioCLI waits for the backend to become ready before marking playback as
+`playing`. With `mpv`, it polls playback state every 500ms and ICY metadata every
+2.5s, then cleans the metadata before showing it in the receiver and live footer.
+
+### FFT Processing
+
+RadioCLI does not currently tap decoded PCM audio or run a real FFT in the Node
+process. The receiver visuals are procedural signal displays driven by playback
+truth, the selected style, terminal dimensions, theme, and a small `pulse`
+counter. That keeps the TUI lightweight and avoids duplicating audio decoding
+work already handled by `mpv`. The spectrum-like modes are generated from
+deterministic samples, so they should be read as receiver visualizers rather than
+measurement-grade audio analysis.
+
+### Terminal Rendering And Refresh Rate
+
+Ink renders React components into ANSI terminal frames. The app recomputes a
+terminal layout from the current row/column size, then each screen gets stable
+row budgets for station lists, the map, receiver panels, and the adaptive
+footer. Visualizers return text rows or colored text segments; the Now Playing
+screen frames those rows inside the receiver panel.
+
+Live receiver animation advances every 80ms, about 12.5 frames per second, only
+on the Now Playing screen while playback is `playing` and backend-ready.
+Ambient/idle-style animation uses a slower 140ms interval, and the loading
+spinner uses 120ms. Inactive playback states render zero-signal frames instead
+of animating.
+
+### CPU Usage
+
+CPU cost is intentionally bounded: audio decode stays in the native backend,
+there is no JavaScript FFT worker, metadata polling is infrequent, and the pulse
+timer does not run outside live Now Playing. In practice the terminal renderer
+does string and color-segment generation for the current screen only; `mpv` does
+the stream work, and idle/library/search/map screens do not pay the visualizer
+animation cost.
+
 Radio Browser is the primary provider. Its own docs recommend using a speaking user agent, resolving station clicks through `/json/url`, and retrying with other servers when one fails; RadioCLI follows that shape with mirror fallback and durable cache. Explore and Nearby use a cached geotagged Radio Browser atlas, then compute local distance in the app so map movement is not biased toward the most-clicked stations worldwide. Radio Garden support is experimental because the useful endpoints are publicly discoverable but unofficial, and they can be blocked or changed independently of this project.
 
-Playback prefers `mpv` because it handles real-world streams, redirects, HLS, codecs, and metadata better than a hand-rolled stream client. RadioCLI controls `mpv` through JSON IPC for readiness, pause, mute, volume, and metadata polling.
+Playback prefers `mpv` because it handles real-world streams, redirects, HLS, codecs, and metadata better than a hand-rolled stream client. RadioCLI controls `mpv` through JSON IPC for readiness, pause, mute, volume, and metadata polling, using Unix sockets on macOS/Linux and named pipes on Windows.
 
 The npm package is `@ciphore/radiocli`, and the installed executable is `radiocli`. Current installs store data under RadioCLI paths such as `radiocli.json` and `radiocli-cache.json`. Existing Radio Atlas data is still discovered when a new RadioCLI store does not exist, and legacy `RADIO_ATLAS_HOME` / animation environment variables remain supported as migration fallbacks. New automation should use `RADIOCLI_HOME` and `RADIOCLI_DISABLE_ANIMATION`.
 

package/dist/player/backend-install.js

@@ -39,7 +39,7 @@ export function mpvInstallCommand(platform = process.platform, osRelease = readL
         return 'brew install mpv';
     }
     if (platform === 'win32') {
-        return 'use WSL with sudo apt install mpv, or install mpv from https://mpv.io/installation/';
+        return 'winget install --id shinchiro.mpv -e';
     }
     if (platform !== 'linux') {
         return 'install mpv with your system package manager';
@@ -67,7 +67,7 @@ function ffplayInstallCommand(platform = process.platform, osRelease = readLinux
         return 'brew install ffmpeg';
     }
     if (platform === 'win32') {
-        return 'use WSL with sudo apt install ffmpeg, or install FFmpeg from https://ffmpeg.org/download.html';
+        return 'winget install --id Gyan.FFmpeg -e';
     }
     if (platform !== 'linux') {
         return 'install FFmpeg with your system package manager';

package/dist/player/player-controller.js

@@ -169,7 +169,7 @@ export class PlayerController {
         return null;
     }
     playWithMpv(url, initialTitle) {
-        this.ipcPath = join(tmpdir(), `radiocli-${process.pid}-${Date.now()}.sock`);
+        this.ipcPath = createMpvIpcPath();
         this.currentMpvMediaTitle = cleanMediaTitle(initialTitle) ?? 'RadioCLI';
         this.process = spawn('mpv', [
             '--no-video',
@@ -296,7 +296,7 @@ export class PlayerController {
                 await waitForStartupWindow(() => this.process, Math.min(500, timeoutMs));
                 return;
             }
-            if (this.ipcPath && existsSync(this.ipcPath)) {
+            if (this.ipcPath) {
                 try {
                     await this.queryMpv({ command: ['get_property', 'path'] });
                     return;
@@ -374,7 +374,7 @@ export class PlayerController {
         }
     }
     cleanupIpc() {
-        if (this.ipcPath && existsSync(this.ipcPath)) {
+        if (this.ipcPath && !isWindowsNamedPipePath(this.ipcPath) && existsSync(this.ipcPath)) {
             try {
                 unlinkSync(this.ipcPath);
             }
@@ -392,6 +392,15 @@ export class PlayerController {
         }
     }
 }
+export function createMpvIpcPath(platform = process.platform, pid = process.pid, timestamp = Date.now()) {
+    if (platform === 'win32') {
+        return `\\\\.\\pipe\\radiocli-${pid}-${timestamp}`;
+    }
+    return join(tmpdir(), `radiocli-${pid}-${timestamp}.sock`);
+}
+function isWindowsNamedPipePath(path) {
+    return path.startsWith('\\\\.\\pipe\\');
+}
 function clampVolume(volume) {
     return Math.min(100, Math.max(0, Math.round(volume)));
 }

package/dist/ui/screens/StatsScreen.js

@@ -35,7 +35,8 @@ function buildContributionGraph(days, width) {
         cells: weeks.map(week => {
             const day = week[dayIndex];
             const level = contributionLevel(day?.seconds ?? 0, maxSeconds);
-            return { key: day?.date ?? `${week[0]?.date ?? 'empty'}-${dayIndex}`, level, text: '█'.repeat(cellWidth) };
+            const text = cellWidth > 1 ? `${'█'.repeat(cellWidth - 1)} ` : '█';
+            return { key: day?.date ?? `${week[0]?.date ?? 'empty'}-${dayIndex}`, level, text };
         })
     }));
     return { months: monthLine(weeks, cellWidth), rows };

package/dist/ui/theme.js

@@ -54,46 +54,47 @@ export function themeAccent(theme) {
     return '#74f28a';
 }
 export function themeContributionColors(theme) {
+    const emptyContribution = '#1c1c1c';
     if (theme === 'amber') {
-        return ['#161b22', '#5f3700', '#9a6200', '#d68a00', '#ffb000'];
+        return [emptyContribution, '#5f3700', '#9a6200', '#d68a00', '#ffb000'];
     }
     if (theme === 'blue') {
-        return ['#161b22', '#12385f', '#1f6feb', '#3388dd', '#53a8ff'];
+        return [emptyContribution, '#12385f', '#1f6feb', '#3388dd', '#53a8ff'];
     }
     if (theme === 'ruby') {
-        return ['#161b22', '#4c1230', '#8f274f', '#c93f68', '#ff5f87'];
+        return [emptyContribution, '#4c1230', '#8f274f', '#c93f68', '#ff5f87'];
     }
     if (theme === 'ice') {
-        return ['#161b22', '#24474d', '#4a95a0', '#86dce8', '#b9f6ff'];
+        return [emptyContribution, '#24474d', '#4a95a0', '#86dce8', '#b9f6ff'];
     }
     if (theme === 'teal') {
-        return ['#161b22', '#123f3c', '#1f766c', '#2dd4bf', '#5eead4'];
+        return [emptyContribution, '#123f3c', '#1f766c', '#2dd4bf', '#5eead4'];
     }
     if (theme === 'violet') {
-        return ['#161b22', '#302047', '#5b3f8f', '#7c5cff', '#a78bfa'];
+        return [emptyContribution, '#302047', '#5b3f8f', '#7c5cff', '#a78bfa'];
     }
     if (theme === 'copper') {
-        return ['#161b22', '#44281f', '#7f4f37', '#b86f52', '#d08770'];
+        return [emptyContribution, '#44281f', '#7f4f37', '#b86f52', '#d08770'];
     }
     if (theme === 'cyan') {
-        return ['#161b22', '#0e3b42', '#168a9e', '#22b8cf', '#22d3ee'];
+        return [emptyContribution, '#0e3b42', '#168a9e', '#22b8cf', '#22d3ee'];
     }
     if (theme === 'lime') {
-        return ['#161b22', '#2f3d12', '#5f7d1f', '#84b32b', '#a3e635'];
+        return [emptyContribution, '#2f3d12', '#5f7d1f', '#84b32b', '#a3e635'];
     }
     if (theme === 'coral') {
-        return ['#161b22', '#4c2018', '#9a4032', '#d65c49', '#ff7e6b'];
+        return [emptyContribution, '#4c2018', '#9a4032', '#d65c49', '#ff7e6b'];
     }
     if (theme === 'rose') {
-        return ['#161b22', '#4c2238', '#8f3f6a', '#d65c9a', '#ff8fc7'];
+        return [emptyContribution, '#4c2238', '#8f3f6a', '#d65c9a', '#ff8fc7'];
     }
     if (theme === 'slate') {
-        return ['#161b22', '#2a3340', '#4f6178', '#7c91ab', '#9fb4cf'];
+        return [emptyContribution, '#2a3340', '#4f6178', '#7c91ab', '#9fb4cf'];
     }
     if (theme === 'mono') {
-        return ['#161b22', '#3a3a3a', '#767676', '#b0b0b0', '#d0d0d0'];
+        return [emptyContribution, '#3a3a3a', '#767676', '#b0b0b0', '#d0d0d0'];
     }
-    return ['#161b22', '#0e4429', '#26a641', '#39d353', '#74f28a'];
+    return [emptyContribution, '#0e4429', '#26a641', '#39d353', '#74f28a'];
 }
 export function nextTheme(theme) {
     const index = themeNames.indexOf(theme);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciphore/radiocli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A terminal-first world radio receiver built with Ink, mpv, and resilient public-radio providers.",
   "type": "module",
   "license": "MIT",
@@ -61,6 +61,7 @@
     "smoke:data": "tsx src/smoke/data-smoke.ts",
     "smoke:playback": "tsx src/smoke/playback-smoke.ts",
     "demo:script": "node scripts/demo-script.mjs",
+    "demo:assets": "node scripts/capture-demo-assets.mjs",
     "fresh:check": "node scripts/fresh-check.mjs"
   },
   "dependencies": {