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).

5.5 KiB Raw Blame History