INTEGRATION_AR.md

# ربط كل الخدمات على خادم واحد — جسر

الآن **خادم واحد** (Hugging Face Space) يقدّم الخدمات الثلاث، والسيرفر الوسيط
(`api-server.js`) يوجّه إليه فقط. عنوان واحد لكل شيء.

## المعمارية بعد الربط

```
[تطبيق Flutter]
   │  يرسل: نص للترجمة / صوت للتفريغ / نص للنطق
   ▼
[api-server.js]  ← وسيط خفيف (Node، صفر تبعيات)
   │  يحوّل طلبات REST إلى نداءات Gradio
   ▼
[Hugging Face Space]  ← خادم واحد على ZeroGPU
   ├── /translate  → MADLAD-400-3b-mt  (Apache 2.0 تجاري، 400+ لغة)
   ├── /stt        → Whisper small
   └── /tts        → Chatterbox (استنساخ صوتي، 7 لغات)
```

## ما الذي تغيّر

**في الـ Space** (`app.py` + `requirements.txt`):
- أضيف endpoint `translate` يستخدم MADLAD-400 (تجاري، بديل NLLB غير التجاري)
- أضيف endpoint `stt` يستخدم Whisper
- الواجهة الآن ثلاثة تبويبات: توليد كلام / ترجمة / تفريغ

**في السيرفر الوسيط** (`api-server.js`):
- حُذفت `TRANSLATE_URL` و `STT_URL` — لم تعد هناك خدمات منفصلة
- كل الطلبات تذهب لنفس `INFERENCE_BASE_URL` عبر مُنادٍ Gradio عام
- التفريغ يرفع الملف لـ Gradio ثم ينادي `stt`

**في التطبيق** (`api_service.dart`):
- التفريغ الآن يرسل بايتات الصوت الخام مع ترويسة `x-lang`

## خطوات التشغيل

### 1) الـ Space
انسخ (Duplicate) الـ Space الرسمي ResembleAI/Chatterbox-Multilingual-TTS-V3،
ثم استبدل `app.py` و `requirements.txt` بالنسختين المرفقتين، وارفع `default_voice.wav`.
اختر عتاد **ZeroGPU**.

> تحميل أول مرة: MADLAD-3B (~12 جيجا) + Whisper + Chatterbox. أول طلب لكل
> خدمة يستغرق وقتاً للتحميل، ثم يصبح سريعاً. لو أردت MADLAD أصغر/أسرع اضبط
> متغير البيئة `MADLAD_MODEL=google/madlad400-3b-mt` (الافتراضي) — أو للجودة
> الأعلى `google/madlad400-7b-mt`.

### 2) السيرفر الوسيط
```bash
INFERENCE_BASE_URL=https://YOUR-USERNAME-SPACENAME.hf.space node api-server.js
```
متغير واحد فقط! (اختياري: `HF_TOKEN` لو الـ Space خاص، `PORT`).

### 3) التطبيق
```bash
flutter run --dart-define=API_BASE_URL=https://your-bridge-server.com
```

## اختبار سريع للخادم الموحّد

```bash
BASE=https://YOUR-USERNAME-SPACENAME.hf.space

# ترجمة
curl -X POST $BASE/gradio_api/call/translate \
  -H "Content-Type: application/json" \
  -d '{"data":["مرحبا بالعالم","العربية (ar)","English (en)"]}'
# ثم curl $BASE/gradio_api/call/translate/EVENT_ID
```

## ملاحظة الترخيص
- **MADLAD-400**: Apache 2.0 ✅ تجاري مسموح (بديل NLLB الذي كان CC-BY-NC)
- **Whisper**: MIT ✅
- **Chatterbox**: MIT ✅
كلها آمنة لتطبيق مدفوع.