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

Documentation tree

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

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

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)

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.