Metadata-Version: 2.4
Name: tiny-voca-ru
Version: 0.1.0
Summary: A lightweight 4.5M-parameter Russian text-to-speech model
Author: Evgeniy Chetvertkov
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/yilbegan/tiny-voca-ru
Project-URL: Repository, https://github.com/yilbegan/tiny-voca-ru
Project-URL: Model, https://huggingface.co/egnch/tiny-voca-ru
Project-URL: Dataset, https://huggingface.co/datasets/egnch/tiny-voca-ru-dataset
Project-URL: Demo, https://huggingface.co/spaces/egnch/tiny-voca-ru-demo
Keywords: tts,text-to-speech,russian,onnx,speech-synthesis,tiny-voca
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Russian
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: src/tiny_voca_ru/frontend/data/LICENSE-ruaccent
Requires-Dist: numpy<3,>=1.24
Provides-Extra: onnx
Requires-Dist: onnxruntime<2,>=1.17; extra == "onnx"
Requires-Dist: soundfile<1,>=0.12; extra == "onnx"
Requires-Dist: huggingface-hub<3,>=0.34; extra == "onnx"
Provides-Extra: torch
Requires-Dist: torch<3,>=2.4; extra == "torch"
Requires-Dist: safetensors<1,>=0.4; extra == "torch"
Requires-Dist: soundfile<1,>=0.12; extra == "torch"
Requires-Dist: onnxruntime<2,>=1.17; extra == "torch"
Requires-Dist: onnx<2,>=1.15; extra == "torch"
Requires-Dist: huggingface-hub<3,>=0.34; extra == "torch"
Provides-Extra: ruaccent
Requires-Dist: ruaccent==1.5.8.3; extra == "ruaccent"
Requires-Dist: onnxruntime<2,>=1.17; extra == "ruaccent"
Requires-Dist: huggingface-hub<3,>=0.34; extra == "ruaccent"
Provides-Extra: train
Requires-Dist: torch<3,>=2.4; extra == "train"
Requires-Dist: safetensors<1,>=0.4; extra == "train"
Requires-Dist: soundfile<1,>=0.12; extra == "train"
Requires-Dist: onnxruntime<2,>=1.17; extra == "train"
Requires-Dist: librosa<1,>=0.10.2; extra == "train"
Requires-Dist: transformers<5,>=4.40; extra == "train"
Requires-Dist: torchaudio<3,>=2.1; extra == "train"
Requires-Dist: scipy<2,>=1.10; extra == "train"
Requires-Dist: huggingface-hub<3,>=0.34; extra == "train"
Dynamic: license-file

# tiny-voca-ru

English | [Русский](https://github.com/yilbegan/tiny-voca-ru/blob/main/README.ru.md)

A 4.5M-parameter Russian text-to-speech adaptation of [`tiny-voca`](https://github.com/n4ze3m/tiny-voca) (24 kHz mono, two synthetic voices `F` and `M`) with a pure-Python Russian text frontend, safetensors/ONNX Runtime inference, custom-voice fine-tuning, and a client-side browser demo.

- **Model:** [`egnch/tiny-voca-ru`](https://huggingface.co/egnch/tiny-voca-ru)
- **Dataset:** [`egnch/tiny-voca-ru-dataset`](https://huggingface.co/datasets/egnch/tiny-voca-ru-dataset)
- **Browser Demo:** [`egnch/tiny-voca-ru-demo`](https://huggingface.co/spaces/egnch/tiny-voca-ru-demo)
- **PyPI:** [`tiny-voca-ru`](https://pypi.org/project/tiny-voca-ru/)

## Installation

Requires Python 3.10+. Works with `pip` or [`uv`](https://docs.astral.sh/uv/).

```bash
# Minimal Russian text frontend only (no PyTorch)
pip install tiny-voca-ru

# Lightweight ONNX Runtime inference (no PyTorch)
pip install "tiny-voca-ru[onnx]"

# PyTorch inference + safetensors + ONNX export
pip install "tiny-voca-ru[torch]"

# Full training & custom-voice fine-tuning stack
pip install "tiny-voca-ru[train]"

# Optional full ruaccent homograph disambiguation
pip install "tiny-voca-ru[ruaccent]"
```

## Quick Start: Inference

`Synthesizer` loads models from Hugging Face Hub (`egnch/tiny-voca-ru` by default) or a local directory, automatically selecting PyTorch (`model.safetensors` + `config.json`) or ONNX Runtime (`model.onnx` + `model.json`).

### Python API

```python
from tiny_voca_ru import Synthesizer

# Load from Hugging Face Hub (defaults to "egnch/tiny-voca-ru")
synth = Synthesizer.from_pretrained("egnch/tiny-voca-ru")
# Explicit ONNX Runtime backend (downloads only onnx/model.onnx + onnx/model.json)
# synth = Synthesizer.from_pretrained("egnch/tiny-voca-ru", backend="onnx")
# Local safetensors or ONNX directory
# synth = Synthesizer("checkpoints/tiny-voca-ru")

result = synth.save_wav(
    "Здравствуйте! Встречу перенесли на 15:30, 14 марта.",
    "hello.wav",
    voice="M",  # "F" or "M"
    speed=1.0,  # 0.25 .. 4.0
    pitch_shift=0.0,  # log-F0 offset (0.058 ≈ +1 semitone)
    pitch_range=1.0,  # 0.0 .. 3.0
    stress="lite",  # "lite" | "ruaccent" | "none"
    pause_seconds=0.0,  # optional silence gap between sentences
)
```

### CLI

```bash
# Uses Hugging Face Hub ("egnch/tiny-voca-ru") by default
tiny-voca-ru-speak \
  --voice F \
  --text "Привет! Билет стоит 1250 рублей." \
  --output out.wav

# Explicit ONNX Runtime backend
tiny-voca-ru-speak \
  --model egnch/tiny-voca-ru \
  --backend onnx \
  --voice M \
  --text "Привет! Билет стоит 1250 рублей." \
  --output out_onnx.wav

# Local checkpoint or ONNX directory
tiny-voca-ru-speak \
  --model checkpoints/tiny-voca-ru \
  --voice F \
  --text "Привет! Билет стоит 1250 рублей." \
  --output out_local.wav
```

## Russian Text Frontend

`tiny_voca_ru.frontend` has no PyTorch or eSpeak dependency. It normalizes Russian text (numbers, dates, times, currencies, units, Roman numerals, abbreviations, acronyms, Latin words), places lexical stress, and outputs a 61-symbol IPA phoneme sequence.

```python
from tiny_voca_ru import accentuate, normalize, phonemize, transcribe

normalize("В 1999 году билет стоил 12,50 руб.")
accentuate("Я открыл зам+ок ключом.")  # explicit '+' marks are preserved
transcribe("Здравствуйте!")  # readable IPA with ˈ
seq = phonemize("Привет, мир!", stress="lite")
```

| Stress Provider | Dependencies | Notes |
| --- | --- | --- |
| `lite` (default) | Bundled `stress.txt.gz` + `accent.onnx` (`onnxruntime`) | Fast, offline, runs in browser via JS `accent.onnx` |
| `ruaccent` | `tiny-voca-ru[ruaccent]` | Full `ruaccent` (`turbo3.1`) neural homograph resolver |
| `none` | None | Preserves existing `+` stress marks only |

## Custom-Voice Fine-Tuning

### 1. Prepare a dataset

Create a `metadata.csv` (or `metadata.jsonl`) with columns `audio`, `text`, and optional `speaker`, `split`, `id`:

```csv
audio,text,speaker
wavs/001.wav,Добрый день! Как ваши дела?,alice
wavs/002.wav,Сегодня отличная погода.,alice
```

Extract 24 kHz features and `wav2vec2` CTC alignments:

```bash
tiny-voca-ru-prepare \
  --metadata data/metadata.csv \
  --audio-root data \
  --output work/alice-prepared \
  --val-ratio 0.05
```

### 2. Fine-tune from a pretrained checkpoint

When fine-tuning onto new speakers, `tiny-voca-ru-train` copies compatible weights and initializes new speaker embeddings from `--init-voice` (or the mean of pretrained voices):

```bash
tiny-voca-ru-train \
  --data-dir work/alice-prepared \
  --init-from checkpoints/tiny-voca-ru \
  --init-voice F \
  --output work/alice-run \
  --steps 5000 \
  --learning-rate 1e-4 \
  --save-every 500
```

Add `--freeze-encoder` for small datasets (< 30 min). Resume with `--resume work/alice-run/last.pt`. Safetensors checkpoints are saved to `work/alice-run/inference/` and `work/alice-run/best/`.

## ONNX Export & Legacy Checkpoint Conversion

```bash
# Export safetensors checkpoint -> model.onnx + model.json
tiny-voca-ru-export \
  --checkpoint checkpoints/tiny-voca-ru \
  --output checkpoints/tiny-voca-ru-onnx

# Convert legacy .pt checkpoint -> model.safetensors + config.json
tiny-voca-ru-convert \
  --source path/to/tiny-voca-ru.pt \
  --output checkpoints/tiny-voca-ru
```

## Browser Demo

The static demo in `web/public/` runs `tiny_voca_ru.frontend` in Pyodide and `model.onnx` + `accent.onnx` via ONNX Runtime Web entirely offline:

```bash
bash web/build_assets.sh checkpoints/tiny-voca-ru-onnx
python3 -m http.server --directory web/public 8000
```

## Development

```bash
uv sync --python 3.12 --extra torch --extra onnx --extra train --group dev
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run basedpyright
```

## Citation

Machine-readable citation metadata is available in [CITATION.cff](https://github.com/yilbegan/tiny-voca-ru/blob/main/CITATION.cff).

```bibtex
@misc{chetvertkov2026tinyvocaru,
  author = {Chetvertkov, Evgeniy},
  title  = {tiny-voca-ru: A 4.5M-Parameter Russian Text-to-Speech Model},
  year   = {2026},
  url    = {https://huggingface.co/egnch/tiny-voca-ru},
  note   = {ORCID: https://orcid.org/0009-0006-6158-2624}
}
```

Please also consider citing the original [`tiny-voca`](https://huggingface.co/n4ze3m/tiny-voca) by Muhammed Nazeem (2026).

## License & Attribution

Code and weights are licensed under the Apache License 2.0 ([LICENSE](https://github.com/yilbegan/tiny-voca-ru/blob/main/LICENSE)).
See [NOTICE](https://github.com/yilbegan/tiny-voca-ru/blob/main/NOTICE) for attribution to `tiny-voca` (Muhammed Nazeem, Apache-2.0) and `ruaccent` (MIT License, bundled `stress.txt.gz` and `accent.onnx` in `src/tiny_voca_ru/frontend/data/`).
