react-audio-wavekit

React components for audio waveform visualization and live recording.

Features

• Full TypeScript - Complete type safety with detailed type definitions
• Easy to Use - Simple API with sensible defaults, works out of the box
• Mobile Compatible - WASM fallback decoder for reliable mobile browser support
• Headless Hooks - Full control with raw audio data for custom implementations
• SSR Safe - Compatible with Next.js and other SSR frameworks

Installation

npm install react-audio-wavekit
# or
pnpm add react-audio-wavekit
# or
bun add react-audio-wavekit

Requirements: React 18+, Web Audio API, MediaRecorder API

Waveform

Visualize existing audio files (mp3, wav, etc.) with playhead and seek support.

AudioWaveform

Static waveform visualization with playhead and drag-to-seek.

▶ Demo

<AudioWaveform
  // Also accepts classnames, compatible with tailwind.
  className=""
  blob={audioBlob}
  currentTime={currentTime}
  duration={duration}
  onSeekStart={() => audio.pause()}
  onSeekDrag={(time) => setCurrentTime(time)}
  onSeekEnd={(time) => {
    audio.currentTime = time;
    audio.play();
  }}
  style={{
    // Or use classNames with Tailwind
    width: '400px',
    height: '100px',
  }}
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | blob | Blob \| null | - | Audio blob to visualize | | peaks | number[] | - | Pre-computed peaks (0-1 range, skips decoding) | | currentTime | number | - | Current playback time in seconds | | duration | number | - | Total audio duration in seconds | | onSeek | (time: number) => void | - | Callback for simple click-to-seek | | onSeekStart | () => void | - | Callback when drag starts (pause playback) | | onSeekDrag | (time: number) => void | - | Callback during drag (real-time updates) | | onSeekEnd | (time: number) => void | - | Callback when drag ends (resume playback) | | suspense | boolean | false | Enable React Suspense mode | | appearance | AudioWaveformAppearance | - | See Appearance Options |

SSR note: When suspense is true, decoding only starts on the client after mount. On the server (and during the first client render), the waveform renders without peaks, so wrap the component in a Suspense boundary to show a fallback during hydration.

Recorder

Real-time waveform visualization during recording using MediaRecorder API.

useAudioRecorder

Headless hook to manage recording state. Use with recorder components below.

Config:

| Option | Type | Default | Description | |--------|------|---------|-------------| | mimeType | string \| (() => string) | auto | MIME type for recording | | audioConstraints | MediaTrackConstraints \| boolean | true | Audio constraints for getUserMedia | | onRecordingComplete | (blob: Blob) => void | - | Callback when recording is complete |

Returns:

| Property | Type | Description | |----------|------|-------------| | startRecording | () => Promise<void> | Start recording from microphone | | stopRecording | () => void | Stop recording and generate blob | | pauseRecording | () => void | Pause current recording | | resumeRecording | () => void | Resume paused recording | | clearRecording | () => void | Clear recording and reset state | | mediaRecorder | MediaRecorder \| null | MediaRecorder instance | | recordingBlob | Blob \| null | Recorded audio blob | | recordingTime | number | Recording duration in seconds | | isRecording | boolean | Whether currently recording | | isPaused | boolean | Whether recording is paused | | error | Error \| null | Any error that occurred |

LiveStreamingRecorder

This is an example image. The component includes only the waveform.

Scrolling timeline waveform (Voice Memos style). Canvas grows horizontally as recording continues.

▶ Demo

<LiveStreamingRecorder.Root
  mediaRecorder={mediaRecorder}
  className="h-12 w-80 rounded bg-slate-100"
  appearance={{ scrollbar: { thumbColor: "#94a3b8" } }}
>
  <LiveStreamingRecorder.Canvas appearance={{ barColor: "#3b82f6", barWidth: 2, barGap: 1 }} />
</LiveStreamingRecorder.Root>

Root Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | mediaRecorder | MediaRecorder \| null | - | MediaRecorder instance (required) | | fftSize | number | 2048 | FFT size for frequency analysis | | smoothingTimeConstant | number | 0.8 | Smoothing constant (0-1) | | sampleInterval | number | 50 | Sample interval in ms | | amplitudeScale | number | 1.5 | Amplitude multiplier (lower = quieter waveform) | | appearance | LiveStreamingRecorderAppearance | - | See Appearance Options |

Canvas Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | appearance | WaveformAppearance | - | See Appearance Options |

LiveStreamingStackRecorder

This is an example image. The component includes only the waveform.

Fixed-width waveform where bars compress as recording grows.

▶ Demo

<LiveStreamingStackRecorder
  mediaRecorder={mediaRecorder}
  className="h-12 w-80 rounded bg-slate-100"
  appearance={{ barColor: "#3b82f6", barWidth: 2, barGap: 1 }}
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | mediaRecorder | MediaRecorder \| null | - | MediaRecorder instance (required) | | fftSize | number | 2048 | FFT size for frequency analysis | | smoothingTimeConstant | number | 0.8 | Smoothing constant (0-1) | | sampleInterval | number | 50 | Sample interval in ms | | amplitudeScale | number | 1.5 | Amplitude multiplier (lower = quieter waveform) | | appearance | WaveformAppearance | - | See Appearance Options |

LiveRecorder

This is an example image. The component includes only the waveform.

Real-time frequency bars visualization.

▶ Demo

<LiveRecorder mediaRecorder={mediaRecorder} />

| Prop | Type | Default | Description | |------|------|---------|-------------| | mediaRecorder | MediaRecorder \| null | - | MediaRecorder instance (required) | | fftSize | number | 2048 | FFT size for frequency analysis | | smoothingTimeConstant | number | 0.8 | Smoothing constant (0-1) | | showIdleState | boolean | true | Show minimal bars when not recording | | amplitudeScale | number | 1.5 | Amplitude multiplier (lower = quieter waveform) | | appearance | WaveformAppearance | - | See Appearance Options |

Appearance Options

WaveformAppearance

Common appearance options for all waveform components.

| Property | Type | Default | Description | |----------|------|---------|-------------| | barColor | string | "#3b82f6" | Color of waveform bars | | barWidth | number | 1 | Width of each bar in pixels | | barGap | number | 1 | Gap between bars in pixels | | barRadius | number | 0 | Border radius of bars | | barHeightScale | number | 0.95 | Scale factor for bar height (0-1) |

AudioWaveformAppearance

Extends WaveformAppearance with playhead options.

| Property | Type | Default | Description | |----------|------|---------|-------------| | playheadColor | string | "#ef4444" | Color of the playhead line | | playheadWidth | number | 2 | Width of the playhead line |

ScrollbarAppearance

Options for scrollbar in LiveStreamingRecorder.

| Property | Type | Default | Description | |----------|------|---------|-------------| | thumbColor | string | "rgba(148, 163, 184, 0.5)" | Scrollbar thumb color | | hidden | boolean | false | Hide scrollbar completely |

Styling

Components accept className, style, and all standard canvas HTML attributes.

<AudioWaveform
  blob={blob}
  className="h-32 w-full rounded-lg bg-slate-900 p-4"
  // or style prop
  style={{
    width: "100%",
    height: "100%",
  }}
  appearance={{
    barColor: "#3b82f6",
    barWidth: 2,
    barGap: 1,
    barRadius: 1,
    playheadColor: "#ef4444",
    playheadWidth: 2,
  }}
/>

License

CC0 1.0 - Public Domain