easilybaffled/state-speech-synth

Created with CodeSandbox

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

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

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

state-speech-synth's Issues

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on Greenkeeper branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please click the 'fix repo' button on account.greenkeeper.io.