Metadata-Version: 2.4
Name: speak-cli
Version: 0.1.0
Summary: Speak text out loud from the command line using Supertonic 3 (local, offline TTS)
Project-URL: Repository, https://github.com/MohamedAliRashad/tts-cli
Project-URL: Issues, https://github.com/MohamedAliRashad/tts-cli/issues
Author: Mohamed Rashad
License: MIT
Keywords: cli,offline,speech,supertonic,text-to-speech,tts
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Requires-Dist: supertonic>=1.3.1
Description-Content-Type: text/markdown

# speak — local text-to-speech CLI

Speak text out loud from the command line using [Supertonic 3](https://huggingface.co/Supertone/supertonic-3) — a fast, ~99M-parameter TTS model that runs entirely on your CPU. No cloud, no API keys.

```bash
speak "hello world"
echo "piped text works too" | speak
speak -v noah "a different voice"
speak "مرحبا بالعالم"          # language auto-detected from the text
speak -o clip.wav "save to a file instead"
```

## Install

```bash
uv tool install speak-cli
```

Or without waiting for a PyPI release, straight from GitHub:

```bash
uv tool install git+https://github.com/MohamedAliRashad/tts-cli
```

(From a clone, `uv tool install .` works too.) All dependencies are prebuilt Python wheels — no compilers, no apt packages. On the first `speak`, the Supertonic 3 models (~400 MB) are downloaded once to `~/.cache/supertonic3/`; everything after that works fully offline. `say` is installed as an alias of `speak` (handy, but if another tool on your machine already provides `say`, just use `speak`).

## How it stays fast

The first call starts a background daemon that keeps the models loaded in memory, so subsequent calls speak in well under a second. The daemon exits after 15 minutes idle (tune with `SPEAK_IDLE_TIMEOUT` seconds) and is respawned transparently. If the daemon can't run for any reason, `speak` silently falls back to in-process synthesis — it always works.

```bash
speak --stop        # stop the daemon manually
speak --no-daemon   # bypass the daemon for one call
```

## Voices

```
speak --list-voices
```

| Female | Male |
|---|---|
| sara *(default)* | james |
| emma | daniel |
| lily | leo |
| maya | ryan |
| nora | noah |

`--voice` accepts any of these names, case-insensitive. Set a persistent default with `export SPEAK_VOICE=noah`.

## Options

| Flag | Default | Meaning |
|---|---|---|
| `-v, --voice` | sara | voice name |
| `-s, --speed` | 1.05 | speech speed (0.7–2.0) |
| `-l, --lang` | auto | language code, `auto`, or `na` (language-agnostic) |
| `--steps` | 8 | quality/speed trade-off (5–12) |
| `-o, --out FILE` | — | write WAV instead of playing (`--play` for both) |
| `--verbose` | — | show detected language, timing, synthesis path |

Language auto-detection is script-based: Arabic, Japanese, Korean, Russian, Greek, and Hindi are detected from their alphabets; all Latin-script text is assumed English (use `--lang fr`, `--lang de`, … to override). Supported languages: en ko ja ar bg cs da de el es et fi fr hi hr hu id it lt lv nl pl pt ro ru sk sl sv tr uk vi.

Expression tags can be embedded in the text: `speak "well <laugh> that was funny"` (also `<breath>`, `<sigh>`, …).

## Playback

Audio is played through the first working system player among `paplay`, `pw-play`, `aplay`, `afplay` (macOS), `ffplay`, `play` (sox) — every mainstream desktop has at least one. If none works, `speak` tells you and suggests `--out`.

## Licenses

CLI code: MIT. Supertonic 3 model weights: [OpenRAIL-M](https://huggingface.co/Supertone/supertonic-3/blob/main/LICENSE) (via the `supertonic` SDK's auto-download).
