speakable

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.

Usage

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>

Options

The currently supported options are:

Name	Description	Default	init()	`data-*`
selector	DOM Selector to find speakable elements.	`".spkbl"`	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.	`true`	Yes	Yes
multivoice	Look out for `lang` attributes on contained elements and try to use the most appropriate voice available for a particular language	`true`	Yes	Yes
hidden	Hide the player for assistive technology (via `aria-hidden="true"`)	`false`	Yes	Yes
player	Custom player implementation, constructor function name or reference (see below for details)	`null`	Yes	Yes
l18n	Language labels	—	—	—
l18n.play	Play button label	`"Read text"`	Yes	Yes
l18n.pause	Pause / resume button label	`"Pause"`	Yes	Yes
l18n.progress	Progress bar label	`"Progress"`	Yes	Yes
l18n.stop	Stop button label	`"Stop"`	Yes	Yes

Custom player

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.

Audio file player

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>

Known problems

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!

To-do

Add tests
Add visual highlighting of text currently being read

Changelog

Please refer to the changelog for a complete release history.

Contributing

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.

Security

If you discover any security related issues, please email info@tollwerk.de instead of using the issue tracker.

tollwerk/speakable