Audio Player

audio

AudioPlayerAudioProp

—

Audio prop can be either: 1. An array or a single {@link AudioPlayerClip } (pre-loaded elements with absolute startedAt/endedAt for transcript alignment). 2. An array or a single URL string for simpler cases. URLs and elements may grant access to sensitive recordings. Do not log, persist in localStorage, or attach to DOM attributes for debugging.

activePlayerId

string | null

—

When set, identifies which player is globally active. When this changes to a different value than playerId, this player will stop. Clearing to null stops the player that was active. Use opaque IDs (e.g. chatroom or clip keys), not names, phone numbers, or free text — values may surface in React DevTools.

currentTime

number

—

Optional (for controlled mode). Current playback time in ms (global timeline)

description

string

—

Secondary line under the title (e.g. formatted date/time).

includePlaybackRates

boolean

—

When true, shows the playback-rate dropdown with the default rates [0.75, 1, 1.25, 1.5, 2].

isPlaying

boolean

—

Optional (for controlled mode). Whether playback is currently active.

onManualTimeScrub

((time: number) => void)

—

Callback when manual scrub occurs

onPlaybackRateChange

((rate: number) => void)

—

Fired when the user picks a new rate.

onPlayingChange

((playing: boolean) => void)

—

Callback when playback state changes

onPressNext

(() => void)

—

Next-track handler. When provided, shows the next-track button. Also used by shouldAutoPlayNext.

onPressPlay

(() => Promise<void | AudioPlayerAudioProp>)

—

Async callback invoked before playback starts (e.g. fetch signed or access-controlled URLs). If this returns audio URLs/clips, they will replace the current audio prop. If it returns void/undefined, the existing audio prop is used. Do not log return values or errors that embed URLs — they may grant access to sensitive audio.

onPressPrevious

(() => void)

—

Previous-track handler. When provided, shows the previous-track button.

onTimeChange

((time: number) => void)

—

Callback for every time change (via natural progression or manual scrub)

playbackRate

number

—

Controlled playback speed. When omitted, the player manages rate internally.

playerId

string

—

This player's ID for coordination with {@link AudioPlayerProps.activePlayerId}. Prefer an opaque identifier; avoid PII in this value.

shouldAutoPlayNext

boolean

false

When true, calls onPressNext automatically when the current audio finishes.

showTimeStamps

boolean

—

Show time stamps on the player

skipInterval

number

—

When set, shows skip backward/forward buttons that jump by this many milliseconds.

timeDisplayMode

TimeDisplayMode

TimeDisplayMode.Combined

Controls how timestamps are displayed when showTimeStamps is true. - combined (default): "00:15 / 01:30" shown together after the volume control - split: current time shown before the slider, total time shown after the slider

timeNotifyIntervalMs

number

—

Target ms between playback time samples (slider, timestamps, onTimeChange). Default 250. Values **under 250** use rAF + currentTime so intervals like 10–50 ms work; the timeupdate event alone is typically only ~4 Hz in browsers.

title

string

—

Title shown on the left of the bar (e.g. resource/seat name). Avoid PII you don't want in the DOM.

variant

AudioPlayerVariant

—

Layout variant. Omit for the standard inline bar (small icons, no section dividers). Minimal — play/pause only. Full — large icons and bordered sections per universal player mocks.