TROUBLESHOOTING.md

# 🛠️ دليل استكشاف الأخطاء - SyncMaster Enhanced
# Troubleshooting Guide - SyncMaster Enhanced

## 🔍 الأخطاء الشائعة وحلولها / Common Errors and Solutions

### 1. خطأ الاتصال بالخادم / Server Connection Error
```
Error: Failed to fetch
POST http://localhost:5001/record net::ERR_CONNECTION_REFUSED
```

**الأسباب المحتملة / Possible Causes:**
- الخادم غير يعمل / Server not running
- منفذ 5001 مستخدم من برنامج آخر / Port 5001 used by another application
- جدار حماية يحجب الاتصال / Firewall blocking connection

**الحلول / Solutions:**

#### أ) تشغيل اختبار النظام / Run System Test:
```bash
python test_system.py
```

#### ب) تشغيل الخادم يدوياً / Start Server Manually:
```bash
# إيقاف جميع العمليات / Stop all processes
taskkill /f /im python.exe

# تشغيل الخادم / Start server
python recorder_server.py
```

#### ج) استخدام البدء المتقدم / Use Debug Startup:
```bash
python start_debug.py
```

#### د) فحص المنافذ / Check Ports:
```bash
# Windows
netstat -an | findstr :5001

# Linux/Mac
lsof -i :5001
```

### 2. مشكلة مفتاح API / API Key Issues
```
ERROR: GEMINI_API_KEY not found in environment variables
```

**الحل / Solution:**
1. تأكد من وجود ملف `.env`:
```bash
# إنشاء ملف .env / Create .env file
echo GEMINI_API_KEY=your_actual_api_key_here > .env
```

2. احصل على مفتاح API من:
   - [Google AI Studio](https://makersuite.google.com/app/apikey)

3. أضف المفتاح إلى `.env`:
```
GEMINI_API_KEY=AIzaSyAS7JtrXjlNjyuo3RG5z6rkwocCwFy1YuA
```

### 3. مشاكل الصوت / Audio Issues
```
UserWarning: PySoundFile failed. Trying audioread instead.
```

**الحلول / Solutions:**

#### أ) تثبيت SoundFile مرة أخرى / Reinstall SoundFile:
```bash
pip uninstall soundfile
pip install soundfile
```

#### ب) تثبيت FFmpeg (إذا لزم الأمر) / Install FFmpeg if needed:
```bash
# Windows (using chocolatey)
choco install ffmpeg

# Or download from: https://ffmpeg.org/download.html
```

#### ج) فحص تنسيق الملف / Check Audio Format:
- استخدم WAV بدلاً من MP3
- تأكد من جودة التسجيل

### 4. مشاكل الترجمة / Translation Issues
```
WARNING: Gemini returned empty translation response
```

**الحلول / Solutions:**

#### أ) فحص اتصال الإنترنت / Check Internet Connection:
```bash
ping google.com
```

#### ب) اختبار مفتاح API / Test API Key:
```python
python test_system.py
```

#### ج) تغيير النموذج / Change Model:
- إذا فشل `gemini-2.5-flash`، جرب `gemini-1.5-flash`

### 5. مشاكل الواجهة / UI Issues

#### أ) الواجهة لا تحمّل / Interface Won't Load:
```bash
# تحقق من المنفذ / Check port
python -c "import socket; s=socket.socket(); s.bind(('',8501)); print('Port 8501 available')"

# تشغيل على منفذ مختلف / Run on different port
streamlit run app.py --server.port 8502
```

#### ب) مشاكل اللغة العربية / Arabic Language Issues:
- تأكد من دعم المتصفح للـ RTL
- استخدم Chrome أو Firefox للأفضل

### 6. مشاكل الأداء / Performance Issues

#### أ) بطء في المعالجة / Slow Processing:
- تحقق من سرعة الإنترنت
- قلل حجم الملف الصوتي
- استخدم جودة أقل للتسجيل

#### ب) استهلاك ذاكرة عالي / High Memory Usage:
```bash
# إعادة تشغيل النظام / Restart system
python start_debug.py
```

## 🔧 أدوات التشخيص / Diagnostic Tools

### 1. اختبار شامل / Complete Test:
```bash
python test_system.py
```

### 2. فحص المنافذ / Port Check:
```python
python -c "
import socket
ports = [5001, 8501, 8502]
for port in ports:
    try:
        s = socket.socket()
        s.bind(('localhost', port))
        s.close()
        print(f'Port {port}: Available ✅')
    except:
        print(f'Port {port}: Busy ❌')
"
```

### 3. فحص التبعيات / Dependencies Check:
```bash
pip list | grep -E "(streamlit|flask|librosa|soundfile|google-generativeai)"
```

### 4. فحص العمليات / Process Check:
```bash
# Windows
tasklist | findstr python

# Linux/Mac
ps aux | grep python
```

## 📱 نصائح لحل المشاكل / Troubleshooting Tips

### للطلاب الجدد / For New Users:
1. **ابدأ بالاختبار الشامل / Start with system test**:
   ```bash
   python test_system.py
   ```

2. **استخدم البدء المتقدم / Use debug startup**:
   ```bash
   python start_debug.py
   ```

3. **تحقق من المتطلبات / Check requirements**:
   - Python 3.8+
   - مفتاح Gemini API صالح
   - اتصال إنترنت مستقر

### للطلاب المتقدمين / For Advanced Users:
1. **مراجعة السجلات / Check logs**:
   - افتح console المتصفح (F12)
   - راجع سجلات الطرفية

2. **تخصيص الإعدادات / Customize settings**:
   - غير المنافذ في حالة التضارب
   - عدّل إعدادات الصوت

3. **التشخيص المتقدم / Advanced diagnostics**:
   ```python
   # اختبار الاتصال / Test connection
   import requests
   response = requests.get('http://localhost:5001/record')
   print(response.status_code, response.text)
   ```

## 🆘 طلب المساعدة / Getting Help

### معلومات مطلوبة / Required Information:
1. نظام التشغيل / Operating System
2. إصدار Python / Python Version
3. نتائج `python test_system.py`
4. رسائل الخطأ الكاملة / Complete error messages
5. سجلات الطرفية / Terminal logs

### خطوات الإبلاغ / Reporting Steps:
1. شغّل الاختبار الشامل
2. احفظ النتائج
3. صوّر رسائل الخطأ
4. اذكر الخطوات التي أدت للمشكلة

---

## 🎯 Quick Fix Commands / أوامر الإصلاح السريع

```bash
# إعادة تعيين كامل / Complete Reset
taskkill /f /im python.exe
python test_system.py
python start_debug.py

# إصلاح التبعيات / Fix Dependencies  
pip install --upgrade -r requirements.txt

# إصلاح المنافذ / Fix Ports
python start_debug.py

# اختبار الترجمة / Test Translation
python -c "from translator import AITranslator; t=AITranslator(); print(t.translate_text('Hello', 'ar'))"
```

---

**تذكر: معظم المشاكل تُحل بإعادة تشغيل النظام وتشغيل الاختبار الشامل! 🔄**

**Remember: Most issues are solved by restarting and running the system test! 🔄**