Waveform

A static waveform of a clip with a smooth playhead, seeking, hover time, regions and markers.

2 min read · 317 words

Installation

$ pnpm dlx shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/waveform.json

$ npx shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/waveform.json

$ yarn dlx shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/waveform.json

$ bunx --bun shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/waveform.json

Usage

<script lang="ts">
	import { Waveform } from "#lib/components/ui/waveform/index.js";
	import { useAudioPlayer } from "#lib/hooks/use-audio-player.svelte.js";
	import { useWaveformData } from "#lib/hooks/use-waveform-data.svelte.js";

	let { src }: { src: string } = $props();

	const player = useAudioPlayer(() => ({ src }));
	const waveform = useWaveformData(() => src);
</script>

<Waveform
	duration={waveform.duration}
	onSeekCommit={player.seek}
	peaks={waveform.peaks}
	time={player.time}
/>

Pass time (a frame source) for a playhead that moves every frame without going through Svelte state, or bind currentTime for plain controlled use.

Anatomy

<Waveform>
	<WaveformCanvas />
	<WaveformCursor />
	<WaveformHover />
	<WaveformRegion />
	<WaveformMarker />
</Waveform>

Examples

Variants

bars

mirror

line

Regions and markers

Intro ends

Clip 0:09 – 0:22

Theming

Variable or attribute	Meaning
`--waveform`	Unplayed colour, default `muted-foreground`
`--waveform-progress`	Played colour, default `primary`
`--waveform-cursor`	Playhead colour
`--waveform-position`	Live playhead position, 0..1
`data-loading`, `data-dragging`, `data-disabled`	State

Accessibility

When interactive, the waveform is a slider with aria-valuetext such as "1:24 of 3:40". Arrow keys seek by step, Shift by largeStep, and Home and End jump to the ends. Region edges are separate sliders.

API reference

Waveform

Prop	Type	Default
`peaks` 0..1, from useWaveformData.	`ArrayLike<number> \| null`	—
`duration` Seconds.	`number`	—
`currentTime` Playhead in seconds. Bindable.	`number`	`0`
`time` A smooth playhead with no state updates.	`FrameSource<number> \| null`	—
`onSeek` While seeking.	`(time) => void`	—
`onSeekCommit` On release or after keyboard seeking.	`(time) => void`	—
`step / largeStep` Seconds for the keyboard.	`number`	`5 / 15`
`variant`	`"bars" \| "line" \| "mirror"`	`"bars"`
`barWidth / barGap / barRadius` Pixels.	`number`	`2 / 1 / 1`
`interactive` false is display only.	`boolean`	`true`
`loading` Shows a skeleton.	`boolean`	`false`
`disabled`	`boolean`	`false`

WaveformRegion

Prop	Type	Default
`start / end` Seconds. Bindable.	`number`	—
`onValueChange`	`({ start, end }) => void`	—
`resizable` Drag the edges.	`boolean`	`true`
`draggable` Drag the whole region.	`boolean`	`true`
`minLength` Seconds.	`number`	`0.1`

WaveformMarker

Prop	Type	Default
`time` Seconds. Children become the label.	`number`	—