Metadata-Version: 2.5
Name: flockspeech
Version: 0.1.0
Summary: Tiny on-device text to speech: the Junco voice, 44 MB, runs faster than real time on one CPU thread.
Project-URL: Homepage, https://huggingface.co/flockspeech/junco
Author: Flock Speech
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: src/flockspeech/models/LICENSE-vocos
Keywords: edge,offline,on-device,onnx,speech-synthesis,text-to-speech,tts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: espeakng-loader>=0.2.4
Requires-Dist: numpy>=1.22
Requires-Dist: onnxruntime>=1.17
Requires-Dist: phonemizer>=3.2
Description-Content-Type: text/markdown

# flockspeech

Tiny text to speech that runs on your own device. No GPU, no cloud and no PyTorch: just ONNX Runtime and numpy.

This first release ships **Junco v0.1**, one English (US) voice at 24 kHz.

```sh
pip install flockspeech
flockspeech "Hello! I'm Junco, and I run on your own computer." -o hello.wav --play
```

```python
from flockspeech import Junco

tts = Junco()                          # loads in under a second
audio = tts("Hello there.")            # float32 numpy array, 24 kHz mono
tts.save("Hello there.", "hello.wav")

for chunk in tts.stream(long_text):    # sentence by sentence: the first audio arrives fast
    play(chunk)
```

## Why it suits small devices

| | |
|---|---|
| Model files | 44 MB, bundled in the package; nothing is downloaded at run time |
| Runtime | onnxruntime + numpy; works offline |
| Memory | about 265 MB peak |
| Start-up | about 0.7 s |
| Speed on an Apple M1 | 8.7× real time on 1 thread, 19× on 4 threads |
| First audio when streaming | about 0.25 s on 4 threads |

Speed was measured on typical one-sentence replies, vocoder included. Add `steps=4` (CLI `--steps 4`) for 1.5× more
speed with slightly rougher audio.

## Quality

Quality was measured on 40 unseen LibriTTS-R sentences with UTMOS (a predictor of listener ratings from 1 to 5):

| Version | UTMOS |
|---|---|
| Original model (PyTorch, fp32) | 4.21 |
| **This package** (int8 decoder, fp16 storage) | **4.18** (difference not significant) |
| This package with `steps=4` | 4.12 |

In our wider benchmark of 150 sentences, Junco scored a word error rate of 1.71% with Whisper. Real recordings of the same
sentences scored 2.30%.

## Options

| Option | CLI | Default | Effect |
|---|---|---|---|
| `speed` | `--speed` | 1.0 | 1.2 talks 20% faster |
| `steps` | `--steps` | 8 | flow-matching steps: fewer is faster |
| `seed` | `--seed` | 0 | fixes the small random variation in delivery |
| `threads` | `--threads` | up to 4 | CPU threads for ONNX Runtime |
| `coreml` | `--coreml` | off | Apple silicon only: runs the vocoder with CoreML. Faster on 1 thread, but uses twice the memory |

The CLI also reads text from a file (`-f story.txt`) or from standard input (`echo hi | flockspeech -`).

## Limits

- One voice, English (US) only, in a read-aloud style.
- No text normalisation yet. Write numbers, money and abbreviations out in words ("five dollars", not "$5"; "Doctor",
  not "Dr.").
- Long text is split into sentences, and very long sentences are split at commas.
- Platforms: macOS (Apple silicon and Intel), Linux (x86-64 and ARM64, which includes a 64-bit Raspberry Pi OS) and
  Windows, wherever onnxruntime and espeakng-loader have wheels.

## How it works

1. espeak-ng turns the text into phonemes.
2. A transformer encoder and a duration predictor read the phonemes.
3. A flow-matching decoder draws a mel spectrogram in 8 guided steps.
4. The Vocos vocoder turns the spectrogram into sound.

The acoustic model has 11.4M parameters and was trained from scratch on LJ Speech.

## Licence

The code and the Junco weights are Apache-2.0. The bundled Vocos vocoder weights are MIT (Charactr Inc.). Phonemes come
from `phonemizer` and espeak-ng (through `espeakng-loader`). Both are GPL-3.0 and are installed as separate dependencies,
not included in this package. See `NOTICE`.
