hkilang/TTS-models

香港圍頭話及客家話文字轉語音

_{Hong Kong Waitau & Hakka Text-to-Speech}

本儲存庫包含香港圍頭話及客家話文字轉語音之 ONNX 模型。當選擇離線推導模式時，朗讀器程式會使用其進行模型推導，於程式內直接產生音訊。

This repository contains the ONNX models of the Hong Kong Waitau & Hakka Text-to-Speech reader. In offline inference mode, the TTS application uses them to generate audio through model inference right inside the app.

Files

Each voice consists of one inference graph, model.onnx, and its external weights file, model.data. Keep both files together; the graph includes duration prediction, alignment, and waveform generation.

manifest.json
waitau/male/{model.onnx,model.data,validation.json}
waitau/female/{model.onnx,model.data,validation.json}
hakka/male/{model.onnx,model.data,validation.json}
hakka/female/{model.onnx,model.data,validation.json}

manifest.json (schema 1) describes the required files, decoded byte sizes, SHA-256 checksums, model format, symbol tables, external-data mappings, and input/output ABI. Its releaseId is an opaque content identifier. Download the manifest and its referenced files from the same immutable repository revision. Per-voice validation.json files describe numerical validation and export warnings; they are not needed for inference.

Inference (hkilang-vits2-onnx-v1)

The models use a BERT-free VITS2 architecture, ONNX opset 17, and float32 weights. Batch size is fixed to 1; token count and output duration are dynamic.

Input	Type	Shape	Meaning
x	int64	[1, tokens]	Phone IDs including interspersed blanks
x_lengths	int64	[1]	Token count
sid	int64	[1]	Speaker ID, 0
tone	int64	[1, tokens]	Tone IDs
language	int64	[1, tokens]	Language IDs, 0
speed	float32	scalar []	Speaking speed; 1 is normal, app range 0.5–2
noise	float32	scalar []	Latent noise scale; typical value 0.8
noise_w	float32	scalar []	Duration noise scale; typical value 0.6

All inputs are required. Output audio is float32 [1, 1, samples] at 44,100 Hz. The stochastic duration predictor ratio is fixed to 1. Use the manifest's ordered symbols for phone IDs. Hakka's UI zero-medial label ∅ maps to checkpoint symbol #. Padding and interspersed blank IDs are 0.

Browser File loading

ONNX Runtime Web 1.30.0 onnxruntime-web/jspi supports range reads from a Blob/File supplied as external data. For weights stored in OPFS, obtain a File with getFile() and supply {path: 'model.data', data: file} in the session's externalData options. Load the graph separately and preserve its literal external-data path model.data; the manifest's file field identifies the corresponding repository file.

JSPI builds avoid materializing the entire weights file in JavaScript during initialization. Runtime weights and activations still occupy CPU/GPU memory. Conventional builds materialize a supplied File, so this behavior depends on the runtime build and browser capabilities.

Export script

export_models.py exports the four Waitau/Hakka male/female checkpoints using the matching BERT-free TTS-API source. Dependencies are pinned in requirements-export.txt; the validated environment is Python 3.13, PyTorch 2.9.0, NumPy 2.2.0, ONNX 1.20.1, and native ONNX Runtime 1.23.2.

python -m pip install -r requirements-export.txt
python export_models.py --source /path/to/TTS-API --output /path/to/output

The source directory supplies data/config.json and data/<language>_<voice>.pth by default. --config and --checkpoints select other input locations; --force permits replacing existing exporter outputs. Source files and checkpoints are read-only inputs. The script stages and validates all four voices before replacing its output files.

Validation includes ONNX graph checks, zero-noise waveform parity for 1/2/10 syllables and speeds 0.5/1/2, and finite stochastic output at those speeds. Parity limits are maximum absolute error 1e-3 and RMSE 1e-4. Reports establish numerical compatibility, not listening quality or mobile memory requirements.