README.md

---
library_name: transformers
license: other
license_name: axiveri-research-license
license_link: LICENSE.md
language:
- yo
- ha
- ig
- en
pipeline_tag: text-to-speech
base_model:
- ResembleAI/chatterbox
tags:
- text-to-speech
- tts
- voice-cloning
- yoruba
- hausa
- igbo
- pidgin
- nigerian-english
- african-languages
---

# WazobiaVoice
![image/png](logo.png)

## Table of Contents

1. [Model Summary](#model-summary)
2. [Model Description](#model-description)
   - [Architecture](#architecture)
   - [How WazobiaVoice Compares](#how-wazobiavoice-compares)
3. [Inbuilt Voice Personas](#inbuilt-voice-personas)
4. [Speech Samples](#speech-samples)
   - [Native Language Samples](#native-language-samples)
   - [Cross-Lingual Voice Cloning](#cross-lingual-voice-cloning)
5. [How to Use](#how-to-use)
6. [Bias, Risks, and Limitations](#bias-risks-and-limitations)
   - [The Yoruba Tonal Problem](#the-yoruba-tonal-problem)
   - [Recommendations](#recommendations)
7. [Prohibited Uses](#prohibited-uses)
8. [License](#license)
9. [Training](#training)
10. [Ongoing Research: VITS for Yoruba](#ongoing-research-vits-for-yoruba)
11. [Future Improvements](#future-improvements)
12. [Citation](#citation)
13. [Credits & References](#credits--references)

<video controls width="600">
  <source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/final_demo.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>

*Demo video generated using [ememediaforge](https://github.com/Ememzyvisuals/ememediaforge), also authored by Emmanuel Ariyo (Ememzyvisuals).*

## Model Summary

WazobiaVoice is a multilingual text-to-speech (TTS) and voice cloning model covering **Yoruba, Hausa, Igbo, Nigerian Pidgin, and Nigerian English** — five languages, one model, one set of weights. **~2B parameters** across the T3 transformer backbone and S3Gen flow-matching vocoder combined (see [Architecture](#architecture)). It is built by extending [chatterbox](https://github.com/resemble-ai/chatterbox)'s multilingual architecture to support four languages and orthographies it was never originally designed for, including Yoruba's tonal diacritic system, which required expanding the model's grapheme vocabulary and patching its hardcoded language-support list at both training and inference time.

WazobiaVoice ships with **13 inbuilt voice personas** across all five languages — each individually sourced from real speakers, gender-verified against source metadata (not guessed), and quality-ranked before selection — plus full voice-cloning support from any reference audio clip.

Built by [Axiveri](https://huggingface.co/Axiveri), led by Emmanuel Ariyo, with a mission to bring genuinely open, commercially-usable AI voice infrastructure to African developers and startups — a space where the strongest existing results are locked behind non-commercial research licenses (see [Ongoing Research](#ongoing-research-vits-for-yoruba)).

## Model Description

### Architecture

Chatterbox's multilingual variant (`ChatterboxMultilingualTTS`) generates speech in two stages: a transformer backbone (**T3**) autoregressively predicts discrete speech tokens from input text, and a flow-matching-based generative vocoder (**S3Gen**) converts those tokens into a waveform. Flow-matching sits in the same generative-modeling family as diffusion — both learn to transform noise into structured output through an iterative process — and it's what gives chatterbox its voice-cloning capability: a short reference clip conditions the generation so the output waveform is shaped in that speaker's voice.

The base chatterbox architecture was pretrained on a fixed set of ~23 languages, none of which were Yoruba, Hausa, Igbo, or Nigerian Pidgin. Bringing WazobiaVoice's five target languages online required real engineering at multiple layers, not just a data swap:

- **Grapheme vocabulary expansion** — the tokenizer's character set had to be extended to properly represent Yoruba's tonal diacritics (underdots, tone marks) as distinct, meaningful characters rather than silently normalizing or dropping them.
- **Runtime language-whitelist patch** — the installed chatterbox package hardcodes a `SUPPORTED_LANGUAGES` dictionary that rejects any `language_id` outside its original ~23 languages at generation time, independent of what the underlying weights actually learned. WazobiaVoice's fork (see [How to Use](#how-to-use)) bakes this patch in directly so the model works out of the box.
- **Multi-source, license-audited data pipeline** — training data was assembled from a diverse collection of publicly available and properly licensed Nigerian-language speech sources, explicitly filtered to exclude anything with non-commercial restrictions, and engineered for genuine multi-speaker diversity per language rather than single-speaker bias.
- **One named exception to source-anonymity:** WazobiaVoice's Hausa data is meaningfully strengthened by **wazobia-tts-cc**, an original Axiveri-curated dataset of high-quality Hausa political, government, and civic-affairs speech sourced from established Hausa radio stations and podcasts — chosen specifically because everyday political and civic discourse is a demanding, high-value register for a production voice model to get right.

### How WazobiaVoice Compares

No two Nigerian-language TTS efforts have taken quite the same architectural path, and it's worth naming them directly rather than vaguely:

- **[YarnGPT](https://huggingface.co/saheedniyi/YarnGPT)** (SmolLM2-360M backbone + [WavTokenizer](https://github.com/jishengpeng/WavTokenizer)) takes the same broad approach as chatterbox — an LLM predicting discrete audio tokens — and, like WazobiaVoice, produces strong Nigerian-accented English but runs into the same category of tonal/pronunciation gaps on Yoruba. Its own model card is candid about this. The hosted commercial product at [yarngpt.ai](https://yarngpt.ai) produces near-perfect Yoruba output (independently verified) — a genuinely strong result — but the underlying open model still shows the gaps typical of this architecture family, suggesting the production version benefits from additional proprietary training, framework tuning, or backbone work not reflected in what's publicly released.
- **[MMS-TTS](https://huggingface.co/facebook/mms-tts)** (Meta) uses **VITS** — a mel-spectrogram and duration-predictor based architecture, fundamentally different from the token-autoregressive family above — and gets real, working Yoruba results because of it. This is strong evidence the architecture family matters here, not just data volume. The catch: Meta's MMS-TTS checkpoints are released under a non-commercial license, off-limits for production use by any startup or developer trying to build a real product.

WazobiaVoice's own Yoruba performance (see [The Yoruba Tonal Problem](#the-yoruba-tonal-problem)) shows this same architectural pattern — which is exactly why Axiveri has an active VITS-based research track underway, aimed at closing this gap without the non-commercial restriction. See [Ongoing Research](#ongoing-research-vits-for-yoruba).

## Inbuilt Voice Personas

Every persona below was individually sourced from real speaker audio, verified for gender against the source dataset's own metadata where available, and quality-ranked before selection — not synthesized or guessed.

| Persona | Language | Gender | Region | Traits | Best Use Case |
|---|---|---|---|---|---|
| Wura | Yoruba | Female | Lagos | Social, expressive | Social media content, conversational/casual content, entertainment |
| Bọlaji | Yoruba | Male | Ibadan | Neutral, basic | General narration, everyday announcements, informational content |
| Elder Deji | Yoruba | Male | — | Elderly, native Yoruba speaker | Storytelling, folklore/proverbs, cultural/heritage content, audiobooks |
| Ifé | Yoruba | Female | — | Teenage girl, news-style delivery | Youth-oriented news reading, educational content for younger audiences |
| Musa | Hausa | Male | Kano | Expressive, confident | Sports commentary, ads/promos, energetic announcements |
| Hauwa | Hausa | Female | Kaduna | Calm, professionally expressive | Customer service / IVR, professional narration |
| Emeka | Igbo | Male | Enugu | Bold, neutrally expressive | General narration, e-learning, corporate voice |
| Adaeze | Igbo | Female | Imo | Neutrally expressive | General narration, audiobooks, virtual assistant |
| Tunde | Nigerian Pidgin | Male | Lagos | Calm | Calm narration, wellness/meditation content |
| Ngozi | Nigerian Pidgin | Female | Port Harcourt | Competent, professional | Customer service, business communications |
| John | Nigerian Pidgin | Male | — | Teenage boy, expressive, confident, loud | Ads/promos, youth entertainment, games, energetic social content |
| James | Nigerian English | Male | Lagos Island | Professional | Corporate narration, business communications |
| Amara | Nigerian English | Female | Lagos Island | Calm, friendly, expressive | Friendly customer service, conversational assistant, onboarding content |

## Speech Samples

### Native Language Samples

<div style="margin-top: 20px;">
<table style="width: 100%; border-collapse: collapse;">
  <thead>
    <tr>
        <th style="border: 1px solid #ddd; padding: 8px; text-align: left; width: 15%;">Persona</th>
        <th style="border: 1px solid #ddd; padding: 8px; text-align: left; width: 45%;">Sample Text</th>
        <th style="border: 1px solid #ddd; padding: 8px; text-align: left; width: 40%;">Audio</th>
    </tr>
  </thead>
  <tbody>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Wura (Yoruba, F)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Ọrẹ́ mi ti dé láti ìlú ẹ̀kọ́ ní òní, a sì ń sọ̀rọ̀ nípa bí a ṣe ń lọ sí ọjà...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/wura.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Bọlaji (Yoruba, M)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Ọrẹ́ mi ti dé láti ìlú ẹ̀kọ́ ní òní, a sì ń sọ̀rọ̀ nípa bí a ṣe ń lọ sí ọjà...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/bolaji.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Elder Deji (Yoruba, M)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Ọrẹ́ mi ti dé láti ìlú ẹ̀kọ́ ní òní, a sì ń sọ̀rọ̀ nípa bí a ṣe ń lọ sí ọjà...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/elder_deji.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Ife (Yoruba, F)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Ọrẹ́ mi ti dé láti ìlú ẹ̀kọ́ ní òní, a sì ń sọ̀rọ̀ nípa bí a ṣe ń lọ sí ọjà...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/ife.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Musa (Hausa, M)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Yau na tashi da safe na ci abincin safe sannan na fita zuwa kasuwa...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/musa.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Hauwa (Hausa, F)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Yau na tashi da safe na ci abincin safe sannan na fita zuwa kasuwa...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/hauwa.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Emeka (Igbo, M)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">N'ụtụtụ, m gara ahịa zụta ihe oriri dị ka akwụkwọ nri na azụ̀ ọhụrụ...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/emeka.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Adaeze (Igbo, F)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">N'ụtụtụ, m gara ahịa zụta ihe oriri dị ka akwụkwọ nri na azụ̀ ọhụrụ...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/adaeze.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Tunde (Pidgin, M)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">My guy don land from Abuja since morning, we dey gist about how we go reach market...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/tunde.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Ngozi (Pidgin, F)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">My guy don land from Abuja since morning, we dey gist about how we go reach market...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/ngozi.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">John (Pidgin, M, teen)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">My guy don land from Abuja since morning, we dey gist about how we go reach market...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/john.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">James (English, M)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">My friend arrived from Lagos this morning, and we've been chatting about going to the market...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/james.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Amara (English, F)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">My friend arrived from Lagos this morning, and we've been chatting about going to the market...</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/amara.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
  </tbody>
</table>
</div>

*Each persona has 2 additional sample lines in [`model_card_samples/`](https://huggingface.co/Axiveri/WazobiaVoice/tree/main/model_card_samples) — this table shows one representative line per voice.*

### Cross-Lingual Voice Cloning

The same reference voice can speak **any** of the five supported languages — not just the one it was originally recorded in. Below, Ifé (a native Yoruba voice) and John (a native Pidgin voice) are shown speaking languages outside their own:

<div style="margin-top: 20px;">
<table style="width: 100%; border-collapse: collapse;">
  <thead>
    <tr>
        <th style="border: 1px solid #ddd; padding: 8px; text-align: left; width: 20%;">Voice (native language)</th>
        <th style="border: 1px solid #ddd; padding: 8px; text-align: left; width: 15%;">Speaking</th>
        <th style="border: 1px solid #ddd; padding: 8px; text-align: left; width: 40%;">Audio</th>
    </tr>
  </thead>
  <tbody>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Ifé (native: Yoruba)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Hausa</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/ife_ha.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Ifé (native: Yoruba)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Igbo</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/ife_ig.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Ifé (native: Yoruba)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Nigerian Pidgin</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/ife_pcm.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">Ifé (native: Yoruba)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">English</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/ife_en.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">John (native: Pidgin)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Yoruba</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/john_yo.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">John (native: Pidgin)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Hausa</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/john_ha.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">John (native: Pidgin)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">Igbo</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/john_ig.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
    <tr>
        <td style="border: 1px solid #ddd; padding: 8px;">John (native: Pidgin)</td>
        <td style="border: 1px solid #ddd; padding: 8px;">English</td>
        <td style="border: 1px solid #ddd; padding: 8px;"><audio controls style="width: 100%;"><source src="https://huggingface.co/Axiveri/WazobiaVoice/resolve/main/model_card_samples/john_en.wav" type="audio/wav">Your browser does not support the audio element.</audio></td>
    </tr>
  </tbody>
</table>
</div>

*Full cross-lingual set (24 samples) available in [`model_card_samples/`](https://huggingface.co/Axiveri/WazobiaVoice/tree/main/model_card_samples) and [`cross_lang_manifest.csv`](https://huggingface.co/Axiveri/WazobiaVoice/blob/main/cross_lang_manifest.csv).*

## How to Use

WazobiaVoice runs on **[wazobiavoice-TTS](https://github.com/Ememzyvisuals/wazobiavoice-TTS)**, a fork of chatterbox with the language-whitelist and grapheme-vocabulary patches described in [Architecture](#architecture) baked in directly — no manual patching needed.

### Install

```bash
git clone https://github.com/Ememzyvisuals/wazobiavoice-TTS.git
cd wazobiavoice-TTS
bash scripts/install.sh
```

The install is staged deliberately (a plain `pip install .` will fail on this stack — `deepfilternet` and `torchmetrics` send pip's resolver backtracking into incompatible years-old releases). `scripts/install.sh` handles the correct order: system Rust toolchain for `deepfilternet`'s extension, numpy/torch first, then the remaining audio libraries with the flags they actually need. Full reasoning is commented inline in the script itself.

**Requirements:** Python 3.10+, a CUDA GPU recommended (CPU works but is slow).

### Quickstart

```python
import torch
import torchaudio as ta
from wazobiavoice_tts.mtl_tts import WazobiaVoiceMultilingualTTS

device = "cuda" if torch.cuda.is_available() else "cpu"
model = WazobiaVoiceMultilingualTTS.from_pretrained(device)

wav = model.generate(
    "My guy don land from Abuja since morning, we dey gist about how we go "
    "reach market buy beans and fresh fish for evening chop.",
    language_id="pcm",
    audio_prompt_path="path/to/a_5_to_10_second_reference_clip.wav",
    exaggeration=0.55,
    cfg_weight=0.55,
)
ta.save("output.wav", wav, model.sr)
```

`language_id` accepts `yo` (Yoruba), `ha` (Hausa), `ig` (Igbo), `pcm` (Nigerian Pidgin), `en` (English) — plus the ~23 other languages inherited from the base multilingual model. `audio_prompt_path` is a short (5–10s) reference clip of the voice to clone; omit it to reuse whatever voice was last prepared via `model.prepare_conditionals(...)`.

**Full parameter list:**

```python
model.generate(
    text,                    # str, required
    language_id,             # str, required — see SUPPORTED_LANGUAGES
    audio_prompt_path=None,  # str, path to reference audio for voice cloning
    exaggeration=0.5,        # float, emotion/expressiveness intensity
    cfg_weight=0.5,          # float, classifier-free guidance weight
    temperature=0.8,
    repetition_penalty=1.2,
    min_p=0.05,
    top_p=1.0,
)
```

**Listing supported languages:**

```python
from wazobiavoice_tts.mtl_tts import SUPPORTED_LANGUAGES
print(SUPPORTED_LANGUAGES)
# {'ar': 'Arabic', ..., 'yo': 'Yoruba', 'ha': 'Hausa', 'ig': 'Igbo', 'pcm': 'Nigerian Pidgin', 'en': 'English', ...}
```

**Loading from a local checkpoint instead of the Hub:**

```python
model = WazobiaVoiceMultilingualTTS.from_local("path/to/checkpoint_dir", device)
```

### Demo apps

```bash
python multilingual_app.py       # Gradio web UI, multilingual
python gradio_tts_turbo_app.py   # Gradio web UI, turbo model
python gradio_vc_app.py          # Gradio web UI, voice conversion
```

Full repo, install script reasoning, and license/notice files: **[github.com/Ememzyvisuals/wazobiavoice-TTS](https://github.com/Ememzyvisuals/wazobiavoice-TTS)**

## Bias, Risks, and Limitations

WazobiaVoice's language coverage was built from the ground up rather than inherited, and quality is not uniform across the five supported languages:

- **Nigerian English, Igbo, and Hausa** perform strongly — clear pronunciation, correct accent, stable delivery.
- **Nigerian Pidgin** performs well, close to the English/Igbo/Hausa tier.
- **Yoruba** is the clear outlier. See [The Yoruba Tonal Problem](#the-yoruba-tonal-problem) below for a full technical breakdown — in short, the model pronounces words it saw well-represented in training reasonably well, but struggles with tonal diacritics and pronunciation on less-represented words and patterns.

The model may not capture the full range of regional accents within each language, and inbuilt persona voices reflect the specific speakers they were sourced from rather than every possible voice within a given region or demographic.

### The Yoruba Tonal Problem

This deserves a direct, technical explanation rather than a vague disclaimer, because it's the single most important limitation of this model.

Yoruba is a tonal language where pitch changes the *meaning* of a word, marked in text through diacritics (tone marks and underdots) that are not optional decoration — they're load-bearing. WazobiaVoice's underlying architecture (see [Architecture](#architecture)) generates speech through an autoregressive transformer predicting discrete tokens one at a time — the same broad approach used by [YarnGPT](https://huggingface.co/saheedniyi/YarnGPT). This was not a hypothesis we left untested: after the model's initial training, we ran a dedicated follow-up training pass using 36+ hours of high-diacritic-quality Yoruba audio, specifically targeting this weakness. Despite following the exact same training methodology that worked for the other four languages, quality did not improve — the model produced mispronunciations, unstable prosody, and in some cases outright hallucinated output. In short, the result did not come out as expected: throwing more hours of clean, well-diacritized Yoruba data at the problem did not translate into better Yoruba output, and in some cases made outputs less predictable rather than more. This is the main reason we don't treat "just fine-tune on more Yoruba data" as a real fix here — the data volume and quality were already there for this pass, and it still didn't move the needle.

This points to an architectural ceiling rather than a data problem: token-based autoregressive TTS appears to structurally struggle with representing tone the way Yoruba requires. This is consistent with what we observe in YarnGPT's own results, and with why architectures built specifically to solve this — like **VITS**, used by [MMS-TTS](https://huggingface.co/facebook/mms-tts) — get meaningfully better Yoruba results by design, not luck. We're acting on this finding directly — see [Ongoing Research](#ongoing-research-vits-for-yoruba).

### Recommendations

Users building on WazobiaVoice for Yoruba-language use cases should test thoroughly against their own target vocabulary before production use, and should not assume uniform quality across all Yoruba text the way they reasonably could for the model's other four languages. Feedback, real-world testing reports, and contributions of additional high-quality diacritic-marked Yoruba training data are welcomed.

## Prohibited Uses

In line with responsible AI practice, WazobiaVoice must not be used to:

- Clone or impersonate a real, identifiable individual's voice without that person's explicit, informed consent
- Generate speech for fraud, scams, impersonation, or deceptive purposes of any kind
- Produce political disinformation, fabricated statements attributed to real public figures, or election-related deception
- Generate hateful, harassing, or discriminatory content targeting any individual or group
- Generate any content sexualizing or otherwise harming minors
- Violate the license terms of any underlying dataset, architecture, or dependency this model is built on

This is not a hypothetical list — it reflects real decisions made during this model's development. A planned persona built from a real, identifiable public figure's voice was deliberately excluded during development specifically because informed consent wasn't in place, even though the underlying audio itself was otherwise usable.

## License

WazobiaVoice is released under a custom **Axiveri Research License** — free to use for **research and non-commercial purposes only**. Full terms are in [`LICENSE.md`](LICENSE.md).

WazobiaVoice was fine-tuned on Axiveri's own curated training data, and Axiveri retains the rights to license the model. **Any commercial use — including integrating the model into a SaaS product, application, or any tool that collects money from users in any way — requires contacting the developer first to obtain a separate commercial license.**

To request a commercial license, contact:

- Email: **ememzyvisuals@gmail.com**

This license covers the WazobiaVoice model weights and checkpoints in this repository. The underlying chatterbox architecture and the `wazobiavoice-TTS` inference code (see [How to Use](#how-to-use)) remain under their own respective licenses (MIT) — see [Credits & References](#credits--references).

## Training

WazobiaVoice was fine-tuned via LoRA on top of chatterbox's multilingual base, across **7 epochs**, on a diverse collection of publicly available and properly licensed Nigerian-language speech data — spanning multiple independent sources per language to ensure genuine multi-speaker diversity rather than single-speaker bias. Hausa training data is meaningfully strengthened by **wazobia-tts-cc**, an original Axiveri-curated dataset of high-quality political, government, and civic-affairs Hausa speech sourced from established Hausa radio stations and podcasts.

Training ran across multiple independent, interruptible cloud training sessions rather than one continuous run — the pipeline was built with automatic checkpoint-resume specifically so training could survive session interruptions and infrastructure limits without losing progress, picking back up exactly where it left off each time.

A dedicated Yoruba-focused continuation pass (see [The Yoruba Tonal Problem](#the-yoruba-tonal-problem)) used an additional 36+ hours of high-diacritic-quality Yoruba-only audio, isolated from the other four languages to concentrate the model's full capacity on Yoruba specifically.

## Ongoing Research: VITS for Yoruba

The architecture family underlying WazobiaVoice (and YarnGPT, and most public token-based Nigerian TTS efforts) has a real, demonstrated ceiling on Yoruba tonal accuracy. The architectures that *have* solved this — **VITS**, as used by Meta's [MMS-TTS](https://huggingface.co/facebook/mms-tts) — are released under non-commercial licenses, unusable for any real product or startup.

Axiveri is actively researching and training a **VITS-based Yoruba TTS model from scratch**, using only commercially-licensed data and open training code, with the explicit goal of closing this gap for African developers and startups without the non-commercial restriction blocking every other working solution to this problem. This work is ongoing.

**This research is compute-intensive and self-funded.** Individual sponsors, partnerships, and donations that would help bring this to completion faster are genuinely welcomed:

- Email: **axiveriltd@gmail.com**
- Twitter/X: **[@ememzyvisuals](https://twitter.com/ememzyvisuals)** / **[@Axiveri](https://twitter.com/Axiveri)**

## Future Improvements

- Resolve the Yoruba tonal accuracy gap via the VITS research track above
- Expand inbuilt persona coverage (additional regional accents, additional age ranges per language)
- Public inference API / hosted endpoint
- Expanded voice-cloning documentation and fine-tuning guides via the [GitHub fork](https://github.com/Ememzyvisuals/wazobiavoice-TTS)

## Citation

#### BibTeX:

```
@software{wazobiavoice2026,
  author = {Ariyo, Emmanuel},
  title  = {WazobiaVoice: Nigerian Multilingual Text-to-Speech},
  year   = {2026},
  url    = {https://github.com/Ememzyvisuals/wazobiavoice-TTS},
  note   = {Built under Axiveri. Fine-tuned from Chatterbox (Resemble AI).}
}
```

#### APA:

```
Ariyo, E. (2026). WazobiaVoice: Nigerian Multilingual Text-to-Speech. Built under Axiveri. https://github.com/Ememzyvisuals/wazobiavoice-TTS
```

## Credits & References

- [chatterbox](https://github.com/resemble-ai/chatterbox) — Resemble AI, base multilingual architecture, MIT License
- [chatterbox-finetuning-multilingual](https://github.com/Ahmed-Ezzat20/chatterbox-finetuning-multilingual) — fine-tuning framework used for training
- [YarnGPT](https://huggingface.co/saheedniyi/YarnGPT) — Saheed Azeez, referenced throughout this card for architectural comparison
- [MMS-TTS](https://huggingface.co/facebook/mms-tts) — Meta, referenced for VITS architecture comparison
- [Ememzyvisuals/wazobiavoice-TTS](https://github.com/Ememzyvisuals/wazobiavoice-TTS) — patched fork for direct model usage, MIT License
- [Ememzyvisuals/ememediaforge](https://github.com/Ememzyvisuals/ememediaforge) — used to generate this model card's demo video

Built and maintained by **Emmanuel Ariyo (Ememzyvisuals)**, an independent Machine Learning and AI Engineer, under **Axiveri** — an initiative building the African AI models that African companies, startups, developers, and researchers can build on.

- GitHub: [Ememzyvisuals](https://github.com/Ememzyvisuals)
- Contact: <ememzyvisuals@gmail.com>
- Portfolio: [https://ememzyvisuals.vercel.app](https://ememzyvisuals.vercel.app)