Nigerian TTS

Modular, test-driven Nigerian accent text-to-speech converter with pluggable backends and rotating proxy support.

Features

• Authentic Nigerian accent — Azure Neural voices en-NG-AbeoNeural (male) and en-NG-EzinneNeural (female)
• Two backends — edge-tts (free, unlimited, no watermarks) or FreeTTS.org (fallback)
• Pluggable architecture — swap backends via protocol without changing caller code
• Proxy rotation — multi-source proxy aggregation, health verification, blacklisting
• Smart text chunking — splits at sentence/paragraph/clause boundaries
• Batch processing — convert long scripts into chunked MP3s
• CLI and Python API — use from terminal or import as a library

Installation

pip install -e .

With dev dependencies:

pip install -e ".[dev]"

Quick Start

Python

from nigerian_tts import NigerianTTS

tts = NigerianTTS()  # edge-tts backend (default)
audio = tts.generate("Hello from Lagos")
tts.generate_to_file("Good morning", "greeting.mp3")

CLI

# Basic usage
nigerian-tts "Hello from Lagos"

# Save to file with female voice
nigerian-tts "Good morning" -o greeting.mp3 --voice female

# Batch mode for long scripts
nigerian-tts --file script.txt --batch --output-dir ./audio/

# Use FreeTTS backend
nigerian-tts "Hello" --backend freetts --no-proxy

# List available voices
nigerian-tts --list-voices

Backends

edge-tts (default)

• Free, unlimited, no watermarks
• Same Azure Neural TTS voices
• Requires no API key or proxy
• Best for production use

FreeTTS.org (fallback)

• Free tier: 2,000 chars/day, 1,000 chars/request
• Has audible watermark
• Requires rotating proxy for sustained use
• Non-commercial only

Proxy System

When using the FreeTTS backend, proxies are rotated automatically:

from nigerian_tts import NigerianTTS, ProxyFetcher, ProxyPool
from nigerian_tts.proxy.sources import SOURCES
from nigerian_tts.proxy.verifier import ProxyVerifier
from nigerian_tts.proxy.manager import ProxyPool

# Fetch from multiple free sources
sources = [cls() for cls in SOURCES.values()]
fetcher = ProxyFetcher(sources=sources)
raw = fetcher.fetch_all()

# Verify and build pool
verifier = ProxyVerifier(timeout=5)
verified = verifier.verify_batch(raw, max_workers=10)
pool = ProxyPool()
pool.load(verified)

# Use with client
tts = NigerianTTS(backend="freetts", proxy_pool=pool)

CLI proxy options:

# Auto-fetch and verify proxies
nigerian-tts "Hello" --backend freetts

# Use custom proxy file
nigerian-tts "Hello" --backend freetts --proxy-file proxies.txt

# Disable proxy rotation
nigerian-tts "Hello" --backend freetts --no-proxy

Project Structure

nigerian_tts/
  src/nigerian_tts/
    __init__.py              # Package entry, lazy imports
    client.py                # NigerianTTS client (delegates to backends)
    cli.py                   # Click CLI entry point
    chunker.py               # Smart text splitting (950 char chunks)
    batch.py                 # BatchProcessor for multi-file output
    voices.py                # Voice dataclass + catalog with filtering
    utils.py                 # RateLimiter, retry decorator, UA rotation
    backends/
      __init__.py            # TTSBackend protocol + registry + factory
      edge_tts_backend.py    # edge-tts wrapper (primary, free)
      freetts_backend.py     # FreeTTS.org backend (fallback)
    proxy/
      __init__.py
      sources.py             # Proxy dataclasses + source scrapers
      fetcher.py             # Multi-source aggregation + dedup
      verifier.py            # Health check via httpbin.org/ip
      manager.py             # ProxyPool with rotation + blacklisting
  tests/
    test_client.py
    test_cli.py
    test_batch.py
    test_chunker.py
    test_voices.py
    test_utils.py
    test_backends/
    test_proxy/
  demo/
    generate_sample.py       # Generates demo MP3s with edge-tts
    *.mp3                    # Pre-generated Nigerian accent samples

Tests

# Run all tests
pytest

# With coverage
pytest --cov=nigerian_tts --cov-report=term-missing

168 tests across client, CLI, batch processing, text chunking, voices, utilities, backends, and proxy subsystems. Target: 85% coverage minimum.

Voice Quality

Overall: 9/10 (Azure Neural)

Aspect	Score	Notes
Clarity	9/10	Clear pronunciation, natural prosody
Accent	9/10	Authentic Nigerian English, not generic "African"
Consistency	9/10	No glitches, pops, or artifacts
Content creation	7/10	Limited emotional range for dramatic content
Cost	10/10	Free via edge-tts, unlimited usage

Best for: Educational content, news explainers, tutorials, podcast narration, YouTube content

Not ideal for: Dramatic storytelling, character voices, cinematic content

Audio Specs

• Format: MP3 (MPEG-2 Layer III)
• Bitrate: 48 kbps
• Sample rate: 24,000 Hz
• Channels: Mono

License

See LICENSE for details.