Metadata-Version: 2.4
Name: superclonica-cpu
Version: 0.6.25
Summary: Faster, cleaner Supertonic 3 text-to-speech: robust text cleanup, learned audio finishing and fast inference (CPU)
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: Operating System :: MacOS
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
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<2,>=1.20
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

```python
from superclonica import Superclonica

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

From the command line:

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

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

## 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

The ten built-in voices are just the start. [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;
* 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="F3", 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 F3 --lang en --seed 7 --output morning.wav
superclonica --text-file story.txt --voice my_voice.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/).
