Skip to main content

KittenTTS2 C++

C++ inference for KittenTTS2 on the CPU, with an optional NVIDIA GPU (CUDA) path, built-in voices, expression controls, and prepared reference voices. The runtime downloads prepared model assets and runs synthesis natively in C++. Users do not need to run the Python exporter.

The speech language model runs through llama.cpp/GGML, text normalization uses the kitten-text-processing submodule, and the S3 waveform decoder uses LibTorch on the CPU or on the GPU. Only KittenTTS2 checkpoints are supported.

Features

  • Built-in voices, including Bruno, Bella, Jasper, Luna, Rosie, Hugo, Kiki, and Leo.
  • Emotion tags, vocal events, and emphasis: [joyful], <laugh>, and (((really))).
  • Stable and expressive sampling presets, sentence-aware chunking, and audio joins.
  • A 1.03 GB GGUF with lossless packing of the checkpoint's ternary weights, plus an FP16 reference export.
  • Default S3 and optional student_w4 / student_w8 decoder exports.
  • Mono float32 WAV output at 24 kHz.

Python interface

Precompiled wheel builds are configured for Linux x86-64/ARM64, Apple Silicon macOS, Windows x86-64, and experimental Windows ARM64. See the wheel matrix and installation guide.

The py-interface branch includes a native Python package with a KittenTTS-style API. setup.py invokes CMake during installation and bundles the normalizer grammar data. Install a CPU PyTorch build first, then build against that same installation:

git submodule update --init vendor/kitten-text-processing
python3 -m venv .venv
. .venv/bin/activate
python -m pip install torch==2.13.0 --index-url https://download.pytorch.org/whl/cpu
python -m pip install setuptools wheel cmake numpy soundfile
python -m pip install . --no-build-isolation

A C++20 compiler and OpenSSL development headers are required for HTTPS downloads (libssl-dev on Debian/Ubuntu). Set CMAKE_BUILD_PARALLEL_LEVEL=8 to control build parallelism. CMAKE_ARGS accepts extra CMake flags, such as -DOPENSSL_ROOT_DIR=/path/to/openssl. Builds optimize for the local CPU; use CMAKE_ARGS="-DGGML_NATIVE=OFF" when building a wheel for other machines. Source-built wheels require the exact PyTorch release used at build time and the linked system OpenSSL libraries. The portable CI wheels instead link LibreSSL statically.

from kitten_tts_cpp import KittenTTS  # KittenTTS2 and get_model are also available

with KittenTTS("KittenML/kitten-tts-2", decoder="student_w4", threads=8) as model:
    print(model.available_voices)
    audio = model.generate("Hello again.", voice="Bruno", advanced={"seed": 1234})
    model.generate_to_file("Hello again.", "hello.wav", voice="Bruno")
    for chunk in model.generate_stream("A longer passage goes here.", voice="Bruno"):
        pass  # Each chunk is a float32 NumPy array at model.sample_rate.

For NVIDIA GPUs, install the GPU package instead (kitten-tts-cpp-cu12 on Linux, kitten-tts-cpp-cu13 on Windows) and pass gpu_layers=99; see the GPU wheel guide.

Weights and the decoder stay loaded between calls. The GIL is released during native loading and inference. Native inference calls are serialized because the TorchScript decoder uses process-wide random and thread settings. Streaming yields untrimmed sentence chunks as they are decoded; close the iterator when stopping early. generate applies the same chunk joins as the CLI. last_report contains token IDs, generation timings and the LM placement (last_report["lm"]["placement"]).

The constructor also accepts cache_dir, hf_token, revision, offline, decoder_threads, repack, model_path (a local GGUF override), data_dir, and ca_file (a custom HTTPS trust bundle). A local prepared asset directory can replace the repository ID. Generation supports the Python KittenTTS2 preset, sampling, normalization, reference-prompt, and advanced options, including use_emotion.

Only KittenTTS2 and weights="packed" are supported; device= accepts only "cpu" (use gpu_layers and decoder_device for the GPU). This package uses the separate kitten_tts_cpp import name so it can coexist with kittenml. Raw-audio reference= cloning is not implemented; prepare a reference with prepare_reference.py and select its voice name. It does not provide the older ONNX models or guarantee identical sampled output to Python's original PyTorch backend.

For development, python setup.py build_ext --inplace builds the extension; set PYTHONPATH=python to import it directly. python setup.py bdist_wheel produces an installable wheel, and python setup.py sdist includes the native sources and normalizer submodule contents.

Build

The build commands use a Linux shell. Requires a C++20 compiler, CMake, Python 3.10+, OpenSSL development files (libssl-dev on Debian/Ubuntu), and LibTorch 2.13.0. Use the CPU PyTorch environment from Python interface; it supplies LibTorch. Publishers use a separate export environment.

git submodule update --init vendor/kitten-text-processing

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_STANDARD=20 \
  -DCMAKE_CXX_STANDARD_REQUIRED=ON \
  -DGGML_CUDA=OFF -DGGML_METAL=OFF \
  -DLLAMA_BUILD_KITTEN_TTS=ON \
  -DLLAMA_BUILD_SERVER=OFF \
  -DLLAMA_BUILD_TESTS=OFF \
  -DLLAMA_BUILD_EXAMPLES=OFF \
  -DCMAKE_PREFIX_PATH="$(python -c 'import torch; print(torch.utils.cmake_prefix_path)')"

cmake --build build --target kitten-tts -j 8

The normalizer prepares its grammar data using Python at build time. To use existing grammar data, configure with -DKITTEN_DATA_DIR=/path/to/data.

GPU (CUDA) build

For the recommended full GPU setup, install an NVIDIA driver, CUDA 12.8 (nvcc on PATH), and CMake 3.28+. From the repository root:

python3 -m venv .venv-cuda
. .venv-cuda/bin/activate
python -m pip install torch==2.13.0 --index-url https://download.pytorch.org/whl/cu129
git submodule update --init vendor/kitten-text-processing
cmake -S . -B build-cuda \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_STANDARD=20 \
  -DCMAKE_CXX_STANDARD_REQUIRED=ON \
  -DGGML_CUDA=ON -DGGML_METAL=OFF \
  -DCMAKE_CUDA_ARCHITECTURES='75-real;86-real;89-real;120a-real' \
  -DLLAMA_BUILD_KITTEN_TTS=ON \
  -DLLAMA_BUILD_SERVER=OFF \
  -DLLAMA_BUILD_TESTS=OFF \
  -DLLAMA_BUILD_EXAMPLES=OFF \
  -DCMAKE_PREFIX_PATH="$(python -c 'import torch; print(torch.utils.cmake_prefix_path)')"
cmake --build build-cuda --target kitten-tts -j 8
build-cuda/bin/kitten-tts --gpu-layers 99 --decoder-device cuda --timings --text 'Hello from the GPU.' --output gpu.wav

--gpu-layers 99 runs the language model on the GPU; the default, 0, keeps the CPU path and its output unchanged. To run the S3 decoder on the GPU as well, add --decoder-device cuda: the runtime downloads the decoder's CUDA export (default and student_w4; student_w8 has none) and needs a CUDA build of LibTorch (how).

Setup (RTX 4090) Real-time factor (lower is faster) GPU memory
Language model and decoder on the GPU (recommended) 0.15 about 2.2-2.9 GB
Language model on the GPU, decoder on the CPU 0.41 about 1.7 GB
CPU only 1.28 none

Running the decoder on the CPU, or only part of the language model on the GPU (--allow-hybrid), is supported but slower. Details: GPU guide.

Download and run

The runtime fetches config.json from KittenML/kitten-tts-2 first, then downloads its GGUF, selected TorchScript decoder, and matching voice conditioning. Assets are cached under $XDG_CACHE_HOME/kitten-tts, or ~/.cache/kitten-tts when it is unset. HOME falls back to USERPROFILE on Windows.

build/bin/kitten-tts --text 'Hello from Kitten T T S.' --output hello.wav
build/bin/kitten-tts --decoder student_w4 --text 'Hello again.' --output w4.wav

Use --repo OWNER/REPO to select another KittenTTS2 repository, --revision COMMIT to pin a model version, --cache-dir DIR to change the cache location, and --offline to use cached files without network access. HF_TOKEN supports private repositories. --download-only --decoder student_w4 prepares the cache without synthesis. Only assets needed for the selected mode are downloaded.

The model repository must publish a cpp manifest and prepared files as described in the publisher guide. Local exports and model repository directories remain supported through --assets DIR; --model FILE overrides the GGUF.

The default GGUF uses this fork's TQ2_1 format: 256 ternary weights packed into 64 bytes, plus two FP16 scales for the checkpoint's 128-weight groups. The exporter requires exact reconstruction. This reduces the model from 1.45 GB with Q4_0 to 1.03 GB. Embeddings remain FP16 and one-dimensional tensors remain FP32. GGML's quantized activation arithmetic can still introduce small logit differences.

TQ2_1 requires this fork; it is not standard TQ2_0 and stock llama.cpp cannot load it. The fork has CPU kernels for it, and GPU builds repack it losslessly to Q2_0 at load time. Use --outtype ternary-q4_0 for the previous standard Q4_0 storage format, or --outtype f16 for the reference export.

On supported Intel CPUs, the runtime losslessly repacks TQ2_1 weights into the existing AMX Q4_0 layout at load time. The GGUF stays 1.03 GB, but runtime transformer-weight storage grows from about 357 MiB to 756 MiB. Use --no-repack to keep the compact CPU representation; it affects only CPU buffers, not the GPU repack to Q2_0. CPUs without AMX use the existing compact kernels.

See the detailed guide for FP16 exports, student decoders, reference voice preparation, and the normalizer submodule setup.

Generate speech

build/bin/kitten-tts \
  --text 'Hello there. This is Kitten T T S running on the CPU.' \
  --voice Bruno --threads 8 --seed 1234 \
  --output hello.wav --report hello.json

For expressive speech:

build/bin/kitten-tts \
  --text '[joyful] We won the grant <laugh> I can (((hardly))) believe it!' \
  --voice Kiki --preset expressive \
  --output expressive.wav

Use --help for sampling, repetition penalties, chunking, and decoder thread settings. --tokens-only skips waveform decoding; --repeat 3 benchmarks repeated synthesis with the model and decoder kept loaded.

Python parity and CPU performance

The implementation is checked against kittenml.kittentts2:

Check Recorded result
Text normalization and chunking 228 cases passed
Sampling rules 12 cases passed
Audio joins 3 cases passed
Packed weights All 310 tensors reconstruct the FP16 reference exactly
Native waveform decoding Agreement with Python within numerical tolerances in tested cases
Packed LM logits Close numerical agreement with the Python reference

On a Xeon Platinum 8462Y+ with eight pinned CPU cores, the AMX path reduced a 256-token forced-sequence workload from 6.40 to 5.60 seconds (about 14% higher throughput). Prompt evaluation fell from 1.09 to 0.58 seconds. TQ2_1 reached 45.7 generated tokens/second, comparable to Q4_0 at 44.3 in the same test. These are medians of three warmed runs, including prompt evaluation and sampling but excluding model loading. Performance varies with hardware and workload.

Run the differential checks with:

python tools/kitten-tts/check_parity.py \
  --binary build/bin/kitten-tts \
  --python-package ../KittenTTS \
  --repo ../kitten-tts-2 --assets models/kitten2 \
  --model models/kitten2/model-tq2_1.gguf \
  --lm --decoder

Measurements and source revisions are recorded in validation.json.

Current scope

Sampled output is not bit-identical to Python: BF16 arithmetic, GGML activation quantization, and sampling RNGs differ. Matching seeds do not guarantee matching generated tokens across runtimes.

Voice cloning requires an offline Python preparation step and a reference transcript. The Python interface supports sentence-chunk streaming; sample-by-sample streaming is not implemented. Waveform decoding currently depends on LibTorch, on the CPU or on CUDA.

Credits

KittenTTS2 and kitten-text-processing are from KittenML. See the implementation guide for decoder attribution and license details.

Built on DeepGrove's llama.cpp fork.

Metadata

Release files for haaztest-kitten-tts-cpp 0.2.0.post1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for haaztest-kitten-tts-cpp 0.2.0.post1
File Actions
haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.34+ x86-64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_x86_64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_aarch64.whl CPython 3.14 CPython 3.14 Linux glibc 2.34+ ARM64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_aarch64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.34+ x86-64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_x86_64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_aarch64.whl CPython 3.13 CPython 3.13 Linux glibc 2.34+ ARM64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_aarch64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.34+ x86-64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_x86_64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_aarch64.whl CPython 3.12 CPython 3.12 Linux glibc 2.34+ ARM64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_aarch64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.34+ x86-64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_x86_64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_aarch64.whl CPython 3.11 CPython 3.11 Linux glibc 2.34+ ARM64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_aarch64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.34+ x86-64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_x86_64.whl
haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_aarch64.whl CPython 3.10 CPython 3.10 Linux glibc 2.34+ ARM64 Details for haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_aarch64.whl

Total release size: 193.6 MB

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_x86_64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_x86_64.whl
Size 19.5 MB
Tags CPython 3.14 Linux glibc 2.34+ x86-64
SHA-256 checksum
How to use checksums
c5bf1fbcdfee9d0b9df0fdeb0336dc6a59ffd75a5a25f6ceff24693db9a1b1fb
BLAKE2b-256 checksum
How to use checksums
76c0597f73ac8be162ee217a52d491aecfbff3b38eebd1b1fab15935aeb6facc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.16

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_aarch64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp314-cp314-manylinux_2_34_aarch64.whl
Size 19.2 MB
Tags CPython 3.14 Linux glibc 2.34+ ARM64
SHA-256 checksum
How to use checksums
578026f192f3b5032915c34e2080fac924aeb8f680b13b564b71c43db0ead68d
BLAKE2b-256 checksum
How to use checksums
18c26ff188e4d690a6d974dc959e63b0e62c54d34444508cbcac563306c9d9ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_x86_64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_x86_64.whl
Size 19.5 MB
Tags CPython 3.13 Linux glibc 2.34+ x86-64
SHA-256 checksum
How to use checksums
bd1244f920bd5327a1ff746b22865b0000fb24a96e698a1e5e829654c62d2f15
BLAKE2b-256 checksum
How to use checksums
b966ca5d2a76a7e264cd84085205ecf866d216e98599cb98102a1bba0c18a87d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.16

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_aarch64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp313-cp313-manylinux_2_34_aarch64.whl
Size 19.2 MB
Tags CPython 3.13 Linux glibc 2.34+ ARM64
SHA-256 checksum
How to use checksums
5a6c1c9aa7552ecac06bb3c6c06ca5cf67c0525ff501fd9e10e01a0ee30fe11f
BLAKE2b-256 checksum
How to use checksums
89fb41805764ea36404b838e6de1a0428dc0e666194722c82b3ab47e32f44dfd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_x86_64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_x86_64.whl
Size 19.5 MB
Tags CPython 3.12 Linux glibc 2.34+ x86-64
SHA-256 checksum
How to use checksums
b3f31d9863644dafec594814b5d31e506fc11b05ada8f9c93e2d07fd40f758a1
BLAKE2b-256 checksum
How to use checksums
190a055ac60866e90591c50f97f8f47f394ded1ef0f37af67c2a6cf31e42246b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.16

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_aarch64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp312-cp312-manylinux_2_34_aarch64.whl
Size 19.2 MB
Tags CPython 3.12 Linux glibc 2.34+ ARM64
SHA-256 checksum
How to use checksums
f522e4ec1e00d3691de86a39a27fee77fc4e4b2c333d7267469c602b704ad016
BLAKE2b-256 checksum
How to use checksums
9953c215cc6c11042d918712f66563c5d91d90065c6f3ac8a8f6a7d3a0b910df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_x86_64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_x86_64.whl
Size 19.5 MB
Tags CPython 3.11 Linux glibc 2.34+ x86-64
SHA-256 checksum
How to use checksums
1b68413dbc317e238345d8d9ac4c188bc7a7d692e477eb00f841db48941e0f88
BLAKE2b-256 checksum
How to use checksums
fb90e4a12e402b022d8b4789a51850186e58bb2f6ff842c6e368444216ba4224
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.16

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_aarch64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp311-cp311-manylinux_2_34_aarch64.whl
Size 19.2 MB
Tags CPython 3.11 Linux glibc 2.34+ ARM64
SHA-256 checksum
How to use checksums
04d135517242015b5767b882f5757cde0038b8ce8f3135dba370f475f23532d0
BLAKE2b-256 checksum
How to use checksums
eabe2812c1b09f938b53d216d07a9def795b0ec8baafa0082e9ab570ab84f427
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_x86_64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_x86_64.whl
Size 19.5 MB
Tags CPython 3.10 Linux glibc 2.34+ x86-64
SHA-256 checksum
How to use checksums
bb8b409612f5e2cf6a7bb02f049c5058f9e34b7e7694cdae877fabe795be6c3a
BLAKE2b-256 checksum
How to use checksums
d8ff66002386531b909d07d0fa899ab77abd5f77a5b0efe8fa3d1c72ccee7f22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.16

Release files / haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_aarch64.whl

Download URL haaztest_kitten_tts_cpp-0.2.0.post1-cp310-cp310-manylinux_2_34_aarch64.whl
Size 19.2 MB
Tags CPython 3.10 Linux glibc 2.34+ ARM64
SHA-256 checksum
How to use checksums
0d7817d37cdd9eb8b6e702ca23b32f601cd2417c87110009fb6a70cb1303a138
BLAKE2b-256 checksum
How to use checksums
43cff68a5a6d50911e390441d07d49014fb84f328515dbc78525a2b2cf4bf66d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for haaztest-kitten-tts-cpp 0.2.0.post1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page