Skip to content

Latest commit

 

History

History
157 lines (133 loc) · 5.96 KB

README.md

File metadata and controls

157 lines (133 loc) · 5.96 KB
Raw

choo-tts stability

npm version build status downloads js-standard-style

Simple text-to-speech in the browser for choo

Usage

var choo = require('choo')
var html = require('choo/html')

var app = choo()
app.use(require('choo-tts')())
app.route('/', mainView)
app.mount('body')

function mainView (state, emit) {
  return html`
    <body>
      <button onclick=${onclick}>Say something</button>
    </body>
  `

  function onclick () {
    // speak with default voice
    emit('tts:speak', 'Hello world')
  }
}

Events

tts:error | tts.events.ERROR

Emitted when there is an error. It will get the error thrown as argument.

tts:speak | tts.events.SPEAK

Emit this event to speak some text. Can get a string and speak it with the default settings, or can get an object with text, rate, pitch and volume properties, only text is mandatory (lang is set in the voice, and the voice to speak is set in the state.selectedVoice property or with the tts:set-voice event). If you pass an object you can set an additional id property that can be used to identify this speech for the speech events.

tts:pause | tts.events.PAUSE

Emit this event to pause an ongoing speak. If there is no speaking taking place, it will do nothing.

tts:resume | tts.events.RESUME

Emit this event to resume an ongoing speak. If there is no paused speaking, it will do nothing.

tts:cancel | tts.events.CANCEL

Emit this event to cancel all qeued speechs.

tts:voices-changed | tts.events.VOICES_CHANGED

Set this event to handle every change on the availaible voices.

tts:set-voice | tts.events.SET_VOICE

Set the voice you want passing a string with the name of the voice. Use this event if you are sure of the name of the voice and that the voice is present in the client, otherwise it will throw. If you are unsure of the name, directly select the voice object from the state.tts.voices array.

tts:speech-start | tts.events.SPEECH_START

Emitted when a speech starts. The argument object has two properties, the event itself and an id. This event will be fired with every speech, but you can set this for a specific speech, if you set an id property to the object passed to the speak event. For example,

function speech (state, emitter) {
  emitter.on('tts:speech-start', function ({ event }) {
    console.log('Speech started!')
  })
  emitter.on('tts:speech-start', function ({ event, id }) {
    if (id === 'my-speech') console.log('My speech just started!')
  })
}

// later in your view
function view (state, emit) {
  return html`<body>
    <button onclick="${regularSpeech}">regular speech</button>
    <button onclick="${customSpeech}">custom speech</button>
  </body>`

  function regularSpeech () {
    emit('tts:speak', 'Just some regular speaking')
  }
  function customSpeech () {
    emit('tts:speak', {
      text: 'This speech is really special!',
      id: 'my-speech'
    })
  }
}

tts:speech-boundary | tts.events.SPEECH_BOUNDARY

Emitted when a word or sentence boundary is reched during a speech. The argument object has two properties, the event itself and an id. This event will be fired with every speech, but you can set this for a specific speech, if you set an id property to the object passed to the speak event.

tts:speech-end | tts.events.SPEECH_END

Emitted when a speech finish being spoken. The argument object has two properties, the event itself and an id. This event will be fired with every speech, but you can set this for a specific speech, if you set an id property to the object passed to the speak event.

API

plugin = tts([opts])

The plugin accept an options object and return the plugin. The opts object can have the following properties:

  • voice: A string with the name of the voice to be selected as selectedVoice. if not set, or not found, will use the browser default voice.
  • rate: The speed of the utterance to be spoken, can be a value from 0.1 to 10, defaults to 1.
  • pitch: The pitch of the utterance to be spoken, can be a value from 0 to 2, defaults to 1.
  • volume: The volume of the utterance to be spoken, can be a value from 0 to 1, defaults to 0.5.

If everything goes right, then the plugin will populate a tts object to the state.

  • tts.state: Get the state of text-to-speech object. Can be any of the following strings: PAUSED, PENDING, SPEAKING or READY.
  • tts.voices: The list of availaible voices. Notice that this object isn't allways populated until the dom has loaded, so you should use it there and re render your app if you are using it in the body of your html, check the example for more info.
  • tts.selectedVoice: The actual voice to be used for the next speaking, unless you pass an object to the speak event.
  • tts.rate: The speed of the utterance to be spoken, can be a value from 0.1 to 10, defaults to 1.
  • tts.pitch: The pitch of the utterance to be spoken, can be a value from 0 to 2, defaults to 1.
  • tts.volume: The volume of the utterance to be spoken, can be a value from 0 to 1, defaults to 0.5.

License

MIT