Data Display

Spectrogram

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

import { Spectrogram } from '@lostgradient/cinder/spectrogram';
chartspectrogramsignalaudio
01

Overview

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

Usage

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

<Spectrogram label="Voice spectrogram" frames={[]} height={220}>
  {#snippet empty()}
    No audio analyzed yet.
  {/snippet}
</Spectrogram>

Guidance

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.

Rendering and theming

Spectrogram uses SVG and derives its plot margins from the time and frequency labels. The default foreground follows currentColor, the chart background remains transparent, and heatmap colors resolve through --cinder-chart-series-* against the semantic inset surface. Pass a partial theme to override the palette or chart colors. Rendering is bounded for dense inputs, while the semantic table preserves a readable sampled representation.

Live preview
02

When to use

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.
03

Examples

Empty state

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

Loading state

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

Voice spectrogram

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

04

Props

Props for spectrogram
NameTypeDefaultDescription
label required text Accessible label for the chart. Required for screen readers.
description text Optional description rendered below the label.
frames required SpectrogramFrame[] 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.
theme ChartTheme Partial visual theme override.
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 text