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.
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 achapterspart in the look, a button opens and closes it; without one, it always shows.listalso takes the options in The list's forms. -
Four parts for the look, shown only with chapters:
chapter(the one playing),previousChapter,nextChapterandchapters. The previous chapter's button is.sonicframe-previous-chapter. -
The
chapterchangeevent, 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.