Voice Agent Nodes
Text-to-speech through the voice agent: resolve voices (including the narrator's), unpack voice data and generate speech, and read or rewrite the text of a chunk before it is spoken.
Unpack Generation Emission and Set Chunk Text belong in an event module listening for agent.tts.generate.before, which fires once per chunk of text right before its audio is generated. Text Manipulation walks through the setup.
Reading the chunk
<Event>.event<Unpack Generation Emission>.emission
The text, character_name, type, api, message_id and voice outputs describe the chunk the agent is about to send to the backend.
Rewriting the text
<Unpack Generation Emission>.text<Replace>.string<Unpack Generation Emission>.emission<Set Chunk Text>.emission<Replace>.result<Set Chunk Text>.text<Make Bool>.value<Set Chunk Text>.state
The backend reads the chunk after the event, so the replaced text is what gets spoken. Writing empty text does not cancel the generation.
8 nodes.
| Node | Registry path |
|---|---|
| Audio Tag Support | agents/tts/AudioTagSupport |
| Generate TTS | agents/tts/Generate |
| Get Narrator Voice | agents/tts/GetNarratorVoice |
| Get Voice | agents/tts/GetVoice |
| Set Chunk Text | agents/tts/SetChunkText |
| TTS Agent Settings | agents/tts/Settings |
| Unpack Generation Emission | agents/tts/UnpackGenerationEmission |
| Unpack Voice | agents/tts/UnpackVoice |
Audio Tag Support
agents/tts/AudioTagSupport
Whether the voice backend of a chunk accepts sound tags such as [laugh] or [sigh], and which ones. Use it on agent.tts.generate.before before adding a tag with Set Chunk Text.
Inputs
| Input | Type | Description |
|---|---|---|
emission |
event,tts/generation_emission |
The generation emission |
tag |
str |
A tag name to format for this backend, e.g. laugh (optional) |
Outputs
| Output | Type | Description |
|---|---|---|
emission |
tts/generation_emission |
The emission, passed through |
supported |
bool |
True when the backend and model accept sound tags |
allowed_tags |
list |
The tags the backend accepts, or None when any tag is accepted |
tag_format |
str |
How a tag is written for this backend, with {{ tag }} for the name |
formatted_tag |
str |
The tag input written in the backend's format, or None when the backend does not accept it |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
tag |
str |
"" |
A tag name to format for this backend |
Generate TTS
agents/tts/Generate
Generates speech audio for the given text via the TTS agent and queues it for playback in the frontend. Either a voice or a character must be provided; when a character is given its assigned voice is used, while an explicit voice input overrides it. Does nothing when the TTS agent is disabled or not ready.
Inputs
| Input | Type | Description |
|---|---|---|
state |
any |
The graph state |
text |
text |
(optional) The text to speak (required at runtime despite the optional socket) |
voice |
tts/voice |
The voice to use (optional) |
character |
character |
The character to speak as (optional) |
Outputs
| Output | Type | Description |
|---|---|---|
state |
any |
The state input, passed through |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
text |
text |
unset |
The text to generate |
Get Narrator Voice
agents/tts/GetNarratorVoice
Gets the narrator voice from the TTS agent.
Outputs
| Output | Type | Description |
|---|---|---|
voice |
tts/voice |
Get Voice
agents/tts/GetVoice
Looks up a voice in the TTS agent's voice library by voice ID.
Inputs
| Input | Type | Description |
|---|---|---|
voice_id |
str |
(optional) The ID of the voice to get (required at runtime despite the optional socket) |
Outputs
| Output | Type | Description |
|---|---|---|
voice |
tts/voice |
The voice object (None if no voice with that ID exists) |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
voice_id |
str |
unset |
The ID of the voice to get |
Set Chunk Text
agents/tts/SetChunkText
Replaces the text of the chunk carried by a TTS generation emission, letting a graph rewrite what is spoken before the audio is generated. Empty text still reaches the backend and produces no audio for that chunk.
Inputs
| Input | Type | Description |
|---|---|---|
state |
any |
The graph state (required — wire through any gating switch so the node is skipped when the chunk should be left alone) |
emission |
event,tts/generation_emission |
The generation emission |
text |
str,text |
(optional) The text to speak instead (required at runtime despite the optional socket) |
Outputs
| Output | Type | Description |
|---|---|---|
state |
any |
The state input, passed through |
emission |
tts/generation_emission |
The emission, passed through |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
text |
text |
unset |
The text to speak instead |
TTS Agent Settings
agents/tts/Settings
Base node to render TTS agent settings.
Every setting of the tts agent is exposed as an output socket named after the setting - see the agent's documentation under Agents for what each setting does.
Unpack Generation Emission
agents/tts/UnpackGenerationEmission
Unpacks a TTS generation emission into the fields of the chunk that is about to be spoken.
Inputs
| Input | Type | Description |
|---|---|---|
emission |
event,tts/generation_emission |
The generation emission |
Outputs
| Output | Type | Description |
|---|---|---|
emission |
tts/generation_emission |
The emission, passed through |
text |
str,text |
The text of the chunk |
character_name |
str |
The name of the character speaking the chunk |
type |
str |
The chunk type (dialogue or exposition) |
api |
str |
The TTS provider (API) generating the chunk |
message_id |
int,str |
The ID of the message the chunk belongs to |
voice |
tts/voice |
The voice the chunk will be spoken with |
model |
str |
The model of the voice, when the voice sets one |
Unpack Voice
agents/tts/UnpackVoice
Unpacks a voice object into its individual fields.
Inputs
| Input | Type | Description |
|---|---|---|
voice |
tts/voice |
The voice to unpack |
Outputs
| Output | Type | Description |
|---|---|---|
voice |
tts/voice |
The voice, passed through |
label |
str |
The voice's display label |
provider |
str |
The TTS provider (API) the voice belongs to |
provider_id |
str |
The voice's ID at the provider |
provider_model |
str |
The provider model the voice uses |
tags |
list |
The voice's tags |
parameters |
dict |
The voice's generation parameters |
is_scene_asset |
bool |
Whether the voice is stored as a scene asset |