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.

The same package also runs the small multilingual models Kitten TTS 2 mini, nano and pico (KittenTTS2Tiny, all in ggml, no LibTorch for synthesis); see Kitten TTS 2 mini, nano and pico below.

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 14 or newer (not Intel Macs), Windows x86-64, and experimental Windows ARM64. See the wheel matrix and installation guide.

From PyPI, the install block in Kitten TTS 2 mini, nano and pico also runs the KittenTTS example below on the CPU (its first call downloads about 1 GB and prints llama.cpp's loading log). To build from source instead: 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. On macOS, run xcode-select --install first (compiler and git); macOS has no OpenSSL headers, and on Apple silicon the native build is slower, so run the last line as CMAKE_ARGS="-DLLAMA_BUILD_LIBRESSL=ON -DGGML_NATIVE=OFF" python -m pip install . --no-build-isolation. 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.

For KittenTTS, 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.

Kitten TTS 2 mini, nano and pico

The package needs Python 3.10 to 3.14 (check with python3 --version, or py --version on Windows). If your python3 is older, use a newer Python in the first line, for example python3.12 -m venv .venv. On macOS (Apple silicon, macOS 14 or newer), a new Mac has no Python 3: python3 only opens a dialog that offers the developer tools (you can cancel it). Install Python 3.14 with the "macOS 64-bit universal2 installer" from python.org (not 3.15, which this package does not support yet), then open a new Terminal window and run the block there.

python3 -m venv .venv && . .venv/bin/activate
python -m pip install -U pip
pip install "kitten-tts-cpp>=0.3" --extra-index-url https://download.pytorch.org/whl/cpu
python -c "from kitten_tts_cpp import KittenTTS2Tiny; KittenTTS2Tiny('KittenML/kitten-tts-2-nano').generate_to_file('Guten Morgen.', 'hallo.wav', language='de')"

On Windows, run the block in a Command Prompt (in PowerShell, type cmd first), with py -m venv .venv and then .venv\Scripts\activate.bat in place of the first line. A new Windows installation also needs the Microsoft Visual C++ Redistributable, which PyTorch and espeak-ng use: winget install Microsoft.VCRedist.2015+.x64 (without it the import fails with WinError 126). The package is tested on Linux (x86-64 and Arm64), Windows x64 and macOS (Apple M4, on the CPU); Windows on Arm has not been tested with these models yet.

KittenML/kitten-tts-2-mini speaks 16 languages, -nano and -pico 8 each. The first use downloads the official weights and converts them to GGUF once (no Hugging Face account is needed; the warning about HF_TOKEN can be ignored). This one install covers every language, Japanese included (its first use downloads a 47 MB dictionary once). An NVIDIA GPU needs the GPU build of the package (kitten-tts-cpp-cu12 on Linux, kitten-tts-cpp-cu13 on Windows), which is not on PyPI yet: build it with the CUDA toolkit as in Building and install it as in Installing an artifact; KittenTTS2Tiny then runs on the GPU by default. Options, weights, speed and the C API: tools/kitten-tts-tiny/README.md.

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.3.0.post4

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.3.0.post4
File Actions
haaztest_kitten_tts_cpp-0.3.0.post4-cp314-cp314-macosx_14_0_arm64.whl CPython 3.14 CPython 3.14 macOS 14.0+ ARM64 Details for haaztest_kitten_tts_cpp-0.3.0.post4-cp314-cp314-macosx_14_0_arm64.whl
haaztest_kitten_tts_cpp-0.3.0.post4-cp313-cp313-macosx_14_0_arm64.whl CPython 3.13 CPython 3.13 macOS 14.0+ ARM64 Details for haaztest_kitten_tts_cpp-0.3.0.post4-cp313-cp313-macosx_14_0_arm64.whl
haaztest_kitten_tts_cpp-0.3.0.post4-cp312-cp312-macosx_14_0_arm64.whl CPython 3.12 CPython 3.12 macOS 14.0+ ARM64 Details for haaztest_kitten_tts_cpp-0.3.0.post4-cp312-cp312-macosx_14_0_arm64.whl
haaztest_kitten_tts_cpp-0.3.0.post4-cp311-cp311-macosx_14_0_arm64.whl CPython 3.11 CPython 3.11 macOS 14.0+ ARM64 Details for haaztest_kitten_tts_cpp-0.3.0.post4-cp311-cp311-macosx_14_0_arm64.whl
haaztest_kitten_tts_cpp-0.3.0.post4-cp310-cp310-macosx_14_0_arm64.whl CPython 3.10 CPython 3.10 macOS 14.0+ ARM64 Details for haaztest_kitten_tts_cpp-0.3.0.post4-cp310-cp310-macosx_14_0_arm64.whl

Total release size: 168.9 MB

Release files / haaztest_kitten_tts_cpp-0.3.0.post4-cp314-cp314-macosx_14_0_arm64.whl

Download URL haaztest_kitten_tts_cpp-0.3.0.post4-cp314-cp314-macosx_14_0_arm64.whl
Size 33.8 MB
Tags CPython 3.14 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
a1b8151d131337cd0e4ad862eaa1010ef7e1975b120dbbb3a876c8e8eb299c2b
BLAKE2b-256 checksum
How to use checksums
0ffe8a419a2670bb314a22768db9004bb9d86b7cf84b2fe03d1acc4c7a8ab1f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / haaztest_kitten_tts_cpp-0.3.0.post4-cp313-cp313-macosx_14_0_arm64.whl

Download URL haaztest_kitten_tts_cpp-0.3.0.post4-cp313-cp313-macosx_14_0_arm64.whl
Size 33.8 MB
Tags CPython 3.13 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
c6592f2259f081e3ccd2aa73f24679abbdfb2859470c1dfba8fd2bd16ac3b87c
BLAKE2b-256 checksum
How to use checksums
6fc4ddb6b07bdfd1cff241e229854158db1a6855636ff3a3b5717baa09da8560
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / haaztest_kitten_tts_cpp-0.3.0.post4-cp312-cp312-macosx_14_0_arm64.whl

Download URL haaztest_kitten_tts_cpp-0.3.0.post4-cp312-cp312-macosx_14_0_arm64.whl
Size 33.8 MB
Tags CPython 3.12 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
7a3aee01606e290ab61c265518d9cae2f82a11ff033dbdb2fa7a44942ed0c48f
BLAKE2b-256 checksum
How to use checksums
f5c4dfc3b3de6fb4c13b31efc11e66fb72c819feecda1b0597383b135114ec97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / haaztest_kitten_tts_cpp-0.3.0.post4-cp311-cp311-macosx_14_0_arm64.whl

Download URL haaztest_kitten_tts_cpp-0.3.0.post4-cp311-cp311-macosx_14_0_arm64.whl
Size 33.8 MB
Tags CPython 3.11 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
957e10cfd825fe1614ad72d5ab518965f9d52769e3223efa3240f0c37ee91a26
BLAKE2b-256 checksum
How to use checksums
fb2c8626f377045257123690bcec6b30b117811160a306aefbb70348e5a5ba1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / haaztest_kitten_tts_cpp-0.3.0.post4-cp310-cp310-macosx_14_0_arm64.whl

Download URL haaztest_kitten_tts_cpp-0.3.0.post4-cp310-cp310-macosx_14_0_arm64.whl
Size 33.8 MB
Tags CPython 3.10 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
6a304d4c5a0ba15603d8bc1ffd78ba54dde324c7adee5b80f99cb36ce6b015cf
BLAKE2b-256 checksum
How to use checksums
57ccb51e4b719cb55032bf58378b59a2c1ffb621b7b40d20f7af69abc937605b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for haaztest-kitten-tts-cpp 0.3.0.post4

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