# Audio player

A React component in [Beamline](https://beamline.io/)'s [Voice & audio](https://beamline.io/components/voice) category. Live demo: https://beamline.io/components/audio-player

One audio element and its controls: play with a loading state, a scrub bar with time, skip, speed and a playlist whose rows play into the same player. Use the ready layouts or compose the parts.

## Use it for

- Call recordings, voice notes and generated speech in an app.
- A list of recordings that play one at a time in a shared player.

## Not for

- Video ([video](https://beamline.io/components/video)).
- A transcript that follows the audio word by word ([transcript-viewer](https://beamline.io/components/transcript-viewer)).
- Only a position control for your own player ([scrub-bar](https://beamline.io/components/scrub-bar)).

## Anatomy

- root (one <audio>)
- play button (loading while buffering)
- title and subtitle
- scrub bar with elapsed and total time
- skip back / forward
- speed menu
- playlist (rows: state, title, subtitle, length)
- error line with retry

## Variants

- **layout**: card, inline

## States

- empty (no source)
- loading metadata (length unknown, hatched)
- paused
- playing
- buffering
- ended
- error (file failed: the words and Retry replace the title; the play button turns quiet so Retry leads)
- playlist: current row (filled disc in the accent, row tint), playing row (level bars and "Playing")

## Keyboard

- Tab reaches play, skip, the scrub bar, speed and each playlist row
- On the scrub bar: ← → seek 5 s, Page keys a tenth, Home / End, Space or K play and pause
- Speed menu: ↑ ↓ and Enter
- Playlist row: Enter or Space plays it (or pauses the one playing)

## Motion

The playing row's level bars move only while it plays and stop under reduced motion (the row says Playing instead). Everything else is instant.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src / title / subtitle` | `string` | — | One recording; or pass tracks. |
| `tracks` | `AudioTrack[]` | — | { id, src, title, subtitle?, duration? }; rows of the playlist. |
| `value / defaultValue / onValueChange` | `string` | — | Id of the loaded track. |
| `rate / defaultRate / onRateChange` | `number` | `1` |  |
| `rates` | `number[]` | `[0.75, 1, 1.25, 1.5, 2]` |  |
| `layout` | `"card" \| "inline"` | `"card"` | Ready layouts used when there are no children. |
| `autoAdvance` | `boolean` | `true` | Play the next track when one ends. |
| `onEnded` | `(track: AudioTrack) => void` | — |  |
| `children` | `ReactNode` | — | Your own composition of AudioPlayerButton, AudioPlayerScrubber, AudioPlayerTime, AudioPlayerSkip, AudioPlayerSpeed, AudioPlayerTitle, AudioPlayerPlaylist; useAudioPlayer() reads the state. |
| `classNames` | `AudioPlayerClassNames` | — |  |
| `style / ref` | `CSSProperties / native Ref` | — |  |
| `AudioPlayer parts native props / ref` | `Button, div, span, ul or ScrubBar props` | — | Built-in playback handlers and required media accessibility remain owned by the player; classNames combines player and part overrides. |

## Built from

- button
- [scrub-bar](https://beamline.io/components/scrub-bar)
- [dropdown-menu](https://beamline.io/components/dropdown-menu)
- tooltip

## Dependencies

`lucide-react`

## Import

```tsx
import { AudioPlayer, AudioPlayerButton, AudioPlayerTitle, AudioPlayerScrubber, AudioPlayerTime, AudioPlayerSkip } from "@/components/audio-player/audio-player";
```

## Get it

Audio player is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Voice & audio

- [Bar visualizer](https://beamline.io/components/bar-visualizer): A row of bars that says what a voice agent is doing: a sweep while connecting, the person's voice while listening, a slow breath while thinking, the…
- [Conversation bar](https://beamline.io/components/conversation-bar): The control bar of a voice call with an agent: one button to call and hang up, the agent's state as bars, a call timer, mute, and typing when talking is…
- [Live waveform](https://beamline.io/components/live-waveform): Loudness drawn as it happens: a scrolling history of the microphone (or any live source) or its spectrum, a calm processing state while words are…
- [Matrix](https://beamline.io/components/matrix): A dot-matrix display: animated frame sets (loading, pulse, wave, syncing), text and digits in a 5×7 font, or a VU meter of levels or a live source. One…
- [Microphone selector](https://beamline.io/components/mic-selector): Choose the microphone, test it with a live level and mute it, with every permission and device state spelled out: not yet allowed, blocked (and how to…
- [Orb](https://beamline.io/components/orb): The agent's presence: a thin ring of light around a lens in the brand's hue that holds still at rest, sends an arc round while thinking and widens with…
- [Scrub bar](https://beamline.io/components/scrub-bar): A seekable timeline for audio or video: elapsed and total time, what has loaded, chapter marks, a time preview under the pointer, and the full keyboard…
- [Speech input](https://beamline.io/components/speech-input): A text field you can speak into: the mic dictates through any speech-to-text provider, the phrase being heard shows apart from the finished words, and…
- [Transcript viewer](https://beamline.io/components/transcript-viewer): A recording and its words together: the spoken word lights up as it plays and the transcript follows it, any word or paragraph time plays from there…
- [Voice button](https://beamline.io/components/voice-button): The control that starts and stops talking: click to toggle or hold to talk (pointer, Space, Enter or a global shortcut), with a live level while…
- [Voice picker](https://beamline.io/components/voice-picker): Choose a text-to-speech voice from a searchable list (name, accent, tone, use) and hear it first: each voice has its own orb, previews play one at a time…
- [Waveform](https://beamline.io/components/waveform): The shape of a recording: one bar per slice of loudness, fitted to any width, with the played part in the accent, unmeasured slices hatched and a loading…