5.5 KiB
OpenSpec Change: enterprise-react-audio-player
- Change ID: enterprise-react-audio-player
- Package:
@suaveplan/react-audio-player - Category: react
- Target path:
packages/ui/react/react-audio-player - Status: PROPOSED
- Date: 2026-05-15
- Design:
./design.md - Spec delta:
./specs/react-audio-player/spec.md
Replaces the prior 2026-04-24 draft flagged
NEEDS-REWRITE. See../REACT_AUDIO_WAVE_REWRITE_COMPLETE.md.
Summary
Deliver @suaveplan/react-audio-player on genesis from scratch at enterprise quality. The package is a track-style media player UI suite built on the unified architecture: it consumes AudioPlayerPlugin from @suaveplan/audio-fx-plugin-base as its playback source, hosts an optional FX chain via the universal PluginChain primitive, exposes a Zustand-backed player store layered over the transport, and provides three player variants (<BasicPlayer>, <AudioPlayer>, <PremiumPlayer>) plus karaoke (LRC parsing + <LyricsDisplay>), localStorage-backed playlist, two visualisers (waveform + spectrum) sourced from useAnalyser, two R3F screensavers (<GLBViewer>, <ShaderBackground>), and (in the premium variant) WebRTC multi-peer playback sync via @suaveplan/react-audio-stream.
The package owns no DSP, no transport scheduler, no parameter automation, no audio context. Every audio operation goes through @suaveplan/react-audio's hooks; UI state goes into a per-provider Zustand store; persistence goes through an injectable store (default localStorage).
Current-state audit (genesis)
The package does not exist on genesis yet — fresh build replacing the obsolete pre-tier 2026-04-24 draft.
Parity Checklist (vs upstream ../suaveplan/packages/react/media/react-audio-player/)
| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
Zustand useAudioPlayerStore |
✅ | ⬆️ | Slimmer; no playback state (lives on transport). UI + playlist + lyrics state only. |
<AudioPlayerProvider> |
✅ | ✅ | Thin wrapper that nests <AudioProvider> from react-audio and adds player-specific stores. |
createPluginManager |
✅ | ⚠️ refactored | Replaced by the generic <PluginChainView> from react-audio; consumers can drop in any AudioFxPlugin. |
<PlayPauseButton> |
✅ | ✅ | Uses useTransport().play/pause. |
<VolumeControl> |
✅ | ✅ | Drives the player's AudioPlayerPlugin volume parameter. |
<ProgressBar> |
✅ | ✅ | Reads useTransportTime. |
<Queue> (playlist) |
✅ | ✅ | Backed by usePlaylist from react-audio. |
| 3-band EQ + presets | ✅ | ⬆️ | Built on EQPlugin from audio-fx-plugin-base. Presets via usePreset. |
| LRC karaoke parser | ✅ | ✅ | Universal parser; no UI deps. |
<LyricsDisplay> |
✅ | ✅ | Reads useTransportTime for per-line highlight. |
createNetworkSyncManager (WebRTC/WebSocket multi-peer) |
✅ | ⬆️ | Delegated to @suaveplan/react-audio-stream; this package consumes its hooks. |
| localStorage-backed track storage | ✅ | ✅ | Through injectable store (default localStorage). |
<GLBViewer> R3F screensaver |
✅ | ✅ | Optional subpath; r3f peer dep. |
<ShaderBackground> R3F screensaver |
✅ | ✅ | Optional subpath; r3f peer dep. |
<WaveformVisualizer> |
✅ | ⬆️ | Reads useAnalyser from react-audio. |
<SpectrumAnalyzer> |
✅ | ⬆️ | Reads useAnalyser from react-audio. |
| Coverage | partial | ✅ | 100/100/100/100. |
| Storybook | partial | ✅ | Every component: default + interactive + edge. |
No 🚫 rows.
Available workspace deps on genesis
| Package | Role |
|---|---|
@suaveplan/react-audio (workspace:^) |
Provider + hooks (useAudioFxPlugin, useTransport, useTransportTime, useAnalyser, usePlaylist) |
@suaveplan/audio-fx-plugin-base (workspace:^) |
AudioPlayerPlugin, EQPlugin, PluginChain |
@suaveplan/audio-transport (workspace:^) |
Transport reference |
@suaveplan/error, @suaveplan/types, @suaveplan/opentelemetry, @suaveplan/events |
foundations |
react, optional @react-three/fiber + three for screensavers (peer deps; gated by subpath) |
|
zustand (catalog:state), framer-motion (catalog:animation), lucide-react (catalog:ui), zod (catalog:forms) |
File layout
packages/ui/react/react-audio-player/
src/
index.ts
error-codes.ts
provider/ audio-player-provider/
stores/ use-audio-player-store/ use-playlist-store/ use-lyrics-store/
hooks/ use-audio-player/ use-playlist-controls/ use-lyrics/ use-eq-band/
karaoke/ lrc-parser/ lyrics-display/ use-active-lyric/
components/
basic-player/ audio-player/ premium-player/
play-pause-button/ volume-control/ progress-bar/
queue/ eq-panel/ preset-selector-3band/
waveform-visualizer/ spectrum-analyzer/
screensavers/ ← optional subpaths, R3F-gated
glb-viewer/ shader-background/
sync/ ← optional subpaths, WebRTC-gated
use-multi-peer-sync/
__benchmarks__/
lrc-parse.bench.ts
visualizer.bench.ts
tests/
integration.test.tsx
purity.test.ts
exports.test.ts
e2e/
play.spec.ts
karaoke.spec.ts
Impact
Breaking changes: none — fresh build.
Prerequisites: react-audio, audio-fx-plugin-base, audio-transport, foundations.
Affected dependents
No dependents in this batch (verified by bunx turbo ls --filter=...@suaveplan/react-audio-player).