Waveform

Waveforms visualize audio amplitude over time.

When connected to navigation, dragging directly on the waveform scrubs across the recording, while scrolling or pinching zooms into sample-level detail.

The basics

Waveforms attach to standard HTML <canvas> elements. Calling createWaveform without options initializes a 2D line envelope with auto-resizing:

import { Sonoscope } from "@sonoscope/core";

const scope = await Sonoscope.fromUrl("/audio/sample.wav");

// Create a waveform using default options
const waveform = scope.createWaveform(waveformCanvas);

// Synchronize drag and zoom interactions
scope.attachNavigation(waveformCanvas, { axis: "time" });

Set the initial time range and zoom limits on Sonoscope, not on the waveform:

const scope = await Sonoscope.fromUrl("/audio/sample.wav", {
  startTime: 5,
  endTime: 15,
  minDuration: 0.05,
  maxDuration: 30,
});

---

Example configurations

1. Default waveform

Draws a continuous line envelope with auto-resizing:

scope.createWaveform(waveformCanvas);

2. Segmented bars

Renders vertical bars across the audio timeline:

scope.createWaveform(waveformCanvas, {
  renderer: "bars",
});

3. Colormapped accent color

Samples a solid color from a colormap to visually match an adjacent spectrogram:

scope.createWaveform(waveformCanvas, {
  colorMap: "magma",
});

4. Custom color

Applies a solid theme color to the waveform line:

scope.createWaveform(waveformCanvas, {
  color: "#50c878",
});

5. Custom bar layout

Customizes bar width, gap spacing, and rounding:

scope.createWaveform(waveformCanvas, {
  renderer: {
    type: "bars",
    barWidth: 4,
    barGap: 3,
    rounded: true,
  },
});

6. Amplitude scaling

Boosts or attenuates the vertical display gain without changing the audio data:

scope.createWaveform(waveformCanvas, {
  amplitudeScale: 2,
});

---

Configuration options

Waveform options

Options accepted by scope.createWaveform(canvas, options). Full reference: WaveformConfig.

Option	Type	Default	Description
autoRenderopt	boolean	true	Whether to automatically re-render when viewport or configuration changes.
channelopt	number	0	Audio channel index to visualize (0 for left/mono, 1 for right).
coloropt	string	"#38bdf8"	Primary color for the waveform line or bars.
backgroundColoropt	string	"transparent"	Background fill color for the canvas.
amplitudeScaleopt	number	1.0	Multiplier applied to audio sample amplitudes for gain adjustment.
colorMapopt	ColorMapConfig	undefined	Named colormap or palette configuration used to derive a matching solid color. Samples a representative accent color from the palette to align with spectrogram visuals. Overrides the `color` property when specified.
rendereropt	WaveformRendererMode	"canvas2d"	Rendering engine: - "canvas2d": Standard 2D canvas line/envelope renderer. - "webgl2": Hardware-accelerated GPU shader renderer. - "bars": Segmented pill/bar waveform renderer. - Custom object with bar configuration options (`{ type: "bars", barWidth, barGap, ... }`).
autoResizeopt	boolean	true	Whether to automatically resize canvas pixel resolution when container dimensions change.
devicePixelRatioopt	boolean | number	window.devicePixelRatio	Device pixel ratio scaling factor for HiDPI/Retina displays.

Bar renderer options

Detailed layout properties when using renderer: { type: "bars", ... }. Full reference: BarsWaveformRendererOptions.

Option	Type	Default	Description

---

Navigation & interaction

Use scope.attachNavigation(canvas, options) to link panning and zooming across waveforms, spectrograms, and rulers:

• Time axis navigation: Restrict interactions with { axis: 'time' } so horizontal dragging pans along the audio timeline.
• Drag & scroll: Dragging scrubs through the recording; scrolling or pinching zooms in to inspect transient peaks or out for the full track.
• Synchronized views: Navigating on any attached canvas immediately updates all connected waveforms and views.

---

Try it yourself!

Play around with the code in the live sandbox below:

• Drag the waveform to scrub across the audio timeline.
• Scroll / Pinch over the waveform to zoom in and out.
• Edit the options in index.ts to switch between bars, webgl2, or canvas2d renderers and test colormaps live.