Update README.md

README.md

@@ -1,75 +1,175 @@
+
 ---
 license: apache-2.0
 pipeline_tag: text-to-speech
 language:
-- ar
-- zh
-- en
-- ja
-- ko
-- de
-- fr
-- ru
-- pt
-- es
-- it
+  - ar
+  - zh
+  - en
+  - ja
+  - ko
+  - de
+  - fr
+  - ru
+  - pt
+  - es
+  - it
 tags:
-- audio
-- tts
-- voice-clone
+  - audio
+  - tts
+  - voice-clone
+  - multilingual-tts
+  - arabic-tts
 base_model:
-- Qwen/Qwen3-TTS-12Hz-0.6B-Base
+  - Qwen/Qwen3-TTS-12Hz-0.6B-Base
 ---
 
 <p align="center">
-  <img src="logo.jpg" alt="A3S Logo" width="400" high="600"/>
+  <img src="logo.jpg" alt="A3S Logo" width="400" height="600"/>
 </p>
 
-# A3S — Sample Audios
+# A3S — Multilingual Text-to-Speech
 
-Multilingual Text-to-Speech supporting **11 languages** and **3 speakers**. Arabic is available in **3 dialects**: Saudi, Emirati, and Modern Standard Arabic (MSA).
+**A3S** is a multilingual Text-to-Speech (TTS) model built upon **Qwen3-TTS-12Hz-0.6B-Base**, extending its original 10-language support with **Arabic**.
 
-## Arabic Voices
+The model supports **11 languages** (Arabic, Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, and Italian)
 
-| Language | Audio Sample |
+Arabic speech generation supports **3 dialects**:
+
+- 🇸🇦 Saudi Arabic (Saudi Arabia)
+- 🇦🇪 Emirati Arabic (United Arab Emirates)
+- 🌍 Modern Standard Arabic (MSA)
+
+## Available Arabic Speakers
+
+A3S provides three Arabic speaker identities:
+
+| Speaker |
+|---|
+| `omar` |
+| `hanouf` |
+| `fahad` |
+
+Speaker selection is performed using the `speaker` parameter during inference.
+
+---
+
+## Arabic Voice Samples
+
+Listen to the model's Arabic speech generation across different dialects.
+
+| Language / Dialect | Audio Sample |
 |---|---|
-| **Saudi Arabic** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/AR-Sa.wav"></audio> |
-| **Emirati Arabic** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/AR-uae.wav"></audio> |
+| **Saudi Arabic (Saudi Arabia)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/AR-Sa.wav"></audio> |
+| **Emirati Arabic (United Arab Emirates)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/AR-uae.wav"></audio> |
 | **Modern Standard Arabic (MSA)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/AR.wav"></audio> |
 
-## Multilingual Samples
+---
+
+##  Multilingual Voice Samples
+
+A3S supports speech generation in the following 11 languages.
 
 | Language | Audio Sample |
 |---|---|
-| **English** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/English.wav"></audio> |
-| **Chinese** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Chinese.wav"></audio> |
-| **Japanese** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Japanese.wav"></audio> |
-| **Korean** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/korean.wav"></audio> |
-| **German** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/German.wav"></audio> |
-| **French** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/French.wav"></audio> |
-| **Russian** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Russian.wav"></audio> |
-| **Portuguese** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Portuguese.wav"></audio> |
-| **Spanish** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Spanish.wav"></audio> |
-| **Italian** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Italian.wav"></audio> |
+| **English (English)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/English.wav"></audio> |
+| **Chinese (Mandarin Chinese)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Chinese.wav"></audio> |
+| **Japanese (Japanese)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Japanese.wav"></audio> |
+| **Korean (Korean)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/korean.wav"></audio> |
+| **German (German)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/German.wav"></audio> |
+| **French (French)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/French.wav"></audio> |
+| **Russian (Russian)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Russian.wav"></audio> |
+| **Portuguese (Portuguese)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Portuguese.wav"></audio> |
+| **Spanish (Spanish)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Spanish.wav"></audio> |
+| **Italian (Italian)** | <audio controls src="https://huggingface.co/MahmoudIbrahim/A3S/resolve/main/samples/Italian.wav"></audio> |
 
 ---
 
-## Quick Start 
 
-Try out the model directly in Google Colab:
+## Quick Start
+
+Get started with A3S using our ready-to-run Google Colab notebook, or follow the instructions below to run the model locally.
 
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1QGViKk_b38jqDyzp6MBuSZrFcZ9ILI6Q?usp=sharing)
 
 
-### Model Performance Comparison (NVIDIA A10 GPU)
+### Local Installation
+
+Install the required dependencies:
+
+```bash
+pip install qwen_tts soundfile
+```
+
+For Ubuntu or Google Colab:
+
+```bash
+apt-get update && apt-get install -y sox libsox-fmt-all
+```
+
+**Optional: FlashAttention 2**
+
+For compatible NVIDIA GPUs (Ampere or newer):
+
+```bash
+pip install flash-attn --no-build-isolation
+```
+
+FlashAttention is optional and requires a compatible CUDA environment.
+
+### Load the Model
+
+```python
+import torch
+import soundfile as sf
+from qwen_tts import Qwen3TTSModel
+from transformers import logging as hf_logging
+from IPython.display import Audio, display
+
+hf_logging.set_verbosity_error()
+
+device = "cuda:0"
+
+tts = Qwen3TTSModel.from_pretrained(
+    "MahmoudIbrahim/A3S",
+    device_map=device,
+    dtype=torch.bfloat16,
+    # attn_implementation="flash_attention_2",
+)
+```
+
+### Generate Speech
+
+```python
+wavs, sr = tts.generate_custom_voice(
+    text="وش علومك؟ طال عمرك كنت مسرع ومستعجل بروح الدوام، بس الزحمة هدت حيلنا وتأخرت شوي، وقفت على الطاير أخذت لي قهوة وكملت يومي.",
+    speaker="hanouf",
+    temperature=0.7,
+    subtalker_temperature=0.3
+)
+
+sf.write("output.wav", wavs[0], sr)
+
+display(Audio("output.wav"))
+```
+
+Change the `speaker` parameter to select a different voice.
+
+---
+
+## Model Performance Comparison (NVIDIA A10 GPU)
+
+The following table presents reported inference performance for A3S and other TTS models.
 
 | Model | Model Size | TTFC (Time to First Chunk) | TTFA (Time to First Audio) | RTF (Real-Time Factor) | Generation Speed | Total Latency (3.8s Audio) |
 | :--- | :---: | :--- | :--- | :--- | :--- | :--- |
-| **A3S** | 0.6B | ~60 ms | 200 – 400 ms | ~0.18 *(5.5x faster)* | ~110+ tokens/sec | ~650 ms |
-| **OmniVoice** *(Non-Streaming)* | 0.6B | ~1,410 ms | ~1,410 ms | ~0.37 *(2.7x faster)* | N/A | ~1,410 ms |
-| **Higgs** | 4B | ~60 ms | 356 – 550 ms | ~0.70 *(1.43x faster)* | ~39.3 tokens/sec | ~2,692 ms |
-
-## Authors
- 
-- [Collaborator Nada saed](https://www.linkedin.com/in/nada-saeed-mohamed-8b5a96216/)
-- [Collaborator Mahmoud Ibrahim](https://www.linkedin.com/in/mahmoud-ibrahim-93a376258/)
+| **A3S** | 0.6B | ~60 ms | 200–400 ms | ~0.18 (5.5x faster) | ~110+ tokens/sec | ~650 ms |
+| **OmniVoice (Non-Streaming)** | 0.6B | ~1,410 ms | ~1,410 ms | ~0.37 (2.7x faster) | N/A | ~1,410 ms |
+| **Higgs** | 4B | ~60 ms | 356–550 ms | ~0.70 (1.43x faster) | ~39.3 tokens/sec | ~2,692 ms |
+
+---
+
+##  Authors & Collaborators
+
+- [Nada Saeed Mohamed](https://www.linkedin.com/in/nada-saeed-mohamed-8b5a96216/) — Collaborator
+- [Mahmoud Ibrahim](https://www.linkedin.com/in/mahmoud-ibrahim-93a376258/) — Collaborator