skills/docs/ui/react/react-audio-player/README.md

# @suaveplan/react-audio-player - Track-style media player suite: karaoke (LRC parser + LyricsDisplay) + a thin re-export facade over @suaveplan/react-audio's player components, hooks, and provider. Self-contained karaoke surface ships with this package; multi-peer playback sync via WebRTC is deferred until @suaveplan/react-audio-stream lands.

Track-style media-player surface for the Suaveplan audio family.
The package ships two kinds of exports:

1. **Karaoke** — a self-contained LRC parser, `useLyrics` hook, and
   `<LyricsDisplay>` component implemented in this package.
2. **Re-export façade** — namespace and flat aliases for the player
   UI that already lives in
   [`@suaveplan/react-audio`](../react-audio/README.md):
   `<AudioProvider>`, `<AudioPlayer>`, `<BasicPlayer>`,
   `<PremiumPlayer>`, `<TransportControls>`, `<Mixer>`,
   `<PluginChainView>`, `<PresetManager>`, plus hooks
   (`useTransport`, `useTransportTime`, `useAnalyser`, `usePlaylist`,
   …).

Consumers can either import directly from `@suaveplan/react-audio`
(the original home of those components) or from
`@suaveplan/react-audio-player`, whichever reads better in their
codebase. The named entry points resolve to the same singletons via
ESM re-export — no duplication, no extra bundle weight.

<!-- begin:auto-docs -->
## Documentation tree

- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/react-audio-player`. Every error thrown by a public surface in this package…
  - [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/react-audio-player`. Every error thrown by a public surface in this package…
- [lrc-parser](./src/karaoke/lrc-parser/lrc-parser.md) — `parseLrc(source, opts?)` parses LRC) karaoke source into a timestamp-sorted array of `Lyric` entries suitable for the…
  - [lrc-parser](./src/karaoke/lrc-parser/lrc-parser.md) — `parseLrc(source, opts?)` parses LRC) karaoke source into a timestamp-sorted array of `Lyric` entries suitable for the…
- [lyrics-display](./src/karaoke/lyrics-display/lyrics-display.md) — `<LyricsDisplay>` is the karaoke surface that renders a stack of lyric lines with the active line highlighted. It is th…
  - [lyrics-display](./src/karaoke/lyrics-display/lyrics-display.md) — `<LyricsDisplay>` is the karaoke surface that renders a stack of lyric lines with the active line highlighted. It is th…
- [use-lyrics](./src/karaoke/use-lyrics/use-lyrics.md) — `useLyrics(opts)` is the engine-agnostic karaoke hook. It owns the active-line state, samples it at a fixed interval (1…
  - [use-lyrics](./src/karaoke/use-lyrics/use-lyrics.md) — `useLyrics(opts)` is the engine-agnostic karaoke hook. It owns the active-line state, samples it at a fixed interval (1…
<!-- end:auto-docs -->

## Status

This package targets the *additive* scope of the
`enterprise-react-audio-player` change. The pre-existing player
components (`<BasicPlayer>`, `<AudioPlayer>`, `<PremiumPlayer>`,
visualisers, transport controls, mixer, preset manager) already live
in `@suaveplan/react-audio`; duplicating them here would violate the
"do not duplicate enterprise components" guidance. Instead this
package adds:

- The karaoke surface — LRC parser, `useLyrics`, `<LyricsDisplay>`.
- A namespaced re-export façade (`ReactAudio.*`) plus flat aliases
  for the most common entry points.
- Stable `REACT_AUDIO_PLAYER.*` error codes.

### Deferred scope

- **Multi-peer playback sync** (`useMultiPeerSync`) is deferred until
  `@suaveplan/react-audio-stream` exists . The spec
  requirement is retained in the canonical capability spec with a
  `> Deferred (multi-peer)` marker; once the dependency lands, the
  hook adds in a follow-up change without breaking this package's
  public surface.
- R3F screensavers (`<GLBViewer>`, `<ShaderBackground>`) — the spec
  requirement is retained; consumers needing these today can
  compose any R3F surface as a sibling of `<PremiumPlayer>`. The
  optional `./screensavers/*` subpaths will be filled by a focused
  follow-up change.

The two hooks consumed by visualisers (`useAnalyser`) and queues
(`usePlaylist`) **are** shipped — they were added to
`@suaveplan/react-audio` alongside this package and are re-exported
here for ergonomic reach.

## Quick start — karaoke

```tsx
import {
    AudioProvider,
    AudioPlayer,
    LyricsDisplay,
} from "@suaveplan/react-audio-player";

function App({ track, lrc }: { track: string; lrc: string }) {
    return (
        <AudioProvider options={{ /* … */ }}>
            <AudioPlayer source={track} />
            <KaraokeLine lrc={lrc} />
        </AudioProvider>
    );
}

import { useTransportTime } from "@suaveplan/react-audio";
function KaraokeLine({ lrc }: { lrc: string }) {
    const seconds = useTransportTime();
    return <LyricsDisplay lrc={lrc} currentSec={seconds} />;
}
```

## Quick start — standalone preview (no provider)

```tsx
import {
    parseLrc,
    LyricsDisplay,
} from "@suaveplan/react-audio-player";
import { useMemo, useState } from "react";

export function Preview({ lrc }: { lrc: string }) {
    const lyrics = useMemo(() => parseLrc(lrc), [lrc]);
    const [t, setT] = useState(0);
    return (
        <div>
            <input
                type="range"
                min={0}
                max={120}
                step={0.1}
                value={t}
                onChange={(e) => setT(Number(e.currentTarget.value))}
                aria-label="time"
            />
            <LyricsDisplay lyrics={lyrics} currentSec={t} />
        </div>
    );
}
```

## Subpath exports

| Subpath | Surface |
| --- | --- |
| `.` | Root barrel — karaoke + flat aliases + `ReactAudio` namespace + error codes. |
| `./karaoke` | All karaoke exports. |
| `./karaoke/lrc-parser` | `parseLrc`, `activeLyricIndex`, types. |
| `./karaoke/use-lyrics` | `useLyrics` and types. |
| `./karaoke/lyrics-display` | `<LyricsDisplay>` and types. |
| `./error-codes` | `REACT_AUDIO_PLAYER.*` registry. |

See the per-feature `.md` files for full API references.