README.md

metadata

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)

pip install kokoro-onnx soundfile huggingface_hub

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:

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.