bbgfm 0.1.0

package/dist/app.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [INPUT]: ink render/useInput/useApp, all components, usePlayer hook, channel data
+ * [OUTPUT]: App root component — layout + state machine + keyboard handler
+ * [POS]: Central orchestrator assembling Header, ChannelList, Player, StatusBar
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+interface Props {
+    initialChannel?: string;
+}
+export declare function App({ initialChannel }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/app.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * [INPUT]: ink render/useInput/useApp, all components, usePlayer hook, channel data
+ * [OUTPUT]: App root component — layout + state machine + keyboard handler
+ * [POS]: Central orchestrator assembling Header, ChannelList, Player, StatusBar
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import { useState, useEffect, useRef } from 'react';
+import { Box, useInput, useApp } from 'ink';
+import { CHANNELS, DEFAULT_CHANNEL_ID } from './data/channels.js';
+import { usePlayer } from './hooks/usePlayer.js';
+import { Header } from './components/Header.js';
+import { ChannelList } from './components/ChannelList.js';
+import { Player } from './components/Player.js';
+import { StatusBar } from './components/StatusBar.js';
+export function App({ initialChannel }) {
+    const { exit } = useApp();
+    const player = usePlayer();
+    // Stable refs for player functions — useInput always gets the latest
+    const playerRef = useRef(player);
+    playerRef.current = player;
+    const defaultIndex = CHANNELS.findIndex(c => c.id === (initialChannel ?? DEFAULT_CHANNEL_ID));
+    const [selectedIndex, setSelectedIndex] = useState(Math.max(0, defaultIndex));
+    const selectedRef = useRef(selectedIndex);
+    selectedRef.current = selectedIndex;
+    // Auto-play default channel on mount
+    useEffect(() => {
+        const channel = CHANNELS[selectedRef.current];
+        if (channel)
+            playerRef.current.play(channel);
+    }, []);
+    // Helper: switch channel and auto-play
+    const switchAndPlay = (nextIndex) => {
+        setSelectedIndex(nextIndex);
+        selectedRef.current = nextIndex;
+        const channel = CHANNELS[nextIndex];
+        if (channel)
+            playerRef.current.play(channel);
+    };
+    // Keyboard bindings — all reads go through refs, zero stale closures
+    useInput((input, key) => {
+        const p = playerRef.current;
+        // Quit
+        if (input === 'q') {
+            p.stop().then(() => exit());
+            return;
+        }
+        // Navigate + auto-play
+        if (input === 'k' || key.upArrow) {
+            const cur = selectedRef.current;
+            switchAndPlay(cur > 0 ? cur - 1 : CHANNELS.length - 1);
+            return;
+        }
+        if (input === 'j' || key.downArrow) {
+            const cur = selectedRef.current;
+            switchAndPlay(cur < CHANNELS.length - 1 ? cur + 1 : 0);
+            return;
+        }
+        // Toggle play/stop
+        if (input === ' ') {
+            if (p.status === 'playing' || p.status === 'connecting') {
+                p.stop();
+            }
+            else {
+                const channel = CHANNELS[selectedRef.current];
+                if (channel)
+                    p.play(channel);
+            }
+            return;
+        }
+        // Volume
+        if (input === '+' || input === '=') {
+            p.adjustVolume(5);
+            return;
+        }
+        if (input === '-') {
+            p.adjustVolume(-5);
+            return;
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Header, {}), _jsx(Player, { channel: player.channel, status: player.status, volume: player.volume, audioLevelRef: player.audioLevelRef, error: player.error }), _jsx(ChannelList, { channels: CHANNELS, selectedIndex: selectedIndex, activeChannelId: player.channel?.id ?? null }), _jsx(StatusBar, {})] }));
+}

package/dist/components/ChannelList.d.ts

@@ -0,0 +1,14 @@
+/**
+ * [INPUT]: ink Text/Box, Channel type from data/channels
+ * [OUTPUT]: ChannelList component — selectable channel items
+ * [POS]: Channel navigation panel, rendered by App
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import type { Channel } from '../data/channels.js';
+interface Props {
+    channels: Channel[];
+    selectedIndex: number;
+    activeChannelId: string | null;
+}
+export declare function ChannelList({ channels, selectedIndex, activeChannelId }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ChannelList.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+// ============================================================
+// Component
+// ============================================================
+export function ChannelList({ channels, selectedIndex, activeChannelId }) {
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, marginBottom: 1, children: [_jsx(Text, { bold: true, underline: true, color: "white", children: " CHANNELS " }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: channels.map((ch, i) => {
+                    const isSelected = i === selectedIndex;
+                    const isActive = ch.id === activeChannelId;
+                    const pointer = isSelected ? '▸' : ' ';
+                    const indicator = isActive ? '♫' : ' ';
+                    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: isSelected ? 'green' : 'white', children: pointer }), _jsx(Text, { color: isActive ? 'green' : isSelected ? 'green' : 'gray', children: indicator }), _jsx(Text, { color: isSelected ? 'green' : 'white', bold: isSelected, children: ch.name }), _jsxs(Text, { dimColor: true, children: [" ", ch.tag] })] }, ch.id));
+                }) })] }));
+}

package/dist/components/Header.d.ts

@@ -0,0 +1,7 @@
+/**
+ * [INPUT]: ink Text/Box
+ * [OUTPUT]: Header component — ASCII banner with version
+ * [POS]: Top-level decorative banner, rendered by App
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+export declare function Header(): import("react/jsx-runtime").JSX.Element;

package/dist/components/Header.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+// ============================================================
+// ASCII Banner
+// ============================================================
+const BANNER = `
+ ██████╗ ██████╗  ██████╗    ███████╗███╗   ███╗
+ ██╔══██╗██╔══██╗██╔════╝    ██╔════╝████╗ ████║
+ ██████╔╝██████╔╝██║  ███╗   █████╗  ██╔████╔██║
+ ██╔══██╗██╔══██╗██║   ██║   ██╔══╝  ██║╚██╔╝██║
+ ██████╔╝██████╔╝╚██████╔╝██╗██║     ██║ ╚═╝ ██║
+ ╚═════╝ ╚═════╝  ╚═════╝ ╚═╝╚═╝     ╚═╝     ╚═╝
+`.trimStart();
+export function Header() {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "green", bold: true, children: BANNER }), _jsx(Text, { dimColor: true, children: "  Blockchain AI Radio \u2014 Terminal Player v0.1.0" })] }));
+}

package/dist/components/Player.d.ts

@@ -0,0 +1,18 @@
+/**
+ * [INPUT]: ink Text/Box, Channel type, PlayerStatus, audioLevelRef, SpectrumVisualizer
+ * [OUTPUT]: Player component -- now playing display + spectrum + volume bar
+ * [POS]: Playback status panel, rendered by App
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import { type MutableRefObject } from 'react';
+import type { Channel } from '../data/channels.js';
+import type { PlayerStatus } from '../hooks/usePlayer.js';
+interface Props {
+    channel: Channel | null;
+    status: PlayerStatus;
+    volume: number;
+    audioLevelRef: MutableRefObject<number>;
+    error: string | null;
+}
+export declare function Player({ channel, status, volume, audioLevelRef, error }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Player.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { SpectrumVisualizer } from './SpectrumVisualizer.js';
+// ============================================================
+// Helpers
+// ============================================================
+function statusLabel(status) {
+    const map = {
+        idle: { text: 'IDLE', color: 'gray' },
+        connecting: { text: 'CONNECTING...', color: 'yellow' },
+        playing: { text: 'ON AIR', color: 'green' },
+        paused: { text: 'PAUSED', color: 'yellow' },
+        stopped: { text: 'STOPPED', color: 'red' },
+        error: { text: 'ERROR', color: 'red' },
+    };
+    return map[status];
+}
+function volumeBar(volume) {
+    const filled = Math.round(volume / 5);
+    const empty = 20 - filled;
+    return '█'.repeat(filled) + '░'.repeat(empty);
+}
+// ============================================================
+// Component
+// ============================================================
+export function Player({ channel, status, volume, audioLevelRef, error }) {
+    const label = statusLabel(status);
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: status === 'playing' ? 'green' : 'gray', paddingX: 2, paddingY: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Text, { bold: true, color: "white", children: "NOW PLAYING" }), _jsxs(Text, { color: label.color, bold: true, children: ["[", label.text, "]"] })] }), channel ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { gap: 1, alignItems: "center", children: [_jsx(Text, { color: "green", bold: true, children: channel.name }), _jsx(SpectrumVisualizer, { status: status, audioLevelRef: audioLevelRef })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: channel.desc }) })] })) : (_jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "No channel selected \u2014 press Enter to play" }) })), _jsxs(Box, { marginTop: 1, gap: 1, children: [_jsx(Text, { dimColor: true, children: "VOL" }), _jsx(Text, { color: "green", children: volumeBar(volume) }), _jsxs(Text, { bold: true, children: [volume, "%"] })] }), error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Error: ", error] }) }))] }));
+}

package/dist/components/SpectrumVisualizer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * [INPUT]: PlayerStatus + audioLevelRef (shared MutableRefObject<number>) from usePlayer
+ * [OUTPUT]: SpectrumVisualizer -- ASCII waveform bars driven by real audio energy
+ * [POS]: Decorative element rendered inside Player card.
+ *        Reads audioLevel from shared ref -- bypasses React render pipeline.
+ *        Animation model (25fps, exp-decay 0.82, lerp-attack 0.7):
+ *        1. Playing + signal  -> audio-reactive with per-bar jitter
+ *        2. Playing + silent  -> simulated jitter over bell-curve envelope
+ *        3. Idle              -> subtle breathing over bell-curve envelope
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import { type MutableRefObject } from 'react';
+import type { PlayerStatus } from '../hooks/usePlayer.js';
+interface Props {
+    status: PlayerStatus;
+    audioLevelRef: MutableRefObject<number>;
+}
+export declare function SpectrumVisualizer({ status, audioLevelRef }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/SpectrumVisualizer.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * [INPUT]: PlayerStatus + audioLevelRef (shared MutableRefObject<number>) from usePlayer
+ * [OUTPUT]: SpectrumVisualizer -- ASCII waveform bars driven by real audio energy
+ * [POS]: Decorative element rendered inside Player card.
+ *        Reads audioLevel from shared ref -- bypasses React render pipeline.
+ *        Animation model (25fps, exp-decay 0.82, lerp-attack 0.7):
+ *        1. Playing + signal  -> audio-reactive with per-bar jitter
+ *        2. Playing + silent  -> simulated jitter over bell-curve envelope
+ *        3. Idle              -> subtle breathing over bell-curve envelope
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import { useEffect, useRef, useState } from 'react';
+import { Box, Text } from 'ink';
+// ============================================================
+// Constants
+// ============================================================
+const BAR_COUNT = 16;
+const BLOCKS = [' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+const TICK_MS = 40; // 25fps -- visual fluidity threshold
+const ATTACK_LERP = 0.7; // aggressive rise -- near-instant transient response
+const DECAY_FACTOR = 0.82; // fast exponential fall -- ~80ms to half-height
+const FLOOR = 0.06; // minimum bar height
+// Bell-curve envelope -- natural shape for idle / fallback
+const ENVELOPE = (() => {
+    const out = [];
+    for (let i = 0; i < BAR_COUNT; i++) {
+        const t = i / (BAR_COUNT - 1);
+        const peak = Math.exp(-Math.pow((t - 0.55) * 2.8, 2)) * 0.95;
+        out.push(Math.max(FLOOR, peak));
+    }
+    return out;
+})();
+// Per-bar jitter frequencies -- avoid lockstep by giving each bar
+// a unique oscillation speed and phase offset
+const JITTER_FREQ = Array.from({ length: BAR_COUNT }, (_, i) => 3.1 + i * 0.37);
+const JITTER_PHASE = Array.from({ length: BAR_COUNT }, (_, i) => i * 1.13);
+// Green (#5BFF9F) at edges → Cyan (#00E5FF) at center
+const BAR_COLORS = (() => {
+    const out = [];
+    for (let i = 0; i < BAR_COUNT; i++) {
+        const t = i / (BAR_COUNT - 1);
+        // Bell curve peaks at center → cyan; edges → green
+        const center = Math.exp(-Math.pow((t - 0.5) * 3.0, 2));
+        const r = Math.round(0x5b * (1 - center) + 0x00 * center);
+        const g = Math.round(0xff * (1 - center) + 0xe5 * center);
+        const b = Math.round(0x9f * (1 - center) + 0xff * center);
+        out.push(`#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`);
+    }
+    return out;
+})();
+// ============================================================
+// Helpers
+// ============================================================
+function toBlock(value) {
+    const idx = Math.round(value * (BLOCKS.length - 1));
+    return BLOCKS[Math.max(0, Math.min(BLOCKS.length - 1, idx))] || ' ';
+}
+/** Clamp value to [FLOOR, 1] */
+function clamp(v) {
+    return v < FLOOR ? FLOOR : v > 1 ? 1 : v;
+}
+export function SpectrumVisualizer({ status, audioLevelRef }) {
+    const [heights, setHeights] = useState([...ENVELOPE]);
+    const prevRef = useRef([...ENVELOPE]);
+    useEffect(() => {
+        const startTime = Date.now();
+        const timer = setInterval(() => {
+            const elapsed = Date.now() - startTime;
+            const t = elapsed / 1000;
+            const level = audioLevelRef.current; // direct ref read -- zero React overhead
+            const prev = prevRef.current;
+            const next = [];
+            const isActive = status === 'playing' || status === 'connecting';
+            const hasSignal = isActive && level > 0.01;
+            if (hasSignal) {
+                // ── State 1: Audio-reactive ──
+                // Exponential decay on fall, lerp on rise, per-bar jitter
+                for (let i = 0; i < BAR_COUNT; i++) {
+                    const shape = ENVELOPE[i];
+                    const jitter = Math.sin(t * JITTER_FREQ[i] + JITTER_PHASE[i]) * 0.18;
+                    const target = clamp(level * shape + jitter * level);
+                    // Rise: lerp toward target; Fall: exponential decay
+                    const h = target > prev[i]
+                        ? prev[i] + (target - prev[i]) * ATTACK_LERP
+                        : Math.max(target, prev[i] * DECAY_FACTOR);
+                    next.push(clamp(h));
+                }
+            }
+            else if (isActive) {
+                // ── State 2: Simulated fallback (playing but no signal) ──
+                for (let i = 0; i < BAR_COUNT; i++) {
+                    const base = ENVELOPE[i];
+                    const jitter = Math.sin(t * JITTER_FREQ[i] + JITTER_PHASE[i]) * 0.15;
+                    next.push(clamp(base + jitter));
+                }
+            }
+            else {
+                // ── State 3: Idle breathing ──
+                for (let i = 0; i < BAR_COUNT; i++) {
+                    const breath = Math.sin(t * 0.83 + i * 0.3) * 0.04;
+                    next.push(clamp(ENVELOPE[i] + breath));
+                }
+            }
+            prevRef.current = next;
+            setHeights(next);
+        }, TICK_MS);
+        return () => clearInterval(timer);
+    }, [status]);
+    return (_jsx(Box, { gap: 1, children: heights.map((h, i) => (_jsx(Text, { color: BAR_COLORS[i], children: toBlock(h) }, i))) }));
+}

package/dist/components/StatusBar.d.ts

@@ -0,0 +1,7 @@
+/**
+ * [INPUT]: ink Text/Box
+ * [OUTPUT]: StatusBar component — keyboard shortcut help
+ * [POS]: Bottom bar with key bindings, rendered by App
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+export declare function StatusBar(): import("react/jsx-runtime").JSX.Element;

package/dist/components/StatusBar.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+// ============================================================
+// Component
+// ============================================================
+export function StatusBar() {
+    return (_jsxs(Box, { gap: 2, marginTop: 1, children: [_jsxs(Text, { dimColor: true, children: [_jsx(Text, { color: "white", bold: true, children: "j/k" }), " switch channel"] }), _jsxs(Text, { dimColor: true, children: [_jsx(Text, { color: "white", bold: true, children: "Space" }), " play/stop"] }), _jsxs(Text, { dimColor: true, children: [_jsx(Text, { color: "white", bold: true, children: "+/-" }), " volume"] }), _jsxs(Text, { dimColor: true, children: [_jsx(Text, { color: "white", bold: true, children: "q" }), " quit"] })] }));
+}

package/dist/data/channels.d.ts

@@ -0,0 +1,16 @@
+/**
+ * [INPUT]: None (pure data)
+ * [OUTPUT]: Channel type, CHANNELS array, DEFAULT_CHANNEL_ID
+ * [POS]: Data registry for radio HLS streams, consumed by usePlayer and ChannelList
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+export interface Channel {
+    id: string;
+    slug: string;
+    name: string;
+    tag: string;
+    url: string;
+    desc: string;
+}
+export declare const CHANNELS: Channel[];
+export declare const DEFAULT_CHANNEL_ID = "bbg-en";

package/dist/data/channels.js

@@ -0,0 +1,25 @@
+/**
+ * [INPUT]: None (pure data)
+ * [OUTPUT]: Channel type, CHANNELS array, DEFAULT_CHANNEL_ID
+ * [POS]: Data registry for radio HLS streams, consumed by usePlayer and ChannelList
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+export const CHANNELS = [
+    {
+        id: 'bbg-en',
+        slug: 'en',
+        name: 'BBG · ENGLISH',
+        tag: 'BLOCKCHAIN · NEWS & TALK',
+        url: 'https://koe.bbg.fm/channels/1/playlist.m3u8',
+        desc: 'Blockchain Live Broadcast | News · Analysis · Culture',
+    },
+    {
+        id: 'bbg-cn',
+        slug: 'zh',
+        name: 'BBG · 中文',
+        tag: '区块链 · 新闻资讯',
+        url: 'https://koe.bbg.fm/channels/2/playlist.m3u8',
+        desc: '区块链实时广播 | 新闻 · 深度 · 文化',
+    },
+];
+export const DEFAULT_CHANNEL_ID = 'bbg-en';

package/dist/hooks/usePlayer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * [INPUT]: node-mpv for HLS playback, Channel type from data/channels
+ * [OUTPUT]: usePlayer hook — play/pause/stop/setVolume/audioLevel + reactive state
+ * [POS]: Audio backend abstraction, consumed by App root component
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import type { Channel } from '../data/channels.js';
+export type PlayerStatus = 'idle' | 'connecting' | 'playing' | 'paused' | 'stopped' | 'error';
+export declare function usePlayer(): {
+    audioLevelRef: import("react").MutableRefObject<number>;
+    play: (channel: Channel) => Promise<void>;
+    togglePause: () => Promise<void>;
+    adjustVolume: (delta: number) => void;
+    stop: () => Promise<void>;
+    status: PlayerStatus;
+    volume: number;
+    channel: Channel | null;
+    error: string | null;
+};

package/dist/hooks/usePlayer.js

@@ -0,0 +1,189 @@
+/**
+ * [INPUT]: node-mpv for HLS playback, Channel type from data/channels
+ * [OUTPUT]: usePlayer hook — play/pause/stop/setVolume/audioLevel + reactive state
+ * [POS]: Audio backend abstraction, consumed by App root component
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import NodeMpv from 'node-mpv';
+// Cross-platform mpv IPC path
+const MPV_SOCKET = process.platform === 'win32'
+    ? '\\\\.\\pipe\\bbgfm-mpv'
+    : join(tmpdir(), 'bbgfm-mpv.sock');
+// ============================================================
+// Hook — refs for mutable state, command chain for IPC safety
+// ============================================================
+export function usePlayer() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- node-mpv .d.ts is malformed
+    const mpvRef = useRef(null);
+    const volumeRef = useRef(100);
+    const statusRef = useRef('idle');
+    const cmdChain = useRef(Promise.resolve());
+    const volTimer = useRef(null);
+    const levelTimer = useRef(null);
+    // Shared ref -- SpectrumVisualizer reads this directly, no React render hop
+    const audioLevelRef = useRef(0);
+    const [state, setState] = useState({
+        status: 'idle',
+        volume: 100,
+        channel: null,
+        error: null,
+    });
+    // Sync status ref + state
+    const setStatus = useCallback((s) => {
+        statusRef.current = s;
+        setState(prev => ({ ...prev, status: s }));
+    }, []);
+    // Serialize mpv IPC commands — prevents socket flooding
+    const runCmd = useCallback((fn) => {
+        cmdChain.current = cmdChain.current.catch(() => { }).then(fn).catch(() => { });
+        return cmdChain.current;
+    }, []);
+    // --------------------------------------------------------
+    // Audio level polling — reads astats Peak_level from mpv
+    // --------------------------------------------------------
+    const startLevelPolling = useCallback(() => {
+        if (levelTimer.current)
+            return;
+        let polling = false; // guard -- prevent async IPC overlap
+        let baseline = 0; // adaptive baseline (slow EMA of linear amplitude)
+        levelTimer.current = setInterval(async () => {
+            if (polling)
+                return;
+            const mpv = mpvRef.current;
+            if (!mpv?.isRunning())
+                return;
+            polling = true;
+            try {
+                const raw = await mpv.getProperty('af-metadata/astats/lavfi.astats.Overall.Peak_level');
+                const dB = parseFloat(raw);
+                if (isNaN(dB))
+                    return;
+                // Convert dB to linear amplitude (0..1)
+                const linear = Math.pow(10, dB / 20);
+                // Adaptive baseline: slow-moving EMA (~2s time constant at 50ms intervals)
+                // Tracks the "floor" of the signal -- steady music sits near this
+                baseline = baseline < 0.001
+                    ? linear
+                    : baseline * 0.96 + linear * 0.04;
+                // Output = relative deviation from baseline, amplified
+                // For speech: linear spikes far above baseline -> high level
+                // For music: transients (drums, accents) spike above steady baseline
+                const deviation = linear - baseline * 0.7;
+                const headroom = Math.max(baseline * 1.5, 0.05);
+                audioLevelRef.current = Math.max(0, Math.min(1, deviation / headroom));
+            }
+            catch {
+                // af-metadata not available yet -- ignore silently
+            }
+            finally {
+                polling = false;
+            }
+        }, 50);
+    }, []);
+    const stopLevelPolling = useCallback(() => {
+        if (levelTimer.current) {
+            clearInterval(levelTimer.current);
+            levelTimer.current = null;
+        }
+        audioLevelRef.current = 0;
+    }, []);
+    // Lazy-init mpv — with astats audio filter for level metering
+    const getMpv = useCallback(() => {
+        if (!mpvRef.current) {
+            // @ts-expect-error — node-mpv .d.ts declares class but module shape is off
+            mpvRef.current = new NodeMpv({
+                audio_only: true,
+                verbose: false,
+                socket: MPV_SOCKET,
+            }, ['--af=@astats:lavfi=[astats=metadata=1:measure_overall=Peak_level+RMS_level:reset=1]']);
+        }
+        return mpvRef.current;
+    }, []);
+    // Play a channel
+    const play = useCallback(async (channel) => {
+        setStatus('connecting');
+        setState(prev => ({ ...prev, channel, error: null }));
+        await runCmd(async () => {
+            const mpv = getMpv();
+            if (!mpv.isRunning()) {
+                await mpv.start();
+                await mpv.volume(volumeRef.current);
+            }
+            await mpv.load(channel.url);
+        }).then(() => {
+            setStatus('playing');
+            startLevelPolling();
+        }, (err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            setStatus('error');
+            setState(prev => ({ ...prev, error: msg }));
+        });
+    }, [getMpv, setStatus, runCmd, startLevelPolling]);
+    // Toggle pause/resume
+    const togglePause = useCallback(async () => {
+        const s = statusRef.current;
+        if (s !== 'playing' && s !== 'paused')
+            return;
+        await runCmd(async () => {
+            const mpv = getMpv();
+            if (!mpv.isRunning())
+                return;
+            if (s === 'playing') {
+                await mpv.pause();
+                setStatus('paused');
+            }
+            else {
+                await mpv.resume();
+                setStatus('playing');
+            }
+        });
+    }, [getMpv, setStatus, runCmd]);
+    // Volume — state updates instantly, mpv command debounced
+    const adjustVolume = useCallback((delta) => {
+        const next = Math.max(0, Math.min(100, volumeRef.current + delta));
+        volumeRef.current = next;
+        setState(prev => ({ ...prev, volume: next }));
+        // Debounce: only send the final value to mpv after 50ms of inactivity
+        if (volTimer.current)
+            clearTimeout(volTimer.current);
+        volTimer.current = setTimeout(() => {
+            runCmd(async () => {
+                const mpv = getMpv();
+                if (mpv.isRunning())
+                    await mpv.volume(volumeRef.current);
+            });
+        }, 50);
+    }, [getMpv, runCmd]);
+    // Stop and quit mpv
+    const stop = useCallback(async () => {
+        stopLevelPolling();
+        if (volTimer.current)
+            clearTimeout(volTimer.current);
+        await runCmd(async () => {
+            const mpv = getMpv();
+            if (mpv.isRunning()) {
+                await mpv.stop();
+                await mpv.quit();
+            }
+        });
+        mpvRef.current = null;
+        setStatus('stopped');
+    }, [getMpv, setStatus, runCmd, stopLevelPolling]);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            if (levelTimer.current)
+                clearInterval(levelTimer.current);
+            if (volTimer.current)
+                clearTimeout(volTimer.current);
+            const mpv = mpvRef.current;
+            if (mpv?.isRunning()) {
+                mpv.stop().then(() => mpv.quit()).catch(() => { });
+            }
+        };
+    }, []);
+    return { ...state, audioLevelRef, play, togglePause, adjustVolume, stop };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * [INPUT]: ink render, App component, child_process for mpv check
+ * [OUTPUT]: CLI entry point -- parses args, checks mpv, renders App
+ * [POS]: Executable entry, registered as bin in package.json
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * [INPUT]: ink render, App component, child_process for mpv check
+ * [OUTPUT]: CLI entry point -- parses args, checks mpv, renders App
+ * [POS]: Executable entry, registered as bin in package.json
+ * [PROTOCOL]: Update this header on changes, then check AGENTS.md
+ */
+import { execFileSync } from 'node:child_process';
+import { render } from 'ink';
+import { App } from './app.js';
+// ============================================================
+// Preflight -- mpv is required for audio playback
+// ============================================================
+function ensureMpv() {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        execFileSync(cmd, ['mpv'], { stdio: 'ignore' });
+    }
+    catch {
+        console.error('\n  mpv is required but not found.\n');
+        console.error('  Install via:');
+        console.error('    brew install mpv        # macOS');
+        console.error('    sudo apt install mpv     # Debian/Ubuntu');
+        console.error('    sudo pacman -S mpv       # Arch');
+        console.error('    scoop install mpv        # Windows (scoop)');
+        console.error('    choco install mpv        # Windows (choco)');
+        console.error('    winget install mpv        # Windows (winget)\n');
+        process.exit(1);
+    }
+}
+// ============================================================
+// Arg Parsing (minimal, no dependency)
+// ============================================================
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const channelIdx = args.indexOf('--channel');
+    const channel = channelIdx !== -1 ? args[channelIdx + 1] : undefined;
+    return { channel };
+}
+// ============================================================
+// Boot
+// ============================================================
+ensureMpv();
+const { channel } = parseArgs();
+render(_jsx(App, { initialChannel: channel }));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "bbgfm",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "bbgfm": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.tsx",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "ink": "^5.2.0",
+    "node-mpv": "^2.0.0-beta.2",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.13",
+    "@types/react": "^18.3.18",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}