speakable
speakable copied to clipboard
tollwerk
Simple and privacy friendly on-page screenreader / text-to-speech player using the native JavaScript Web Speech API
= 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 https://tollwerk.github.io/speakable[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 https://github.com/tollwerk/speakable[speakable's Github repository] (use spkbl.min.js for a minified script version):
[source,html]
Next, add speakable sections to your page by assigning the spkbl CSS class to suitable HTML elements:
[source,html]
This is a speakable section
The player will read all the text inside the section.
Finally, the players on your page need to be initialized:
[source,html]
Your page should now display one player for each speakable section. Initialization takes an optional configuration object as single argument (<<options,see below for details>>). Config values provided like this will apply to all players on the page:
[source,html]
Alternatively, you can provide most of the options on per-player basis as well by adding them as data attributes (prefixed by data-spkbl-):
[source,html]
This is a speakable section
The player will read all the text inside the section.
[[options]] == Options
The currently supported options are:
[width="100%",cols="2,4,1,1,1",frame="none",options="header"]
|=======
|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 (<<customplayer,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
|=======
[[customplayer]] == 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:
[source,js]
{ player: <DOMElement>, // Overall player container controls: { play: <DOMElement>, // Play button (typically
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.
[source,html]
This is a speakable section
The player will read all the text inside the 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 link:CHANGELOG.adoc[changelog] for a complete release history.
== Contributing
Found a bug or have a feature request? https://github.com/tollwerk/speakable/issues[Please have a look at the known issues] first and open a new issue if necessary. Please see link:CONDUCT.adoc[conduct] for details.
== Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
== Credits
- https://tollwerk.de[Joschi Kuphal]
- link:../../contributors[All Contributors]
== Legal
Copyright © 2020 tollwerk GmbH [email protected] / https://twitter.com/tollwerk[@tollwerk]. + speakable is licensed under the terms of the link:LICENSE[MIT license].
tollwerk