Speech Synthesis

Speak text aloud through the platform synthesizer

One.SpeechSynthesis speaks text aloud through the platform voice. Reach for it for read-aloud articles, navigation prompts, and accessibility announcements. It is separate from One.Speech, which is microphone dictation going the other way.

On iOS utterances queue on AVSpeechSynthesizer. On Android they queue on the system text-to-speech engine. On web the browser’s speech synthesis speaks.

Usage

import { One } from 'one'

One.SpeechSynthesis.speak('Hello', {
  language: 'en-US',
  rate: 1,
  onDone: () => console.log('finished'),
})

await One.SpeechSynthesis.stop()

speak queues while another utterance speaks. Each call carries its own start, done, stopped, and error callbacks, and every utterance ends with exactly one of done, stopped, or error.

How it works

Options default to the natural voice: pitch 1, rate 1, volume 1, and a system voice matching the language, which itself defaults to the current voice’s language. Volume runs 0 (muted) to 1. The text must fit maxInputLength, read once from the engine; iOS reports no limit. stop clears the queue and the interrupted utterance reports stopped. pause and resume hold and continue synthesis on iOS and resolve quietly on Android. isSpeaking covers this app’s queue, so it turns false once the queue finishes or stop resolves, and stays true while paused. getAvailableVoices resolves identifier, language, name, and quality entries, where quality is default or enhanced.

On iOS physical devices speech stays silent when the silent switch is on. On web cancellation maps to onStopped and every voice reports default quality. Without a synthesizer, speak does nothing, reads report empty, and callbacks never fire.

API reference

Platform differences

Limits and gotchas

• The silent switch mutes iOS. Physical devices say nothing with the switch on. Warn in audio-critical flows.
• Every utterance ends once. Done, stopped, or error, exactly one. Drive completion UI from those, not from timers.
• Pause is iOS only. Android resolves without holding. Stop and re-speak there for equivalent behavior.
• Callbacks belong to their speak. Each call’s options fire only for its own utterance, even when several queue.
• Speech is fire-and-forget. speak returns void; confirmation arrives through the callbacks.

Examples

import { useEffect } from 'react'
import { Button } from 'react-native'
import { One } from 'one'

function ReadAloud({ paragraphs }: { paragraphs: string[] }) {
  useEffect(() => {
    return () => {
      void One.SpeechSynthesis.stop()
    }
  }, [])

  function read() {
    for (const text of paragraphs) {
      One.SpeechSynthesis.speak(text, { rate: 1.1 })
    }
  }

  return <Button title="Read aloud" onPress={read} />
}

Queueing every paragraph at once speaks the article in order without manual chaining. Unmounting stops the queue so speech never outlives the screen.

import { useEffect, useState } from 'react'
import { Button } from 'react-native'
import { One } from 'one'

function Announcer({ message }: { message: string }) {
  const [voice, setVoice] = useState<string | undefined>(undefined)

  useEffect(() => {
    One.SpeechSynthesis.getAvailableVoices().then((voices) => {
      const enhanced = voices.find((entry) => entry.quality === 'enhanced')
      setVoice(enhanced?.identifier)
    })
  }, [])

  function announce() {
    One.SpeechSynthesis.speak(message, {
      voice,
      onError: () => {},
    })
  }

  return <Button title="Announce" onPress={announce} />
}

An enhanced voice reads announcements more naturally where one is installed; elsewhere the identifier stays undefined and the system voice speaks. The empty error callback keeps a failed announcement quiet.