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:

python test_system.py

ب) تشغيل الخادم يدوياً / Start Server Manually:

# إيقاف جميع العمليات / Stop all processes
taskkill /f /im python.exe

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

ج) استخدام البدء المتقدم / Use Debug Startup:

python start_debug.py

د) فحص المنافذ / Check Ports:

# 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:

# إنشاء ملف .env / Create .env file
echo GEMINI_API_KEY=your_actual_api_key_here > .env

2. احصل على مفتاح API من:

   • Google AI Studio

3. أضف المفتاح إلى .env:

GEMINI_API_KEY=AIzaSyAS7JtrXjlNjyuo3RG5z6rkwocCwFy1YuA

3. مشاكل الصوت / Audio Issues

UserWarning: PySoundFile failed. Trying audioread instead.

الحلول / Solutions:

أ) تثبيت SoundFile مرة أخرى / Reinstall SoundFile:

pip uninstall soundfile
pip install soundfile

ب) تثبيت FFmpeg (إذا لزم الأمر) / Install FFmpeg if needed:

# 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:

ping google.com

ب) اختبار مفتاح API / Test API Key:

python test_system.py

ج) تغيير النموذج / Change Model:

• إذا فشل gemini-2.5-flash، جرب gemini-1.5-flash

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

أ) الواجهة لا تحمّل / Interface Won't Load:

# تحقق من المنفذ / 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:

# إعادة تشغيل النظام / Restart system
python start_debug.py

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

1. اختبار شامل / Complete Test:

python test_system.py

2. فحص المنافذ / Port Check:

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:

pip list | grep -E "(streamlit|flask|librosa|soundfile|google-generativeai)"

4. فحص العمليات / Process Check:

# Windows
tasklist | findstr python

# Linux/Mac
ps aux | grep python

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

للطلاب الجدد / For New Users:

1. ابدأ بالاختبار الشامل / Start with system test:

   python test_system.py
   

2. استخدم البدء المتقدم / Use debug startup:

   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:

   # اختبار الاتصال / 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 / أوامر الإصلاح السريع

# إعادة تعيين كامل / 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! 🔄