Troubleshooting Qwen3 TTS#

nvigi.core.framework.dll is missing#

Run the setup script from the pack root:

setup_sample.bat

The standalone pack intentionally downloads the NVIGI Core/HWI runtime during setup instead of including it in the initial package payload.

Qwen plugin is not found#

Run the CLI from bin\x64\Release or bin\x64\Production. The executable must remain beside its plugin DLLs. For functional testing use Release; the Production configuration validates signed plugins.

Model files are not found#

Pass --models to the directory containing nvigi.plugin.tts.qwen3:

nvigi.tts.qwen.exe --models ..\..\..\data\nvigi.models --text "Hello" --output hello.wav

The shipped model directory contains a Q4_K_M talker and an F32 tokenizer/codec GGUF. Do not mix these files with a different Qwen runtime build.

An invalid or missing model root is a command error: the CLI prints the model path that failed and exits with a non-zero status. Correct the --models path instead of treating generated output from another directory as a valid run.

A voice JSON fails to load#

Use a Qwen JSON created by get_voice_embeddings.py or nvigi.tts.qwen.exe --extractEmbedding. JSONs generated for other TTS models are not compatible with Qwen3 TTS.

For a new reference:

  • Use a clean, single-speaker WAV.

  • Convert it to mono 24 kHz PCM WAV.

  • Provide an exact transcript to retain ICL reference codes.

  • Keep --speaker and --refAudio mutually exclusive.

UnicodeEncodeError while extracting a JSON#

The helper accepts both normal UTF-8 and UTF-8-with-BOM transcript files. If an older helper is used, save the transcript as UTF-8 without a BOM, or update the package helper.

D3D12 or Vulkan initialization fails#

First verify CUDA:

nvigi.tts.qwen.exe --models ..\..\..\data\nvigi.models --text "Backend smoke test" --output cuda.wav --backend cuda

Then verify the requested backend. D3D12 requires the shipped Agility SDK files under bin\x64\<configuration>\D3D12; Vulkan requires a compatible driver. Capture the generated nvigi_log_*.txt file when reporting an issue. The first successful D3D12 synthesis can include one-time shader and graph warm-up; it is not a steady-state performance result.

Long text changes voice or stops early#

Use a locally generated --speaker JSON (or --refAudio plus --refText) for any paragraph that exceeds the configured --max_words_per_chunk limit. The CLI applies that same Qwen conditioning to every bounded segment. If no voice reference is supplied, long multi-segment Base synthesis is rejected with an actionable error rather than concatenating independently generated voices.

The 3D sample starts but ASR/GPT is unavailable#

This is expected for the standalone Qwen TTS pack. Supply an NVIGI Developer SDK path to setup_sample.bat to overlay ASR/GPT plugins and model data for full integration testing.