SonicFrame v1.3.2

Regions

Stretches of the sound to mark, play or loop: a verse to practice, a part to cut, a passage to comment on. Made with the pointer, changed with the pointer or the keys.

Adding regions

import { regions } from 'sonicframe';

const parts = regions({
    items: [{ start: 8.5, end: 16, label: 'Verse' }],
    onChange: (list) => save(list),
});
frame.use(parts);
  • Shift + drag makes a region (a plain drag still scrubs).
  • Drag the body to move it, an edge to resize it.
  • The cursor shows what a press will do: an open hand, a closed one while moving, a resize arrow on the edges.

Keys

  • R and Shift + R select the next and previous region
  • Enter plays it, L loops it, Delete removes it
  • [ ] nudge its start, { } its end
  • Escape stops it and lets it go

Each key can be turned off, and the two letters can be your own. keys: false turns them all off.

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

const box = document.querySelector('#regions-keys');
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);
const frame = new SonicFrame({
    container: wave,
    media,
    peaks: () => loadWaveform('./sounds/little-elf.dat'),
});

frame.use(
    regions({
        items: [{ start: 8.5, end: 16, label: 'Verse' }],
        keys: {
            select: 'g', // G and Shift+G in place of R ('r'; false turns it off)
            loop: false, // no loop key ('l')
            play: true, // Enter
            nudge: true, // [ ] { }
            remove: false, // Delete and Backspace
            release: true, // Escape
        },
    }),
);

Options

Option Default What it does
maxText 120 The longest label kept, in characters, from 1 to 1000.
items [] Regions to start with: { start, end, label, color, id } in seconds. An id is kept when no other region has it.
create true Whether the pointer makes regions; false leaves it to code.
createGesture 'shift-drag' How the pointer makes one: 'shift-drag' (a plain drag still scrubs) or 'drag'.
minLength 0.25 The shortest region, in seconds; at least 0.01.
color the theme's The band color (translucent).
keys true The single-key shortcuts, all on; false turns them off, or { select, loop, play, nudge, remove, release } sets each one (see Keys).
max 200 The most regions kept, at most 200; anything that is not a number is 200.
scrollIntoView false Zoomed in, a region chosen by R comes into view.
pixelSnap false Edges on whole device pixels: a little crisper, each moved by less than half a pixel.
cursors hands { body, moving, edge }, any CSS cursor.
a11y.words the frame's language What the keys say: { place, loopOn, loopOff }; place takes {from} and {to} ("0:08 to 0:16").
onChange Called with the regions after a change: once when a drag is let go, and after each change by code or the keys. The place to save them.
onInput Called at every move of a drag that changes a region, to show its times as they change.
onSelect Called with a copy of the region selected, or null when the selection goes.

From code

const made = parts.add({ start: 20, end: 26, label: 'Chorus' }); // a copy, or null
parts.update(made.id, { end: 28 });
parts.play(made.id, { loop: true });
parts.stop();
parts.remove(made.id);
parts.select(null); // let the selection go (or select an id)
parts.clear(); // remove every region
parts.items; // every region, copies in the order added
parts.set([{ start: 2, end: 6, label: 'Intro' }]); // replace them all

set(items) replaces every region at once, lets the selection go and calls onChange once. Regions are fitted to the sound once its length is known, and follow the view while zoomed in.

add() gives null when max regions exist or a start or end is not a number. Every region keeps an id no other one has, and a region taken away stops playing.

Export and import

Regions go out and come back as the files other programs read: JSON, WebVTT, CSV for a spreadsheet, and Audacity's labels. Reading finds the format by itself.

import { readRegions, writeRegions } from 'sonicframe';

const vtt = writeRegions(parts.items, { format: 'vtt' }); // 'json' by default
parts.set(readRegions(await file.text())); // any of the four formats

                        

Draw, move or resize a region above and the file follows. Saving makes the file on this page; nothing is sent.

Option Default What it does
format 'json'; reading: 'auto' 'json', 'vtt', 'csv' or 'audacity'. Reading finds it by the content when it is not given.
separator ',' CSV: ',', ';' or a tab. Reading takes the one the first line uses.
decimal '.' CSV: the times' decimal mark, '.' or ','. Reading takes either.
guardFormulas true CSV: a ' before a label, a color or an id a spreadsheet would run as a formula (=, +, -, @), taken back when it is read.
  • JSON keeps every field: id, start, end, label and color.
  • WebVTT writes a cue each, in order of their starts, with the id as its identifier.
  • CSV starts with a header; reading takes the columns by their names, or in that order when it knows none.
  • Audacity labels are the start, the end and the label by tabs; reading skips the frequency lines.

Reading refuses a text over 512 KB and keeps at most 2000 regions or markers; your code may raise them up to 5 MB and 20,000 with maxSize and maxItems (past either, a RangeError). It leaves out one whose time is not a number from zero or whose end comes before its start, and cleans each label to one line of 120 characters (maxText, up to 1000). A text that is no such file throws a TypeError; a file that holds no region gives an empty list, so check its length before set() replaces the regions you have. The same functions are on sonicframe/analysis, for a server.