@ciphore/radiocli 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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).
 
+## [Unreleased]
+
+## [0.1.5] - 2026-05-31
+
+### Fixed
+
+- 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
+
+### Added
+
+- Added a dedicated AirPlay receiver picker and AirPlay Code screen for
+  passcode-protected receivers.
+
+### Changed
+
+- 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 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
 
 ### Added
@@ -21,9 +60,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
-- AirPlay sender support is disabled unless a compatible sender package passes
-  RadioCLI's dependency safety gate; the current public `node-airtunes2` package
-  line remains blocked because of vulnerable transitive dependencies.
+- 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.
@@ -80,6 +118,8 @@ Initial public release.
   backend/volume that already appear in the header and footer. The reclaimed
   rows go to the visualizer.
 
+[0.1.5]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.5
+[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
 [0.1.1]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.1

package/README.md

@@ -70,7 +70,7 @@ Live public radio from around the world
   5 Countries · Browse by country list with a world-map toggle
   6 Nearby · Opt-in approximate location for local stations
   7 Stats · Listening graph, sessions, streaks, hours
-  8 Settings · Playback backend, colors, providers
+  8 Settings · Audio output, colors, providers
 
 3 recent · 2 favorites · 1 imported
 
@@ -137,10 +137,10 @@ Set `NEXT_PUBLIC_SITE_URL` for the canonical public docs URL. Preview builds als
 
 Requirements:
 
-- Homebrew on macOS: installs RadioCLI, Node.js, and `mpv`
+- Homebrew on macOS: installs RadioCLI, Node.js, `mpv`, and FFmpeg
 - npm on macOS, Linux, and Windows: Node.js 22 or newer
 - `mpv` for playback, pause, mute, volume, media keys, metadata, and readiness checks
-- `ffmpeg` plus an audited, compatible sender package on macOS for experimental AirPlay
+- FFmpeg on macOS for experimental AirPlay and optional `ffplay` fallback
 - `ffplay` from FFmpeg as an optional playback-only fallback
 
 Recommended macOS install:
@@ -150,24 +150,12 @@ brew install ciphore/tap/radiocli
 radiocli
 ```
 
-The Homebrew formula depends on `node` and `mpv`, so the native playback backend
-comes from the native package manager.
+The Homebrew formula depends on `node`, `mpv`, and FFmpeg, so the native playback
+and AirPlay prerequisites come from the native package manager.
 
-AirPlay playback on macOS is experimental. RadioCLI discovers AirPlay/RAOP
-receivers with Bonjour and decodes streams with `ffmpeg`, but it only advertises
-the `airplay` backend when a compatible sender package passes its dependency
-safety gate.
-
-```bash
-brew install ffmpeg
-npm audit --audit-level=low
-```
-
-Do not install `node-airtunes2` blindly just to enable this feature: the current
-public package line is blocked by RadioCLI because its transitive dependency tree
-contains known vulnerable versions. If you supply a patched compatible sender,
-passcode-protected receivers prompt in the TUI; enter the code with
-`:airplay-code 1234`.
+AirPlay playback on macOS is experimental, but the sender bridge is bundled with
+RadioCLI. The app discovers AirPlay/RAOP receivers with Bonjour and decodes
+streams with FFmpeg; passcode-protected receivers prompt in the TUI.
 
 Universal npm install:
 
@@ -296,7 +284,9 @@ Page-specific footer controls:
 | World map | `/` filter, `↑` / `↓` move, `Enter` open country, `w` list, `b` home |
 | Station lists | `↑` / `↓` or `n` / `p` move, `Enter` tune, `f` favorite, `[` / `]` page, `b` home |
 | Now Playing | `space` / `F8` pause, `f` favorite, `m` mute, `s` sleep, `d` diagnostics, `b` home |
-| Settings | `Enter` change selected, `g` Radio Garden, `l` location, `x` skip broken streams, `o` backend, `a` AirPlay, `r` health, `b` home |
+| Settings | `Enter` change selected, `g` Radio Garden, `l` location, `x` skip broken streams, `o` audio output, `a` AirPlay, `r` health, `b` home |
+| AirPlay | `↑` / `↓` choose, `Enter` select receiver, `c` code entry, `r` refresh, `b` settings |
+| AirPlay Code | type receiver code, `Backspace` edit, `Enter` submit, `Esc` AirPlay |
 | Stats | `b` home |
 
 Other active shortcuts:
@@ -306,7 +296,7 @@ Other active shortcuts:
 - `/`: edit search or country filter on screens that support it.
 - `[` / `]`: page through long station and country lists.
 - `m`: mute.
-- `o`: cycle playback backend.
+- `o`: cycle audio output. If a station is playing, RadioCLI retunes it on the new output immediately.
 - `g`: toggle the experimental Radio Garden adapter.
 - `l`: toggle nearby location lookup.
 - `x`: toggle skip-broken-stream behavior.
@@ -344,6 +334,7 @@ Useful command palette entries:
 :learn play
 :learn next
 :keys reset
+:airplay
 :airplay-code 1234
 :map
 :library
@@ -354,10 +345,15 @@ Useful command palette entries:
 
 Settings persist display colors and receiver styles without editing config files. The fourteen display colors are green, amber, blue, ruby, ice, teal, violet, copper, cyan, lime, coral, rose, slate, and mono, cycled with `t`. The 50 receiver styles span classic receiver displays, high-resolution braille visuals, and generative motion scenes; cycle them with `v` (see the [Demo](#demo) for the full family breakdown). The stats graph and legend follow the selected display color, and the selected Now Playing style is restored on the next launch.
 
-On macOS, Settings can cycle AirPlay targets discovered through Bonjour when
-`ffmpeg` and a compatible sender package pass RadioCLI's dependency safety gate.
-Select the `airplay` backend with `o`, choose a receiver with `a`, then tune a
-station. If the receiver asks for a code, enter it with `:airplay-code 1234`.
+On macOS, Settings opens a dedicated AirPlay receiver picker for Bonjour
+receivers. Change Audio output to AirPlay with `o`, open AirPlay with `a` or
+`:airplay`, and choose a visible receiver. If a station is already playing,
+RadioCLI moves it to the selected receiver immediately; switch Audio output back
+to `This device (mpv)` to leave AirPlay. RadioCLI does not auto-pick a receiver.
+AirPlay is a current-session output: restarting RadioCLI returns to automatic
+local playback while remembering the last receiver for the next manual switch.
+If the receiver asks for a code, RadioCLI opens the AirPlay Code screen; you can
+also press `c` from AirPlay settings or use `:airplay-code 1234`.
 
 ## Architecture
 
@@ -418,7 +414,7 @@ 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, using Unix sockets on macOS/Linux and named pipes on Windows. `ffplay` remains a playback-only fallback and is intentionally labeled with limited controls in the UI and doctor output. Experimental AirPlay output is available on macOS only when Bonjour discovery, `ffmpeg`, and a compatible sender package pass RadioCLI's safety gate.
+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. `ffplay` remains a playback-only fallback and is intentionally labeled with limited controls in the UI and doctor output. Experimental AirPlay output is available on macOS when Bonjour discovery and FFmpeg are available.
 
 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/airplay-discovery.js

@@ -1,4 +1,6 @@
 import { spawn } from 'node:child_process';
+import { lookup } from 'node:dns/promises';
+import { networkInterfaces } from 'node:os';
 import { commandExists } from './command.js';
 const defaultTimeoutMs = 2500;
 const defaultMaxDevices = 12;
@@ -12,10 +14,41 @@ export async function discoverAirPlayDevices({ platform = process.platform, time
     const instances = parseRaopBrowseOutput(browseOutput).slice(0, Math.max(0, maxDevices));
     const devices = await mapWithConcurrency(instances, Math.max(1, lookupConcurrency), async (instance) => {
         const lookupOutput = await runDnsSd(['-L', instance, '_raop._tcp', 'local'], timeoutMs, maxOutputBytes).catch(() => '');
-        return parseRaopLookupOutput(instance, lookupOutput);
+        const device = parseRaopLookupOutput(instance, lookupOutput);
+        return device ? enrichAirPlayDeviceHost(device) : null;
     });
     return devices.filter((device) => Boolean(device));
 }
+async function enrichAirPlayDeviceHost(device) {
+    const addresses = await lookup(device.host, { all: true, family: 4 }).catch(() => []);
+    if (addresses.length === 0) {
+        return device;
+    }
+    const localAddresses = localIpv4Addresses();
+    const preferred = addresses.find(address => !isLoopbackAddress(address.address)) ?? addresses[0];
+    if (!preferred) {
+        return device;
+    }
+    return {
+        ...device,
+        host: preferred.address,
+        local: addresses.some(address => localAddresses.has(address.address))
+    };
+}
+function localIpv4Addresses() {
+    const addresses = new Set(['127.0.0.1']);
+    for (const entries of Object.values(networkInterfaces())) {
+        for (const entry of entries ?? []) {
+            if (entry.family === 'IPv4') {
+                addresses.add(entry.address);
+            }
+        }
+    }
+    return addresses;
+}
+function isLoopbackAddress(address) {
+    return address === '127.0.0.1' || address.startsWith('127.');
+}
 export function parseRaopBrowseOutput(output) {
     const instances = new Set();
     for (const line of output.split('\n')) {

package/dist/player/airplay-sender-health.js

@@ -10,11 +10,13 @@ export function airPlaySenderHealth(lookupPackage = lookupInstalledPackage) {
             available: false,
             safe: false,
             packageName: airPlaySenderPackageName,
-            message: 'AirPlay sender package not installed. Install an audited node-airtunes2-compatible sender next to RadioCLI.',
-            vulnerablePackages: []
+            message: 'AirPlay sender package is not installed.',
+            vulnerablePackages: [],
+            warningPackages: []
         };
     }
-    const vulnerablePackages = vulnerableAirPlaySenderPackages(sender, lookupPackage);
+    const vulnerablePackages = blockingAirPlaySenderPackages(sender, lookupPackage);
+    const warningPackages = warningAirPlaySenderPackages(sender, lookupPackage);
     if (vulnerablePackages.length > 0) {
         return {
             available: true,
@@ -22,7 +24,8 @@ export function airPlaySenderHealth(lookupPackage = lookupInstalledPackage) {
             packageName: sender.name,
             version: sender.version,
             message: `Installed AirPlay sender ${sender.name}@${sender.version} is blocked because vulnerable transitive dependencies were found: ${vulnerablePackages.join(', ')}.`,
-            vulnerablePackages
+            vulnerablePackages,
+            warningPackages
         };
     }
     return {
@@ -30,18 +33,26 @@ export function airPlaySenderHealth(lookupPackage = lookupInstalledPackage) {
         safe: true,
         packageName: sender.name,
         version: sender.version,
-        message: `AirPlay sender ${sender.name}@${sender.version} passed the dependency safety gate.`,
-        vulnerablePackages: []
+        message: warningPackages.length > 0
+            ? `Bundled AirPlay sender ${sender.name}@${sender.version} is available with warnings: ${warningPackages.join(', ')}.`
+            : `AirPlay sender ${sender.name}@${sender.version} passed the dependency safety gate.`,
+        vulnerablePackages: [],
+        warningPackages
     };
 }
-function vulnerableAirPlaySenderPackages(sender, lookupPackage) {
+function blockingAirPlaySenderPackages(sender, lookupPackage) {
     const packagePaths = [sender.root];
     const vulnerable = [];
     const protobuf = lookupPackage('protobufjs', packagePaths);
-    const elliptic = lookupPackage('elliptic', packagePaths);
     if (protobuf && compareSemver(protobuf.version, '7.5.8') < 0) {
         vulnerable.push(`protobufjs@${protobuf.version}`);
     }
+    return vulnerable;
+}
+function warningAirPlaySenderPackages(sender, lookupPackage) {
+    const packagePaths = [sender.root];
+    const vulnerable = [];
+    const elliptic = lookupPackage('elliptic', packagePaths);
     if (elliptic && compareSemver(elliptic.version, '6.6.2') < 0) {
         vulnerable.push(`elliptic@${elliptic.version}`);
     }

package/dist/player/airplay-sender-patch.js

@@ -0,0 +1,138 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const setupAp2DigestGuard = 'this.status === SETUP_AP2_1 && response.code === 401';
+const responseHeadersMarker = '    headers = response.headers';
+const processDataResponseMarker = '  if (this.status != OPTIONS && this.status != OPTIONS2 && this.mode == 0) {';
+const setupAp2TimingPortMarker = `      let sa1_bplist = bplistParser.parseBuffer(buf7)
+      this.eventPort = sa1_bplist[0]['eventPort']
+      if (sa1_bplist[0]['timingPort'])
+        this.timingDestPort = sa1_bplist[0]['timingPort']
+      console.log('timing port ok', sa1_bplist[0]['timingPort'])`;
+const setupAp2TimingPortFallback = `      let sa1_bplist
+      try {
+        sa1_bplist = buf7.length > 0 ? bplistParser.parseBuffer(buf7) : [{}]
+      }
+      catch (_) {
+        sa1_bplist = [{}]
+      }
+      this.eventPort = sa1_bplist[0]['eventPort'] || this.eventPort || this.socket.remotePort || 7000
+      if (sa1_bplist[0]['timingPort'])
+        this.timingDestPort = sa1_bplist[0]['timingPort']
+      console.log('timing port ok', sa1_bplist[0]['timingPort'])`;
+const socketDataHandlerMarker = `  var blob = ''
+  this.socket.on('data', function (data) {
+    if (self.encryptedChannel && self.credentials) {
+      // if (self.debug != false) console.log("incoming", data)
+      data = self.credentials.decrypt(data)
+    }
+    self.clearTimeout()
+
+    /*
+     * I wish I could use node's HTTP parser for this...
+     * I assume that all responses have empty bodies.
+     */
+    var rawData = data
+    data = data.toString()
+
+    blob += data
+    var endIndex = blob.indexOf('\\r\\n\\r\\n')
+
+    if (endIndex < 0) {
+      return
+    }
+
+    endIndex += 4
+
+    blob = blob.substring(0, endIndex)
+    self.processData(blob, rawData)
+
+    blob = data.substring(endIndex)
+  })`;
+const bufferedSocketDataHandler = `  var blob = Buffer.alloc(0)
+  this.socket.on('data', function (data) {
+    if (self.encryptedChannel && self.credentials) {
+      // if (self.debug != false) console.log("incoming", data)
+      data = self.credentials.decrypt(data)
+    }
+    self.clearTimeout()
+
+    blob = Buffer.concat([blob, Buffer.from(data)])
+    while (blob.length > 0) {
+      var endIndex = blob.indexOf('\\r\\n\\r\\n')
+
+      if (endIndex < 0) {
+        return
+      }
+
+      endIndex += 4
+      var headers = blob.slice(0, endIndex).toString()
+      var lengthMatch = /(?:^|\\r\\n)Content-Length:\\s*(\\d+)/i.exec(headers)
+      var contentLength = lengthMatch ? parseInt(lengthMatch[1], 10) : 0
+      var messageLength = endIndex + contentLength
+
+      if (blob.length < messageLength) {
+        return
+      }
+
+      var rawData = blob.slice(0, messageLength)
+      self.processData(headers, rawData)
+
+      blob = blob.slice(messageLength)
+    }
+  })`;
+let installed = false;
+export function installAirPlaySenderPatch(packageName = 'node-airtunes2') {
+    if (installed) {
+        return true;
+    }
+    let rtspPath;
+    try {
+        rtspPath = require.resolve(`${packageName}/lib/rtsp.js`);
+    }
+    catch {
+        return false;
+    }
+    const moduleLoader = require('node:module');
+    const originalLoader = moduleLoader._extensions['.js'];
+    if (!originalLoader) {
+        return false;
+    }
+    moduleLoader._extensions['.js'] = (module, filename) => {
+        if (filename !== rtspPath) {
+            originalLoader(module, filename);
+            return;
+        }
+        module._compile(patchAirTunesRtspSource(readFileSync(filename, 'utf8')), filename);
+    };
+    installed = true;
+    return true;
+}
+export function patchAirTunesRtspSource(source) {
+    let patched = source;
+    if (patched.includes(socketDataHandlerMarker) && !patched.includes('Buffer.concat([blob, Buffer.from(data)])')) {
+        patched = patched.replace(socketDataHandlerMarker, bufferedSocketDataHandler);
+    }
+    if (patched.includes(setupAp2TimingPortMarker) && !patched.includes("this.socket.remotePort || 7000")) {
+        patched = patched.replace(setupAp2TimingPortMarker, setupAp2TimingPortFallback);
+    }
+    if (patched.includes(responseHeadersMarker) && !patched.includes('headers = response.headers || {}')) {
+        patched = patched.replace(responseHeadersMarker, '    headers = response.headers || {}');
+    }
+    if (patched.includes(setupAp2DigestGuard) || !patched.includes(processDataResponseMarker)) {
+        return patched;
+    }
+    const setupAp2DigestRetry = `  if (${setupAp2DigestGuard} && headers['WWW-Authenticate'] && this.password) {
+    const auth = headers['WWW-Authenticate']
+    const di = {
+      realm: parseAuthenticate(auth, 'realm'),
+      nonce: parseAuthenticate(auth, 'nonce'),
+      username: 'iTunes',
+      password: this.password,
+    }
+    this.sendNextRequest(di)
+    return
+  }
+`;
+    return patched.replace(processDataResponseMarker, `${setupAp2DigestRetry}${processDataResponseMarker}`);
+}

package/dist/player/airplay-worker-protocol.js

@@ -33,18 +33,13 @@ function validateWorkerStart(value) {
     if (!isRecord(value) || !isRecord(value.device)) {
         throw new Error('Invalid AirPlay worker start payload.');
     }
-    const streamUrl = boundedString(value.streamUrl, 'streamUrl', 4096);
-    const parsedUrl = new URL(streamUrl);
-    if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
-        throw new Error('AirPlay streams must use http or https URLs.');
-    }
     const device = value.device;
     const port = Number(device.port);
     const txt = Array.isArray(device.txt)
         ? device.txt.slice(0, 64).map(item => boundedString(item, 'txt', 512)).filter(Boolean)
         : [];
     return {
-        streamUrl,
+        streamUrl: boundedHttpUrl(value.streamUrl, 'streamUrl'),
         stationName: boundedText(value.stationName, 'stationName', maxWorkerTextBytes),
         volume: clampVolume(Number(value.volume)),
         muted: typeof value.muted === 'boolean' ? value.muted : false,
@@ -72,6 +67,18 @@ function validateWorkerMessage(value) {
     if (value.type === 'setMuted') {
         return typeof value.muted === 'boolean' ? { type: 'setMuted', muted: value.muted } : null;
     }
+    if (value.type === 'retune') {
+        try {
+            return {
+                type: 'retune',
+                streamUrl: boundedHttpUrl(value.streamUrl, 'streamUrl'),
+                stationName: boundedText(value.stationName, 'stationName', maxWorkerTextBytes)
+            };
+        }
+        catch {
+            return null;
+        }
+    }
     if (value.type === 'passcode') {
         if (typeof value.code !== 'string' || Buffer.byteLength(value.code, 'utf8') > maxPasscodeBytes) {
             return null;
@@ -79,7 +86,7 @@ function validateWorkerMessage(value) {
         const code = cleanText(value.code, maxPasscodeBytes);
         return code ? { type: 'passcode', code } : null;
     }
-    if (value.type === 'ready' || value.type === 'playing' || value.type === 'password-required' || value.type === 'stopped') {
+    if (value.type === 'ready' || value.type === 'playing' || value.type === 'retuned' || value.type === 'password-required' || value.type === 'stopped') {
         return { type: value.type };
     }
     if (value.type === 'buffer') {
@@ -100,6 +107,14 @@ function boundedString(value, field, maxBytes) {
 function boundedText(value, field, maxBytes) {
     return boundedString(value, field, maxBytes);
 }
+function boundedHttpUrl(value, field) {
+    const streamUrl = boundedString(value, field, 4096);
+    const parsedUrl = new URL(streamUrl);
+    if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
+        throw new Error('AirPlay streams must use http or https URLs.');
+    }
+    return streamUrl;
+}
 function cleanText(value, maxBytes) {
     if (typeof value !== 'string') {
         return '';

package/dist/player/airplay-worker.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { airPlaySenderHealth } from './airplay-sender-health.js';
+import { installAirPlaySenderPatch } from './airplay-sender-patch.js';
 import { parseWorkerMessage, decodeWorkerStart, maxWorkerMessageBytes, serializeWorkerMessage } from './airplay-worker-protocol.js';
 const require = createRequire(import.meta.url);
 // node-airtunes2 writes diagnostics with console.log; keep stdout reserved for JSON events.
@@ -16,8 +17,10 @@ const AirTunes = loadAirTunesSender();
 const start = decodeStartPayload(encodedStart);
 const airtunes = new AirTunes();
 let deviceKey = '';
+let ffmpeg = null;
 let muted = start.muted;
 let volume = start.volume;
+let retuning = false;
 let stopping = false;
 airtunes.on('device', (key, status) => {
     if (typeof key === 'string') {
@@ -40,9 +43,11 @@ airtunes.on('device', (key, status) => {
     }
 });
 airtunes.on('buffer', status => {
-    emit({ type: 'buffer', status: String(status) });
-    if (status === 'playing') {
-        emit({ type: 'playing' });
+    const statusText = String(status);
+    emit({ type: 'buffer', status: statusText });
+    if (retuning && statusText === 'playing') {
+        retuning = false;
+        emit({ type: 'retuned' });
     }
 });
 airtunes.on('error', error => {
@@ -58,40 +63,7 @@ const device = airtunes.add(start.device.host, {
     mode: start.device.airplay2 ? 2 : 0
 });
 deviceKey = device.key;
-const ffmpeg = spawn('ffmpeg', [
-    '-hide_banner',
-    '-loglevel',
-    'error',
-    '-i',
-    start.streamUrl,
-    '-f',
-    's16le',
-    '-ac',
-    '2',
-    '-ar',
-    '44100',
-    'pipe:1'
-], {
-    stdio: ['ignore', 'pipe', 'pipe']
-});
-ffmpeg.stdout.on('data', chunk => {
-    airtunes.write(chunk);
-});
-ffmpeg.stderr.on('data', chunk => {
-    process.stderr.write(chunk);
-});
-ffmpeg.once('error', error => {
-    emit({ type: 'error', message: error.message });
-    stop(1);
-});
-ffmpeg.once('exit', code => {
-    if (!stopping) {
-        if (code !== 0) {
-            emit({ type: 'error', message: `ffmpeg exited with code ${code}` });
-        }
-        stop(code ?? 0);
-    }
-});
+startFfmpeg(start.streamUrl);
 let stdinBuffer = '';
 process.stdin.on('data', chunk => {
     stdinBuffer += chunk.toString('utf8');
@@ -125,10 +97,76 @@ function handleCommand(command) {
         muted = command.muted;
         setAirPlayVolume(muted ? 0 : volume);
     }
+    else if (command.type === 'retune') {
+        retuning = true;
+        airtunes.reset();
+        startFfmpeg(command.streamUrl);
+    }
     else if (command.type === 'passcode') {
         device.setPasscode?.(command.code);
     }
 }
+function startFfmpeg(streamUrl) {
+    const previous = ffmpeg;
+    const child = spawn('ffmpeg', [
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        // Recover from transient source drops without tearing down the AirPlay session.
+        // These are input options and must precede -i. -reconnect_streamed is essential for
+        // non-seekable radio; with no retry cap ffmpeg keeps trying until the station returns.
+        '-reconnect',
+        '1',
+        '-reconnect_on_network_error',
+        '1',
+        '-reconnect_streamed',
+        '1',
+        '-reconnect_delay_max',
+        '2',
+        '-i',
+        streamUrl,
+        '-f',
+        's16le',
+        '-ac',
+        '2',
+        '-ar',
+        '44100',
+        'pipe:1'
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    ffmpeg = child;
+    if (previous && !previous.killed) {
+        previous.kill('SIGTERM');
+    }
+    child.stdout.on('data', chunk => {
+        if (ffmpeg === child && !stopping) {
+            airtunes.write(chunk);
+        }
+    });
+    child.stderr.on('data', chunk => {
+        if (ffmpeg === child) {
+            process.stderr.write(chunk);
+        }
+    });
+    child.once('error', error => {
+        if (ffmpeg !== child || stopping) {
+            return;
+        }
+        emit({ type: 'error', message: error.message });
+        stop(1);
+    });
+    child.once('exit', code => {
+        if (ffmpeg !== child || stopping) {
+            return;
+        }
+        ffmpeg = null;
+        if (code !== 0) {
+            emit({ type: 'error', message: `ffmpeg exited with code ${code}` });
+        }
+        stop(code ?? 0);
+    });
+}
 function setAirPlayVolume(nextVolume) {
     if (deviceKey) {
         airtunes.setVolume(deviceKey, nextVolume);
@@ -143,11 +181,12 @@ function loadAirTunesSender() {
         emit({ type: 'error', message: health.message });
         process.exit(1);
     }
+    installAirPlaySenderPatch();
     try {
         return require('node-airtunes2');
     }
     catch {
-        emit({ type: 'error', message: 'AirPlay sender package could not be loaded after passing the safety gate.' });
+        emit({ type: 'error', message: 'AirPlay sender bridge could not be loaded.' });
         process.exit(1);
     }
 }
@@ -165,9 +204,10 @@ function stop(code) {
         return;
     }
     stopping = true;
-    if (!ffmpeg.killed) {
+    if (ffmpeg && !ffmpeg.killed) {
         ffmpeg.kill('SIGTERM');
     }
+    ffmpeg = null;
     airtunes.stopAll(() => {
         emit({ type: 'stopped' });
         process.exit(code);

package/dist/player/backend-install.js

@@ -61,7 +61,7 @@ export function playbackBackendInstallHint(platform = process.platform, osReleas
 export function playbackBackendStatusLines(backends, platform = process.platform, osRelease = readLinuxOsRelease()) {
     const backendSet = new Set(backends);
     const lines = [
-        'npm_install=RadioCLI only; native playback comes from mpv, ffplay, or AirPlay prerequisites',
+        'npm_install=RadioCLI installs the optional AirPlay sender when native dependencies are available; playback tools come from mpv and FFmpeg',
         `install_mpv=${mpvInstallCommand(platform, osRelease)}`,
         `optional_ffplay=${ffplayInstallCommand(platform, osRelease)}`
     ];