SonicFrame v1.3.2

Analysis and clips

Pure functions that measure a sound, safe in Node or a worker, and a recorder that turns a stretch of the wave into a short video to share.

Analysis

On sonicframe/analysis (and the main entry). None of them touch the DOM.

Function What it gives
levels(samples, sampleRate, options) Loudness over time, as Levels.
peakLevel(samples) The loudest sample and its clipping, as PeakLevel.
findSilences(samples, sampleRate, options) Quiet stretches, from samples.
silencesFromPeaks(peaks, duration, options) Quiet stretches, from peaks.
mixdown(source, max) One channel from many, at most max samples.
resamplePeaks(peaks, count) Peaks fitted to count values, keeping the loudest of each slice. normalizePeaks(peaks), on the main entry, makes the loudest one 1.
outlineSound, describeSound The wave in words, ahead of time.
writeWaveform An audiowaveform file; see Ready-made peaks.
writeRegions, readRegions, writeMarkers, readMarkers Regions and markers as JSON, WebVTT, CSV or Audacity labels, and back; see Regions.

Levels

levels takes LevelsOptions: windowSeconds, the window measured, 0.05 by default. It gives Levels: rms and peak, one value per window, and the windowSeconds it used.

Silences from samples

findSilences takes FindSilencesOptions:

Option Default What it does
thresholdDb -45 Below this is quiet, in dB of each window's RMS (0 dB is a full-scale sample). A silence ends once the level rises 6 dB above it.
minDuration 0.4 The shortest silence kept, in seconds.
windowSeconds 0.02 The window the level is measured on, in seconds, from 0.001 to 1.
maxWindows 200000 The most windows measured, from 1 to 2,000,000; a longer sound widens them.
maxSilences 10000 The most silences kept, from 1 to 100,000. Past either end of it or of maxWindows, a RangeError names it.

Silences from peaks

silencesFromPeaks takes SilencesFromPeaksOptions:

Option Default What it does
threshold 0.05 Below this peak is quiet, on the peaks' own 0 to 1 scale, as given (not a share of the loudest peak), from 0.001 to 0.45. A silence ends above twice it.
minDuration 0.4 The shortest silence kept, in seconds.
maxSilences 10000 The most silences kept, from 1 to 100,000.

Both give a list of { start, end }, in seconds.

Peak level

peakLevel gives a PeakLevel:

Field What it is
peak The loudest sample's size (1 is full scale).
peakDb The same in dB (0 dB is full scale; -Infinity for silence).
clipped Whether the sound clips.
clipRuns How many times it clips: each run of samples at full scale (0.999 or more) counts once.

Exporting a clip

frame.exportClip(options) records a short video of the wave playing, in the frame's drawing and colors, with the sound. It resolves with { blob, mimeType, duration }.

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

const box = document.querySelector('#analysis-clip');
const media = new Audio('./sounds/little-elf.mp3');
const row = document.createElement('div');
row.style.display = 'flex';
row.style.alignItems = 'center';
row.style.gap = '0.75rem';
const button = document.createElement('button');
button.type = 'button';
button.textContent = 'Make a clip of 0:08 to 0:16';
const video = document.createElement('video');
video.controls = true;
video.hidden = true;
box.append(row, button, video);

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

button.addEventListener('click', async () => {
    button.disabled = true;
    button.textContent = 'Making the clip…';
    const clip = await frame.exportClip({
        start: 8,
        end: 16,
        caption: 'The second verse',
    });
    video.src = URL.createObjectURL(clip.blob);
    video.hidden = false;
    button.textContent = 'Done: play it below';
});
Option What it does
start, end The stretch, in seconds.
caption A line of text in the video.
width, height, fps The video's size and frame rate: 1280 × 720 at 30 by default, up to 3840 × 2160 at 60.
maxSeconds The longest clip: 120 seconds, up to 600.
bitrate The video's bits a second: 8,000,000, from 100,000 to 50,000,000.
maxBytes The largest source downloaded and the largest clip: 100 MiB, up to 1 GiB. Past either end of maxSeconds, bitrate or maxBytes, a RangeError names it.
signal An AbortSignal that cancels it, download included.
maxSourceSeconds The longest source decoded: 600 seconds by default, up to 7200 (2 hours).
audio The sound: an address, a Blob or an AudioBuffer; the frame's own media by default.
mimeTypes The video types to try, in order (DEFAULT_CLIP_TYPES by default); the first the browser can record is used.
onProgress Called with how far the clip got, from 0 to 1.

The options are ClipOptions; the frame fills in its own peaks, bars, drawing and colors, and a page may give its own instead.

Call it from a click Browsers keep audio suspended until the person does something. A clip whose audio never starts is rejected instead of waiting forever.

The source is decoded whole before the clip is cut, about 23 MB of memory per minute of stereo audio, so it is limited to maxSourceSeconds. Raise it where memory allows, up to 2 hours (a larger value is 2 hours), or pass a Blob or AudioBuffer holding just the part to clip.