Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,94 @@
+---
+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
+
+A broadcast-grade text-to-speech engine powered by **Kokoro-ONNX**, featuring the **Grounded Documentary** voice profile (55% `bm_george` + 45% `bm_daniel`, British RP).
+
+Tuned specifically for long-form documentary, philosophical, and educational narration with:
+1. **Deliberate Pacing**: Unhurried speed (`0.92`), natural sentence pauses (`0.42s`), and extended pauses (`1.25s–1.35s`) across major thematic shifts.
+2. **Grounded Tone**: Deep, comforting lower-mid chest resonance preventing listening fatigue over long sessions.
+3. **Subtle Modulation**: Narrative emphasis carried via pitch inflection rather than jarring volume spikes.
+4. **Targeted De-Essing & Mastering**: Built-in broadcast mastering chain cutting harsh sibilance on high frequencies ('s', 'sh') with 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.92,
+    lang="en-gb",
+    sentence_pause=0.42,
+    clause_pause=0.20
+)
+
+sf.write("output.wav", audio, sr)
+print(f"Generated {len(audio)/sr:.2f}s of broadcast narration!")
+```
+
+---
+
+## Broadcast Mastering Chain (FFmpeg)
+
+For broadcast-grade warmth and smooth de-essing matching YouTube documentary standards:
+
+```bash
+ffmpeg -y -i output.wav -af \
+  "highpass=f=80,\
+   equalizer=f=160:t=q:w=1.0:g=2.8,\
+   equalizer=f=260:t=q:w=1.2:g=2.0,\
+   equalizer=f=450:t=q:w=2.0:g=-2.0,\
+   equalizer=f=3200:t=q:w=2.0:g=-1.6,\
+   equalizer=f=5800:t=q:w=2.5:g=-3.5,\
+   equalizer=f=7200:t=q:w=2.5:g=-3.0,\
+   lowpass=f=11000,\
+   deesser=i=0.45:m=0.5:f=0.55:s=o,\
+   compand=attacks=0.03:decays=0.3:points=-80/-80|-35/-25|-16/-13|0/-3,\
+   loudnorm=I=-16:TP=-1.5:LRA=8.5" \
+  -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`: Self-contained Python helper script for single-command generation.