ElevenLabs TTS
v1.1.0
The ElevenLabs TTS LOP generates high-quality, natural-sounding speech from text using the ElevenLabs API. It streams audio over WebSockets directly into a TouchDesigner CHOP for low-latency playback, and supports saving generated audio to disk and recalling previously generated clips from local storage or the ElevenLabs API history.
Requirements
Section titled “Requirements”- ElevenLabs API Key: Obtain one from your ElevenLabs account and enter it on the ElevenLabs page. The key is stored securely in a local configuration file.
- Python Dependencies:
websockets,requests,numpy, andsoundfile. Pulse ‘Install Dependencies’ on the ElevenLabs page to install them automatically, or pulse ‘Check Dependencies’ to verify they are present.
Input/Output
Section titled “Input/Output”Inputs
Section titled “Inputs”- Input DAT (optional): When ‘Text Input Source’ is set to ‘Input DAT [ in2 ]’, the operator reads text from a DAT connected to its second input instead of the parameter field.
Outputs
Section titled “Outputs”- Output CHOP: Contains the streamed or loaded audio data (mono, 24kHz PCM). The CHOP output mode can be switched between ‘Playback’ and ‘Full Audio’ using ‘Output 1 (CHOP) out2’ on the Playback page.
- Saved Audio Files: When ‘Auto Save To Disk’ is enabled, audio files (WAV, MP3, or OGG) and JSON metadata are saved to the configured ‘Output Folder’.
Usage Examples
Section titled “Usage Examples”Basic Text-to-Speech
Section titled “Basic Text-to-Speech”- Enter your ElevenLabs API Key on the ElevenLabs page.
- Pulse ‘Fetch Available Voices’ to populate the ‘Voice’ menu, then select a voice.
- Choose a ‘Model’ (Eleven Multilingual v2 is the default high-quality option; Turbo and Flash models offer lower latency).
- Enter text in ‘Text to Speak’.
- Ensure ‘Play On Result’ is enabled so audio plays as soon as it starts streaming.
- Pulse ‘Start Streaming’. Audio streams in and plays through the configured audio device.
Streaming from an Input DAT
Section titled “Streaming from an Input DAT”- Set ‘Text Input Source’ to ‘Input DAT [ in2 ]’.
- Connect a Text DAT to the second input of the ElevenLabs operator.
- Enter or pipe text into that DAT.
- Pulse ‘Start Streaming’.
Saving Audio to Disk
Section titled “Saving Audio to Disk”- On the Playback page, enable ‘Auto Save To Disk’.
- Set the ‘Output Folder’ and optionally configure ‘Base Name’ (use
$JOBIDfor unique filenames), ‘File Type’ (WAV, MP3, or OGG), and ‘Auto Version’. - Stream audio as usual. After a successful generation, the audio file and a JSON metadata file are saved automatically.
- To manually save the current audio, pulse ‘Save File’.
Recalling Audio from History
Section titled “Recalling Audio from History”- On the History page, pulse ‘Update History’ to refresh the list from local storage and the ElevenLabs API.
- Use ‘Select From’ to filter between all sources, all local files, or the current project folder only.
- Choose an entry from the ‘Audio to Load’ menu. Use the ‘Display’ menu to change how entries are labeled (by voice name, input text, timestamp, or file path).
- Pulse ‘Load Audio File’ to load the selected audio into the output CHOP.
- Enable ‘Playback From History’ and pulse ‘Play Start’ to play the loaded clip.
Playback Configuration
Section titled “Playback Configuration”The Playback page provides direct control over audio output hardware:
- Driver: Choose between the default system driver (DirectSound on Windows, CoreAudio on macOS) or ASIO for low-latency output.
- Device: Select the specific audio output device.
- Volume: Adjust playback volume (0.0 to 1.0).
Voice Settings
Section titled “Voice Settings”On the ElevenLabs page, three parameters fine-tune voice synthesis:
- Stability: Controls randomness in the generated speech. Lower values produce more expressive but less consistent output.
- Similarity Boost: Higher values make the output sound closer to the original voice sample, but may introduce artifacts at extreme settings.
- Use Speaker Boost: Enhances speaker clarity. Recommended when using multilingual models.
Troubleshooting
Section titled “Troubleshooting”- No voices in the menu: Pulse ‘Fetch Available Voices’ after entering a valid API key. If the menu remains empty, check the API key and your network connection.
- Audio not playing: Verify that ‘Play’ is enabled, the correct audio ‘Device’ is selected on the Playback page, and ‘Active’ is toggled on under Audio Device Settings.
- Dependency errors: Pulse ‘Install Dependencies’ on the ElevenLabs page. If issues persist, pulse ‘Check Dependencies’ to see which packages are missing.
- Credit limits: Pulse ‘Check Credits’ to view your current character usage, quota, and reset date in the ‘Credit Info’ field.
Parameters
Section titled “Parameters”ElevenLabs
Section titled “ElevenLabs” Status (Status)
op('tts_elevenlabs').par.Status Str Displays the current status of the operator.
- Default:
"" (Empty String)
Active (Active)
op('tts_elevenlabs').par.Active Toggle - Default:
False
Playing (Playing)
op('tts_elevenlabs').par.Playing Toggle - Default:
False
Play Start (Playstart)
op('tts_elevenlabs').par.Playstart Pulse - Default:
False
Play (Play)
op('tts_elevenlabs').par.Play Toggle - Default:
True
Play On Result (Playonresult)
op('tts_elevenlabs').par.Playonresult Toggle Starts playback when the stream starts.
- Default:
True
Start Streaming (Stream)
op('tts_elevenlabs').par.Stream Pulse Connects to the WebSocket and starts streaming TTS for the input text.
- Default:
False
Stop Streaming (Stop)
op('tts_elevenlabs').par.Stop Pulse Disconnects the WebSocket and stops any ongoing streaming.
- Default:
False
Clear Stored Audio (Clearaudio)
op('tts_elevenlabs').par.Clearaudio Pulse Clears any audio currently stored in the output CHOP.
- Default:
False
Text to Speak (Text)
op('tts_elevenlabs').par.Text Str Text to convert to speech if Text Input Source is "Parameter Text".
- Default:
text to speak
Stability (Stability)
op('tts_elevenlabs').par.Stability Float Controls randomness. Lower values are more expressive but less stable.
- Default:
0.5- Range:
- 0 to 1
- Slider Range:
- 0 to 1
Similarity Boost (Similarityboost)
op('tts_elevenlabs').par.Similarityboost Float Higher values make the speech more similar to the original voice, but can introduce artifacts.
- Default:
0.8- Range:
- 0 to 1
- Slider Range:
- 0 to 1
Use Speaker Boost (Usespeakerboost)
op('tts_elevenlabs').par.Usespeakerboost Toggle Boosts speaker clarity. Recommended for multilingual models.
- Default:
True
ElevenLabs API Key (Apikey)
op('tts_elevenlabs').par.Apikey Str Enter your ElevenLabs API key. It will be stored securely.
- Default:
"" (Empty String)
Get API Key (Getapikey)
op('tts_elevenlabs').par.Getapikey Pulse Opens elevenlabs.io in your browser. Find the key in your account settings.
- Default:
False
Fetch Available Voices (Getvoices)
op('tts_elevenlabs').par.Getvoices Pulse Retrieves the list of available voices from the ElevenLabs API.
- Default:
False
Check Credits (Checkcredits)
op('tts_elevenlabs').par.Checkcredits Pulse Retrieves current usage and quota information from your ElevenLabs account.
- Default:
False
Credit Info (Creditinfo)
op('tts_elevenlabs').par.Creditinfo Str Displays current character usage, limit, and reset date.
- Default:
"" (Empty String)
Install Dependencies (Installdeps)
op('tts_elevenlabs').par.Installdeps Pulse - Default:
False
Check Dependencies (Checkdeps)
op('tts_elevenlabs').par.Checkdeps Pulse - Default:
False
Playback
Section titled “Playback” Audio Device Settings Header
Active (Audioactive)
op('tts_elevenlabs').par.Audioactive Toggle - Default:
True
Volume (Volume)
op('tts_elevenlabs').par.Volume Float - Default:
1.0- Range:
- 0 to 1
- Slider Range:
- 0 to 1
Save Audio To File Header
Auto Save To Disk (Autosavetodisk)
op('tts_elevenlabs').par.Autosavetodisk Toggle Automatically save generated audio and metadata locally after successful streaming.
- Default:
True
Save File (Savefile)
op('tts_elevenlabs').par.Savefile Pulse - Default:
False
Base Name (Name)
op('tts_elevenlabs').par.Name Str Base filename for saved audio. Use $JOBID for unique names.
- Default:
"" (Empty String)
Output Folder (Folder)
op('tts_elevenlabs').par.Folder Folder - Default:
tts_elevenlabs_outs
Auto Version (Autoversion)
op('tts_elevenlabs').par.Autoversion Toggle - Default:
True
CHOP Outputs Header
History
Section titled “History” Playback From History (Playbackfromhistory)
op('tts_elevenlabs').par.Playbackfromhistory Toggle - Default:
False
Playing (Playinghistory)
op('tts_elevenlabs').par.Playinghistory Toggle - Default:
False
Audio File Path (Audiofilepath)
op('tts_elevenlabs').par.Audiofilepath Str - Default:
$TT/Audio/JeremyCaulfield_www.dumb-unit.com.mp3
Load Audio File (Loadfile)
op('tts_elevenlabs').par.Loadfile Pulse Downloads/Loads the audio for the specified History ID (local first) and loads it into the output CHOP.
- Default:
False
Update History (Fetchhistory)
op('tts_elevenlabs').par.Fetchhistory Pulse Retrieves the latest generation history items from the ElevenLabs API.
- Default:
False
Callbacks
Section titled “Callbacks” Callbacks Header
Create Callbacks (Createcallbacks)
op('tts_elevenlabs').par.Createcallbacks Pulse - Default:
False
Callback DAT (Callbackdat)
op('tts_elevenlabs').par.Callbackdat DAT - Default:
tts_elevenlabs_callbacks
onGenerate (Ongenerate)
op('tts_elevenlabs').par.Ongenerate Toggle - Default:
True
onDone (Ondone)
op('tts_elevenlabs').par.Ondone Toggle - Default:
True
onPlayStart (Onplaystart)
op('tts_elevenlabs').par.Onplaystart Toggle - Default:
True
onPlayEnd (Onplayend)
op('tts_elevenlabs').par.Onplayend Toggle - Default:
True
onSave (Onsave)
op('tts_elevenlabs').par.Onsave Toggle - Default:
True
Callbacks
Section titled “Callbacks” Available Callbacks:
onGenerateonDoneonPlayStartonPlayEndonSave
Example Callback Structure:
def onGenerate(info):
# Called before streaming starts
# info: {'job_id', 'text', 'voice_id', 'model_id'}
print(f"Starting generation job: {info.get('job_id')}")
def onDone(info):
# Called when streaming finishes or errors
# info: {'job_id', 'status', 'message', 'duration', 'text', 'voice_id', 'model_id'}
print(f"Generation finished: {info.get('status')} ({info.get('duration')}s)")
def onPlayStart(info):
# Called when playback starts
# info: {'job_id', 'audio_duration', 'text'}
print(f"Playback started for job: {info.get('job_id')}")
def onPlayEnd(info):
# Called when playback ends
# info: {'job_id', 'audio_duration', 'text'}
print(f"Playback finished for job: {info.get('job_id')}")
def onSave(info):
# Called after audio is saved successfully
# info: {'job_id', 'filepath', 'filename', 'folder', 'duration', 'text'}
print(f"Audio saved to: {info.get('filepath')}")Changelog
Section titled “Changelog”v1.1.02025-07-30
- Refactored Core Systems: Major overhaul to align the operator with the latest
DotLOPUtilsstandards. - Centralized API Key Management: Switched to using the central
key_managerfor API key storage, eliminating local config files and extraneous folder creation on startup. - Unified Output Folder: All file-saving logic now correctly and exclusively uses the
Folderparameter, ensuring all audio and metadata are stored in a single, user-defined location. - Robust Dependency Installation: Replaced the previous dependency check with the standard
python_managerpattern, including a dedicated "Dependencies" page with an "Install Dependencies" button for a smoother setup. - Improved Stream Handling: Implemented an idle timeout for the websocket connection to prevent the
onDonecallback from being delayed, making the operator more responsive. - Bug Fix: Corrected an error in the audio streaming logic that was causing a crash when initializing the output CHOP.
- Added Reset Functionality: Implemented a comprehensive
ResetOpfunction and a corresponding UI button on a new "Settings" page to allow for a clean reset of the operator's state and logs. - Inheritance Update: Changed the base class from
DotChatUtiltoDotLOPUtilsto leverage new helper functions.
v1.0.02025-04-28
Initial release