Cairo-TTS · كايرو

Fast Egyptian Arabic text-to-speech with English code-switching, live streaming and zero-shot voice cloning.
_{It runs on CPU or GPU, starts speaking in under 100 ms on a GPU, and includes 20 preset voices and a web studio.}

Install · Python · Web studio · Colab · Space · Pronunciation · Preprocessing · Parameters

from cairo_tts import CairoTTS

tts = CairoTTS.from_pretrained()          # downloads mohammedaly22/Cairo-TTS, runs on CPU
tts.save("ال meeting بكره الصبح بدري, ف يا ريت متتأخرش.", "out.wav", voice="malak")

✨ Features

📦 Install

pip install cairo-tts            # Python API + CLI
pip install "cairo-tts[ui]"      # + web studio (FastAPI)

From source:

git clone https://github.com/MohammedAly22/Cairo-TTS && cd Cairo-TTS
pip install -e ".[ui]"

• GPU: install the CUDA build of PyTorch first (pytorch.org). Cairo-TTS runs on the CPU by default; pass device="cuda" (or --device cuda) to use the GPU, or device="auto" to pick it when available.
• CPU only: pip install torch --index-url https://download.pytorch.org/whl/cpu keeps the install small.

🐍 Python

from cairo_tts import CairoTTS

tts = CairoTTS.from_pretrained(
    "mohammedaly22/Cairo-TTS",   # or a local folder
    device="cpu",                # "cpu" (default) | "cuda" | "cuda:1" | "auto"
    max_prompt_sec=10,           # seconds of reference audio used for cloning
    quantize=False,              # int8 weights on CPU
    num_threads=None,            # CPU threads
)

# 1) generate: a float32 numpy array at 24 kHz
audio = tts.generate("النهارده الجو حلو اوي, ايه رأيك ننزل نتمشى شوية؟")

# 2) save straight to a file, with a preset voice
tts.save("عارف ايه اكتر حاجة بتخوفني.", "ahmed.wav", voice="ahmed")

# 3) clone any voice (zero-shot) from a short, clean recording
tts.save("ده صوتي انا, بس الموديل هو اللي بيتكلم.", "me.wav", voice="my_voice.wav")
tts.export_voice("my_voice.wav", "my_voice.safetensors")    # instant to reload: voice="my_voice.safetensors"

# 4) stream: chunks arrive while audio is generated
for chunk in tts.stream("حاسس اني واقف مكاني. كل يوم نفس التاسكات, نفس ال meetings.", voice="sara"):
    play(chunk)                                              # your audio sink

# 5) metrics of the last call
m = tts.last_metrics
print(f"TTFA {m.ttfa*1000:.0f} ms · {m.audio:.1f}s audio in {m.total:.2f}s · {m.x_realtime:.1f}x real time · {m.device}")

# 6) see exactly what the model reads
print(tts.normalize("كلمني على 01012345678 الساعة 3:30 م"))

for v in tts.voices():
    print(v["id"], v["name_ar"], v["gender"], v["description_ar"])

A complete script is in examples/infer.py.

Command line

cairo-tts say "ال meeting اتأجل لبكره." -o out.wav --voice ahmed
cairo-tts say "صوتي انا." -o me.wav --voice my_voice.wav --device cpu
echo "النص من ملف" | cairo-tts say - -o out.wav
cairo-tts voices                     # preset voices
cairo-tts normalize "الساعة 3:30 م"   # → الساعة تلاتة ونص العصر
cairo-tts serve --port 8000          # web studio

🎛️ Web studio

pip install "cairo-tts[ui]"
cairo-tts serve                       # http://127.0.0.1:8000   (--device cpu|cuda, --host 0.0.0.0)

• Two modes: توليد كامل (generate the whole clip) and بث مباشر (live streaming, played while it is generated).
• Voices: a searchable dropdown of the 20 presets (descriptions, play/pause previews), or استنسخ صوت (clone a voice): upload a file or record from the microphone.
• Parameters: temperature, LSD steps, EOS threshold, frames after EOS, noise clamp, chunk size.
• Metrics after every run: server TTFA, browser TTFA, total time, audio length, × real time, RTF, chunks / characters, device.
• Pronunciation toolbar (فتحة، ضمة، كسرة، سكون، شدة، ةْ، ~), a random Egyptian sentence button, and a preview of the normalized text.
• A minimal Arabic, RTL, responsive layout with dark and light themes (?theme=light|dark), a waveform that fills in while streaming, and a generation history.
• Streaming plays through an AudioWorklet at the model's 24 kHz rate with a short pre-buffer, so chunks join without gaps or resampling clicks.
• A JSON API at /api/docs: POST /api/generate, POST /api/stream (NDJSON PCM chunks), GET /api/voices, POST /api/voices/upload, POST /api/normalize.

Use it from Python (e.g. in your own app):

from cairo_tts import CairoTTS
from cairo_tts.server import create_app, serve

serve(CairoTTS.from_pretrained(device="cuda"), host="0.0.0.0", port=8000)
# or: app = create_app(tts)  →  mount / run with any ASGI server

📓 Colab notebooks

Notebook
Quick start: load, preset voices, cloning, streaming, preprocessing, diacritics, parameters	01_quickstart.ipynb
Web UI: the full studio inside Colab, no local install	02_web_ui.ipynb

Both download the public model from Hugging Face; no token is needed.

🤗 Hugging Face Space

The Space runs the same studio (Docker SDK, port 7860). To deploy your own:

python scripts/deploy_space.py --space <user>/Cairo-TTS --token-secret   # uploads space/ + the package source

--token-secret stores your token as the Space's HF_TOKEN secret (only needed if you point it at a private model). Optional Space variables: CAIRO_TTS_MODEL, CAIRO_TTS_DEVICE, CAIRO_TTS_QUANTIZE=1.

✍️ Pronunciation control

The model adds diacritics on its own. Write them yourself only where it reads a word wrong:

Order of marks: letter → ~ → shadda → vowel (e.g. ق~َ). The frontend also reorders them for you. ~ is the marker the model learned from CATT's Egyptian «؞» sign.

🔢 Text preprocessing

preprocess_egyptian() runs before the model frontend. You can use it on its own:

from cairo_tts import preprocess_egyptian, prepare_text

preprocess_egyptian("كلمني على 01012345678 او ابعت على ahmed.ali@gmail.com")
# كلمني على زيرو واحد زيرو, واحد اتنين تلاتة اربعة, خمسة ستة سبعة تمانية, او ابعت على احمد دوت علي ات gmail دوت كوم

prepare_text("الاجتماع الساعة 3:30 م و السعر 250 جنيه بخصم 15%")[0]
# الاجتماع الساعة تلاتة ونص العصر و السعر ميتين وخمسين جنية بخصم خمستاشر في المية

Numbers are verbalized in Egyptian (1994 → «الف وتسعمية واربعة وتسعين»). Runs of more than 9 digits are read digit by digit.

⚙️ Parameters

📊 Speed

Measured with this package after warm-up, on 7–11 s sentences:

🧠 Model

The model is a Pocket TTS (Kyutai) architecture: a causal transformer over Mimi latents with a 1-step flow head and a streaming Mimi decoder (24 kHz).

• A 24-layer teacher was fine-tuned on ~747 h of Egyptian podcasts collected with the EgySpeech pipeline, then distilled into this 6-layer student.
• Details are on the model card.

🗂️ Repository

src/cairo_tts/
├── model.py            CairoTTS: loading, devices, voices, generate / stream / save, metrics
├── text/               Egyptian preprocessing + the training frontend (numbers, diacritics, ta marbuta)
├── server/             FastAPI app + static web studio (HTML / CSS / JS)
└── cli.py              cairo-tts say | serve | voices | normalize
notebooks/              Colab quick start + web UI
examples/infer.py       minimal script
space/                  Hugging Face Space (Docker)
scripts/                prepare_voices.py · upload_to_hub.py · deploy_space.py
tests/                  text + inference + API tests (pytest)

⚖️ Responsible use

Cairo-TTS can imitate voices.

• Do not use it to impersonate anyone without their consent, to deceive, or to commit fraud.
• The preset voices are short clips of podcast speakers and are provided for research and demos only.
• Label synthetic audio when you publish it.

📜 License

• The code is MIT.
• The model weights are fine-tuned from Kyutai's Pocket TTS and follow its terms. See NOTICE.md and the model card.