Upgrade guide
What changes from one version to the next, the newest first: from 1.3 to 1.3.1, then back to 0.6. Nothing breaks: every new feature is off until you turn it on (the one exception, a sound that cannot load now says so, is listed below), and every old name keeps working until 2.0.
Update the package
npm install sonicframe@1
In 1.3.1: fixed
-
The keyboard focus stays where it was when a player
is built again (
setTracks,showVolume) and when a playlist changes track: after N or the next track button, the focus is on the same button of the new track's player, so Shift+N right after goes back. Nothing to change in your code.
In 1.3: what works differently
| Change | To keep the old way |
|---|---|
A sound that cannot load says so: a
message over the wave, the same words in
the live region, and an
error event with a
SoundError
|
loadError: false and
a11y.loadError.announce:
false
(the tag's
load-error="false" and
a11y-load-error="false")
|
A <sonic-playlist>'s
own links are inert as well as hidden
while it stands
|
Nothing to do: they come back as they were when the tag leaves the page |
The ceilings on what comes from outside
go up to a fixed most; an option that
shipped before keeps a larger value at
its most until 2.0, and a clip's
maxSourceSeconds: Infinity
means 2 hours
|
Limits on everything from outside |
In 1.3: what you can turn on
| New | Where to read about it |
|---|---|
A now-playing bar that keeps the sound
in reach while the page scrolls
(nowPlaying,
<sonic-now-playing>)
|
Now playing |
A podcast's feed as a playlist
(feed,
readFeed,
loadFeed)
|
Playlist |
Waves for sounds of hours, read in
pieces as they download
(decode.stream,
decode-stream), and
createPeakStream for
servers
|
Long sounds |
Players on pages other people write:
SONIC_TAGS for your HTML
filter
|
On a CMS or WordPress |
The title and
artist parts, and
a11y.sliderName to name the
slider by its sound
|
Player options |
Minified files for pages without a
bundler (sonicframe/min/…)
|
Installation |
In 1.2: what you can turn on
Nothing to change: a player without tracks looks and acts as it did, and the playlist is an entry of its own.
| New | Where to read about it |
|---|---|
A playlist, one player and the list or a
player for each track, with shuffle,
repeat and
<sonic-playlist>
(sonicframe/playlist)
|
Playlist |
The tracks around a player's sound
(tracks): the
previousTrack and
nextTrack parts, N and
Shift+N, and the lock screen's previous
and next
(mediaSession.previousNext)
|
The parts, Changing the track |
Lists in files: readTracks,
writeTracks (JSON, M3U) and
loadTracks
|
Lists in files |
| A language written for 1.0 still registers: newer phrases are said in English | Bringing a whole language |
In 1.1: what you can turn on
Nothing to change: the player's time reads as it did until you turn the new clock on.
| New | Where to read about it |
|---|---|
A precise clock: tenths, hundredths,
milliseconds or a timecode's frames
(timePrecision,
timeFps), the hours
(timeHours), each field's
digits (timeDigits) and the
decimal mark (timeDecimal)
|
A precise clock |
A mask of your own for the time, with
letters, separators and words
(timeFormat)
|
A mask of your own |
The same on the tag:
time-precision,
time-fps,
time-hours,
time-decimal and
time-format
|
Tag attributes |
formatClock, to write a
time in your own page the way the clock
does
|
Frame API |
In 1.0: nothing to change
1.0 is 0.8 with a promise: from here on SonicFrame follows Semantic Versioning, so a 1.x version never breaks code written for 1.0, and old names keep working until 2.0. Versions and support says what the promise covers.
- Every version is published from the repository's GitHub workflow, with npm provenance.
- A vulnerability is reported privately on GitHub, as SECURITY.md explains.
-
The package names where to support the project:
npm fundshows it.
In 0.8: what works differently
Regions tell onChange when a drag ends
onChange of regions() is
called once when a drag is let go, and after each change
by the API or the keys; it was also called at every move
of a drag. An app that saves the regions there now saves
once. To follow the times while they move, use the new
onInput, called at every move of a drag
that changes a region.
regions({
onInput: (list) => showTimes(list), // at every move of a drag
onChange: (list) => save(list), // once it is let go
});
Regions tell only real changes
No onChange comes for a press on a region
that moves nothing, for remove() of an id
no region has or for an update() that
changes nothing, and no onSelect when the
selection stays the same. A region still being drawn
when the drag is cut short goes away with only an
onInput, since onChange never
heard of it.
The tag keeps its sound
<sonic-player> builds its player
again for an attribute it cannot change live, and keeps
the same audio: the sound goes on where it was, at its
volume and speed. A tag moved to another place on the
page keeps its player. Only a new src or
preload brings a new sound, so a page that
counted on a rebuild to stop the sound now pauses it
itself.
Some keys go on to the page
R with no region, and M with no marker, let the key go on to the page, where the player's own keys or yours can answer it. The keys pressed on the minimap's slider stay its own: Delete, Enter, C, M and the zoom keys no longer reach the wave behind it.
In 0.8: what you can turn on
| New | Where to read about it |
|---|---|
The player's own keys
(keys): Space, M, the
arrows, > and
<, in the player or on
the whole page, said aloud with
a11y.keys.announce
|
Keyboard, Player options |
Where each sound was left, the volume
and the speed, kept between visits
(remember), with
forget() and the
resume event
|
Player options, A podcast player |
Regions and markers as files:
writeRegions,
readRegions,
writeMarkers and
readMarkers, in JSON,
WebVTT, CSV and Audacity's labels
|
Regions, Markers |
On the tag: keys,
remember,
remember-key,
a11y-keys,
a11y-remember and the
sonicframe:resume event
|
Tag attributes |
For plugin authors:
KeyModifiers.repeat, true
while a key is held down
|
Plugin API |
In 0.8: fixed
-
Regions keep an id of their own: a file read back
with
region-1no longer makes two regions share it, which removed both. - A region whose start or end is not a number is refused, and a looping region that is removed stops playing.
- The volume bar takes the focus when it is pressed, so its keys work right after a click.
-
formatTimewith decimals shows1:00.0, never0:60.0. -
Player.destroy()stops the download of the sound it made.
The other fixes of 0.8 are in the changelog.
In 0.7: what can look or work differently
Chapter lines follow the palette
Every palette now sets
--sonicframe-chapter, so the chapters'
lines no longer stay gray on the dark and
contrast palettes.
Two names are kept for the recorder's own icons
The recorder screen no longer shows an app button named
resume or cancel. On
<sonic-recorder>, its
icon-resume or icon-cancel
would draw both that button and the screen's own. Give
such a button another name.
Silences keep their numbers in range
findSilences keeps its
windowSeconds from 0.001 to 1 second, and
silencesFromPeaks its
threshold from 0.001 to 0.45, as
outlineSound already did. A threshold over
0.5 used to leave a silence open to the end of the
sound.
In 0.7: the new names
0.7 gave one idea one name across the library. Each old name works the same until 2.0, marked as deprecated so your editor strikes it through and says what to use; when a page gives both, the new name wins. Rename at your own pace; the tables say where each one is documented.
The player and its tag
| 0.6 | 0.7 | Where |
|---|---|---|
setVolume(show) |
showVolume(show) |
Player |
The description event |
descriptionchange |
Player |
The look's narrow,
waveMin,
weight,
volume
|
narrowWidth,
waveMinWidth,
fontWeight,
volumeSlider
|
Layouts |
marqueeHoverPause,
marqueePause (in
milliseconds)
|
marqueePauseOnHover,
marqueePauseSeconds (in
seconds)
|
Layouts |
The part prevChapter, the
class
.sonicframe-prev-chapter
|
previousChapter,
.sonicframe-previous-chapter
|
Chapters |
decode.peaks, the chapter
list's style, the type
ButtonAnimation
|
decode.peakCount,
box,
ListenButtonAnimation
|
Player options |
The tag's
chapter-options and its
words stay,
edges,
autohide,
pauses,
hover-pause
|
chapters-options,
stay-open,
edge-scroll,
auto-hide,
pause-in-value,
pause-on-hover
|
Tag attributes |
A resolved look gives each old key back with the same value, so code that reads it keeps working.
Accessibility, in the a11y group
| 0.6 | 0.7 | Where |
|---|---|---|
The frame's label and
valueText; the player's
label
|
a11y.label and
a11y.valueText;
a11y.label (the tag's
a11y-label)
|
Accessibility |
labels of
PlayButton and
VolumeControl,
words of
markers() and
chapters(),
a11y.labels of the player
and the recorder screen
|
a11y.words |
Words |
The chapters' valueNote and
announceChange; the words
announce and
readable of the tag's
chapter-options
|
a11y.valueNote and
a11y.announce; the tag's
a11y-chapters
|
Chapters |
The minimap's a11y.label;
soundDescription's
announceWhenReady
|
a11y.words.label;
announce
|
Minimap, Words |
Plugins
| 0.6 | 0.7 | Where |
|---|---|---|
markers():
marks and
times, the getter
marks, group,
backGrace
|
items, the getter
items,
groupDistance,
keys.backGrace
|
Markers |
regions():
list(),
create: 'shift-drag' or
'drag',
snap
|
The getter items,
create: true with
createGesture,
pixelSnap
|
Regions |
skipSilences():
dimColor,
snap
|
color,
pixelSnap
|
Skip silences |
chapters():
onChange, the getter
chapters,
lane: 'above' or
'below'
|
onChapterChange, the getter
items,
lane: true with
lanePlacement
|
Chapters |
timeline():
side,
size
|
placement,
height
|
Timeline |
minimap():
side
|
placement |
Minimap |
caption():
size,
tooltipLimit, a section's
limit
|
height,
tooltipMax,
max
|
Captions |
soundDescription() and
describeSound():
times
|
timeFormat |
Words |
liveFrequency():
bars
|
bands |
Live frequency |
side keeps meaning left or right (a
drawer's side); above and below are always
placement. The snap of markers
and chapters, a click going to the exact moment, keeps
its name.
Recording
| 0.6 | 0.7 | Where |
|---|---|---|
RecorderState,
RECORDER_STATES
|
RecorderScreenState,
RECORDER_SCREEN_STATES
|
Recording |
Recorder:
peaks, rate,
mimeType
|
decode: { peakCount },
levelsPerSecond,
mimeTypes
|
|
A Recording's
type
|
mimeType (both are given
until 2.0)
|
|
The screen's window,
recordBlink and
state event; an upload's
body
|
liveSeconds,
recBlink,
statechange (both events
are told until 2.0);
bodyType
|
|
<sonic-recorder>:
max, window,
keep,
record-blink,
sonicframe:state
|
max-seconds,
live-seconds,
after-send="keep",
rec-blink,
sonicframe:statechange
|
Peaks, files and analysis
| 0.6 | 0.7 | Where |
|---|---|---|
normalize,
resample
|
normalizePeaks,
resamplePeaks
|
Analysis |
loadPeaks(url, fetcher),
PeaksFetcher
|
loadPeaks(url, { fetcher }),
Fetcher
|
Peaks |
WaveformFetcher,
ChaptersFetcher,
WaveformResponse
|
Fetcher,
FetchedResponse
|
Waveform files |
writeWaveform:
channels: 'mix' or
'each'
|
channel: 'all' or
'each'
|
Waveform files |
CHAPTER_WORDS,
ZOOM_WORDS,
MINIMAP_WORDS,
DESCRIPTION_WORDS
|
wordsFor(tag) |
Languages |
Claim |
PointerClaim |
Plugin API |
Names that go without a new one
These were the library's own pieces, which it now uses
by itself: markerSpans,
pickMimeType, clipPlan,
MediaLike, soundWords,
SoundWords, playerWords,
PlayerWords, pickPalette,
resolveFont, safeFontUrl,
RecorderEvent and
RECORDER_EVENTS. They work until 2.0.
In 0.7: what you can turn on
| New | Where to read about it |
|---|---|
Heights with their unit:
'1.5rem' or
'20px' for the timeline's,
the caption's and the minimap's
height, the minimap's
gap and the chapters'
laneHeight; the play
button's size in rem
|
Timeline, Minimap, Captions, Chapters |
The timeline and the minimap over the
wave (placement: 'above')
|
Timeline, Minimap |
The player's
setBar(bar) and
setLabel(label); the tag's
player property and the
SonicPlayerElement
type
|
Player, The tag |
Your own keys for markers and regions (a
letter, or false)
|
Keyboard |
a11y.tooltip.readable on
the caption (on by default, as before)
|
Captions |
loadPeaks with
shared: false, fetching
every time
|
Peaks |
<sonic-recorder>
with wave and
font, as the player's tag
|
Recording |
In 0.7: for plugin authors
Nothing changes for a plugin written for 0.6. The types
a plugin works with now have names you can import:
WavePoint, PointerClaim,
Placement, KeyModifiers and
TooltipA11y.
What changes in 2.0
A few things cannot keep an old name, because they are values a page compares, not names it calls. They stay as they are until 2.0:
-
A view moved by the keys says
'keys'(ViewSource), while a seek by the keys says'keyboard'(SeekSource). In 2.0 both say'keyboard'. -
The
hoverevent gives[ratio, time], whiletimeupdategives[time, ratio]. In 2.0 both give the time first. - Every old name in the tables of 0.7's new names goes away.
The detail of the tags' events stays a list
of the event's arguments, in the order
on() gives them.
In 0.7: fixed
-
soundDescription()with akeys.backGracethat is not a number kept Shift+P from going back at all; it now takes the usual second. -
silencesFromPeakswith athresholdover 0.5 left a silence open to the end of the sound.
Every change, and those of earlier versions, is in the changelog.
If an update saved you time
Each release is built, tested and documented by one person. Supporting SonicFrame pays for the next one and for accessibility in audio.