Audio Player

InstallCopy Anchor Link

pnpm exec vegastack-design verify audio-player

pnpm dlx shadcn@4.21.0 add @vegastack/audio-player

UsageCopy Anchor Link

Closing or pausing cancels queued lazy playback and seeks. Late source resolution cannot resume a cancelled request.

import { AudioPlayer } from "@/components/ui/audio-player";

<AudioPlayer src="/media/demo.mp3" label="Product demo audio" />;

AnatomyCopy Anchor Link

AudioPlayer exports several parts. Every exported part, with the data-slot it renders (generated from the canonical source):

ExamplesCopy Anchor Link

BasicCopy Anchor Link

A single-line transport rendered statically on a card. Left to right: play/pause, rewind and forward (±15s), the combined elapsed / duration readout, a flexible seek bar, and a tappable speed control. Every transport control is a ghost Button, so the chrome stays quiet against the card. The docs preview uses a 90-second local audio fixture, so it can play without network access.

Mobile layoutCopy Anchor Link

Below the @sm container width the transport reflows to two lines while staying compact. The top line carries the seek bar with elapsed and duration pinned to either edge in a smaller font; the bottom line centres play/pause with rewind and forward flanking it, a transcript control on the leading edge, and the tappable speed on the trailing edge. The transcript control renders only when onTranscriptClick is supplied — wire it to open your app's transcript. The example is width-limited so the mobile layout is visible on a desktop screen.

WaveformCopy Anchor Link

Set variant="waveform" to render the decoded audio as the seek bar. The waveform is sampled from the real audio via the Web Audio API — played bars fill as playback advances, and the bars seek by click, drag, or keyboard just like the slider. Until decoding finishes (or if it fails), flat placeholder bars render and the seek stays operable.

Stored peaksCopy Anchor Link

Decoding downloads the whole file, which is wasteful for a long recording. Compute the peaks once at upload with probeAudio from the media-probe lib (up to 200 values), store them with the file, and pass them as peaks: the waveform draws at once and the file is only streamed when it plays. Any count works; the loudest peak is drawn full height.

import { probeAudio } from "@/lib/media-probe";

const { duration, peaks } = await probeAudio(file); // at upload
<AudioPlayer src={url} variant="waveform" peaks={peaks} />;

Still waveformCopy Anchor Link

AudioWaveform draws the same stored peaks as a still picture — the player's bars in muted-foreground, with no playback and no seek — for an audio file's card in a grid, where a player would be too much. It fills its width (h-12 unless you size it) and reduces long peak arrays to bars (48) so it keeps its gaps at card width; empty peaks draw flat placeholder bars. It is decorative (aria-hidden): the card's title names the recording.

<MediaCard
  size="lg"
  title={file.name}
  image={null}
  fallback={<AudioWaveform peaks={file.peaks} className="h-1/2 px-4" />}
  imageBadge={formatDuration(file.duration)}
/>

Decode limitCopy Anchor Link

Without peaks, the waveform variant decodes the file itself only up to maxDecodeBytes (20 MB). A larger file — by its Content-Length, or as soon as the download passes the limit — is never decoded, and the player shows the plain seek slider instead of a flat, fake waveform.

With copyCopy Anchor Link

Use title and description when the player needs a visible track name or short context.

Docked with closeCopy Anchor Link

Set docked to pin the player to the bottom of its scroll column. It is position: sticky, so it sits at the end of the column's content and stays on its bottom edge while the column scrolls, with a border, the popover surface and a shadow, padded clear of the bottom safe-area inset. A docked player is a landmark region named by label, so a screen-reader user can jump to it.

Pass open and onOpenChange to make it closable. The close button (named by closeLabel, "Close player" by default) pauses playback, calls onOpenChange(false) and hands focus back to the control that opened the player. A hidden player stays mounted and inert and slides out with the docked-control pair, so its playback position survives a hide. Escape does not close it: Escape belongs to whatever overlay the page opens above it.

FloatingCopy Anchor Link

variant="floating" is a one-line pill — back 10s, play (the filled primary), forward 10s, elapsed, seek, total, a speed menu, a volume popover and close — with no visible title (title is not shown; label still names the region). Every icon button is size-8, play is size-9, times are tabular. The seek bar is a thin Slider with a buffered shade, a time readout on hover and a thumb that appears on hover. Space plays or pauses and ←/→ move 5 seconds anywhere on the pill. It is centred in its container and sticky 16px above the bottom of its scroll column. Render it as the last child of the column it floats over, so it centres on the content, not across a sidebar. Below the sm breakpoint it spans the full width on the bottom edge, clear of the safe-area inset, with tighter padding and no volume control. It always sits at the bottom of its flex column (mt-auto), however short the page. With an end rail beside the content, set --audio-player-inset-end on an ancestor to the width the rail takes and the pill centres on the main column instead of overlapping the rail; inside AppShell, a RecordLayoutRail sets it (22rem) automatically from the 5xl content width. Like docked, it is a region named by label.

Global playerCopy Anchor Link

To keep one recording playing while the reader moves between pages, mount AudioPlayerProvider in the app shell above the routes and render GlobalAudioPlayer at the end of the main content column. Any page calls useGlobalPlayer().open(track, { at }); opening the same id again seeks instead of reloading. The pill's title links back to href through renderLink, so the jump is a client navigation. useGlobalPlayerTime() reads the position from its own context — feed it to Transcript's currentTime — and onSourceExpired on the track renews an expired signed URL.

Import the provider, the hooks and GlobalAudioPlayer from audio-player-global in the app shell: that module is small and loads the player UI only once a recording opens (open() starts the load), so routes that never play one ship no player code. audio-player re-exports the same names.

// app shell — import from "@/components/ui/audio-player-global"
<AudioPlayerProvider renderLink={(props) => <Link {...props} />}>
  <main className="flex min-h-0 flex-1 flex-col overflow-auto">
    {children}
    <GlobalAudioPlayer />
  </main>
</AudioPlayerProvider>;

// a meeting page
const player = useGlobalPlayer();
const time = useGlobalPlayerTime();
const track = {
  id: meeting.id,
  src: mintAudioUrl,
  onSourceExpired: mintAudioUrl,
  title: meeting.title,
  href: `/meetings/${meeting.id}`,
};
<Button onClick={() => player.open(track)}>Play</Button>;
<Transcript
  currentTime={player.track?.id === meeting.id ? time : undefined}
  onSeek={(at) => player.open(track, { at })}
/>;

In a listCopy Anchor Link

deferControls renders a light play button — and the still waveform when peaks are given — until the first play, then the full controls, with focus moved to their play button. Use it for a list of recordings, where a full player on every row costs more than it gives. Any play (mediaRef, actionsRef) mounts the controls as well. It does not apply to floating or docked.

<AudioPlayer
  src={file.url}
  label={file.name}
  peaks={file.peaks}
  deferControls
/>

One at a timeCopy Anchor Link

Starting a player pauses any other that is playing — AudioPlayer, VideoPlayer, the global player and the FileViewer stages alike — and nothing resumes by itself. exclusive={false} opts a player out both ways (a preview that may play under another).

While the global player is open it sets --dock-inset-bottom (its height plus 8px) on the AppShell root, so an ActionBar — a list's selection bar — floats 8px above the pill instead of on it, and a selecting DataList keeps its last row clear of both.

Lazy sourceCopy Anchor Link

src also takes a function that resolves a URL, for a short-lived signed URL you only want to fetch when someone listens. It is called once, on the first play (or the first actionsRef seek), and the result is kept. While it resolves the play button shows a spinner. To load a different recording, remount the player with a new key.

<AudioPlayer
  src={() => getSignedUrl(recording.id)}
  label={`${recording.title} recording`}
/>

Loading and errorCopy Anchor Link

The player renders its full layout from the start, and no state changes its height. loading — and a lazy src resolving, or the media buffering after play — swaps the play button's glyph for a spinner of the same size in the same button, which gets aria-busy and keeps its name and its action. loadingLabel ("Loading audio…") is announced once to screen readers and never shown. error renders an alert in the destructive ink with a "Try again" button (retryLabel). The retry reloads the source, resolves a lazy src again and calls onRetry, where you clear error.

A signed URL can expire while the page is open. Pass onSourceExpired — an async function that returns a fresh URL — and a media error calls it once: the player loads the new URL and resumes at the same position, playing if it was. Only a second failure, or a rejection, shows the error line; "Try again" and a new src arm the renewal again.

<AudioPlayer
  label="Meeting recording"
  src={mintAudioUrl}
  onSourceExpired={mintAudioUrl}
/>

Seek from outsideCopy Anchor Link

To jump the player from a transcript line or a chapter list, attach actionsRef. Its seek(seconds, { play }), play() and pause() are the player's own: a seek made before the metadata loads is queued and applied on loadedmetadata, and a lazy src is resolved first. mediaRef still exposes the raw <audio> element for anything else, such as reading currentTime.

const actions = React.useRef<AudioPlayerActions>(null);
const media = React.useRef<HTMLAudioElement>(null);

<AudioPlayer
  src={url}
  label="Call recording"
  actionsRef={actions}
  mediaRef={media}
/>;
<Button onClick={() => actions.current?.seek(line.start, { play: true })}>
  {line.text}
</Button>;

Playback ratesCopy Anchor Link

Pass playbackRates and defaultPlaybackRate to control the options the tappable speed control cycles through. Each tap advances to the next rate in order and wraps past the end.

PlaygroundCopy Anchor Link

Every AudioPlayer prop, auto-generated from its TypeScript types.

API ReferenceCopy Anchor Link

AudioPlayerProviderCopy Anchor Link

GlobalAudioPlayerCopy Anchor Link

AudioWaveformCopy Anchor Link

useGlobalPlayerCopy Anchor Link

AccessibilityCopy Anchor Link

• Pass a descriptive label; it names the media element and prefixes every custom control.
• The seek rail composes Slider, so keyboard and screen-reader slider semantics stay intact.
• Icon-only transport buttons are Button size="icon", each carrying its own aria-label.
• Tooltips expose the primary keyboard shortcuts for pointer and keyboard users.
• Playback speed is a single tappable button that cycles the rates; its accessible name always announces the current speed.
• Rewind and forward are visible buttons on both layouts (inline on a wide player; flanking play/pause on the second line of a narrow, mobile-width player) and keyboard shortcuts anywhere inside the player (J / L).
• The transcript control appears only on the narrow layout and only when onTranscriptClick is supplied; it carries an accessible name derived from label and opens whatever the consumer wires.
• Mute and a volume rail are present in both layouts. The rail is a vertical Slider that opens from the mute button on hover or focus; mute also stays on the M key. (Before the 2026-09-07 audit, audio had no volume control at all and mute was keyboard-only.)
• The seek thumb is hidden at rest only where a pointer can hover. On a touch device it stays visible — without it there is no scrub affordance at all.
• The native <audio> element is used as the media engine and does not expose browser-native controls; VegaStack renders the consistent control surface.
• A docked player is a region named by label, not a toolbar: every control keeps its own tab stop and the seek rail keeps its arrow keys. A hidden player is inert, so nothing invisible is focusable, and closing returns focus to the control that opened it. Escape does not close it.
• loading is announced once through a polite live region (buffering is not announced), and the play button carries aria-busy while it shows the spinner; error is a role="alert" line in the -text ink, with the retry as a separate button after it.

Do / Don'tCopy Anchor Link