tiny-swara / SETUP.md
Xeven7's picture
docs: add cross-project usage section
c2819dd verified
|
Raw History Blame Contribute Delete
6.02 kB
# Setup
Get tiny-swara speaking in a few minutes. Works on CPU only; no GPU or account
needed. Tested on Linux and macOS with Python 3.10+ and espeak-ng 1.5x.
## What you need
- Python 3.10 or newer
- [espeak-ng](https://github.com/espeak-ng/espeak-ng) (a system package, not pip)
- About 100 MB of disk space
## 1. Install espeak-ng
```bash
# Ubuntu / Debian / WSL
sudo apt update && sudo apt install espeak-ng
# macOS
brew install espeak-ng
```
Check it:
```bash
espeak-ng --version
```
On Windows, use WSL (Ubuntu inside Windows) and follow the Ubuntu line.
## 2. Download the model
```bash
pip install -U huggingface_hub
hf download Xeven7/tiny-swara --local-dir tiny-swara
```
If `hf` is not found, use:
```bash
python3 -c "from huggingface_hub import snapshot_download; snapshot_download('Xeven7/tiny-swara', local_dir='tiny-swara')"
```
## 3. Install the Python dependencies
```bash
cd tiny-swara
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
If `python3 -m venv` fails on Ubuntu, install it first:
`sudo apt install python3-venv`.
## 4. Generate speech
```bash
python inference.py --text "আমি ভালো আছি, আপনার অর্ডার কনফার্ম হয়েছে।" --voice BF --output hello.wav
```
Expected output:
```
Saved: .../hello.wav (24000 Hz, voice=BF)
Model: .../onnx/tiny-swara-int8.onnx
```
Play `hello.wav`. Use `--voice BM` for the male voice.
| Voice | Who |
| ----- | ---------------- |
| `BF` | female (default) |
| `BM` | male |
Other useful options:
| Option | Meaning |
| ------------------------------ | ---------------------------------- |
| `--text-file input.txt` | read UTF-8 text from a file |
| `--speed 1.2` | faster speech |
| `--model onnx/tiny-swara.onnx` | use the FP32 model instead of INT8 |
| `--output out.wav` | where to save |
## 5. Use it from Python
```python
from inference import TinySwara
tts = TinySwara(voice="BF")
tts.save("আমি তোমাকে পছন্দ করি।", "hello.wav")
```
## 6. Use it in another project
You do not have to `cd` into this folder to use the Python API. `inference.py`
finds `config.json`, `inventory.json`, `lexicon.json`, `tiny_voca/` and `onnx/`
relative to itself (not your current directory), so the folder can live
anywhere as long as you keep that layout intact.
Three things must exist in the other project's environment:
1. **espeak-ng** — the same system package from step 1, installed once per machine.
2. **Python dependencies** — in that project's virtual environment:
`pip install numpy onnxruntime`
3. **This folder** — copy or clone it somewhere stable. You can drop `samples/`
and the `LICENSE`/`.md` files; keep `inference.py`, `tiny_voca/`,
`config.json`, `inventory.json`, `lexicon.json` and `onnx/`.
Then add the folder (the one containing `inference.py`) to `sys.path` and import:
```python
import sys
sys.path.insert(0, "/path/to/tiny-swara-hf")
from inference import TinySwara
tts = TinySwara(voice="BF") # loads the INT8 model by default
tts.save("আমি তোমাকে পছন্দ করি।", "out/hello.wav")
```
Relative output paths resolve against your current working directory, so the
WAV lands wherever your project expects it.
> If you vendor the folder _inside_ your project as a subpackage, keep it on
> `sys.path` as above. `inference.py` imports `tiny_voca` as a top-level module,
> so nesting it under a package name breaks that import.
## Troubleshooting
| Problem | Fix |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `espeak-ng is not installed` | Install it (step 1) and make sure `espeak-ng --version` works in the same terminal |
| `ModuleNotFoundError: No module named 'tiny_voca'` | Run `python inference.py` from inside the `tiny-swara` folder |
| `Could not find an ONNX model` | Keep the folder layout intact; do not move `inference.py` away from `onnx/`, `config.json`, `inventory.json`, `lexicon.json` and `tiny_voca/` |
| Bengali text is garbled in the terminal | Save the sentence to a UTF-8 file and use `--text-file input.txt` |
| `python3 -m venv` fails | `sudo apt install python3-venv` |
`inference.py` loads `inventory.json`, `lexicon.json` and `tiny_voca/text.py`
relative to itself, so always run it from the repository folder.
## What's in the folder
| Path | Purpose |
| ----------------------------------------------- | --------------------------------- |
| `onnx/tiny-swara-int8.onnx` | recommended model, 8.24 MiB |
| `onnx/tiny-swara.onnx` | FP32 reference, 20.4 MiB |
| `inference.py` | CLI and Python API |
| `tiny_voca/text.py` | Bengali text-to-phoneme front end |
| `config.json`, `inventory.json`, `lexicon.json` | vocabulary and pronunciation data |
| `samples/` | example audio from the model card |