The speech API provides text-to-speech output via the browser TTS engine. Supports both global (2D) audio and 3D positional audio attached to ped entities or world coordinates.
Networked audio: When a 3D speak call is made for a networked entity (and network audio is enabled for the calling addon), the sound is broadcast to nearby players automatically via the server relay. Other players hear the speech spatially from the entity's position.
Synthesize and play TTS audio. Pass an entity or coords to produce 3D positioned audio; omit both for global audio.
Syntax
| Name | Type | Description |
|---|---|---|
text | string | Text to speak. Required, non-empty. |
options.voice | string | table | Voice name string ("en-US-GuyNeural") or voice object — see below. |
options.entity | number | Ped entity handle for 3D positioned audio. Voice is auto-detected from NPC config if not specified. |
options.coords | vector3 | World coordinates for 3D audio without a ped entity. |
options.maxDistance | number | Hearing range in metres for 3D audio (default 30.0). |
options.animation | table | false | Animation options for ped entities. false disables all animation. |
options.showSubtitle | boolean | Display a subtitle synced to actual TTS duration. |
options.immediateSubtitle | boolean | Display subtitle immediately without waiting for TTS timing. |
options.npcName | string | Speaker name shown in the subtitle. |
options.networked | boolean | Broadcast 3D audio to nearby players via server relay. |
Returns: { success = true, data = { soundId = "sound_12345_6789", is3D = true } }
For global audio, soundId is nil and is3D is false. For 3D audio, soundId is a string you can pass to stopSpeech.
The voice field accepts either a plain string name or a full settings object:
The legacy flat structure (options.rate, options.pitch, options.volume at the top level) is also supported for backward compatibility.
For entity-based 3D audio on peds, lip-sync and gesture animations are enabled by default:
Pass animation = false to disable all animation entirely.
Your Script
Stop TTS playback. Stop a specific 3D sound by ID or stop all active sounds at once.
Syntax
| Name | Type | Description |
|---|---|---|
soundId | string | Specific 3D sound ID returned from speak. Omit to stop all sounds. |
Returns: { success = true, data = { stopped = 1 } } — stopped is -1 when stopping all (count unknown).
Your Script
Retrieve the list of available TTS voices from the browser engine. Async — the browser engine must be ready.
Syntax
| Name | Type | Description |
|---|---|---|
callback | function | function(result) — called with { success, data = { voices } } on completion or { success = false, code = "TIMEOUT" } on timeout. |
timeout | number | Milliseconds before callback fires with a timeout error (default 5000). |
Without a callback: returns immediately with { success = true, data = { pending = true, listenEvent = "onex-voiceInteraction:tts:voices" } }. Listen to the named event to receive the voice list asynchronously.
Your Script
Get the configured or auto-detected TTS voice for a ped entity. Uses NPC config if available, falls back to gender-based pool selection.
Syntax
| Name | Type | Description |
|---|---|---|
entity | number | Ped entity handle |
Returns: { success = true, data = { voice = "en-US-GuyNeural", gender = "male", cached = false } }
| Field | Type | Description |
|---|---|---|
voice | string | Voice name to use |
gender | string | "male" or "female" |
cached | boolean | true if result was served from cache |
Results are cached per entity using a stable key (network ID + model hash). The cache persists for 5 minutes; local entity cache entries are pruned automatically.
Your Script
Clear the voice assignment cache for a specific ped or all peds. Forces re-detection on the next speak or getVoiceForPed call.
Syntax
| Name | Type | Description |
|---|---|---|
entity | number | Ped entity handle, or omit to clear all cached entries |
Returns: { success = true, data = { cleared = 1 } }
Your Script
Last updated 14 days ago
