alt="state-speech-synth-logo"
src="logo.svg"
width="150px"
/>

state-speech-synth

---

Intro

state-speech-synth is a lightweight wrapper around the native speech-to-text API speechSynthesis+SpeechSynthesisUtterance. It provides a succinct API and the guarantee of consistent data.

Why

Tracking the playing state of speechSynthesis + SpeechSynthesisUtterance can be a headache. There are essentially two paths to take. One is untrustworthy, and the other is cumbersome.

Inconsistent:
speechSynthesis has 3 read-only boolean values speaking, paused, pending. In an idea world only one of these is true at a time, unless they are all false in which case the system is idle. It doesn’t take much finagling from the use to cause 2 of these values to be true at the same time leading you to representing impossible states.
Example: SpeechSynth Native Example - CodeSandbox

Cumbersome:
A solution to the inconsistency issues is use the event handlers on each SpeechSynthesisUtterance instance. There is a handler for almost every situation onend , onerror, onpause , onresume , onstart. It’s missing an event for the onqueued and onprocessing, but that’s more of a nitpick. Which I suppose is the crux of the issue. There’s a lot of little things to write. I should know. That’s how this module is written.

How It Works

This module wraps speechSynthesis + SpeechSynthesisUtterance as a single API. It uses the event listeners to accurately track state changes (aren’t you glad you won’t have to write those 😁). Those listeners fire off to a single handler that will validate the state change and pass the result ( a single value ) to a state change handling function you’ve specified via the onStateChange subscriber function.

Usage

Here are a few examples of the code in action
Native JS: state-speech-synth Vanilla Example - CodeSandbox - compare it to the example above. Not only it is safer, it’s shorter!

React JS: state-speech-synth React Example - CodeSandbox - works so well with React Hooks

Chrome Extension: read-to-me/background.js at master · easilyBaffled/read-to-me · GitHub - A Chrome Extension I use to help with my dyslexia

API

onStateChange( stateChangeHandler )

Adds stateChangeHandler to the subscription list. stateChangeHandler will then be called every time there is a change in the SpeechSynthesis state. You can add as many handlers as you like. They will be called in the order there were added.

When called stateChangeHandlers are passed
currentState (IDLE| PROCESSING|PLAYING|PAUSED): - One of the state Symbols exported by the state-speech-synth module
typeString (string) - the type property from the original SpeechSynthesisUtterance event
event (object) - the original SpeechSynthesisUtterance event
validTransition (boolean) - a value indicating of the change from SpeechSynthsis was valid. If false the currentValue will not change, but the event will be the new invalid event.


#### Arguments
stateChangeHandler (Function) - A function that will be called whenever state changes

#### Returns
(Function) - A function that, when called, will unsubscribe the associated handler.

#### Example
`js
synth.onStateChange( ( currentState, type, event, validTransition ) => {
if ( ! validTransition ) return;

const displayStates = synthStateMap[currentState];

speechControls.map(
(controlElement, i) =>
(controlElement.style.display = getDisplayStyle(displayStates[i]))
);
});
`

speak( text, utteranceConfigObj )


This function is a combination speechSynthesis.speak and new SpeechSynthesisUtterance(text). It will handle setting up the utterance instance and firing it off to be processed.

#### Arguments
text (string) - A string that will be added to the queue for processing and speaking
utteranceConfigObj - and object that will be used to set the properties of the utterance instance. Currently only rate (string|number), voice (string) and volume (string|number) are handled.

#### Example
`js
synth.speak(textInput.value, { voice: 'Alex', rate: 1.7 });
`

pause, resume, cancel


These three functions directly use the SpeechSynthesis functions of the same name.
These are all documented on MDN far better than I could here.
[pause]()
[resume]()
[cancel]()

Roadmap

- [ ] Add queued state
- [ ] add toAudio conversion
- [ ] have speak` take an utterance
- [ ] allow additional utterance options