Skip to content

Latest commit

 

History

History
179 lines (133 loc) · 6.03 KB

README.md

File metadata and controls

179 lines (133 loc) · 6.03 KB
Raw

Easy Speech

JavaScript Style Guide Project Status: Active – The project has reached a stable, usable state and is being actively developed. Test suite CodeQL Semantic Analysis npm npm bundle size npm bundle size

Cross browser Speech Synthesis; no dependencies.

This project was created, because it's always a struggle to get the synthesis part of Web Speech API running on most major browsers.

Note: this is not a polyfill package, if your target browser does not support speech synthesis or the Web Speech API, this package is not usable.

Install

Install from npm via

$ npm install easy-speech

You can also use the various builds for different targets, see the dist folder:

  • /dist/EasySpeech.js - ESM
  • /dist/EasySpeech.cjs.js - CommonJs
  • /dist/EasySpeech.es5.js - Legacy node compatible
  • /dist/EasySpeech.iife.js - Legacy compatible build, works even with older or exotic browsers, as long as they support Promises (PRs welcome to transform to callbacks!)

You can use them via CDN:

<!-- esm -->
<script type="module">
  import easySpeech from 'https://cdn.jsdelivr.net/npm/easy-speech/+esm'
</script>
<!-- classic -->
<script src="https://cdn.jsdelivr.net/npm/easy-speech/dist/EasySpeech.iife.js"></script>

Usage

Import EasySpeech and first, detect, if your browser is capable of tts (text to speech):

import EasySpeech from 'easy-speech'

EasySpeech.detect()

it returns an Object with the following information:

{
  speechSynthesis: SpeechSynthesis|undefined,
  speechSynthesisUtterance: SpeechSynthesisUtterance|undefined,
  speechSynthesisVoice: SpeechSynthesisVoice|undefined,
  speechSynthesisEvent: SpeechSynthesisEvent|undefined,
  speechSynthesisErrorEvent: SpeechSynthesisErrorEvent|undefined,
  onvoiceschanged: Boolean,
  onboundary: Boolean,
  onend: Boolean,
  onerror: Boolean,
  onmark: Boolean,
  onpause: Boolean,
  onresume: Boolean,
  onstart: Boolean
}

If at least SpeechSynthesis and SpeechSynthesisUtterance are defined you are good to go.

Initialize

Preparing everything to work is not as clear as it should, especially when targeting cross-browser functionality. The asynchronous init function will help you with this situation:

EasySpeech.init({ maxTimeout: 5000, interval: 250 })
    .then(() => console.debug('load complete'))
    .catch(e => console.error(e))

Loading voices

The init-routine will go through several stages to setup the environment:

  • detect and that SpeechSynthesis is basically supported, if not -> fail
  • load voices directly
  • if not loaded but onvoiceschanged is available: use onvoiceschanged
  • if onvoiceschanged is not available: fallback to timeout
  • if onvoiceschanged is fired but no voices available: fallback to timeout
  • timeout reloads voices in a given interval until a maxTimeout is reached
  • if voices are loaded until then -> complete
  • if no voices found -> fail

If your init routing has still not detected / loaded any voices, allthough speechSynth is supported please leave an issue!

Placing a fallback voice

If voices are found it will place a fallback voice by the following rules:

  • If there is a voice among all voices with the default property set to true use this as fallback voice
  • Otherwise find the first matching voice by current navigator.language
  • Otherwise use the first voice in the Array

Note: This fallback voice is not overridden by EasySpeech.defaults(), your default voice will be used in favor but the fallback voice will always be there in case no voice is found when calling EasySpeech.speak()

Speak a voice

This is as easy as it gets:

await EasySpeech.speak({
  text: 'Hello, world!',
  voice: myLangVoice, // optional, will use a default or fallback
  pitch: 1,
  rate: 1,
  volume: 1,
  // there are more events, see the API for supported events
  boundary: e => console.debug('boundary reached')
})

The Promise will automatically resolve when the speaking ends or rejects when an error occurred. You can additionally attach these event listeners if you like or use EasySpeech.on to attach default listeners to every time you call EasySpeech.speak.

API

There is a full API documentation available: api docs

Contribution and development

Every contribution is welcomed, please open issues if anything is not working as expected.

If you intend to contribute code, please read the guidelines on contributing.

Resources

This project used several resources to gain insights about how to get the best cross-browser SpeechSynthesis running:

License

MIT, see license file