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) السيرفر الوسيط

INFERENCE_BASE_URL=https://YOUR-USERNAME-SPACENAME.hf.space node api-server.js

متغير واحد فقط! (اختياري: HF_TOKEN لو الـ Space خاص، PORT).

3) التطبيق

flutter run --dart-define=API_BASE_URL=https://your-bridge-server.com

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

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 ✅ كلها آمنة لتطبيق مدفوع.