SonicFrame v1.3.2

Ready-made peaks

For long sounds, write the peaks once on your server and serve them as a small file. The wave and the length show at once, and an hour of audio is never decoded in the browser. This site does it: each page reads a file of a few kilobytes.

Reading a file

import { PlayButton, SonicFrame, loadWaveform } from 'sonicframe';

const box = document.querySelector('#waveform-dat');
box.style.display = 'flex';
box.style.alignItems = 'center';
box.style.gap = '0.75rem';
const media = new Audio('./sounds/little-elf.mp3');

PlayButton.create({ container: box, media });
const wave = document.createElement('div');
wave.style.flex = '1';
wave.style.height = '4rem';
box.append(wave);
new SonicFrame({
    container: wave,
    media,
    peaks: () => loadWaveform('./sounds/little-elf.dat'),
});

SonicFrame reads the files of the audiowaveform tool, binary (.dat) or JSON, version 1 or 2, 8 or 16 bits, any number of channels, and the simple peaks list. The format comes from the content, never from the address.

  • loadWaveform(url, options) fetches a file piece by piece and reads it; the same address is fetched once per page, and a failed fetch can be tried again.
  • readWaveform(input, options) reads one you already have: bytes, JSON text or parsed JSON.
  • Both give { peaks, duration, sampleRate, samplesPerPeak, channels, bits, format }, which peaks takes as it is.
Option Default What it does
maxPeaks 20000 The most peaks kept; more points are folded while reading. Up to 1,000,000.
maxBytes 8000000 A larger file is refused before it is read. Up to 64,000,000.
channel 'all' 'all' keeps the loudest of every channel; a number keeps that channel.
normalize false Makes the loudest peak 1.
shared true loadWaveform: the same address is fetched once per page.
fetcher fetch loadWaveform: your own Fetcher, whose response gives arrayBuffer() (FetchedResponse), as for loadPeaks and loadChapters.
Hostile files are refused A file whose data does not match its header, or with a value out of range, is refused with a TypeError or RangeError; a strange option falls back to its default.

Writing a file

writeWaveform(channels, options) writes the audiowaveform format (version 2) from decoded samples: the bytes of a .dat file, or the JSON as an object. It runs in the browser or in Node.

import { writeWaveform } from 'sonicframe/analysis';

const channels = [0, 1].map((index) => audioBuffer.getChannelData(index));
const bytes = writeWaveform(channels, {
    sampleRate: audioBuffer.sampleRate,
    samplesPerPeak: Math.round(audioBuffer.sampleRate / 40), // 40 points per second
    bits: 8,
});
Option Default What it does
sampleRate (required) The samples' rate, per second.
samplesPerPeak 256 Samples per point.
bits 16 16 or 8.
format 'dat' 'dat' (bytes) or 'json' (an object).
channel 'all' 'all' writes one channel, the loudest of all; 'each' writes every channel.

With the audiowaveform tool

The same files come from the command line tool:

audiowaveform -i episode.mp3 -o episode.dat -z 256 -b 8

How many points?

For a wave that fills the screen, a few thousand points are plenty. To zoom in, keep more: 40 to 100 points per second of sound. An 8-bit file costs 2 bytes per point: six minutes at 40 per second is about 28 KB.