Audio Player

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

AudioPlayer from @prepared911/ui/audio-player renders playback controls for emergency and dispatch audio. It supports URL strings, one or more clips with timeline alignment metadata, controlled or uncontrolled time and play state, optional skip controls, mute, and timestamp display modes. copy is required and holds every visible and accessibility string. Recordings may include sensitive content; the component does not log audio URLs or onPressPlay results—callers must avoid sending those values to analytics or error reporters.

Props

Name	Type	Default	Description
`audio`	`AudioPlayerAudioProp`	—	Audio source: one clip, several clips on an absolute timeline, one URL, or several URLs. URLs and elements may grant access to sensitive recordings. Do not log, persist in storage, or attach to DOM attributes for debugging.
`copy`	`AudioPlayerCopy`	—	Required copy for every visible and accessibility string.
`activePlayerId`	`string \| null`	—	When set, identifies which player is globally active. When this changes to a different value than `playerId`, this player stops. Clearing to `null` stops the player that was active. Use opaque IDs, not names or phone numbers.
`currentTime`	`number`	—	Controlled absolute current time in milliseconds on the timeline.
`defaultCurrentTime`	`number`	—	Uncontrolled initial absolute current time in milliseconds.
`defaultMuted`	`boolean`	—	Uncontrolled initial mute state.
`defaultPlaybackRate`	`number`	—	Uncontrolled initial playback speed.
`defaultPlaying`	`boolean`	—	Uncontrolled initial playback state.
`defaultVolume`	`number`	—	Uncontrolled initial volume from 0 to 1.
`description`	`LocalizedMessage \| DisplayValue`	—	Secondary line under the title in the Full variant.
`includePlaybackRates`	`boolean`	—	When true, renders the playback rate menu.
`locale`	`string`	—	BCP 47 locale for time and rate formatting.
`muted`	`boolean`	—	Controlled mute state.
`onError`	`((details: AudioPlayerErrorDetails) => void)`	—	Called when playback fails with a closed reason.
`onManualTimeScrub`	`((timeMs: number) => void)`	—	Called when the user scrubs the seek slider.
`onMutedChange`	`((muted: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called when mute state changes.
`onPlaybackRateChange`	`((rate: number, details: ChangeDetails<ChangeReason>) => void)`	—	Called when the selected playback rate changes.
`onPlaybackStarted`	`(() => void)`	—	Called each time a clip's `play()` resolves.
`onPlayingChange`	`((playing: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called when playback state changes.
`onPressNext`	`(() => void)`	—	Next-track handler. When provided, shows the next-track button.
`onPressPlay`	`(() => Promise<void \| AudioPlayerAudioProp>)`	—	Async callback invoked before playback starts. When it resolves audio, that result replaces `audio` for this instance. Do not log return values or rejections that may carry sensitive URLs.
`onPressPrevious`	`(() => void)`	—	Previous-track handler. When provided, shows the previous-track button.
`onTimeChange`	`((timeMs: number, details: ChangeDetails<ChangeReason>) => void)`	—	Called when the absolute timeline position changes.
`onVolumeChange`	`((volume: number, details: ChangeDetails<ChangeReason>) => void)`	—	Called when volume changes.
`playbackRate`	`number`	—	Controlled playback speed.
`playerId`	`string`	—	Opaque id for the page-wide single-active registry. When omitted, this player never joins the registry.
`playing`	`boolean`	—	Controlled playback state.
`preload`	`AudioPreload`	—	Preload policy for URL sources. Defaults to {@link AudioPreload.Metadata}.
`shouldAutoPlayNext`	`boolean`	—	When true, calls `onPressNext` automatically when the current audio finishes.
`showTimeStamps`	`boolean`	—	Whether to show elapsed and total timestamps.
`skipInterval`	`number`	—	When set, renders skip buttons that move by this many milliseconds.
`timeDisplayMode`	`TimeDisplayMode`	—	How timestamps are arranged when `showTimeStamps` is true.
`timeNotifyIntervalMs`	`number`	—	Target minimum milliseconds between playback time samples.
`title`	`LocalizedMessage \| DisplayValue`	—	Title shown in the Full variant. Avoid PII you do not want in the DOM.
`totalDurationHintMs`	`number`	—	Display-only total duration before clips load.
`variant`	`AudioPlayerVariant`	—	Layout variant. Defaults to {@link AudioPlayerVariant.Standard}.
`volume`	`number`	—	Controlled volume from 0 to 1.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Markdown reference

Name	Type	Default	Description
`audio`	`AudioPlayerAudioProp`	required	URL string(s), `AudioPlayerClip` object(s), or arrays of either. Clips may include `startedAt` / `endedAt` for transcript alignment.
`activePlayerId`	`string \| null`	—	When set with `playerId`, only one player with matching coordination stays active; others stop. Use opaque IDs.
`playerId`	`string`	—	This instance’s ID for coordination with `activePlayerId`.
`currentTime`	`number`	—	Controlled mode: current time in ms on the global timeline.
`playing`	`boolean`	—	Controlled mode: whether playback is active. `onPlayingChange` also receives change details.
`variant`	`AudioPlayerVariant`	—	Omit for the standard inline bar. `Minimal`: play/pause only (no slider, volume, timestamps). `Full`: large icons and bordered sections.
`showTimeStamps`	`boolean`	—	Show elapsed/total time when not `Minimal`.
`timeDisplayMode`	`TimeDisplayMode`	`Combined`	`Combined`: single "current / total" block. `Split`: current before slider, total after.
`skipInterval`	`number`	—	If set, shows skip back/forward buttons advancing by this many milliseconds.
`copy`	`AudioPlayerCopy`	required	Labels and announcements for every control.
`onPressPlay`	`() => Promise<AudioPlayerAudioProp \| void>`	—	Runs before playback; may return new audio to replace the current prop (e.g. signed URLs).
`onTimeChange`	`(time: number) => void`	—	Fires on playback progress and manual scrub.
`onManualTimeScrub`	`(time: number) => void`	—	Fires when the user scrubs the slider.
`onPlayingChange`	`(playing: boolean) => void`	—	Fires when play/pause state changes.

Also exported: TimeDisplayMode and AudioPlayerVariant enums, formatAudioTime, formatDurationHumanReadable, and type guards isAudioClip, isStringArray, isClipArray.

Import

Full player (split time + skip)

Combined timestamps

Minimal player

Single-active coordination

Use variant={AudioPlayerVariant.Minimal} for compact rows (e.g. table cells) where scrubbing and volume are not required.

Full player with coordination

Pair playerId and activePlayerId (often from React state) so opening playback in one list item stops others.

Lazy URL resolution

Use onPressPlay to fetch a signed or access-controlled URL when the user starts playback; return the resolved audio value to replace the initial prop.

Audio Player / Usage

Audio Player / Accessibility

On this page

Full player (split time + skip)

Combined timestamps

Minimal player

Single-active coordination

Full player with coordination

Lazy URL resolution

Audio Player

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Props

Name	Type	Default	Description
`audio`	`AudioPlayerAudioProp`	—	Audio source: one clip, several clips on an absolute timeline, one URL, or several URLs. URLs and elements may grant access to sensitive recordings. Do not log, persist in storage, or attach to DOM attributes for debugging.
`copy`	`AudioPlayerCopy`	—	Required copy for every visible and accessibility string.
`activePlayerId`	`string \| null`	—	When set, identifies which player is globally active. When this changes to a different value than `playerId`, this player stops. Clearing to `null` stops the player that was active. Use opaque IDs, not names or phone numbers.
`currentTime`	`number`	—	Controlled absolute current time in milliseconds on the timeline.
`defaultCurrentTime`	`number`	—	Uncontrolled initial absolute current time in milliseconds.
`defaultMuted`	`boolean`	—	Uncontrolled initial mute state.
`defaultPlaybackRate`	`number`	—	Uncontrolled initial playback speed.
`defaultPlaying`	`boolean`	—	Uncontrolled initial playback state.
`defaultVolume`	`number`	—	Uncontrolled initial volume from 0 to 1.
`description`	`LocalizedMessage \| DisplayValue`	—	Secondary line under the title in the Full variant.
`includePlaybackRates`	`boolean`	—	When true, renders the playback rate menu.
`locale`	`string`	—	BCP 47 locale for time and rate formatting.
`muted`	`boolean`	—	Controlled mute state.
`onError`	`((details: AudioPlayerErrorDetails) => void)`	—	Called when playback fails with a closed reason.
`onManualTimeScrub`	`((timeMs: number) => void)`	—	Called when the user scrubs the seek slider.
`onMutedChange`	`((muted: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called when mute state changes.
`onPlaybackRateChange`	`((rate: number, details: ChangeDetails<ChangeReason>) => void)`	—	Called when the selected playback rate changes.
`onPlaybackStarted`	`(() => void)`	—	Called each time a clip's `play()` resolves.
`onPlayingChange`	`((playing: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called when playback state changes.
`onPressNext`	`(() => void)`	—	Next-track handler. When provided, shows the next-track button.
`onPressPlay`	`(() => Promise<void \| AudioPlayerAudioProp>)`	—	Async callback invoked before playback starts. When it resolves audio, that result replaces `audio` for this instance. Do not log return values or rejections that may carry sensitive URLs.
`onPressPrevious`	`(() => void)`	—	Previous-track handler. When provided, shows the previous-track button.
`onTimeChange`	`((timeMs: number, details: ChangeDetails<ChangeReason>) => void)`	—	Called when the absolute timeline position changes.
`onVolumeChange`	`((volume: number, details: ChangeDetails<ChangeReason>) => void)`	—	Called when volume changes.
`playbackRate`	`number`	—	Controlled playback speed.
`playerId`	`string`	—	Opaque id for the page-wide single-active registry. When omitted, this player never joins the registry.
`playing`	`boolean`	—	Controlled playback state.
`preload`	`AudioPreload`	—	Preload policy for URL sources. Defaults to {@link AudioPreload.Metadata}.
`shouldAutoPlayNext`	`boolean`	—	When true, calls `onPressNext` automatically when the current audio finishes.
`showTimeStamps`	`boolean`	—	Whether to show elapsed and total timestamps.
`skipInterval`	`number`	—	When set, renders skip buttons that move by this many milliseconds.
`timeDisplayMode`	`TimeDisplayMode`	—	How timestamps are arranged when `showTimeStamps` is true.
`timeNotifyIntervalMs`	`number`	—	Target minimum milliseconds between playback time samples.
`title`	`LocalizedMessage \| DisplayValue`	—	Title shown in the Full variant. Avoid PII you do not want in the DOM.
`totalDurationHintMs`	`number`	—	Display-only total duration before clips load.
`variant`	`AudioPlayerVariant`	—	Layout variant. Defaults to {@link AudioPlayerVariant.Standard}.
`volume`	`number`	—	Controlled volume from 0 to 1.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Markdown reference

Name	Type	Default	Description
`audio`	`AudioPlayerAudioProp`	required	URL string(s), `AudioPlayerClip` object(s), or arrays of either. Clips may include `startedAt` / `endedAt` for transcript alignment.
`activePlayerId`	`string \| null`	—	When set with `playerId`, only one player with matching coordination stays active; others stop. Use opaque IDs.
`playerId`	`string`	—	This instance’s ID for coordination with `activePlayerId`.
`currentTime`	`number`	—	Controlled mode: current time in ms on the global timeline.
`playing`	`boolean`	—	Controlled mode: whether playback is active. `onPlayingChange` also receives change details.
`variant`	`AudioPlayerVariant`	—	Omit for the standard inline bar. `Minimal`: play/pause only (no slider, volume, timestamps). `Full`: large icons and bordered sections.
`showTimeStamps`	`boolean`	—	Show elapsed/total time when not `Minimal`.
`timeDisplayMode`	`TimeDisplayMode`	`Combined`	`Combined`: single "current / total" block. `Split`: current before slider, total after.
`skipInterval`	`number`	—	If set, shows skip back/forward buttons advancing by this many milliseconds.
`copy`	`AudioPlayerCopy`	required	Labels and announcements for every control.
`onPressPlay`	`() => Promise<AudioPlayerAudioProp \| void>`	—	Runs before playback; may return new audio to replace the current prop (e.g. signed URLs).
`onTimeChange`	`(time: number) => void`	—	Fires on playback progress and manual scrub.
`onManualTimeScrub`	`(time: number) => void`	—	Fires when the user scrubs the slider.
`onPlayingChange`	`(playing: boolean) => void`	—	Fires when play/pause state changes.

Also exported: TimeDisplayMode and AudioPlayerVariant enums, formatAudioTime, formatDurationHumanReadable, and type guards isAudioClip, isStringArray, isClipArray.

Import

Full player (split time + skip)

Combined timestamps

Minimal player

Single-active coordination

Use variant={AudioPlayerVariant.Minimal} for compact rows (e.g. table cells) where scrubbing and volume are not required.

Full player with coordination

Pair playerId and activePlayerId (often from React state) so opening playback in one list item stops others.

Lazy URL resolution

Use onPressPlay to fetch a signed or access-controlled URL when the user starts playback; return the resolved audio value to replace the initial prop.

Audio Player / Usage

Audio Player / Accessibility

On this page

Full player (split time + skip)

Combined timestamps

Minimal player

Single-active coordination

Full player with coordination

Lazy URL resolution