# إضافة "مقاعد صوتية" (voice_seats) - CodyChat 10.1

## طريقة التركيب

1. فك ضغط هذا الملف، هتلاقي مجلد اسمه `voice_seats`.
2. ارفع المجلد بالكامل داخل مسار السكربت عندك في:
   `codychat/addons/voice_seats`
3. ادخل على لوحة تحكم الأدمن (admin.php) → **الإضافات (Addons)**.
4. اضغط **تركيب (Install)** على "voice_seats".
5. اضغط على زرار **الإعدادات (⚙)** بجانب الإضافة، واختار الرتب اللي
   تقدر تطلع تقعد على مقعد وتتكلم (افتراضياً كل الرتب الحقيقية مفعّلة).
6. خلاص، شريط المقاعد هيظهر أعلى أي غرفة تلقائياً.

مفيش أي تعديل على أي ملف من ملفات الكفر الأساسي للسكربت. الإضافة
بتستخدم مكتبة Agora ونفس بيانات الاعتماد (App ID / App Secret) المسجلة
بالفعل عندك في **إعدادات المكالمات → تبويب Api** - مفيش أي حساب Agora
جديد أو منفصل مطلوب، ولازم يكون عندك App ID و Secret مسجلين هناك عشان
الإضافة تشتغل (لو مش مسجلين، الأدمن بس هيشوف تنبيه بمكان الشريط
يوضحله إنه يظبطهم).

## إيه اللي بتعمله الإضافة

- شريط أنيق فيه **5 مقاعد صوتية** جنب بعض، ظاهر فعلياً جوه الغرفة
  (مش نافذة منفصلة ولا زرار عائم) أعلى منطقة الشات مباشرة.
- أي عضو رتبته مسموح لها (حسب اختيار الأدمن) يقدر يدوس على مقعد فاضي
  عشان يطلع عليه، وتبان صورته واسمه، وكل اللي في الغرفة يسمعوا صوته
  فوراً (حتى لو هم نفسهم مش قاعدين على مقعد - أي حد في الغرفة بيسمع).
- حلقة خضرا بتنبض حوالين صورة أي حد بيتكلم فعلياً في اللحظة دي (زي
  تطبيقات الصوت الجماعي المعروفة).
- زرار كتم صوت المقاعد (🔇) جنب المقاعد: بيكتم صوت المقاعد كلها بالنسبة
  للي داس عليه بس، من غير ما يأثر على أي حد تاني.
- **العضو القاعد على مقعده**: يدوس على مقعده تاني يظهرله خيار "النزول من المقعد".
- الدوس على مقعد حد تاني (مش انت) بيفتحلك بروفايله.
- **صلاحية إدارة المقاعد**: من إعدادات الإضافة، تقدر تحدد رتب منفصلة
  ("الرتب المسموح لها تدير المقاعد") تظهرلها أيقونة ⚙ صغيرة على كل
  مقعد. الضغط عليها بيفتح قائمة حسب حالة المقعد:
  - مقعد فيه حد: "إنزال من المايك" (يفضل المقعد فاضي وسايب للكل)
    أو "قفل المقعد" (ينزّل اللي عليه ويقفله بالكامل).
  - مقعد فاضي: "قفل المقعد" (يمنع أي حد من القعاد عليه).
  - مقعد مقفول: "فتح المقعد" (يرجّعه متاح تاني).
- **تشغيل موسيقى**: من إعدادات الإضافة، حدد رتب منفصلة تالتة ("الرتب
  المسموح لها تشغّل موسيقى"). أي عضو من الرتب دي، وهو قاعد على مقعد،
  يقدر يدوس على مقعده ويختار "تشغيل موسيقى" من القائمة، يختار أغنية
  من جهازه، والكل في الغرفة (حتى اللي مش قاعدين على مقاعد) يسمعوها.
  - بيظهر شريط "🎵 [الاسم] — [اسم الأغنية]" أعلى المقاعد لكل الغرفة.
  - علامة 🎵 صغيرة بتظهر على مقعد أي حد بيشغّل موسيقى.
  - العضو المشغّل بيظهرله شريط تحكم عائم: تقديم/تأخير 10 ثواني،
    إيقاف/استكمال مؤقت، تحكم في مستوى الصوت، وزرار إلغاء نهائي.
  - زرار كتم منفصل تمامًا "🎵 كتم صوت الموسيقى" (بجانب زرار كتم صوت
    المايكات) لأي مستمع مش عايز يسمع الموسيقى تحديداً، من غير ما يأثر
    على صوت المايكات.
  - صوت الموسيقى مبعوت بهوية Agora منفصلة عن هوية المايك بتاع نفس
    العضو، عشان يبقى ممكن التحكم في الاتنين لوحدهم من غير أي تعارض.
- تبديل الغرفة (من غير ما الصفحة تتحدث) بيسيب قناة الصوت القديمة
  وينضم لقناة الغرفة الجديدة تلقائياً.
- حماية من "المقاعد الشبح": لو حد قفل التاب فجأة من غير ما ينزل من
  مقعده، مقعده بيتفرغ تلقائياً بعد حوالي 40 ثانية.

## لو عايز تلغي التركيب

لوحة تحكم الأدمن → **الإضافات** → **إلغاء تركيب (Uninstall)** على
"voice_seats". ده بيمسح جداول الإضافة بس
(`boom_voice_seats`, `boom_voice_seats_settings`)، ومبيلمسش أي جدول تاني
ولا أي حاجة من نظام المكالمات الأساسي بالسكربت.


## مهم: LiveKit Self-Hosted
هذه النسخة لا تعتمد على api.ex-proj.com ولا على LiveKit Cloud.
بعد تركيب الإضافة:
1. شغّل LiveKit من مجلد `livekit_server`.
2. انسخ API Key وAPI Secret اللذين أنشأتهما الإضافة إلى `livekit.yaml`.
3. اضبط DNS + HTTPS/WSS، ثم ضع `wss://اسم-الدومين` في إعدادات الإضافة.
4. افتح منافذ WebRTC المذكورة في `livekit_server/README_AR.txt`.

المكتبة الأمامية LiveKit تُحمّل من jsDelivr. هذا ليس خادمًا صوتيًا خارجيًا؛ الصوت نفسه يمر عبر LiveKit الموجود على VPS الخاص بك.
