--- title: Speech and subtitles order: 9 summary: Text to speech with open license voices, captions timed to the voice, and the voice catalog. --- Text to speech with open license voices, captions timed to the voice, and the voice catalog. ## audioSpeak Turn text into speech with an installed Piper voice, installing the engine and the voice on first use ```js audioSpeak( text, voice, autoInstall, onProgress, speed=1, pauses, pronunciations ) ``` | Argument | Type | Default | | |---|---|---|---| | `text` | string | required | What to say. | | `voice` | string | required | The voice: an id such as en_US-joe-medium, or its short name such as joe. See audioVoices(). | | `autoInstall` | boolean | optional | May the engine and the voice be downloaded when they are missing. Defaults to the module setting autoInstall, which is true. The first call downloads about 150 MB for the engine and 60 MB or more for the voice. | | `onProgress` | function | optional | A function called as ( name, bytesDone, bytesTotal ) while something downloads. | | `speed` | double | `1` | How fast to speak: 1 is the voice's own pace, 1.25 faster, 0.8 slower. Between 0.25 and 4. Defaults to 1. | | `pauses` | struct | optional | A struct with any of sentence, clause and paragraph, in seconds, to speak the text piece by piece with those pauses between the pieces (defaults 0.35, 0.15 and 0.8). Leave it out to let the voice phrase the whole text itself. | | `pronunciations` | struct | optional | A struct of word to spoken form for words the voice gets wrong, for example { Ortus: "Or tus" }. BoxLang and the names of its family are already said correctly. The text you pass stays as it is, only what the voice is given changes. | **Returns** A mono audio buffer at the voice sample rate, normally 22050 Hz. ## audioSpeakCues Speak a text piece by piece and return the audio with the time each caption line is spoken ```js audioSpeakCues( text, voice, speed=1, pauses, maxChars=80, split="sentence", autoInstall, onProgress, pronunciations ) ``` | Argument | Type | Default | | |---|---|---|---| | `text` | string | required | What to say. Blank lines separate paragraphs. | | `voice` | string | required | The voice: an id such as en_US-joe-medium, or its short name. See audioVoices(). | | `speed` | double | `1` | 1 is the voice's own pace. Between 0.25 and 4. Defaults to 1. | | `pauses` | struct | optional | A struct with any of sentence, clause and paragraph in seconds. Defaults 0.35, 0.15 and 0.8. | | `maxChars` | integer | `80` | Longest caption line in characters; longer sentences are split into several lines. Defaults to 80. | | `split` | string | `"sentence"` | sentence to speak and time whole sentences, clause to work clause by clause (more natural pauses, shorter captions). Defaults to sentence. | | `autoInstall` | boolean | optional | May the engine and the voice be downloaded when missing. Defaults to the module setting autoInstall. | | `onProgress` | function | optional | A function called as ( name, bytesDone, bytesTotal ) while something downloads. | | `pronunciations` | struct | optional | A struct of word to spoken form for words the voice gets wrong, for example { Ortus: "Or tus" }. The captions keep the original words. BoxLang and the names of its family are already said correctly. | **Returns** A struct with audio (a mono buffer), cues (an array of structs with start, end and text, in seconds) and seconds (the length). Pass the cues to audioSubtitles(). ## audioSubtitles Write captions as SRT or WebVTT subtitles for a video ```js audioSubtitles( cues, format="srt", path="", offset=0 ) ``` | Argument | Type | Default | | |---|---|---|---| | `cues` | array | required | An array of structs with start, end (seconds) and text, such as the cues from audioSpeakCues(). | | `format` | string | `"srt"` | srt or vtt. Defaults to srt. | | `path` | string | `""` | A file to write the subtitles to as well. Empty to only return the text. | | `offset` | double | `0` | Seconds added to every time, for narration that starts later in the video. Defaults to 0. | **Returns** The subtitle text. ## audioVoices List the voices of the collection, with their licenses and what you can do with each ```js audioVoices( language="", installed=false, status="offered", license="" ) ``` | Argument | Type | Default | | |---|---|---|---| | `language` | string | `""` | Only voices of this language, for example en_US or en_GB. Empty for all. | | `installed` | boolean | `false` | True to list only the voices that are installed. Same as status="installed". | | `status` | string | `"offered"` | offered (default: voices you can use), installed, downloadable (offered, not installed yet), excluded (not offered, with the reason) or all. | | `license` | string | `""` | Only voices with this license identifier, for example CC0-1.0 or Apache-2.0. | **Returns** An array of structs with id, name, language, quality, license, licenseText, shareAlike, source, sizeMB, installed, status (installed, downloadable or excluded), reasonKind and reason (empty unless excluded). ## audioLicenses List the licenses of the offered voices and what each asks of you. A summary for orientation, the voice's model card is the authority. ```js audioLicenses() ``` **Returns** An array of structs with id, name, url, commercial, attribution, shareAlike, summary and voices (how many offered voices use it). ## audioVoiceInstall Download a voice, or the text to speech engine itself, and check it ```js audioVoiceInstall( voice, onProgress ) ``` | Argument | Type | Default | | |---|---|---|---| | `voice` | string | required | A voice id or short name from audioVoices(), or "engine" for the speech engine that every voice needs. | | `onProgress` | function | optional | A function called as ( name, bytesDone, bytesTotal ) while files download. | **Returns** A struct with name, installed and the path of what was installed. ## audioVoiceRemove Delete an installed voice, or the text to speech engine, from disk ```js audioVoiceRemove( voice ) ``` | Argument | Type | Default | | |---|---|---|---| | `voice` | string | required | A voice id or short name from audioVoices(), or "engine". | **Returns** True if something was deleted, false if it was not installed. ## audioSpeechStatus Describe the text to speech setup: where it lives, whether the engine is installed, and which voices are ```js audioSpeechStatus() ``` **Returns** A struct with home, engineInstalled, engineSizeMB, voicesDir and voices, the ids of the installed voices.