# 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

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