Instructions to use touati-kamel/Hadra-TTS-piper with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Piper
How to use touati-kamel/Hadra-TTS-piper with Piper:
# No code snippets available yet for this library. # To use this model, check the repository files and the library's documentation. # Want to help? PRs adding snippets are welcome at: # https://github.com/huggingface/huggingface.js
- Notebooks
- Google Colab
- Kaggle
Hadra-TTS Piper (Algerian Darja)
Ultra-Fast, Edge-Ready Neural Text-to-Speech for Algerian Arabic
Hadra-TTS-piper is a production-ready, ultra-lightweight neural speech synthesis model fine-tuned specifically for Algerian Darja (الدارجة الجزائرية). Built on the high-efficiency VITS (Conditional Variational Autoencoder with Adversarial Training and Normalizing Flows) architecture and exported to ONNX Runtime, it produces crisp, natural, human-grade speech at over 8x faster than real-time on standard CPUs.
Live Interactive Benchmark Dashboard
Experience the complete test suite directly in your browser. All 75 generated WAV recordings across 5 stress-test tiers and 3 voice personas are hosted on our interactive dashboard:
Explore the Live Hadra Piper Benchmark Dashboard (Netlify)
Benchmark Summary Matrix (75/75 PASS — 100% Quality Rate)
| Test Tier | Focus & Linguistic Challenge | Prompts | Personas | Status | Avg RTF (CPU) |
|---|---|---|---|---|---|
| Tier 1: Pan-Algerian Greetings & French Code-Switching | Natural everyday conversation, welcoming phrases, and transliterated French terms ("c'est bon", "en retard"). | 5 | 3 | 100% PASS | 0.121x |
| Tier 2: Urban & Youth Street Darja | Fast conversational slang ("حطة", "تحلاب", "تمنشير"), colloquial discourse particles. | 5 | 3 | 100% PASS | 0.124x |
| Tier 3: Numbers, Currencies & Quantities | Algerian Centimes / Dinar syntax (ملاين، دورو، ميات ألف), telephone numbers, and time. | 5 | 3 | 100% PASS | 0.128x |
| Tier 4: Cultural Proverbs, Folk Wisdom & Humor | Traditional Algerian adages ("خالتي لعجوزة", "طريق السد", "الحيط واقف"), deep storytelling rhythm. | 5 | 3 | 100% PASS | 0.122x |
| Tier 5: Long-Form Multi-Sentence Stress Tests | 20+ second continuous narratives, breathing flow, complex compound clauses, and sustained prosody. | 5 | 3 | 100% PASS | 0.125x |
| Overall Benchmark | Comprehensive Algerian Speech Synthesis Suite | 25 | 3 (75 clips) | 100% PASS | 0.124x |
Key Performance Takeaway: With an average Real-Time Factor (RTF) of 0.124x, synthesizing a 10-second Algerian speech clip takes just 1.24 seconds on a single CPU core, making it ideal for edge devices, home automation, and low-latency voice assistants.
The 3 Acoustic Personas
Hadra-TTS-piper provides 3 distinct vocal delivery styles calibrated through fine-tuned duration and pitch variability scales (length_scale and noise_scale):
| Persona | Vibe & Delivery Profile | Calibrated length_scale |
Calibrated noise_scale |
Recommended Use Cases |
|---|---|---|---|---|
Kahwa (kahwa) |
Energetic, crisp, natural conversational cadence; lively pan-Algerian street and podcast rhythm. | 0.95 |
0.667 |
Voice assistants, conversational bots, interactive chatbots, podcast intros. |
Rawi (rawi) |
Deep, deliberate, warm narrative voice; contemplative pacing with measured folkloric pauses. | 1.15 |
0.667 |
Audiobooks, history documentaries, long-form storytelling, reflective narrations. |
Loubna (loubna) |
Bright, expressive, gentle female delivery; dynamic melodic pitch with clear enunciations. | 0.90 |
0.667 |
Bedtime stories, children's educational content, friendly notifications, e-learning. |
Quickstart
1. Installation
Install the official Piper Python package:
pip install piper-tts
Download the model checkpoint and config from this repository:
# Download ONNX model (~63MB) and JSON configuration
wget https://huggingface.co/touati-kamel/Hadra-TTS-piper/resolve/main/model.onnx
wget https://huggingface.co/touati-kamel/Hadra-TTS-piper/resolve/main/model.onnx.json
2. Python Quickstart (With Persona Presets)
Synthesize authentic Algerian Darja audio with customized persona scales in just a few lines of code:
import wave
from piper import PiperVoice
# 1. Load the model and configuration
voice = PiperVoice.load("model.onnx", config_path="model.onnx.json", use_cuda=False)
voice.config.num_speakers = 1 # Standard single-speaker ONNX graph
# 2. Calibrated Persona Presets
PERSONAS = {
"kahwa": {"length_scale": 0.95, "noise_scale": 0.667}, # Energetic Podcast
"rawi": {"length_scale": 1.15, "noise_scale": 0.667}, # Deep Storyteller
"loubna": {"length_scale": 0.90, "noise_scale": 0.667}, # Expressive Storyteller
}
# 3. Synthesize an Algerian sentence
text = "صباح الخير والفل والياسمين على ناس وهران والجزائر العاصمة وكامل خاوتنا."
persona = PERSONAS["kahwa"]
with wave.open("output_kahwa.wav", "wb") as wav_file:
voice.synthesize(
text,
wav_file,
length_scale=persona["length_scale"],
noise_scale=persona["noise_scale"]
)
print("Saved output_kahwa.wav (22.05 kHz 16-bit PCM Mono)!")
3. Standalone C++ Piper CLI
Because Hadra-TTS-piper is an official ONNX-compliant Piper model, you can run it directly with the standalone C++ binary on Linux, macOS, or Windows with zero Python dependencies:
# Synthesize with Kahwa persona (Lively cadence)
echo "صحا خويا، راك مليح اليوم؟ واش راك داير فيها؟" | piper \
--model model.onnx \
--config model.onnx.json \
--length-scale 0.95 \
--noise-scale 0.667 \
--output_file greeting_kahwa.wav
# Synthesize with Rawi persona (Deep storytelling tempo)
echo "كان يا ما كان في قديم الزمان، كانت كاين حكاية قديمة راح نحكوهالكم اليوم." | piper \
--model model.onnx \
--config model.onnx.json \
--length-scale 1.15 \
--noise-scale 0.667 \
--output_file story_rawi.wav
4. Home Assistant & Wyoming Protocol Deployment
Integrate native Algerian Darja into your Home Assistant Local Voice Assistant using the Wyoming Piper Docker container:
A. Format File Names
Rename the downloaded files to match the Wyoming naming convention:
mv model.onnx ar_DZ-hadra-medium.onnx
mv model.onnx.json ar_DZ-hadra-medium.onnx.json
B. Docker Compose Configuration
Place both files in a local directory (./piper-data) and run rhasspy/wyoming-piper:
version: "3.8"
services:
wyoming-piper:
image: rhasspy/wyoming-piper:latest
container_name: wyoming-piper-darja
restart: unless-stopped
ports:
- "10200:10200"
volumes:
- ./piper-data:/data
command:
- "--voice"
- "ar_DZ-hadra-medium"
- "--speaker"
- "0"
C. Home Assistant Setup
- Navigate to Settings > Devices & Services > Add Integration.
- Select Wyoming Protocol, enter your host IP and port
10200. - Go to Settings > Voice Assistants, edit your pipeline, and select
ar_DZ-hadra-mediumas your primary TTS engine.
Code-Switching & French Loanword Preprocessor
Spoken Algerian Darja frequently incorporates French loanwords ("c'est bon", "en retard", "portable", "l'hôpital", "rendez-vous"). To ensure optimal pronunciation through the Arabic phonemizer, use this lightweight normalization preprocessor:
import re
LOANWORD_MAP = {
r"\bc['’]est bon\b": "سي بون",
r"\ben retard\b": "اون غوطار",
r"\bnormal\b": "نورمال",
r"\bportable\b": "بورطابل",
r"\bl['’]hôpital\b": "لوبيطال",
r"\bpharmacie\b": "فارماسي",
r"\bordonnance\b": "اوردونونس",
r"\bscanner\b": "سكانير",
r"\bmerci\b": "ميرسي",
r"\bpardon\b": "باردون",
r"\bbonjour\b": "بونجور",
r"\bbon\b": "بون",
r"\bdéjà\b": "ديجا",
r"\bproblème\b": "بروبليم",
r"\bservice\b": "سيرفيس",
r"\brendez-vous\b": "رونديفو",
}
def normalize_algerian_darja(text: str) -> str:
"""Standardizes Algerian text and transliterates Latin loanwords for Piper phonemization."""
# 1. Transliterate frequent Latin code-switched terms
normalized = text
for pattern, replacement in LOANWORD_MAP.items():
normalized = re.sub(pattern, replacement, normalized, flags=re.IGNORECASE)
# 2. Normalize common Arabic letter variants
normalized = re.sub(r"[إأآا]", "ا", normalized)
normalized = re.sub(r"ة\b", "ه", normalized)
normalized = re.sub(r"ى\b", "ي", normalized)
# 3. Clean excess whitespace and unwanted Latin characters
normalized = re.sub(r"[^\w\s\u0600-\u06FF\.\,\!\؟\?]", " ", normalized)
normalized = re.sub(r"\s+", " ", normalized).strip()
return normalized
# Example usage:
raw_text = "صحا خويا، راك en retard c'est bon، الطبيب عطاني ordonnance pour le scanner ف la pharmacie."
clean_text = normalize_algerian_darja(raw_text)
print(clean_text)
# Output: "صحا خويا راك اون غوطار سي بون الطبيب عطاني اوردونونس pour le سكانير ف لا فارماسي"
Model Specifications & Technical Details
| Parameter | Specification | Details |
|---|---|---|
| Model Architecture | VITS | Conditional Variational Autoencoder + Normalizing Flows + HiFi-GAN Vocoder |
| Base Voice | ar_JO-kareem-medium |
Rhasspy Piper Arabic Voice Checkpoint |
| Training Corpus | OddAdmix Algerian Speech Collection | Curated high-fidelity speech datasets: Kahwa Podcast, Rawi Stories, and Loubna Children Tales |
| Sampling Rate | 22,050 Hz | 16-bit PCM Mono WAV |
| Format | ONNX Runtime (v1.17+) | Quantized CPU-friendly graph |
| Model Size | ~63.4 MB | Single unified model.onnx file |
| Runtime Dependencies | piper-tts, onnxruntime |
Pure CPU inference, zero CUDA requirement |
| Phoneme Representation | espeak-ng Arabic phoneme set |
Interleaved blank tokens with zero-padding |
Citations & Acknowledgments
If you use Hadra-TTS-piper in your research, edge devices, or commercial applications, please cite:
@misc{touati2026hadrapiper,
author = {Kamel Touati},
title = {Hadra-TTS-piper: Ultra-Low-Latency Neural Speech Synthesis for Algerian Darja},
year = {2026},
publisher = {Hugging Face},
howpublished = {\url{https://huggingface.co/touati-kamel/Hadra-TTS-piper}}
}
Special thanks to:
- Rhasspy Piper by Michael Hansen for the incredible lightweight VITS speech architecture.
- OddAdmix for collecting and curating open Algerian spoken speech datasets.
- The Algerian NLP open-source community.
- Downloads last month
- 37