SonicFrame v1.3.2

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 fund shows 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-1 no 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.
  • formatTime with decimals shows 1:00.0, never 0: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 hover event gives [ratio, time], while timeupdate gives [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 a keys.backGrace that is not a number kept Shift+P from going back at all; it now takes the usual second.
  • silencesFromPeaks with a threshold over 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.