Prepared Docs

WaveformPlayer from @prepared911/ui-audio-player wraps @wavesurfer/react to render an interactive audio waveform. Optional plugins add hover time labels, zoom, draggable regions, and a timeline ruler. An imperative ref exposes play, pause, seekTo, duration queries, and more for parent-driven workflows.

Name	Type	Default	Description
`audioUrl`	`string`	—	URL to the audio file
`activeRegionColor`	`string`	`rgba(255, 255, 255, 0.25)`	Color applied to the region matching `activeRegionId` (default: `rgba(255, 255, 255, 0.25)`). Use any CSS color string.
`activeRegionId`	`string`	—	Id of the region that should be visually highlighted as active. The matching region's color is replaced with `activeRegionColor`; previously-active regions are restored to whatever color they had before activation. Works with regions in the `regions` prop and with regions created via drag selection — both are tracked internally once they exist on the wavesurfer instance.
`clickToSeek`	`boolean`	`true`	Enable click-to-seek on the waveform (default: true)
`enableDragSelection`	`boolean`	`false`	Enable drag selection for creating regions
`height`	`number`	`96`	Waveform height in pixels (default: 96)
`hoverOptions`	`WaveformHoverOptions`	—	Hover plugin options
`isUpdating`	`boolean`	`false`	When the waveform is already shown (`isReady`) and new audio is being prepared (e.g. redaction regen), show a subtle pulse over the existing canvas instead of the initial loading spinner.
`maxZoom`	`number`	`1000`	Maximum zoom level
`minZoom`	`number`	`10`	Minimum zoom level
`normalize`	`boolean`	`true`	Whether to normalize waveform (default: true)
`onEnded`	`(() => void)`	—	Callback when playback reaches the end
`onError`	`((error: Error) => void)`	—	Callback when an error occurs
`onPlayingChange`	`((isPlaying: boolean) => void)`	—	Callback when playback state changes
`onReady`	`((wavesurfer: WaveSurfer) => void)`	—	Callback when wavesurfer is ready
`onRegionCreated`	`((region: SingleRegion) => void)`	—	Callback when a region is created (via drag selection or programmatically)
`onRegionsPluginReady`	`((plugin: RegionsPlugin) => void)`	—	Callback when regions plugin is ready
`onSeek`	`((time: number) => void)`	—	Callback when user seeks to a new position
`onTimeChange`	`((currentTime: number) => void)`	—	Callback when current time changes during playback
`onZoomChange`	`((zoomLevel: number) => void)`	—	Callback when zoom level changes (from scroll wheel)
`plugins`	`WaveformPlugin[]`	`[]`	Array of plugins to enable
`regions`	`WaveformRegion[]`	`[]`	Array of regions to display
`timelineOptions`	`WaveformTimelineOptions`	—	Timeline plugin options
`zoomLevel`	`number`	`50`	Current zoom level in pixels per second
`zoomOptions`	`WaveformZoomOptions`	—	Zoom plugin options

Name	Type	Default	Description
`audioUrl`	`string`	required	HTTP(S) URL to the audio file. Empty or invalid URLs show an error state.
`plugins`	`WaveformPlugin[]`	`[]`	Enable `Hover`, `Zoom`, `Regions`, `Timeline` (see `WaveformPlugin` enum).
`zoomLevel`	`number`	`50`	Current zoom (pixels per second); paired with `minZoom` / `maxZoom`.
`minZoom`	`number`	`10`	Lower zoom bound.
`maxZoom`	`number`	`1000`	Upper zoom bound.
`onZoomChange`	`(zoom: number) => void`	—	Fires when zoom changes (e.g. scroll wheel).
`zoomOptions`	`WaveformZoomOptions`	—	Zoom plugin sensitivity (`scale`).
`regions`	`WaveformRegion[]`	—	Static regions when `Regions` plugin is enabled.
`onRegionsPluginReady`	`(plugin: RegionsPlugin) => void`	—	Regions plugin instance for advanced APIs.
`onRegionCreated`	`(region: Region) => void`	—	After drag-selection or programmatic create.
`enableDragSelection`	`boolean`	`false`	Allow drag-to-create regions.
`timelineOptions`	`WaveformTimelineOptions`	—	Tick intervals and labels for the timeline plugin.
`hoverOptions`	`WaveformHoverOptions`	—	Hover cursor line and label styling.
`height`	`number`	`96`	Waveform height in pixels.
`normalize`	`boolean`	`true`	Normalize waveform amplitude.
`onReady`	`(ws: WaveSurfer) => void`	—	WaveSurfer ready callback.
`onError`	`(error: Error) => void`	—	Load or runtime errors.
`onPlayingChange`	`(isPlaying: boolean) => void`	—	Play state changes.
`onTimeChange`	`(currentTime: number) => void`	—	Time updates during playback.
`onSeek`	`(time: number) => void`	—	User seek position.
`onEnded`	`() => void`	—	Playback completed.
`clickToSeek`	`boolean`	`true`	Click waveform to seek.

Waveform Player

Props

Storybook

Markdown reference

Import

With hover (local sample)

Default (no plugins)

Hover plugin (remote URL)

Zoom plugin

Timeline plugin

Regions plugin

Basic waveform

Regions and zoom

Waveform Player / Usage

Waveform Player / Accessibility