Metadata-Version: 2.4
Name: speak-cli
Version: 1.1.2
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

<p align="center">
  <img alt="1785884895192-019fcf07-71e9-75bf-8467-be33449f1eec" src="https://github.com/user-attachments/assets/1d6e67cc-82ce-46f0-b7b0-7656d2ae09e7" />
</p>

**Make your computer talk, right from the terminal**. Powered by [Supertonic 3](https://huggingface.co/Supertone/supertonic-3) — everything runs locally on your CPU.

## Install

```bash
# If you don't have uv installed, run this first:
curl -LsSf https://astral.sh/uv/install.sh | sh

# if you do just run this command
uv tool install speak-cli
```
The voice models (~400 MB) download automatically the first time you speak.

## How to use ?

```bash
speak "hello world"
speak -v noah "a different voice"
speak "مرحبا بالعالم"                # language detected automatically
speak -o clip.wav "or save to a file"
speak < article.txt                  # long reads start speaking instantly
ollama run llama3 "tell a story" | speak --live   # voice for your LLM
```
**Note:** `say` also works as an alias.

## Voices

Ten voices, picked by name (`speak --list-voices`):

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

Prefer one? Make it stick: `speak --set-default noah`

## Options

| Flag | Default | Meaning |
|---|---|---|
| `-v, --voice` | sara | voice name |
| `-s, --speed` | 1 | speech speed (0.7–2.0) |
| `-l, --lang` | auto | language (31 supported, auto-detected from the text) |
| `-o, --out FILE` | — | save a WAV instead of playing |
| `--live` | — | speak piped input line by line as it arrives |
| `--steps` | 8 | quality vs speed (5–12) |

Sprinkle in expression tags for natural delivery: `speak "well <laugh> that was funny"` (also `<breath>`, `<sigh>`, …).

## Good to know

- Speech streams: long texts start playing in about a second while the rest is still being synthesized — no waiting, no length limit.
- The first call starts a small background service that keeps the model warm — repeat calls speak in under a second. It shuts itself down after 15 idle minutes; `speak --stop` ends it manually.
- Auto-detection recognizes Arabic, Japanese, Korean, Russian, Greek, and Hindi by their alphabets; other Latin-script languages need a hint, e.g. `--lang fr`.

## Licenses

CLI: MIT · Supertonic 3 model weights: [OpenRAIL-M](https://huggingface.co/Supertone/supertonic-3/blob/main/LICENSE)
