Peaks.js waveform best practices

Peaks.js renders waveforms on canvas, but the data pipeline determines performance. Use precomputed waveform files for long audio, reserve Web Audio rendering for short clips, and always clean up the instance when your route unloads.

Best practices

• Precompute waveform data with audiowaveform for anything longer than short clips.
• Prefer binary .dat files with -b 8 for smaller payloads and faster parses.
• Size zoomview and overview containers explicitly so canvas layout is stable.
• Keep zoomLevels small and curated to avoid extra waveform computation.
• Enable waveformCache when users switch zoom levels frequently.
• Call instance.destroy() when navigating away to release listeners and canvas memory.

Precompute waveform data

audiowaveform -i source.mp3 -o source.dat -b 8

SvelteKit-friendly setup

<script lang="ts">
	import { onDestroy, onMount } from "svelte";
	import Peaks from "peaks.js";

	let peaks;
	let zoomview;
	let overview;
	let audioEl;

	onMount(() => {
		Peaks.init(
			{
				zoomview: { container: zoomview },
				overview: { container: overview },
				mediaElement: audioEl,
				dataUri: { arraybuffer: "/waveforms/source.dat" },
				zoomLevels: [512, 1024, 2048, 4096],
				waveformCache: true
			},
			(err, instance) => {
				if (err) return;
				peaks = instance;
			}
		);
	});

	onDestroy(() => {
		peaks?.destroy();
	});
</script>

Checklist

• dataUri points to a cached waveform file (CDN or static).
• mediaElement audio sources include MIME types for Safari.
• zoomLevels match your annotation granularity.
• emitCueEvents is enabled if you need segment/point callbacks.