Troubleshooting and limitations

Startup and dependencies

• DLL loading failure: use Python 3.12 and uv sync --locked. Use an approved Python installation; do not disable Windows application control.
• Slow first launch: model downloads and loading take time. Check the terminal log.
• Port in use: change GRADIO_SERVER_PORT.
• Offline failure: the tokenizer, codec and watermark models must be cached as well as the main checkpoint.

Voice generation

• CPU inference can be slow. Start with a short sentence and 16 steps, then increase quality as needed.
• Use clear recordings from one speaker. The reference player previews only the first of multiple uploaded clips.
• Reference audio does not guarantee identical voice identity. Check the generated speech against the intended text.
• Outputs are temporary files. Download anything you want to keep.

Hosting

GitHub Pages serves documentation, not Python inference. The uv setup targets local CPU use. The upstream ZeroGPU path remains in the code, but Space metadata and a CUDA environment must be configured separately.