Data Display

Waveform

Responsive SVG rendering of time-domain audio amplitude data as a waveform path or bar display.

import { Waveform } from '@lostgradient/cinder/waveform';
chartwaveformsignalaudio
01

Overview

Responsive SVG rendering of time-domain audio amplitude data as a waveform path or bar display.

Usage

svelte 
<script lang="ts">
  import { Waveform } from '@lostgradient/cinder/waveform';
</script>

Guidance

Use When

  • Visualizing pre-recorded or pre-processed audio amplitude samples in a static display.
  • Showing an audio waveform thumbnail or preview with mocked or pre-computed sample data.

Avoid When

  • Real-time live audio capture is needed — wire AudioContext / AnalyserNode yourself and feed samples as props.
  • Frequency-domain data — use spectrum-chart or spectrogram instead.
Live preview
02

When to use

Use when
  • Visualizing pre-recorded or pre-processed audio amplitude samples in a static display.
  • Showing an audio waveform thumbnail or preview with mocked or pre-computed sample data.
Avoid when
  • Real-time live audio capture is needed — wire AudioContext / AnalyserNode yourself and feed samples as props.
  • Frequency-domain data — use spectrum-chart or spectrogram instead.
03

Examples

Audio waveform (bars mode)

Pre-computed audio amplitude samples rendered as vertical amplitude bars.

Empty state

When `data` is empty, supply an `empty` snippet to explain the absence instead of rendering a flat, meaningless plot.

Loading state

While audio is being decoded, set `loading` and supply a `loadingContent` snippet to render a placeholder over the viewport instead of the plot.

Sine wave (path mode)

A time-domain sine wave rendered as a continuous SVG path.

04

Props

Props for waveform
Name Type Default Required Bindable Description
label text req Accessible label for the waveform. Required for screen readers.
description text Optional description rendered below the label.
data number[] req Time-domain amplitude samples. Each value should be in the range [-1, 1]. Values outside this range are clamped.
renderMode 'path' | 'bars' 'path' How to render the waveform: as a continuous path or vertical amplitude bars. Default path.
height number 80 Pixel height of the chart. Default 80.
loading boolean false Whether the waveform is in a loading state.
dataTableVisibility 'screen-reader-only' | 'visible' | 'hidden' 'screen-reader-only' Controls data table visibility. Default screen-reader-only.
dataTableCaption text Custom data table caption; falls back to label.
empty snippet Snippet rendered when the chart has no data.
loadingContent snippet Snippet rendered while loading.
id unknown req