README.md

---
language:
  - uz
license: apache-2.0
base_model: FunAudioLLM/CosyVoice2-0.5B
pipeline_tag: text-to-speech
tags:
  - cosyvoice2
  - uzbek
  - speech-synthesis
  - expressive-tts
  - voice-cloning
---

# Navoiy TTS

Navoiy TTS is an open Uzbek text-to-speech checkpoint built on [CosyVoice2-0.5B](https://huggingface.co/FunAudioLLM/CosyVoice2-0.5B). It generates highly natural, expressive speech that captures the specific phonetic nuances of the Uzbek language. 

**Note:** This is an LLM component checkpoint, not a standalone model. Inference requires the upstream CosyVoice codebase and the base model.

## Model Overview & Results

Unlike standard TTS models that can sound robotic or struggle with regional phonemes, Navoiy TTS is specifically fine-tuned for emotional prosody and natural pacing in Uzbek. 

* **Training Data:** Trained on a high-quality dataset comprising ~600 hours of neutral speech and an additional 40 hours of heavily expressive/emotional speech.
* **Capabilities:** Supports zero-shot voice cloning and instruction-conditioned emotion generation (e.g., whispering, shouting, varying tones).
* **Evaluation:** Exhibits strong zero-shot robustness, significantly reducing mispronunciations of common Uzbek vocabulary and numbers compared to the base multilingual models.

### Checkpoint Details

| File | Description |
| --- | --- |
| `emotion_600h_joint.pt` | Primary expressive checkpoint. Recommended for most use cases. |

## Quick Start

For reproducible inference, use the pinned revisions below.

### 1. Setup Upstream Environment

```bash
git clone --recursive [https://github.com/FunAudioLLM/CosyVoice.git](https://github.com/FunAudioLLM/CosyVoice.git)
cd CosyVoice
git checkout 074ca6dc9e80a2f424f1f74b48bdd7d3fea531cc
git submodule update --init --recursive
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
cd ..
```

### 2. Download Models
First, clone the Navoiy repository and install its specific requirements:

```bash
git clone [https://huggingface.co/aisha-org/navoiy-tts](https://huggingface.co/aisha-org/navoiy-tts)
pip install -r navoiy-tts/requirements.txt
```

Next, create a Python script (e.g., `download_base.py`) to fetch the exact base model checkpoint needed:

```python
# download_base.py
from huggingface_hub import snapshot_download

print("Downloading CosyVoice2-0.5B base model...")
snapshot_download(
    repo_id="FunAudioLLM/CosyVoice2-0.5B", 
    revision="eec1ae6c79877dbd9379285cf8789c9e0879293d", 
    local_dir="CosyVoice/pretrained_models/CosyVoice2-0.5B"
)
print("Download complete.")
```

Run the script:
```bash
python download_base.py
```

### 3. Run Inference
Requires a CUDA-enabled GPU.

```bash
python navoiy-tts/inference.py \
  --cosyvoice-dir CosyVoice \
  --base-model-dir CosyVoice/pretrained_models/CosyVoice2-0.5B \
  --checkpoint navoiy-tts/emotion_600h_joint.pt \
  --reference reference.wav \
  --text "Bugun siz bilan muhim bir xabarni baham ko'rmoqchiman." \
  --emotion warm \
  --output output.wav
```

Supported Emotion Presets: `calm`, `happy`, `sad`, `angry`, `nervous`, `surprised`, `whisper`, `warm`, `tired`, `sarcastic`. (*Note: Output depends heavily on the reference voice and seed; treat these as style hints, not guaranteed classifications*).

### Text Normalization
The included `uztts.normalize` utility handles Cyrillic-to-Latin conversion, apostrophe canonicalization, and expansion of numbers/dates/units.

```python
from uztts.normalize import normalize

text = "Bugun 16.07.2026, soat 14:30 da uchrashamiz."
print(normalize(text))
```

### Demos
Generated using `emotion_600h_joint.pt` on an **NVIDIA A10-12Q**. Full generation configs, seeds, and RTF metrics are in `demo/manifest.json`.

**Calm**:
> Navoiy TTS o'zbekcha matnni tabiiy va ravon ovozga aylantiradi.

<audio controls preload="none" src="https://huggingface.co/aisha-org/navoiy-tts/resolve/main/demo/calm_intro.wav"></audio>

**Warm Agent**: 
> Assalomu alaykum! Sizga qanday yordam bera olaman?

<audio controls preload="none" src="https://huggingface.co/aisha-org/navoiy-tts/resolve/main/demo/warm_agent.wav"></audio>

**Happy**: 
> Ajoyib yangilik! Bugungi natijalarimiz kutilganidan ham yaxshi bo'ldi.

<audio controls preload="none" src="https://huggingface.co/aisha-org/navoiy-tts/resolve/main/demo/happy.wav"></audio>

**Angry**
> Bu xatoni darhol tuzatish kerak. Bunday holat boshqa takrorlanmasin.

<audio controls preload="none" src="https://huggingface.co/aisha-org/navoiy-tts/resolve/main/demo/angry.wav"></audio>

**Surprised**
> Nahotki, loyiha bir kun ichida tayyor bo'lgan bo'lsa!

<audio controls preload="none" src="https://huggingface.co/aisha-org/navoiy-tts/resolve/main/demo/surprised.wav"></audio>

**Numbers and dates**
> Bugun 16.07.2026, soat 14:30 da uchrashamiz. Manzilgacha 5.5 km qoldi.

<audio controls preload="none" src="https://huggingface.co/aisha-org/navoiy-tts/resolve/main/demo/numbers_dates.wav"></audio>

**Long-form Uzbek**
> Alisher Navoiy merosi o'zbek tili va adabiyotining bebaho xazinasidir.
> Navoiy TTS zamonaviy sun'iy intellekt yordamida tabiiy o'zbekcha nutq
> yaratadi.

<audio controls preload="none" src="https://huggingface.co/aisha-org/navoiy-tts/resolve/main/demo/long_form.wav"></audio>

**Note**: While generally robust, the current checkpoint may occasionally mispronounce complex words, numbers, dates or generate audio artifacts. We are actively refining the training data to resolve these edge cases.


### Constraints & Responsible Use
- **Failure Modes**: Expect potential mispronunciations of highly specialized loanwords or complex mathematical formulas.
- **Ethics & Safety**: Voice cloning requires knowing, explicit consent from the speaker. Do not use this generated speech for safety-critical instructions, fraud, or impersonation. Clearly disclose synthetic speech to listeners.

### License
Apache License 2.0. Derived from [CosyVoice](https://github.com/FunAudioLLM/CosyVoice) and [CosyVoice2-0.5B](https://huggingface.co/FunAudioLLM/CosyVoice2-0.5B).