is a simple and privacy friendly on-page screenreader / text-to-speech player using the native JavaScript Web Speech API. To hear it in action, please visit the demo page which is part of this repository.
Start by adding the speakable JavaScript library to your HTML document.
You may also want to use the default player CSS, but you might as well replace or extend it with your own styles.
Please find the files in the dist directory of speakable’s Github repository (use spkbl.min.js for a minified script version):
<html lang="en">
<head>
<title>Example page</title>
<link rel="stylesheet" href="spkbl.css">
</head>
<body>
<!-- ... -->
<script src="spkbl.min.js"></script>
<script>
/* Initialization, see below */
</script>
</body>
</html>Next, add speakable sections to your page by assigning the spkbl CSS class to suitable HTML elements:
<section class="spkbl">
<h2>This is a speakable section</h2>
<p>The player will read all the text inside the section.</p>
</section>Finally, the players on your page need to be initialized:
<script>
if ('Speakable' in window) {
Speakable.init();
}
</script>Your page should now display one player for each speakable section. Initialization takes an optional configuration object as single argument (see below for details). Config values provided like this will apply to all players on the page:
<script>
if ('Speakable' in window) {
Speakable.init({
multivoice: true,
l18n: {
play: 'Text vorlesen',
pause: 'Pause',
progress: 'Fortschritt',
stop: 'Schließen'
}
});
}
</script>Alternatively, you can provide most of the options on per-player basis as well by adding them as data attributes (prefixed by data-spkbl-):
<section class="spkbl" data-spkbl-multivoice="false" data-spkbl-l18n-play="Abspielen">
<h2>This is a speakable section</h2>
<p>The player will read all the text inside the section.</p>
</section>The currently supported options are:
| Name | Description | Default | init() | data-* |
|---|---|---|---|---|
selector |
DOM Selector to find speakable elements. |
|
Yes |
— |
local |
Use locally available voices only, so that no data is transferred to remote services. The progress bar can only be properly updated with local voices. Remote voices might also stop reading prematurely. |
|
Yes |
Yes |
multivoice |
Look out for |
|
Yes |
Yes |
hidden |
Hide the player for assistive technology (via |
|
Yes |
Yes |
player |
Custom player implementation, constructor function name or reference (see below for details) |
|
Yes |
Yes |
l18n |
Language labels |
— |
— |
— |
l18n.play |
Play button label |
|
Yes |
Yes |
l18n.pause |
Pause / resume button label |
|
Yes |
Yes |
l18n.progress |
Progress bar label |
|
Yes |
Yes |
l18n.stop |
Stop button label |
|
Yes |
Yes |
You may use a custom player implementation by passing in a factory callback (global function name or reference).
The factory method will receive the Speakable reference as its only parameter (so you can access its options including the language strings).
It’s expected to return an object with the following items:
{
player: <DOMElement>, // Overall player container
controls: {
play: <DOMElement>, // Play button (typically <button> or <input>)
pause: <DOMElement>, // Play button (typically <button> or <input>)
progress: <DOMElement>, // Progress bar (typically <progress>)
stop: <DOMElement>, // Play button (typically <button> or <input>)
}
}These DOM elements need to have everything needed for visual presentation (i.e. text content) but they will get CSS classes, event handlers and ARIA attributes added automatically.
You may also use the player to play an audio file instead of using the text-to-speech engine.
For this to work, simply reference a web compatible audio file via the data-spkbl-src attribute.
Obviously the audio file should still represent the readable text. 😉 If for whatever reason the audio file can’t be played, the player will fall back to text-to-speech mode.
<section class="spkbl" data-spkbl-src="demo.mp3">
<h2>This is a speakable section</h2>
<p>The player will read all the text inside the section.</p>
</section>Currently there are no known problems. However, the module is in a very early stage and might have severe bugs. Please let us know if you spot one!
Please refer to the changelog for a complete release history.
Found a bug or have a feature request? Please have a look at the known issues first and open a new issue if necessary. Please see conduct for details.
If you discover any security related issues, please email info@tollwerk.de instead of using the issue tracker.
Copyright © 2020 tollwerk GmbH <info@tollwerk.de> / @tollwerk.
speakable is licensed under the terms of the MIT license.