# Waveform

Audio you can see and scrub: a waveform over a native audio element, with chapters, speed, skips and an imperative handle.

- Family: Signature, imported from `mizu-ui` or `mizu-ui/signature`
- Docs: https://mizu.user64bit.world/components/waveform
- Source: https://github.com/0xuser64bit/mizu/blob/main/packages/mizu/src/signature/Waveform.tsx

## Usage

```tsx
import { Waveform } from "mizu-ui";

export function Example() {
  const src = "/audio/calibration.wav";
  return <Waveform src={src} label="Calibration tone, 440 Hz" />;
}
```

## Copy it with the shadcn CLI

```sh
npx shadcn@latest init 0xuser64bit/mizu/preset # once, where there is no components.json
npx shadcn@latest add 0xuser64bit/mizu/waveform
```

## Props

- `src / label`: `string`. Playable source and accessible name. The example uses public/audio/calibration.wav from this repository; copy it to your app's public/audio folder or supply your own audio URL. The npm package and registry do not install media assets.
- `peaks`: `number[]`. Normalised 0–1 amplitudes. Omit to decode from the source (same-origin or CORS-enabled).
- `markers`: `WaveformMarker[]`. Chapters or comments: id, time in seconds and label. Listed beneath with durations.
- `duration`: `number`. Seconds to show before the media reports its own.
- `rates / height`: `number[] / number` (default `[1, 1.25, 1.5, 2] / 72`). Speed cycle and waveform height.
- `onTimeUpdate / onPlayingChange`: `function`. Follow playback, e.g. to highlight a transcript.
- `ref`: `WaveformHandle`. play(), pause() and seek(seconds) for external controls.

## Keyboard

- Space K: Play or pause (on the waveform)
- ← →: Seek five seconds (Shift: thirty)
- J L: Back or forward ten seconds
- [ ]: Previous or next chapter
- Home End: Start or end

## Accessibility

The waveform is a slider with readable time (“1:14 of 42:10”); arrows seek five seconds, Shift thirty. Play, skip and speed are labelled buttons, chapters are a real list with the current one marked. A failed source is announced with a retry. Letter shortcuts only apply while focus is inside the player.

## Motion

The waveform prints left to right once measured; while decoding, bars breathe in a travelling wave. The play glyph morphs into pause. Reduced motion keeps every state and removes the travel.