Spectrogram

Overview

Responsive SVG time × frequency heatmap for visualizing audio spectrogram data.

<script lang="ts">
  import { Spectrogram } from '@lostgradient/cinder/spectrogram';
</script>

Visualizing how frequency content of a signal changes over time (time × frequency heatmap).
Displaying pre-computed spectrogram frames from an FFT or short-time Fourier transform.

Only a single spectrum snapshot is needed — use spectrum-chart instead.
Real-time live audio spectrogram is needed — feed frames as props yourself.
A categorical × categorical heatmap without a time axis is needed — use matrix-chart instead.

Live preview

Use when

Visualizing how frequency content of a signal changes over time (time × frequency heatmap).
Displaying pre-computed spectrogram frames from an FFT or short-time Fourier transform.

Avoid when

Only a single spectrum snapshot is needed — use spectrum-chart instead.
Real-time live audio spectrogram is needed — feed frames as props yourself.
A categorical × categorical heatmap without a time axis is needed — use matrix-chart instead.

When no `frames` are available, supply an `empty` snippet to explain the absence instead of rendering a blank heatmap.

While frames are still being analyzed, set `loading` and supply a `loadingContent` snippet to render a placeholder over the heatmap.

Time × frequency heatmap showing how frequency content changes over time.

Props for spectrogram
Name	Type	Default	Required	Description
`label`	`text`		req	Accessible label for the chart. Required for screen readers.
`description`	`text`			Optional description rendered below the label.
`frames`	`SpectrogramFrame[]`		req	Ordered sequence of time-indexed frames. Each frame contains a label and an array of per-frequency-bin magnitudes.
`frequencyLabels`	`string[]`			Optional frequency-bin labels for the y-axis (e.g. ['100 Hz', '200 Hz', …]). When omitted, bins are labelled by index.
`height`	`number`	`200`		Pixel height of the chart. Default `200`.
`loading`	`boolean`	`false`		Whether the chart 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 there are no frames.
`loadingContent`	`snippet`			Snippet rendered while loading.
`id`	`unknown`		req