# Changelog (/docs/changelog) 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.2.3 - 2026-09-07 [#023---2026-09-07] ### Added [#added] * Added opt-in local coding-agent control through both a typed stdio MCP server and `radiocli agent` shell commands, covering discovery, playback, favorites, listening stats, appearance, and configurable task-completion actions. * Added automatic MCP setup for detected Codex, Claude Code, OpenCode, Cursor, Gemini CLI, VS Code/Copilot Agent Host, and Orca-backed runtimes, plus a portable configuration for other MCP clients. * Added typed MCP and voice-accessible alarm management, active ringing controls, and macOS AirPlay discovery, receiver selection, local-output switching, and ephemeral passcode submission. * Added `radiocli update --install`, package-manager-aware upgrade commands, an in-app update indicator, read-only MCP update status, and `radiocli mcp repair`. * Added Agent settings for installing or repairing MCP integrations and choosing between a visible terminal player and headless playback. * Added the animated Gallop receiver as the new default and a color-field Crossfade receiver. ### Fixed [#fixed] * Agent playback continues to open the terminal TUI by default on every platform, while interactive setup now explains the macOS Automation prompt and offers an explicit headless opt-out. MCP guidance prevents ordinary task-completion radio actions from creating implicit goals or monitors. * MCP registrations now use upgrade-stable, directly executable launchers, including a shell-free Node command on Windows, and enabled registrations are repaired after an in-app or CLI update. * Active interactive or agent playback now yields cleanly when an alarm begins, preventing overlapping streams while preserving the alarm if TUI handoff fails. * Kept the Countries station-count column fixed while scrolling, added focused marquee reading for overlong country and station names across Explore, Library, and Nearby, and aligned Overview descriptions behind a compact separator-free title column. ### Security [#security] * Agent playback uses a single-owner, authenticated loopback session with serialized commands, private discovery files, and strict isolation from active alarm sessions. Agent tools accept saved or RadioCLI-discovered station IDs rather than arbitrary stream URLs. * Alarm removal requires an exact ID and explicit confirmation. AirPlay receiver IDs must come from local discovery, and receiver passcodes are never persisted or echoed by agent responses. ## 0.2.2 - 2026-09-04 [#022---2026-09-04] ### Added [#added-1] * Added one-time and IANA-timezone recurring radio alarms under Overview, with a full-screen TUI editor, station picker, next-run preview, enable/disable, delete confirmation, test tune, repair, and active ringing controls. * Added native background registration through macOS launchd, Windows Task Scheduler, and systemd user timers on Linux, plus `radiocli alarm` commands for scripting, inspection, health checks, synchronization, and playback control. * Added optional per-alarm wake requests where the OS supports them and a separate cross-platform Alarm Guard that prevents idle sleep until the next occurrence. * Added automatic ringing-control launch in the terminal captured when an alarm is synchronized, with reuse of an already-running RadioCLI TUI. * Added a navigable **Verify alarm setup** rehearsal that exercises a disposable native job, the saved terminal, authenticated controls, sleep protection, system volume, and a three-second configured-station sample before cleanup. * Added `radiocli setup`, an interactive installer that detects supported package managers, previews required playback tools, supports dry runs, guides installation, and verifies the resulting local playback configuration. * Added an adaptive Explore experience with a responsive Cosmo world map, height-aware station lists in micro terminals, pointer-accurate map selection, and safe scrolling marquees for long station details. * Added richer `radiocli doctor` playback diagnostics, including the resolved mpv path, discovery source, launchability, version output, and actionable launch errors. Windows discovery now covers package-manager shims, common application directories, and registered mpv installations. ### Changed [#changed] * Full library backup and restore now carries alarm definitions and latest run outcomes; native jobs, Alarm Guard state, runtime health, and local control credentials remain specific to each machine and are rebuilt by alarm synchronization. * macOS terminal Automation permission is requested during alarm setup, and a TUI opened by a ringing alarm now protects the active native job from startup, repair, edit, and delete reconciliation until playback ends. * Snooze now closes the completed ringing session, returns to Alarms, and shows the next ring time. Alarm playback temporarily unmutes and raises a low local system output to the configured alarm level on macOS, Windows, and supported Linux audio stacks, restoring the previous state afterward. * Alarm list and editor presentation is more concise: historical dismissal text, duplicated controls, and long scheduler caveats were removed; specific field guidance is now inline and Save is presented as a display-color action. * Alarm ringing controls now use Enter to transfer the station into normal interactive playback and Space to stop and snooze for ten minutes. The alarm UI and documentation identify scheduling as experimental beta functionality, explain when the terminal may close, and recommend a secondary device for critical wake-ups. * Playback-backend guidance now directs users to `radiocli setup` when local tools are missing, with updated CLI help, setup documentation, and status messages covering the guided workflow. * Receiver animation updates are isolated from the rest of the application, respect reduced-motion preferences, and use cached visualizer geometry and compact color runs to reduce rendering work without changing visual output. * Radio Browser requests now use atlas-aware timeouts and retain clearer provider failure details when station directories are slow or unavailable. ### Fixed [#fixed-1] * Alarm lists now scroll long text only on the focused interactive row, keep selection and enabled-state markers fixed, and avoid repeating station and next-run details. Compact and micro layouts use shorter next-wake, scheduler, and beta-safety messages instead of clipping desktop-length copy. * Footer shortcut legends now balance actions across every available row, reserve an additional row in compact terminals when space permits, and show concise key-only hints in micro layouts instead of ending in truncated text. The version and update indicator remains independently anchored at bottom right. * Rapid keyboard and mouse-wheel navigation now commits the selected row immediately, cancels pending automatic station skips, and preserves alarm editor scrolling; search input keeps ownership of typed alarm-shortcut characters. * Player shutdown now coalesces concurrent stop requests, while delayed automatic skipping can be canceled during retuning to avoid duplicate process termination and unintended station changes. * Explore maps, station lists, and screen rendering now remain aligned and navigable across compact and true-micro terminal sizes, with improved map centering, cursor mapping, and visible provider errors. ### Security [#security-1] * Active alarm controls and Alarm Guard ownership checks use authenticated loopback-only endpoints with machine-local private token files. ## 0.2.1 - 2026-08-22 [#021---2026-08-22] ### Added [#added-2] * Added compact and micro layouts that keep every screen navigable in small terminal windows, including responsive Now Playing visualizers and settings. * Added complete library backup and restore from Settings or the `:export` and `:import` commands, with validation and an automatic safety copy before an existing library is replaced. * Expanded the receiver collection to 60 styles, including Sumi Ocean, Liftoff, Planetarium, Skyline, Golden Gate, Alpine, and other scenic displays. ### Changed [#changed-1] * Anchored the gapless square-cell listening activity grid to January, made Ultracode the default receiver, and grouped the 60 retained styles by visual family. Retired TV Static, Sunspot, Plasma, Metaballs, and Moonlit Tide with safe preference migration; rebuilt Fire and Stormfront; and replaced Sumi Mountains with the layered blue Sumi Ocean. * Reorganized Settings into labeled, paginated sections and tightened the full layout so the Now Playing receiver and footer use the available space more consistently. * Reworked mpv communication around one reusable IPC connection, keeping rapid volume changes responsive while preserving the last confirmed player state when a command fails. ### Fixed [#fixed-2] * Restored mouse and trackpad wheel navigation for overflowing menus and lists while keeping mouse reporting screen-aware so native terminal scrollback stays available elsewhere. Added a Settings opt-out and legacy X10 mouse fallback. * Protected library and cache writes from concurrent RadioCLI processes, and recovered unfinished listening sessions from their last saved heartbeat. * Made Radio Browser searches and cached station lists more resilient to slow, stale, or partially unavailable directory mirrors. * Added a second-press confirmation for `q` and `Ctrl+C` so an accidental key press does not stop playback and exit. ### Security [#security-2] * Sanitized terminal control and bidirectional text sequences from external station data, and tightened permissions on locally stored library files. ## 0.2.0 - 2026-07-08 [#020---2026-07-08] ### Added [#added-3] * Added update checks for npm releases, including a `radiocli update` command, a `:update` command, and a Settings entry that reports the latest available version and copies or runs the right npm or Homebrew update command. * Added lazy loading for long country station lists and search results, so deeper directories continue loading as you scroll instead of stopping at the first page. * Added mouse wheel scrolling across station, country, map, nearby, explore, search, and library lists. ### Changed [#changed-2] * The footer now shows the installed RadioCLI version, and Settings includes the current version beside update status. * Retuning now keeps the playback footer focused on the station currently buffering, and mpv playback stays in loading until audio has actually started. ## 0.1.9 - 2026-07-03 [#019---2026-07-03] ### Changed [#changed-3] * Nearby station discovery is now enabled by default for new libraries, and the `l` shortcut is limited to Overview, Nearby, and Settings so country lists keep normal letter navigation. * Favorite changes from Library now appear in the footer message row instead of displacing the main page status. * The listening stats activity graph now uses solid truecolor cell backgrounds with tighter rendering on short terminals and fewer split color runs. ### Fixed [#fixed-3] * Nearby keeps showing the last loaded station list when location lookup is turned off or temporarily unavailable. * Long country names are truncated to one terminal row so dense country lists do not wrap into nearby entries. * Pressing `b` from a country station list now returns to Countries before falling back to Overview. ## 0.1.8 - 2026-07-02 [#018---2026-07-02] ### Changed [#changed-4] * Replaced the classic equalizer receiver style with Ultracode, a centered color-ripple display that follows the active display color; saved `equalizer` preferences migrate to `ultracode`. * The listening stats activity graph now renders as a calendar-year grid with larger contribution cells and clearer month labels when the terminal has room. * Muted UI text now uses truecolor neutrals instead of terminal `gray`, making secondary labels more readable across dark terminal palettes. ### Fixed [#fixed-4] * Stale continuous listening sessions are capped before splitting them across days so one long-unclosed playback session cannot dominate listening totals. * Receiver visualizer pulses now reset when an active Ultracode view opens but keep advancing smoothly during normal playback. ## 0.1.7 - 2026-06-29 [#017---2026-06-29] ### Changed [#changed-5] * 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 [#016---2026-06-17] ### Added [#added-4] * 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 [#changed-6] * 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 [#015---2026-05-31] ### Fixed [#fixed-5] * Moved the macOS AirPlay sender bridge to optional npm dependencies so Windows and Linux installs do not fail while compiling an AirPlay-only native module. ## 0.1.4 - 2026-05-31 [#014---2026-05-31] ### Added [#added-5] * Added a dedicated AirPlay receiver picker and AirPlay Code screen for passcode-protected receivers. ### Changed [#changed-7] * Replaced silent AirPlay target cycling with a dedicated receiver picker in Settings, clearer Audio output labels, immediate output switching while a station is playing, and explicit AirPlay receiver selection before tuning. * AirPlay is now an explicit current-session output instead of a persisted default. Restarting RadioCLI returns to automatic local playback while keeping the last receiver available for the next manual AirPlay switch. * Bundled the AirPlay sender bridge and updated the Homebrew formula template to install FFmpeg, so macOS users do not need manual AirPlay package setup. ### Fixed [#fixed-6] * Fixed same-session AirPlay station switching so the worker retunes the active receiver, resets its sender buffer, and keeps the UI in buffering until the new stream is actually ready. * Fixed AirPlay output failures so `skip broken streams` no longer walks through the library when the receiver is missing, off, local, or unavailable. * Fixed library selection after playing a station that moves to the top of recents. * Patched the bundled AirPlay sender for modern macOS AirPlay 2 receivers that return digest-protected setup responses or empty first setup bodies. ## 0.1.3 - 2026-05-30 [#013---2026-05-30] ### Added [#added-6] * Experimental macOS AirPlay playback backend with Bonjour receiver discovery, Settings target selection, `:airplay-code` passcode entry, worker-based stream forwarding, and active receiver labels in the playback footer. ### Changed [#changed-8] * `ffplay` is now treated as a playback-only fallback: the UI labels it as `ffplay fallback`, `radiocli doctor` reports limited controls, and unsupported pause, mute, volume, and media-key actions explain that `mpv` is required. ### Security [#security-3] * AirPlay sender support is worker-isolated and blocks high-risk sender dependency advisories before the backend is advertised. * Hardened AirPlay discovery and worker messaging with bounded payloads, sanitized receiver data, passcode validation, and worker shutdown on startup timeout. ## 0.1.2 - 2026-05-30 [#012---2026-05-30] ### Fixed [#fixed-7] * Ignored Kitty keyboard release events so Ghostty users do not skip multiple tabs from one left/right arrow key press. * Ignored Kitty release events for raw media-key transport sequences so learned or native media keys do not double-fire on key release. ## 0.1.1 - 2026-05-30 [#011---2026-05-30] Initial public release. ### Added [#added-7] * A square braille spinner animates to the left of the station name in the live playback footer while a station is buffering. * Ink-based terminal UI with overview, now playing, library, explore, search, countries, world map, nearby, stats, and settings screens. * Radio Browser provider with mirror fallback, durable cache, and tune resolution, plus an experimental, opt-in Radio Garden provider. * `mpv` playback controls for readiness checks, ICY metadata polling, volume, pause, and mute, with `ffplay` playback fallback, sleep timer, tune timeouts, and skip-broken-stream 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. * Explore map: a braille world map beside the live station list with WASD movement, click-to-place mouse support, and a cached geotagged station atlas ranked by distance. * Local-first library: recents, favorites, imports, listening activity, settings, learned media keys, and provider cache stored as JSON on your machine. * Playlist import/export for `.m3u`, `.pls`, and `.xspf`. * Listening stats with a 52-week local-calendar contribution graph, sessions, streaks, active days, and total hours listened. * `radiocli doctor` to report local playback readiness and print OS-specific setup guidance. * 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 [#changed-9] * Tightened the Now Playing panel below the receiver: collapsed the stream tech/tags, track metadata, and backend/volume rows into two compact lines so more room goes to the visualizer.