---
language:
- en
license: apache-2.0
tags:
- text-to-speech
- kokoro
- onnx
- audio
- voiceover
- documentary
- podcast
pipeline_tag: text-to-speech
---

# Kokoro Grounded Documentary Voiceover Model (v2.0)

A broadcast-grade text-to-speech engine powered by **Kokoro-ONNX**, featuring the **Grounded Documentary v2.0** voice profile (60% `bm_george` + 25% `bm_lewis` + 15% `bm_daniel`, British RP).

Calibrated based on multimodal acoustic analysis for prestigious documentary, philosophical, and cosmological narration:
1. **Calibrated Baritone Tone**: Blends `bm_lewis` with `bm_george` to infuse authoritative sub-chest warmth and remove upper-mid nasal fatigue.
2. **Contemplative Sage Pacing**: Unhurried speed (`0.91`), meditative sentence pauses (`0.65s`), clause pauses (`0.30s`), and extended pauses (`1.1s–1.3s`) across major thematic transitions.
3. **Vedic & Sanskrit Pronunciation Lexicon**: Built-in phonetic dictionary (`pronunciation.py`) accurately pronouncing ancient Sanskrit and mythological terms (e.g., *Rsis*, *Ekam Sat*, *Nasadiya Sukta*, *Yajnavalkya*, *Rta*, *Brahman*, *Atman*).
4. **Broadcast Mastering Filter**: Single-pass FFmpeg chain featuring optical-style soft-knee compression, surgical de-essing, boxiness notch, and EBU R128 (-16 LUFS) loudness normalization.

---

## Quickstart (Python)

```bash
pip install kokoro-onnx soundfile huggingface_hub
```

```python
import numpy as np
import soundfile as sf
from kokoro_onnx import Kokoro
from huggingface_hub import hf_hub_download

REPO_ID = "gitmodelmujtaba/kokoro-grounded-documentary"

# 1. Download model weights and tuned voice profile
model_path = hf_hub_download(repo_id=REPO_ID, filename="kokoro-v1.0.onnx")
voices_path = hf_hub_download(repo_id=REPO_ID, filename="voices-v1.0.bin")
profile_path = hf_hub_download(repo_id=REPO_ID, filename="grounded_documentary.npy")

# 2. Initialize Kokoro
kokoro = Kokoro(model_path, voices_path)
voice_style = np.load(profile_path)

# 3. Generate Speech
text = "Look up at the night sky... To you, it might look like an endless ocean of cold vacuum."
audio, sr = kokoro.create(
    text,
    voice=voice_style,
    speed=0.91,
    lang="en-gb",
    sentence_pause=0.65,
    clause_pause=0.30
)

sf.write("output.wav", audio, sr)
print(f"Generated {len(audio)/sr:.2f}s of broadcast narration!")
```

---

## Gemini-Calibrated Broadcast Mastering Chain (FFmpeg)

For broadcast-grade warmth, optical-style compression, and smooth de-essing matching YouTube documentary standards:

```bash
ffmpeg -y -i output.wav -af \
  "highpass=f=75:p=2,\
   equalizer=f=180:t=q:w=1.2:g=3.2,\
   equalizer=f=480:t=q:w=2.0:g=-1.8,\
   equalizer=f=3200:t=q:w=1.5:g=1.2,\
   equalizer=f=7200:t=q:w=2.5:g=-3.0,\
   lowpass=f=11000,\
   deesser=i=0.7:m=0.5:f=0.65:s=o,\
   compand=attacks=0.02:decays=0.25:points=-70/-70|-45/-32|-20/-14|0/-6:soft-knee=6,\
   loudnorm=I=-16:TP=-1.5:LRA=9" \
  -c:a libmp3lame -b:a 192k output_mastered.mp3
```

---

## Files in this Repository
* `kokoro-v1.0.onnx`: Kokoro ONNX model weights (310 MB).
* `voices-v1.0.bin`: Kokoro voice library (27 MB).
* `grounded_documentary.npy`: Pre-blended float32 voice embedding vector (510 KB).
* `narrator.py`: Voiceover narrator class with built-in mastering chain.
* `pronunciation.py`: Vedic, Sanskrit, and ancient term phonetic lexicon.