Skip to content

API.md

Latest commit

 

History

History
340 lines (277 loc) · 16 KB

API.md

File metadata and controls

340 lines (277 loc) · 16 KB

EasySpeech

module.exports ⏏

EasySpeech is the default export; you can import it with whichever name you like

Kind: Exported member
Example

import EasySpeech from 'easy-speech'

Example

import Easy from 'easy-speech'

module.exports~EasySpeech : Object

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

Setup is very straight forward (see example).

Kind: inner constant of module.exports
See

Example

import EasySpeech from 'easy-speech'

const example = async () => {
  await EasySpeech.init() // required
  await EasySpeech.speak({ 'Hello, world' })
}

EasySpeech.debug(fn)

Enable module-internal debugging by passing your own callback function. Debug will automatically pass through all updates to status

Kind: static method of EasySpeech

Param Type Description
fn function A function, which always receives one argument, that represents a current debug message

Example

import EasySpeech from 'easy-speech'
import Log from '/path/to/my/Log'

EasySpeech.debug(arg => Log.debug('EasySpeech:', arg))

EasySpeech.detect() ⇒ object

Detects all possible occurrences of the main Web Speech API components in the global scope.

The returning object will have the following structure (see example).

Kind: static method of EasySpeech
Returns: object - An object containing all possible features and their status
Example

EasySpeech.detect()

{
    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
}

EasySpeech.status() ⇒ Object

Returns a shallow copy of the current internal status. Depending of the current state this might return an object with only a single field status or a complete Object, including detected features, defaults, handlers and supported voices.

Kind: static method of EasySpeech
Returns: Object - the internal status
Example

import EasySpeech from 'easy-speech'

// uninitialized
EasySpeech.status() // { status: 'created' }

// after EasySpeech.init
EasySpeech.status()

{
  status: 'init: complete',
  initialized: true,
  speechSynthesis: speechSynthesis,
  speechSynthesisUtterance: SpeechSynthesisUtterance,
  speechSynthesisVoice: SpeechSynthesisVoice,
  speechSynthesisEvent: SpeechSynthesisEvent,
  speechSynthesisErrorEvent: SpeechSynthesisErrorEvent,
  voices: [...],
  defaults: {
    pitch: 1,
    rate: 1,
    volume: 1,
    voice: null
  },
  handlers: {}
}

EasySpeech.filterVoices([name], [voiceURI], [language], [localService]) ⇒ Array.<SpeechSynthesisVoice>

Returns a filtered subset of available voices by given parameters. Multiple parameters can be used.

Kind: static method of EasySpeech
Returns: Array.<SpeechSynthesisVoice> - a list of voices, matching the given rules

Param Type Description
[name] string a string that is expected to occur in the voices name; does not need to be the full name
[voiceURI] string a string that is expected to occur in the voices voiceURI; does not need to be the full URI
[language] string a language code to filter by .lang; short and long-form are accepted
[localService] boolean use true/false to include/exclude local/remote voices

EasySpeech.init(maxTimeout, interval, [quiet], [maxLengthExceeded]) ⇒ Promise.<Boolean>

This is the function you need to run, before being able to speak. It includes:

  • feature detection
  • feature assignment (into internal state)
  • voices loading
  • state update
  • inform caller about success

It will load voices by a variety of strategies:

  • 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

Note: if once initialized you can't re-init (will skip and resolve to false) unless you run EasySpeech.reset().

Kind: static method of EasySpeech
Fulfil: Boolean true, if initialized, false, if skipped (because already initialized)
Reject: Error - The error message property will always begin with EasySpeech: and contain one of the following:

  • browser misses features - The browser will not be able to use speech synthesis at all as it misses crucial features
  • browser has no voices (timeout) - No voice could be loaded with neither of the given strategies; chances are high the browser does not have any voices embedded (example: Chromium on *buntu os')
Param Type Description
maxTimeout number [5000] the maximum timeout to wait for voices in ms
interval number [250] the interval in ms to check for voices
[quiet] boolean prevent rejection on errors, e.g. if no voices
[maxLengthExceeded] string defines what to do, if max text length (4096 bytes) is exceeded: - 'error' - throw an Error - 'none' - do nothing; note that some voices may not speak the text at all without any error or warning - 'warn' - default, raises a warning

EasySpeech.voices() ⇒ Array.<SpeechSynthesisVoice>

Returns all available voices.

Kind: static method of EasySpeech
Condition: EasySpeech.init must have been called and resolved to true

EasySpeech.on(handlers) ⇒ Object

Attaches global/default handlers to every utterance instance. The handlers will run in parallel to any additional handlers, attached when calling EasySpeech.speak

Kind: static method of EasySpeech
Returns: Object - a shallow copy of the Object, containing all global handlers
Condition: EasySpeech.init must have been called and resolved to true

Param Type Description
handlers Object
[handlers.boundary] function optional, event handler
[handlers.end] function optional, event handler
[handlers.error] function optional, event handler
[handlers.mark] function optional, event handler
[handlers.pause] function optional, event handler
[handlers.resume] function optional, event handler
[handlers.start] function optional, event handler

EasySpeech.defaults([options]) ⇒ object

Sets defaults for utterances. Invalid values will be ignored without error or warning.

Kind: static method of EasySpeech
Returns: object - a shallow copy of the current defaults
See: https://wicg.github.io/speech-api/#utterance-attributes

Param Type Description
[options] object Optional object containing values to set values
[options.voice] object Optional SpeechSynthesisVoice instance or SpeechSynthesisVoice-like Object
[options.pitch] number Optional pitch value >= 0 and <= 2
[options.rate] number Optional rate value >= 0.1 and <= 10
[options.volume] number Optional volume value >= 0 and <= 1

EasySpeech.speak(options, text, [voice], [handlers]) ⇒ Promise.<(SpeechSynthesisEvent|SpeechSynthesisErrorEvent)>

Speaks a voice by given parameters, constructs utterance by best possible combinations of parameters and defaults.

If the given utterance parameters are missing or invalid, defaults will be used as fallback.

Kind: static method of EasySpeech
Fulfill: SpeechSynthesisEvent Resolves to the end event
Reject: SpeechSynthesisEvent rejects using the error event

Param Type Description
options object required options
text string required text to speak
[voice] object optional SpeechSynthesisVoice instance or structural similar object (if SpeechSynthesisUtterance is not supported)
[options.pitch] number Optional pitch value >= 0 and <= 2
[options.rate] number Optional rate value >= 0.1 and <= 10
[options.volume] number Optional volume value >= 0 and <= 1
[options.force] boolean Optional set to true to force speaking, no matter the internal state
[options.infiniteResume] boolean Optional, force or prevent internal resumeInfinity pattern
[options.noStop] boolean Optional, if true will not stop current voices
[handlers] object optional additional local handlers, can be directly added as top-level properties of the options
[handlers.boundary] function optional, event handler
[handlers.end] function optional, event handler
[handlers.error] function optional, event handler
[handlers.mark] function optional, event handler
[handlers.pause] function optional, event handler
[handlers.resume] function optional, event handler
[handlers.start] function optional, event handler

Example

const voice = EasySpeech.voices()[10] // get a voice you like

EasySpeech.speak({
  text: 'Hello, world',
  voice: voice,
  pitch: 1.2,  // a little bit higher
  rate: 1.7, // a little bit faster
  boundary: event => console.debug('word boundary reached', event.charIndex),
  error: e => notify(e)
})

EasySpeech.cancel()

Cancels the current speaking, if any running

Kind: static method of EasySpeech

EasySpeech.resume()

Resumes to speak, if any paused

Kind: static method of EasySpeech

EasySpeech.pause()

Pauses the current speaking, if any running

Kind: static method of EasySpeech

EasySpeech.reset()

Resets the internal state to a default-uninitialized state

Kind: static method of EasySpeech
⚡