Common Issues

"TTS engine failed to initialize"

Symptoms: App starts but shows error: "TTS engine failed to initialize"

Likely causes:

• Kokoro model file (kokoro.onnx) is missing or corrupt
• Insufficient disk space for model download (~320MB)
• Antivirus blocking the model download

Fixes:

1. Ensure kokoro.onnx exists in the app directory
2. Check %AppData%\TtsCommunicationTool\logs\crash.log for details
3. Temporarily disable antivirus and restart
4. Re-download the app (the model is bundled)

"Configuration file was corrupt"

Symptoms: Notification on startup: "Configuration file was corrupt and has been reset to defaults"

Likely causes:

• Manual editing of config.json while the app was running
• Disk error or power loss during config save
• Corrupt JSON syntax

Fixes:

1. A backup was saved as config.corrupt.<timestamp>.json
2. Restore settings from the backup if needed
3. Re-configure the app through the Settings window

Hotkey not working

Symptoms: Pressing the overlay hotkey does nothing

Likely causes:

• Another application has registered the same hotkey
• The hotkey was not configured (empty binding)
• Win32 RegisterHotKey failed (check logs)

Fixes:

1. Check %AppData%\TtsCommunicationTool\logs\crash.log for hotkey registration errors
2. Try a different hotkey combination in Settings → Hotkeys
3. Restart the app
4. Check for conflicting apps (e.g., Discord, OBS, game overlays)

No audio from monitor output

Symptoms: Speech plays but you can't hear it

Likely causes:

• Monitor output device not selected or disconnected
• Monitor volume set to 0%
• Wrong device selected

Fixes:

1. Go to Settings → Audio
2. Verify the Monitor Output dropdown has a device selected
3. Click Test Monitor to test
4. Check Monitor Volume slider
5. Click Refresh to re-enumerate devices

No audio in Discord/VRChat

Symptoms: You can hear speech through your headphones, but others can't hear you

Likely causes:

• Secondary output device not configured
• Virtual cable not installed
• Voice app microphone set to wrong device
• Secondary volume set to 0%

Fixes:

1. Verify VB-Cable is installed (check Windows Sound settings)
2. Go to Settings → Audio
3. Select CABLE Input (VB-Audio Virtual Cable) as Secondary Output
4. Click Test Secondary to verify
5. In Discord/VRChat, set Microphone to CABLE Output (VB-Audio Virtual Cable)
6. Check Secondary Volume slider

"ElevenLabs API returned 401"

Symptoms: Error when trying to use ElevenLabs voice

Likely causes:

• Invalid API key
• API key has been revoked
• API key was entered incorrectly

Fixes:

1. Go to Settings → Voice
2. Re-enter your ElevenLabs API key
3. Verify the key is active in your ElevenLabs account
4. Check your ElevenLabs subscription status

"ElevenLabs API returned 429"

Symptoms: Error during ElevenLabs synthesis

Likely causes:

• Rate limited — too many requests in a short time
• Character quota exceeded

Fixes:

1. Wait a few seconds and try again
2. Check your ElevenLabs subscription character usage in Settings → Voice
3. Consider upgrading your ElevenLabs plan

"ElevenLabs API returned 404"

Symptoms: Error with voice ID in the message

Likely causes:

• The selected voice no longer exists (deleted from ElevenLabs)
• Voice ID mismatch

Fixes:

1. Go to Settings → Voice
2. Click to refresh the voice list
3. Re-select a voice

Phrase not playing

Symptoms: Clicking a phrase does nothing

Likely causes:

• TTS engine not initialized
• Phrase text is empty
• Phrase cache generation failed

Fixes:

1. Check the app is fully started (tray icon visible)
2. Verify the phrase has text
3. Open the Phrase Editor and click Play Preview
4. Check logs for cache generation errors

Overlay not appearing

Symptoms: Hotkey pressed but no overlay

Likely causes:

• Hotkey conflict with another app
• Overlay already open (re-triggering refocuses)
• App minimized to tray but not responding

Fixes:

1. Check if the overlay is already open (it may be behind another window)
2. Try a different hotkey
3. Restart the app
4. Check logs for hotkey registration errors

App won't start

Symptoms: Double-clicking the EXE does nothing

Likely causes:

• Another instance is already running (single-instance enforcement)
• Missing .NET runtime
• Corrupt installation

Fixes:

1. Check if the app is already running (check system tray)
2. Install .NET 10 runtime
3. Re-download the app
4. Check Windows Event Viewer for crash details

"Already Running" message

Symptoms: Message box: "TTS Swirlotl is already running."

Cause: The app uses a named mutex (Global\TtsCommunicationTool_SingleInstance) to enforce single-instance. Only one instance can run at a time.

Fix: Look for the running instance in the system tray.