Skip to content

Troubleshooting and FAQ

aivrar edited this page Nov 18, 2026 · 2 revisions

Troubleshooting & FAQ

Can't find your problem? The PDF manual has more detail (chapters 15 and 16). If that doesn't help, open an issue and include the server log.

Loading models

Out of memory when loading. Run nvidia-smi to see what's using the GPU, unload engines you aren't using, load this one on another GPU, or pick cpu (Kokoro and Whisper run fine on CPU). Other apps count too: a local LLM in LM Studio can take several GB.

Download fails or stalls. First loads download from Hugging Face. Check your connection and try again, or pre-download from the Launcher's Models & Tools tab. Fish Speech is gated, so it needs a Hugging Face token (set it in the Launcher).

Badge stuck on LOADING. A first load can take a few minutes while files download. Check the log; if nothing moves, restart the instance.

Speech (XTTS, Fish, Kokoro)

Symptom Try this
Slurred or garbled speech Lower temperature (0.6–0.7); use a cleaner reference clip; for XTTS raise repetition penalty
Words skipped Turn on Whisper verification; for Kokoro, spell unusual words phonetically
Keeps retrying the same chunk Lower the Whisper tolerance (e.g. 80 → 72) or turn verification off for that job
Echo or room sound Raise Clean (de-reverb) to 80–100 %, or use a drier reference
Harsh "s" sounds Raise De-ess to 30–60 %
Fish Speech crawls (minutes per chunk) The GPU is out of VRAM and spilling into shared memory. Check nvidia-smi, unload other engines or apps on that card (a local LLM counts), or move Fish to another GPU

A long job stopped half-way. If you used a save path, enter the same save path, type ##recover## as the text, and press Generate. Only the missing chunks are redone. Without a save path there's no job.json, so nothing can be recovered.

"Busy" messages

"Busy: … is already generating." That engine is already running a job, maybe from another tab or a script (its panel says started elsewhere). Wait, or use a different engine. Scripts get 503 plus Retry-After. See Concurrency & Progress.

"save_path is in use." Another engine is writing into the same project folder right now. Use a different save path.

Music (Stable Audio, ACE-Step)

  • Noisy or thin: more steps (Stable 100+, ACE 60), more variants, and let CLAP pick the best.
  • Ignores the prompt: be specific (genre, instruments, mood, tempo), add a negative prompt, raise guidance a little, try another seed.
  • ACE-Step vocals mumble: keep lyrics short and simple, with [verse] / [chorus] tags on their own lines.

Video

  • Create Video is disabled: select an audio file and Transcribe it first; the video needs the .srt.
  • FFmpeg error: check bin/ffmpeg/bin/ffmpeg.exe exists (the Launcher can reinstall it).
  • No subtitles: open the .srt next to the audio; if it's empty, transcribe again.

Chatbot

  • Local model won't load (unknown model architecture): the bundled llama.cpp doesn't support that model family yet. Use a widely supported one (Qwen 2.5, Llama 3.x, Mistral, Gemma 2), or run newer models through LM Studio and pick the LM Studio backend.
  • LM Studio not connecting: start LM Studio's local server with a model loaded; check LMSTUDIO_API_BASE in config.py.
  • Replies cut off: raise Max Tokens (gear icon) and the context length.

FAQ

Do I need a GPU? No, but it helps a lot. Kokoro and Whisper are quick on CPU. The other engines work on CPU but are much slower.

Is anything sent to the internet? No. Models download once from Hugging Face, then everything runs locally. The only exception is the optional OpenRouter chatbot backend.

Can other machines on my network use it? Yes. The server listens on all interfaces, so http://<your-pc>:5006 works from other devices. It has no authentication, so never expose it to the internet.

Which TTS engine should I use?

Kokoro XTTS-v2 Fish Speech
Speed ⚡ Very fast Medium Slow
Voice cloning – ✅ ✅
Built-in voices 54 (9 languages) 58 speakers –
Languages 9 17 Multilingual
Best for Drafts, long narration, CPU Everyday cloning Final takes

How long should a cloning reference be? About 10–30 s of clean, single-speaker speech with no music.

How much disk space do I need? About 2 GB for the app, plus the models you use: roughly 35 GB for all of them.

AMD or Apple GPUs? Not supported. The engines use NVIDIA CUDA; everything else falls back to CPU.

Can I use it commercially? LocalSoundsAPI is MIT-licensed, but each model has its own license: XTTS-v2 (Coqui Public Model License), Stable Audio Open (Stability AI Community License), Fish Speech (CC BY-NC-SA). Check the model's license before commercial use.

Clone this wiki locally