Metadata-Version: 2.4
Name: superclonica-gpu-cuda
Version: 0.6.26
Summary: Faster, cleaner Supertonic 3 text-to-speech: robust text cleanup, learned audio finishing and fast inference (NVIDIA CUDA 12)
Author: superclonica.com
License-Expression: Apache-2.0
Project-URL: Homepage, https://superclonica.com/
Project-URL: Supertonic 3 model, https://huggingface.co/Supertone/supertonic-3
Keywords: tts,text-to-speech,speech-synthesis,supertonic,onnx,multilingual
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: NOTICE.txt
License-File: SUPERTONIC_CODE_LICENSE.txt
License-File: SUPERTONIC_MODEL_LICENSE.txt
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: onnx<2,>=1.16
Requires-Dist: huggingface-hub>=0.23
Requires-Dist: filelock>=3.13
Requires-Dist: soundfile>=0.12
Requires-Dist: pyloudnorm>=0.1.1
Requires-Dist: num2words>=0.5.13
Requires-Dist: onnxruntime-gpu[cuda,cudnn]==1.26.0
Requires-Dist: nvidia-cudnn-cu12==9.10.2.21
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# Superclonica

Faster, cleaner speech from [Supertonic 3](https://huggingface.co/Supertone/supertonic-3):
the same model and voices, with better sound and about 1.5x the speed of stock Supertonic on a
GPU (1.6x on a CPU). 31 languages.

Custom voices for it - free and paid, or trained from your own recording - are at
[superclonica.com](https://superclonica.com/).

## Install

For an NVIDIA GPU (Windows or Linux x86-64, Python 3.11+):

```bash
pip install superclonica-gpu-cuda
```

For any CPU (Windows, Linux, macOS, Python 3.10+):

```bash
pip install superclonica-cpu
```

Install one of them per environment: both provide the same `superclonica` module. To switch
from the CPU package to the GPU one:

```bash
pip uninstall -y superclonica-cpu onnxruntime
pip install superclonica-gpu-cuda
```

### Requirements

* **GPU package:** CUDA 12 and cuDNN come from pip; only an NVIDIA driver with CUDA 12 support
  is needed (R525 or newer; RTX 50-series cards need R570 or newer). Without a working GPU it
  falls back to the CPU with a warning.
* **Linux:** glibc 2.28 or newer (Ubuntu 20.04, Debian 10, RHEL 8 and later).
* **macOS on Intel:** Python 3.10-3.13; ONNX Runtime publishes no newer Intel macOS builds.
* **Windows on ARM:** Python 3.12 or newer; NumPy and SciPy publish no older ARM builds.

### The model

The model (about 385 MB) is downloaded once on first use from its original Hugging Face
repository, at a pinned revision, into `~/.cache/supertonic3` - the same folder the official
`supertonic` package uses. Set `SUPERTONIC_CACHE_DIR` to keep it elsewhere, or pass an existing
copy to work offline:

```python
tts = Superclonica(model_dir="path/to/supertonic-3")
```

## Quick start

Take a free voice - a Supertonic voice-style JSON file - from
[superclonica/supertonic-voices](https://github.com/superclonica/supertonic-voices):

```bash
curl -LO https://raw.githubusercontent.com/superclonica/supertonic-voices/main/voices/ciri/ciri.json
```

```python
from superclonica import Superclonica

tts = Superclonica()                     # GPU if available, else CPU
audio, sr = tts.synthesize("Hello! Nice to meet you.", voice="ciri.json", lang="en", seed=7)
tts.save("hello.wav", audio)
```

From the command line:

```bash
superclonica --text "Good morning, everyone." --voice ciri.json --lang en --output hello.wav
```

Create the engine once and reuse it: start-up takes a few seconds.

## Listen

Free voices speaking nine languages, voiced with this package on a CPU, without editing:
**[https://superclonica.github.io/supertonic-voices/samples.html](https://superclonica.github.io/supertonic-voices/samples.html)**

| Voice | Samples |
|---|---|
| Ciri | [English](https://superclonica.github.io/supertonic-voices/samples/ciri-en.wav) · [German](https://superclonica.github.io/supertonic-voices/samples/ciri-de.wav) · [Japanese](https://superclonica.github.io/supertonic-voices/samples/ciri-ja.wav) · [Russian](https://superclonica.github.io/supertonic-voices/samples/ciri-ru.wav) |
| Trevor Philips | [English](https://superclonica.github.io/supertonic-voices/samples/trevor-philips-en.wav) · [Spanish](https://superclonica.github.io/supertonic-voices/samples/trevor-philips-es.wav) · [French](https://superclonica.github.io/supertonic-voices/samples/trevor-philips-fr.wav) |
| Billy Butcher | [English](https://superclonica.github.io/supertonic-voices/samples/billy-butcher-en.wav) · [Portuguese](https://superclonica.github.io/supertonic-voices/samples/billy-butcher-pt.wav) · [Korean](https://superclonica.github.io/supertonic-voices/samples/billy-butcher-ko.wav) |
| Maya | [English](https://superclonica.github.io/supertonic-voices/samples/maya-en.wav) · [Russian](https://superclonica.github.io/supertonic-voices/samples/maya-ru.wav) · [Italian](https://superclonica.github.io/supertonic-voices/samples/maya-it.wav) |
| Dark Willow | [English](https://superclonica.github.io/supertonic-voices/samples/dark-willow-en.wav) · [French](https://superclonica.github.io/supertonic-voices/samples/dark-willow-fr.wav) · [Russian](https://superclonica.github.io/supertonic-voices/samples/dark-willow-ru.wav) |
| Valera the Gummy Bear | [English](https://superclonica.github.io/supertonic-voices/samples/valera-the-gummy-bear-en.wav) · [German](https://superclonica.github.io/supertonic-voices/samples/valera-the-gummy-bear-de.wav) · [Russian](https://superclonica.github.io/supertonic-voices/samples/valera-the-gummy-bear-ru.wav) |

170+ voices with online demos - try your own phrase in any of them for free - are at
[superclonica.com](https://superclonica.com/en/explore).

## More examples

**One voice, many languages.** Every voice speaks all 31 languages; pass the text's language:

```python
lines = {
    "en": "The road was long, but I'm home now.",
    "de": "Der Weg war lang, aber jetzt bin ich zu Hause.",
    "ja": "長い旅だったけど、やっと帰ってきた。",
    "es": "El camino fue largo, pero ya estoy en casa.",
}
for lang, text in lines.items():
    audio, sr = tts.synthesize(text, voice="ciri.json", lang=lang, seed=7)
    tts.save(f"ciri-{lang}.wav", audio)
```

**A long text** is spoken in natural pieces; `normalize=True` evens the loudness (-18 LUFS):

```python
story = open("story.txt", encoding="utf-8").read()
audio, sr = tts.synthesize(story, voice="ciri.json", lang="en", seed=7, normalize=True)
tts.save("story.wav", audio)
print(f"{len(audio) / sr:.1f} seconds")
```

**A dialogue with two voices** in one batch (results keep the input order):

```python
# curl -LO https://raw.githubusercontent.com/superclonica/supertonic-voices/main/voices/trevor-philips/trevor-philips.json
lines = [("trevor-philips.json", "Relax. I have a plan."),
         ("ciri.json", "That is exactly what worries me.")]
results = tts.synthesize_batch([text for _, text in lines],
                               voices=[voice for voice, _ in lines], langs="en", seeds=7)
for index, (audio, sr) in enumerate(results):
    tts.save(f"line-{index + 1}.wav", audio)
```

**Other formats:** `tts.save("hello.flac", audio)` or `.ogg` - any format soundfile writes.

## Docker

An HTTP server and the command line in one image, on
[Docker Hub](https://hub.docker.com/r/superclonica/superclonica):

```bash
docker run -d -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cpu
docker run -d --gpus all -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cuda
```

A voice goes into the request as the JSON itself; it is about 0.3 MB, so build the request in a
file:

```bash
python -c "import json; json.dump({'text': 'Hello from Docker!', 'lang': 'en', 'voice': json.load(open('ciri.json'))}, open('request.json', 'w'))"
curl -X POST localhost:8000/synthesize -H "Content-Type: application/json" -d @request.json -o hello.wav
```

The first start downloads the model into the `superclonica-models` volume.

## Better than stock Supertonic

### Sound

* **Clean phrase edges.** Small learned models remove clicks and noise at the start and end,
  and stray sounds the model sometimes adds after the last word (a click, a breath, an extra
  syllable, a hum) are cut away. A second pass over the finished phrase removes the faint
  breaths, thumps and clicks the model's hiss hid, and a piece that comes out empty or cut short
  is rendered again.
* **Words stay whole.** The cleanup keeps the words' own sounds - a final s or t that stands
  apart after its closure, a whispered first vowel, a last word after a pause - which is checked
  against the model's raw output with a phoneme recognizer on thousands of renders in
  30+ languages.
* **No clipping.** The model often peaks above full scale; a look-ahead limiter lowers just
  those peaks.
* **No dead air.** The model pads 0.25-0.6 s of silence before speech and 0.6-0.9 s after it;
  this is trimmed to 80 ms and 200 ms, so speech starts sooner (`trim_silence=False` keeps the
  padding).
* **Quiet background.** A denoiser and a pause gate remove the model's hiss between words
  (about 40 dB lower than stock).
* **Fewer stutters and repeated words.** Long text is spoken in pieces of at most 160 characters
  with natural pauses; stock uses up to 300, where repeats become several times more frequent.

### Text

* **Numbers are spoken as words** in 27 languages; stock misreads larger numbers in some
  languages.
* **Any text works.** Emoji, symbols and characters the model doesn't know are cleaned up
  instead of failing the request; words like "can't" and "well-known" stay intact.
* **Abbreviations** such as "pls", "brb", "idk" and "btw" are spelled out before speaking;
  stock reads them as made-up words. `slang=False` keeps them as written.

### Speed

24 short phrases in 8 languages, same settings for both:

| | Stock Supertonic | Superclonica |
|---|---|---|
| RTX 5070 Ti, median phrase | 174 ms | **117 ms** |
| Ryzen 7 5800X (4 threads), median phrase | 697 ms | **432 ms** |

CUDA graphs on GPU, multi-threaded model rewrites on CPU, parallel lanes and batches.

## Custom voices

[superclonica.com](https://superclonica.com/) is a marketplace of custom Supertonic 3 voices,
and they work with Superclonica as they are:

* try any voice online for free, and download the free ones without signing up (they are also on
  GitHub: [superclonica/supertonic-voices](https://github.com/superclonica/supertonic-voices));
* train a voice from your own 5-15 second recording, free, on your own NVIDIA GPU;
* or order a custom voice from one of the authors.

Each voice is a Supertonic voice-style JSON file:

```python
audio, sr = tts.synthesize("Welcome back!", voice="my_voice.json", lang="en")
```

## API

### `Superclonica(...)`

```python
Superclonica(model_dir=None, total_steps=None, speed=1.05, *,
             device="auto", device_id=0, threads=None, lanes=1,
             gpu_memory_mb=1024, cuda_graph="auto", chunking=True, numbers=True,
             denoise=True, target_lufs=-18.0, trim_silence=True, slang=True)
```

| Parameter | What it does |
|---|---|
| `model_dir` | An existing Supertonic 3 copy (default: the automatic download above). |
| `total_steps` | Model steps per phrase (default 8). |
| `speed` | Speaking rate. |
| `device` | `"auto"` (GPU if it works, else CPU), `"cuda"` or `"cpu"`. |
| `device_id`, `gpu_memory_mb`, `cuda_graph` | GPU number, memory limit per model session, CUDA graphs (`"auto"`, `True`, `False`). |
| `threads` | CPU threads (default: one per physical core). |
| `lanes` | Independent model copies for the pieces of a long text and concurrent callers. |
| `chunking`, `numbers`, `denoise`, `trim_silence`, `slang` | Turn the text and sound steps above on or off. |
| `target_lufs` | Loudness used by `normalize=True`. |

### `synthesize`

```python
synthesize(text, voice="M1", lang="en", *, seed=None, effect="auto", numbers=None,
           normalize=False, return_report=False)
```

Returns `(audio, sample_rate)`: float32 mono at 44.1 kHz; with `return_report=True` also a dict
describing the run. `normalize=True` brings the phrase to `target_lufs`; `effect="off"` disables
the ending effects (the cleanup always runs).

### `synthesize_batch`

Several texts at once, with the same options; voices, languages and seeds may be single values or
one per text, and the results keep the input order:

```python
results = tts.synthesize_batch(["First line.", "Second line."],
                               voices="ciri.json", langs="en", seeds=[1, 2])
for audio, sr in results:
    print(len(audio) / sr, "seconds")
```

### `save`

`tts.save(path, audio)` writes WAV (16-bit) or any other format soundfile supports.

### Voices and languages

* **Voices:** `M1`-`M5`, `F1`-`F5`, or any Supertonic voice-style JSON, such as a custom voice
  from [superclonica.com](https://superclonica.com/).
* **Languages (31):** `ar` `bg` `cs` `da` `de` `el` `en` `es` `et` `fi` `fr` `hi` `hr` `hu` `id`
  `it` `ja` `ko` `lt` `lv` `nl` `pl` `pt` `ro` `ru` `sk` `sl` `sv` `tr` `uk` `vi`

## Command line

```bash
superclonica --text "Good morning!" --voice ciri.json --lang en --seed 7 --output morning.wav
superclonica --text-file story.txt --voice ciri.json --lang en --output story.wav
superclonica --help
```

## Responsible use

The Supertonic 3 model is licensed under the BigScience Open RAIL-M license. Its use restrictions
(Attachment A in `SUPERTONIC_MODEL_LICENSE.txt`) apply to everyone using it through this package:
among others, do not impersonate people without their consent, do not defame or harass, and
disclose that generated content is machine-generated.

## License

Apache-2.0, © 2026 superclonica.com. An independent derivative of Supertonic, not an official
Supertone release. The bundled Supertonic SDK code is MIT; the Supertonic 3 model is under the
BigScience Open RAIL-M license. See `NOTICE.txt`.

More about the project, custom voices and how to make your own:
[superclonica.com](https://superclonica.com/).
