SonicFrame v1.3.2

Chapters

Name the stretches of a long sound with the files podcasts already publish. SonicFrame marks where each chapter starts, says it to screen readers and steps through them with one key.

Adding them

import { chapters } from 'sonicframe';

new SonicFrame({
    container,
    media,
    peaks,
    plugins: [chapters({ src: '/episodes/12-chapters.vtt' })],
});

On the player, it is one option: the address, a list, or the options below.

createPlayer({
    container,
    src: '/episodes/12.mp3',
    chapters: { src: '/episodes/12-chapters.vtt', list: true, lane: true },
    look: {
        underStart: 'line',
        line: ['play', 'wave'],
        meta: ['time', 'chapter', 'spacer', 'previousChapter', 'nextChapter', 'chapters'],
    },
});

Hover a line to see its chapter, click it to go there, or focus the wave and press C and Shift + C. The list button opens the chapters under the wave.

The files

The format comes from the content, never from the address. A WebVTT file, as <track kind="chapters"> uses:

WEBVTT

intro
00:00.000 --> 00:02.400
The title

00:02.400 --> 00:09.000
The meeting

Or the Podcasting 2.0 JSON chapters, with pictures, links and chapters left out of the contents ("toc": false):

{
    "version": "1.2.0",
    "chapters": [
        { "startTime": 0, "title": "The title" },
        { "startTime": 2.4, "title": "The meeting", "img": "/art/2.jpg", "url": "/notes#2" }
    ]
}

Or a list, written in code: [{ start: 0, title: 'The title' }, …], with end, image, url and toc when you need them.

Read as untrusted At most 512 KB and 1000 chapters by default; your code may raise them up to 5 MB and 10,000 with load.maxBytes and load.maxChapters. Titles become one line of plain text (120 characters at most). A picture or a link is kept only from a web or relative address, never javascript:, data: or another host by //.

Options

Option Default What it does
items, text, src none The chapters: a list, WebVTT or JSON text, or a file's address (fetched once per page).
load {} How src is fetched: fetcher, shared, maxBytes (512 KB, up to 5 MB) and maxChapters (1000, up to 10,000) and maxText (a title's 120 characters, up to 1000); both also hold for the chapters given as a list or a text.
lines true A line where each chapter starts.
color, width --sonicframe-chapter, 2 The lines' color and width (CSS px). Every palette sets --sonicframe-chapter to its quiet color, so the lines follow a dark palette too.
tooltip true The chapter's name over its line.
a11y.tooltip.readable false The tooltip's text in black or white, whichever reads on its color (4.5:1), as the long chapter name does. Off: the page's color for text on the played color (--sonicframe-on-progress).
snap true A click on a line goes to its chapter's start.
lane false true adds a strip of titles beside the wave; a click on a title goes there.
lanePlacement 'below' Where the strip sits: 'below' the wave or 'above' it.
laneHeight 1.25 The strip's height: a number in rem, or written with its unit ('1.25rem', '20px'). Kept from 0.5 to 4 rem.
keys true C and Shift + C; { letter, backGrace } or false.
a11y.valueNote true The chapter in the slider's value in words.
a11y.announce false Says the chapter playback enters.
list null An element of yours that gets the list (a nav of buttons).
images, links false Pictures and links in the list; links open in a new tab.
a11y.words the frame's language { chapter, list, none, link }; chapter takes {index} and {count}.
onChapterChange, onChapters none The chapter playing changed; the chapters changed.

On the player

chapters takes the address, a list or the options above, without list and a11y.words: the player's words come from its language (a11y.lang) and its own a11y.words. It adds:

  • list: true: the list inside the player, under the wave and on its left edge (under the controls when the wave is on top). With a chapters part in the look, a button opens and closes it; without one, it always shows. list also takes the options in The list's forms.
  • Four parts for the look, shown only with chapters: chapter (the one playing), previousChapter, nextChapter and chapters. The previous chapter's button is .sonicframe-previous-chapter.
  • The chapterchange event, with the chapter and its index.
  • player.chapters, the plugin, to set, load or step through them.
<sonic-player
    src="/episodes/12.mp3"
    chapters="/episodes/12-chapters.vtt"
    chapters-options="list lane"
    a11y-chapters="announce"
></sonic-player>

On the tag, chapters-options takes lane, or above for the strip over the wave, and images links no-keys no-lines. What a screen reader hears goes in a11y-chapters: announce, readable and no-value-note.

Long names

The row under the wave keeps one line: the chapter's name takes the room left and gives it up first. A name too long for its room ends in an ellipsis, or as the look says: it can fade out, show in full under the mouse, and walk across its room as an endless strip, its copy following it, that rests a moment each time round. The mouse stops it; it never walks when the system asks for less motion.

createPlayer({
    container,
    src: '/episodes/12.mp3',
    chapters: '/episodes/12-chapters.vtt',
    look: {
        underStart: 'line',
        line: ['play', 'wave'],
        meta: ['time', 'chapter', 'spacer', 'previousChapter', 'nextChapter'],
        nameOverflow: 'fade',
        nameTooltip: true,
        marquee: true,
    },
});

nameOverflow, nameFade, nameFadeStart, nameTooltip, marquee, marqueeType, marqueeGap, marqueeSpeed, marqueePauseSeconds and marqueePauseOnHover are in every look option; metaWrap: true lets the row break in two instead.

The list's forms

Short of room in the player? The list can float over the page instead: a popover under its button, pointing at it, or a drawer along a side of the page. Both close with Escape, a press outside or a chosen chapter, and give the focus back to the button.

createPlayer({
    container,
    src: '/episodes/12.mp3',
    chapters: {
        src: '/episodes/12-chapters.vtt',
        list: { type: 'popover', animation: true, swipe: true },
    },
});

The first opens a popover; the second, a drawer on the right with its own palette. On a phone, swipe up on the first player, off the wave, to open its list.

Option of list Default What it does
type 'inline' 'inline' (in the player), 'popover' or 'drawer'. The two that float add the chapters button at the end of the line when the look places none.
open false The list in the player starts open.
placement 'auto' A popover opens 'below' its button (over it without room) or 'above'.
side 'right' The page's side a drawer opens on, or 'left'.
width, maxHeight 18 (drawer 20), 20 In rem; past maxHeight a popover scrolls.
stayOpen false Stays open after a chosen chapter.
backdrop false A drawer dims the page; a press there closes it.
animation, animationType false, 'fade' Moves in as it opens: 'fade' or 'slide'. Never for people who asked for less motion.
swipe, swipeDirection false, 'up' A finger swiping on the player, off the wave, opens the list ('up', 'down', 'left', 'right'); the other way closes it. The parts off the wave stop panning the page along the swipe.
palette the player's Its own palette: a name, 'auto' or your colors.
font the player's Its own font, as the player takes it.
box the list's { corner, border, shadow, padding, fontSize }: corners, padding and text in rem, the border in CSS pixels, the shadow 'none', 'soft', 'hard' or 'glow'.

On the tag, chapters-options takes list popover drawer left backdrop open stay-open animation slide swipe.

For screen readers

The slider's value says the chapter: "0:12 / 0:33, Chapter 3 of 4: The question". C and Shift + C say where they landed, or that there are no more chapters. The list is a nav named "Chapters" whose current chapter carries aria-current; the lines, the tooltip and the strip are hidden from screen readers, since the value and the list say the same.

All of it lives in the plugin's a11y group. a11y.valueNote: false keeps the chapter out of the value, a11y.announce says each new chapter as playback enters it, and a11y.words gives your own words.

chapters({
    src: '/episodes/12-chapters.vtt',
    onChapterChange: (chapter, index) => console.log(index, chapter?.title),
    a11y: { announce: true, words: { list: 'Episode parts' } },
});

The plugin's methods

Member What it does
items, index, current The chapters shown, and the one playing (-1 and null outside them).
set(input) A list or text; null clears them. Throws on anything else.
load(url) Fetches a file; rejects on failure.
go(index), next(), previous() Move playback; false when there is nowhere to go.

Without the plugin, readChapters, loadChapters, chapterAt, chapterEnds and nextChapter work on their own, also from sonicframe/analysis on a server.

Styling the list

Each item shows its number (sound bars for the chapter playing), its picture with the chapter's length on it, its title in up to two lines and its stretch; the chapter playing is tinted and fills a thin bar as it plays. listLook (on the player, list.look) changes any of it:

Option Default What it does
thumbWidth, thumbShape, thumbCorner 3.5, 'square', 0.25 The picture: width in rem (1 to 12), 'square' or 'wide' (16:9), corners in rem.
numbers, playingMark true The column of numbers, and the sound bars in place of the playing one's.
span, length true The stretch under the title, and the length on the picture.
tint, progress true The playing chapter's tint and its bar.
titleLines 2 The most lines a title takes, 1 to 4.
itemPadding, itemCorner, gap 0.375, 0.25, 0.125 Each item's padding and corners, and the space between items, in rem.

header: true (on the player, list.header, on by default for a popover or a drawer) heads the list with its name and the place of the chapter playing. For your CSS: .sonicframe-chapters (the nav), .sonicframe-chapters-head, .sonicframe-chapter (each button), .sonicframe-chapter-mark, .sonicframe-chapter-thumb, .sonicframe-chapter-length, .sonicframe-chapter-title, .sonicframe-chapter-span, .sonicframe-chapter-progress and .sonicframe-chapter-link. On the player, the list sits in .sonicframe-chapter-list and the name of the chapter playing in .sonicframe-chapter-now.