Speech and subtitles
Text to speech with open license voices, captions timed to the voice, and the voice catalog.
On this page
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
audioSpeak( text, voice, autoInstall, onProgress, speed=1, pauses )
| 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. |
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
audioSpeakCues( text, voice, speed=1, pauses, maxChars=80, split="sentence", autoInstall, onProgress )
| 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. |
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
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
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.
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
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
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
audioSpeechStatus()
Returns A struct with home, engineInstalled, engineSizeMB, voicesDir and voices, the ids of the installed voices.