Prepared Docs

Overview

AudioPlayer from @prepared911/ui-audio-player is the minimal, inline player used everywhere dispatch surfaces audio: call records in a row, evidence in a drawer, voice notes in a timeline. It's a play/pause cluster with an optional scrub slider, timestamps, and skip controls—not a full media player. The mental model is "the fastest path from 'see a clip' to 'hear the clip'".

Under the hood it wraps a small state machine around <audio>; callers supply the source URL (or an async resolver), volume and speed defaults, and whether to show timestamps or skip buttons. The cluster stays compact so it slots into row heights and condensed panels without reflow.

When to use

Inline review inside table rows

Use AudioPlayer in DataTable cells or compact list rows where operators click to sample a clip without leaving the list. Keep it in-row so the review context—caller, timestamp, outcome—stays visible alongside playback.

Playback inside drawers and detail panels

Drawers that expose evidence, training clips, or caller-side audio should host AudioPlayer in the body. Combine with DataList entries for metadata; the player's compact footprint leaves room for text context above and below.

Short clips with a clear start and end

For one-to-three-minute clips—voicemails, call snippets, short recordings—the slim control is ideal. Users scrub, listen, and move on without the cognitive overhead of a full player.

When not to use

Long-form audio review that benefits from waveform visualization or region annotations. Reach for WaveformPlayer instead.
Background ambient audio. Don't autoplay or loop with AudioPlayer; it's for deliberate review.
Multiple simultaneous players on a view without coordination. If users might play two clips at once, wrap them in a controller that pauses siblings on play.
Video content. AudioPlayer has no video surface; use a product-owned video component.

Composition

AudioPlayer exposes a handful of slots and props:

Source. src as URL or async resolver (for short-lived signed URLs). Handle loading and error states explicitly when using a resolver.
Controls. Play/pause is always present. showSkipButtons adds ±15s skips; showTimeStamps shows current and total duration; showSlider (on by default) exposes the scrub slider.
Speed and volume. Optional controls for playback rate and mute; default speeds are 1×, 1.5×, 2×.
Imperative ref. The ref exposes play, pause, seekTo, and getCurrentTime, so callers can pair multiple players or sync with an external transcript.

Content guidelines

Button titles. Localize and describe the action—"Play recording", "Pause recording", "Skip forward 15 seconds"—so screen reader users get the same cue as sighted users.
Error and loading strings. Surface load failures as inline text ("Audio unavailable") rather than silent broken buttons; retry is better than a stuck spinner.
Timestamp formatting. Use mm:ss for clips under an hour, hh:mm:ss past that. Stay consistent with the rest of the page; don't mix relative and absolute formats.

Behavior and states

Async sources

If src is a promise, the player should render the cluster in a disabled, "loading" state while the URL resolves, then enable controls. A failed resolve shows an inline message and disables play; don't leave the user guessing.

Error handling

When the underlying <audio> errors, render an inline error instead of surfacing browser default messaging. If the error is transient (network), offer a retry that re-invokes the source resolver.

Concurrent playback

In views where multiple players may appear (call list, timeline), pause siblings on play. The shared controller pattern is to lift active-player state into context and have each player observe it.

Offline and restricted networks

For dispatch workflows that may run on restricted networks, show a clear message when the CDN is unreachable. The cluster should gracefully degrade—timestamps visible, scrub disabled—rather than vanish.

Best practices

Keep the player compact; don't grow it into a full media surface.
Pair playback with row or panel context so the operator knows what they're hearing.
Pause other players when starting a new one; avoid overlapping audio.
Show errors inline and always offer retry when transient.

Don't

Don't autoplay on route entry or row hover; audio should start on user action.
Don't hide timestamps when users need to cue to a specific moment.
Don't hide controls behind hover—these are interactive cells; controls must be visible on focus and touch.
Don't rely on color alone to convey playback state.

Accessibility

IconButton play/pause with visible tooltip titles, keyboard-operable slider, and inline error announcements keep AudioPlayer usable with screen readers and keyboards. See the Accessibility page for labeling patterns, live-region decisions, and multi-player focus order.

Waveform player: review long clips with waveform and regions.
Icon button: the control primitive used inside the cluster.
Slider: the scrub slider used for seek.

Calendar Utilities / Accessibility

Audio Player / API and Development

Overview

When to use

Inline review inside table rows

Playback inside drawers and detail panels

Short clips with a clear start and end

Offline and restricted networks

Best practices

Accessibility

Related Components

Overview

When to use

Inline review inside table rows

Playback inside drawers and detail panels

Short clips with a clear start and end

For one-to-three-minute clips—voicemails, call snippets, short recordings—the slim control is ideal. Users scrub, listen, and move on without the cognitive overhead of a full player.

When not to use

Long-form audio review that benefits from waveform visualization or region annotations. Reach for WaveformPlayer instead.
Background ambient audio. Don't autoplay or loop with AudioPlayer; it's for deliberate review.
Multiple simultaneous players on a view without coordination. If users might play two clips at once, wrap them in a controller that pauses siblings on play.
Video content. AudioPlayer has no video surface; use a product-owned video component.

Composition

AudioPlayer exposes a handful of slots and props:

Source. src as URL or async resolver (for short-lived signed URLs). Handle loading and error states explicitly when using a resolver.
Controls. Play/pause is always present. showSkipButtons adds ±15s skips; showTimeStamps shows current and total duration; showSlider (on by default) exposes the scrub slider.
Speed and volume. Optional controls for playback rate and mute; default speeds are 1×, 1.5×, 2×.
Imperative ref. The ref exposes play, pause, seekTo, and getCurrentTime, so callers can pair multiple players or sync with an external transcript.

Content guidelines

Button titles. Localize and describe the action—"Play recording", "Pause recording", "Skip forward 15 seconds"—so screen reader users get the same cue as sighted users.
Error and loading strings. Surface load failures as inline text ("Audio unavailable") rather than silent broken buttons; retry is better than a stuck spinner.
Timestamp formatting. Use mm:ss for clips under an hour, hh:mm:ss past that. Stay consistent with the rest of the page; don't mix relative and absolute formats.

Behavior and states

Async sources

Error handling

When the underlying <audio> errors, render an inline error instead of surfacing browser default messaging. If the error is transient (network), offer a retry that re-invokes the source resolver.

Concurrent playback

In views where multiple players may appear (call list, timeline), pause siblings on play. The shared controller pattern is to lift active-player state into context and have each player observe it.

Offline and restricted networks

Best practices

Keep the player compact; don't grow it into a full media surface.
Pair playback with row or panel context so the operator knows what they're hearing.
Pause other players when starting a new one; avoid overlapping audio.
Show errors inline and always offer retry when transient.

Don't

Don't autoplay on route entry or row hover; audio should start on user action.
Don't hide timestamps when users need to cue to a specific moment.
Don't hide controls behind hover—these are interactive cells; controls must be visible on focus and touch.
Don't rely on color alone to convey playback state.