Screen readers
What a screen reader says comes from three places: each control's name, the wave's value in words, and a shared live region for news. All three speak the player's language.
The wave's value
The wave is a slider whose value is said in words: "0:12
/ 0:45" by default. Change it with
a11y.valueText on the frame, or the
value word on the player:
new SonicFrame({
container,
media,
a11y: {
valueText: (time, ratio, duration) => `${Math.round(ratio * 100)}% played`,
},
});
With the wave in words and pauseInValue,
the value also says where the sound is quiet: "0:22 /
0:33, pause". Plugins can add their own short notes the
same way.
A player with a
precise clock
shows tenths, hundredths or frames, but its value is
still said in whole seconds, so a screen reader is not
flooded with digits that change many times a second. For
more, give your own a11y.valueText, and
write the time with formatClock.
Languages
English is the default; Portuguese (Brazil and
Portugal), Spanish and French are built in.
a11y.lang picks one ('pt',
'pt-PT', 'es-MX'…) or
'auto', the page's language. Given, it also
marks the player with lang, so the screen
reader speaks with a voice of that language. Every
language, and how to bring your own, is in
Languages.
This player's buttons are named in Portuguese: inspect them, or tab through them with a screen reader on.
Your own words
a11y.words renames any control, over the
language's words. A word is cleaned and capped, and its
marks ({seconds}, {speed}…)
are filled with SonicFrame's own values only.
createPlayer({
container,
src,
a11y: {
words: {
player: 'Voice note from Ana',
play: 'Listen',
back: 'Back {seconds} seconds',
},
},
});
| Word | Names |
|---|---|
player,
position
|
The player's group and its wave. |
value |
The wave's value:
'{time} / {duration}'.
|
play, pause
|
The play button, by state. |
back, forward,
backOne,
forwardOne
|
The skip buttons
({seconds}); the
One words when the language
says the number in the singular ("Back 1
second"). Without them, your own
back and
forward serve both.
|
speed |
The speed button ({speed}).
|
mute, unmute,
volume, muted
|
The volume control, and its slider's value while muted. |
listen,
stopListening,
speechFailed
|
The button that reads the description aloud. |
zoomIn,
zoomOut,
zoomReset,
zoomView
|
The zoom buttons and the zoom announcement. |
minimap,
minimapValue
|
The minimap slider. |
chapter,
chapters,
noChapter,
chapterLink,
previousChapter,
nextChapter
|
The chapters: their place
({index},
{count}), the list and its
button, the end of the chapters, a link,
and the two buttons.
|
resume |
Where a remembered sound resumes
({time}).
|
Announcements
One polite live region is shared by every frame on the page. It speaks only when something worth saying happens that the focused control cannot say by itself:
-
a11y.zoom.announce: the new view after a zoom by the keys, a button or two fingers ("Zoom 4×, 1:20 to 2:40"). - The wave in words: the description again on D, and the part reached on P.
-
The player's
a11y.keys.announce: what its own keys change ("Volume 55%", "Volume muted", "Playback speed 1.5×", the place after a skip); see Keyboard. -
The player's
a11y.remember.announce: where a sound resumes, at its first play ("Resuming at 12:30"). -
The player's
a11y.loadError.announce, on by default: why the sound cannot load ("Could not load the sound", "This sound cannot be played here"), also shown over the wave. - The markers' M with no marker that way: "No more markers", as C says "No more chapters".
-
The chapters'
a11y.announce: the new chapter when playback enters it; see Chapters. - When the browser has no voice to read the description aloud, it says so.
A plugin speaks through the same region with
host.announce(text). Nothing is ever said
on its own while nobody is using the player.
Hidden on purpose
The time beside the wave is hidden from screen readers
(the wave already says it), and so is the minimap unless
a11y.minimap.keys makes it a slider. A
frame with interact: false is a picture
(role="img") named by its label.