![\"TextToSpeech](\"./tts-react.png\")
\n\n`tts-react` provides a hook (`useTts`) and component (`TextToSpeech`) to convert text to speech. In most cases you want the hook so you can use custom styling on the audio controls.\n\nBy default `tts-react` uses the [`SpeechSynthesis`](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis) and [`SpeechSynthesisUtterance`](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance) API's. You can fallback to the [`HTMLAudioElement`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio) API by providing a `fetchAudioData` prop to the hook or component.\n\n## Install\n\n```console\nnpm i react react-dom tts-react\n```\n\nFor projects using React 18:\n\n```console\nnpm i react@18 react-dom@18 tts-react@3\n```\n\n## Demo (Storybook)\n\n[morganney.github.io/tts-react](https://morganney.github.io/tts-react/)\n\n## Example\n\n#### ESM + CDN\n\nGet up and running quickly using `tts-react` with ESM from a CDN. This example uses [React 19](https://react.dev/blog/2024/04/25/react-19) with [`htm`](https://github.com/developit/htm):\n\n```html\n\n\n \n \n \n This text will be spoken on render.
\nSome text to be spoken and highlighted.
\nSome text to be spoken.
\n \n )\n}\n```\n\n## `useTts`\n\nThe hook returns the internal state of the audio being spoken, getters/setters of audio attributes, callbacks that can be used to control playing/stopping/pausing/etc. of the audio, and modified `children` if using `markTextAsSpoken`. The parameters accepted are described in the [Props](#props) section. The response object is described by the `TTSHookResponse` type.\n\n```ts\nconst {\n get,\n set,\n state,\n spokenText,\n ttsChildren,\n play,\n stop,\n pause,\n replay,\n playOrPause,\n playOrStop,\n toggleMute\n} = useTts({\n lang,\n voice,\n children,\n autoPlay,\n markTextAsSpoken,\n markColor,\n markBackgroundColor,\n onStart,\n onBoundary,\n onPause,\n onEnd,\n onError,\n onVolumeChange,\n onPitchChange,\n onRateChange,\n fetchAudioData\n})\n\ninterface TTSHookProps extends MarkStyles {\n /** The spoken text is extracted from here. */\n children: ReactNode\n /** The `SpeechSynthesisUtterance.lang` to use. */\n lang?: string\n /** The `SpeechSynthesisUtterance.voice` to use. */\n voice?: SpeechSynthesisVoice\n /** The initial rate of the speaking audio. */\n rate?: number\n /** The initial volume of the speaking audio. */\n volume?: number\n /** Whether the text should be spoken automatically, i.e. on render. */\n autoPlay?: boolean\n /** Whether the spoken word should be wrapped in a `` element. */\n markTextAsSpoken?: boolean\n /** Callback when the volume is changed. */\n onVolumeChange?: (newVolume: number) => void\n /** Callback when the rate is changed. */\n onRateChange?: (newRate: number) => void\n /** Callback when the pitch is changed. */\n onPitchChange?: (newPitch: number) => void\n /** Callback when there is an error of any kind. */\n onError?: (msg: string) => void\n /** Callback when speaking/audio starts playing. */\n onStart?: (evt: SpeechSynthesisEvent | Event) => void\n /** Callback when the speaking/audio is paused. */\n onPause?: (evt: SpeechSynthesisEvent | Event) => void\n /** Calback when the current utterance/audio has ended. */\n onEnd?: (evt: SpeechSynthesisEvent | Event) => void\n /** Function to call when the SpeechSynthesis API is not supported. */\n onNotSupported?: TTSFallback\n /** Callback when a word boundary/mark has been reached. */\n onBoundary?: (evt: SpeechSynthesisEvent | Event) => void\n /** Function to fetch audio and speech marks for the spoken text. */\n fetchAudioData?: (spokenText: string) => PromiseThis is independent of tts-react and will happen if you are using the SpeechSynthesis Web Speech API on a platform that only provides network-based SpeechSynthesisVoices. See the associated issue for more details. Unfortunately, all you can really do is try another platform that has local voices installed.
Due to the way Children.map works
\n\nThe traversal does not go deeper than React elements: they don't get rendered, and their children aren't traversed.
\n
tts-react can not extract the text from child components. Instead, include the text as a direct child of TextToSpeech (or useTts).
markTextAsSpoken sometimes highlight the wrong word?The SpeechSynthesisUtterance boundary event may fire with skewed word boundaries for certain combinations of spokenText and lang or voice props. If you check the value of state.boundary.word in these cases, you will find the event is firing at unexpected boundaries, so there is no real solution other than to find a suitable voice for your given spokenText.
markTextAsSpoken not work on Chrome for Android or Linux?This is a known issue by the Chromium team that apparently they are not going to fix. There is no boundary event fired on platforms that only support network-based voices. You can use fetchAudioData to fallback to the HTMLAudioElement, or try a different browser/OS.
SpeechSynthesis on Firefox and Chrome for Android?See the compat table on MDN for SpeechSynthesis.pause().
\nIn Android, pause() ends the current utterance. pause() behaves the same as cancel().\n
You can use the hook useTts to build custom controls that do not expose a pause, but only stop. If using the TextToSpeech component use the useStopOverPause prop for Android devices.
dangerouslySetInnerHTML not spoken?tts-react does not speak text from dangerouslySetInnerHTML. Instead convert your HTML string into React elements via an html-to-react parser. See this example.
Safari is becoming the new IE, and simply does not follow the spec completely (yet). As one example, Safari 15.6.1 on macOS Monterey 12.5.1, throws a SpeechSynthesisEvent during a SpeechSynthesisUtterance.error, while the spec says errors against utterances \"must use the SpeechSynthesisErrorEvent interface\".