# Design — enterprise-react-audio-player

`@suaveplan/react-audio-player` is a **UI suite** layered on `@suaveplan/react-audio`. Its job is to give a consumer a one-component drop-in player (`<BasicPlayer>` / `<AudioPlayer>` / `<PremiumPlayer>`) that takes a track URL or `Playlist` prop and renders a complete, accessible, beautiful audio player UI, with everything from the source plugin down handled by the unified architecture.

Cross-cutting architecture: see `openspec/changes/enterprise-audio-fx-plugin-base/design.md` and `openspec/changes/enterprise-react-audio/design.md`. This document covers only the player-specific concerns.

---

## 1. Player variants

Three player components share state via the `audio-player-provider` and a Zustand store, differing only in layout density and feature set:

- **`<BasicPlayer>`** — single-track playback, play/pause/seek/volume, no chain, no visualiser. ~5 KB tree-shaken.
- **`<AudioPlayer>`** — adds playlist, 3-band EQ, waveform visualiser, repeat/shuffle. Re-enabled from upstream "commented-out" state via proper subpath exports.
- **`<PremiumPlayer>`** — adds spectrum analyser, R3F screensavers, karaoke (LRC lyrics), multi-peer playback sync via `react-audio-stream`.

The three sit on the same store and the same `AudioPlayerPlugin`. Switching components without unmounting the provider preserves playback state. Each variant is a separate subpath export; importing one does not pull in the others.

---

## 2. Per-player chain layout

The player constructs a fixed track on the timeline (`player-track`) with a fixed chain:

```
chain [
  AudioPlayerPlugin              ← source plugin (index 0)
  EQPlugin (3-band, in BasicPlayer this slot is absent)
  ...consumer-added FX slots...
]
```

`<AudioPlayer>` and `<PremiumPlayer>` expose a `<PluginChainView chain>` slot so consumers can add reverb, delay, etc. The chain owns the FX rack; the player owns the source.

The source plugin's `'ended'` event drives playlist advance via `usePlaylist`; the playlist hook calls `audioPlayerPlugin.load(nextSource)` and `audioPlayerPlugin.play()`.

---

## 3. LRC karaoke

LRC is parsed once into `{ timestampSec, text }[]` and stored in `useLyricsStore`. `<LyricsDisplay>` reads `useTransportTime()` at frame rate and binary-searches the lyric list to find the active line. Active line highlight uses `framer-motion` with `prefers-reduced-motion` honoured.

```ts
const activeIndex = useMemo(
  () => binarySearchActive(lyrics, currentTimeSec),
  [lyrics, Math.floor(currentTimeSec * 10)] // re-bind every 100 ms
)
```

The binary search is O(log n); a 1000-line LRC re-evaluates in ~10 comparisons per 100 ms — well below 1 ms total.

---

## 4. Visualisers

`<WaveformVisualizer>` and `<SpectrumAnalyzer>` both consume `useAnalyser(trackId | 'master')` from `react-audio`. The hook samples the analyser at frame rate; the visualisers render to `<canvas>` (waveform) or `<canvas>` with FFT-bin-to-pixel mapping (spectrum). No new analyser instance is constructed; both share the chain's master analyser node.

---

## 5. R3F screensavers (optional)

`<GLBViewer src animation?>` and `<ShaderBackground shader uniforms>` are R3F components gated to the `./screensavers/*` subpath. They are not pulled in unless explicitly imported. The screensaver wraps the player UI as a backdrop; opacity and visibility are React-controlled.

Three.js is a peer dep — non-screensaver consumers pay nothing.

---

## 6. Multi-peer sync (optional)

`<PremiumPlayer multiPeer={{ roomId, peers }}>` consumes `useMultiPeerSync` from this package, which in turn consumes hooks from `@suaveplan/react-audio-stream` to negotiate WebRTC peers, share transport `play/pause/seek` events across peers via a control channel, and stream the player's audio output to peers via the engine's tap-to-bus surface. The control protocol uses `@suaveplan/audio-transport` as the source of truth for transport state, so a peer disconnect does not desync the local player.

`react-audio-stream` is a peer dep of this subpath — basic/audio players don't pay for it.

---

## 7. Persistence

A `PlayerPersistenceStore` interface backs:

- the playlist (`{ tracks: Track[], position: number, repeat: 'off'|'one'|'all', shuffle: boolean }`),
- the EQ preset (`{ schemaVersion, bands: [...] }` validated against `EQPlugin.schema`),
- the user's volume + mute state.

Default implementation: `localStorage` keyed on the provider's `id` prop. Consumers may inject a different store (cloud-sync, IndexedDB, SSR cookie). Reads return defaults; writes are debounced (300 ms).

---

## 8. Accessibility

Inherits everything from `react-audio`: keyboard, ARIA, reduced-motion. Player-specific additions:

- `<ProgressBar>` is a `role="slider"` keyboard-seekable with arrow keys for 5 s, page-up/down for 30 s.
- `<Queue>` is `role="listbox"` with up/down navigation and `Enter` to play.
- `<LyricsDisplay>` exposes the active lyric as `aria-live="polite"` so screen readers announce lyric changes (configurable off via `announceLyrics={false}`).

---

## 9. Decisions and trade-offs

- **Three variants, one source plugin, one chain.** Sharing the source + chain across variants means switching variants doesn't restart playback.
- **`<AudioPlayer>` and `<PremiumPlayer>` expose the chain via `<PluginChainView>`.** Consumers extend FX without breaking the player UI.
- **LRC binary search re-binds every 100 ms.** Frame-rate re-bind (every 16 ms) is unnecessary; lyrics don't change that fast.
- **Screensavers and multi-peer sync are opt-in subpaths.** R3F and WebRTC peer deps are paid only by consumers that actually use them.
- **Persistence is injectable.** Cloud sync, SSR session, IndexedDB — all the same interface; localStorage is just the default.
- **No new analyser node.** Reuse the engine's master analyser; one instance per chain, not per visualiser.