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,labelandcolor. - 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.