بسم الله الرحمن الرحيم
بعد النقاش السابق، بدأ فريق mp3quran العمل على نسخة جديدة من mp3quran.net API — v4، وهي متاحة حاليًا على بيئة Staging للاختبار وجمع الملاحظات قبل الإصدار النهائي.
الإصدارات v1 وv2 وv3 مستمرة في العمل دون أي تغيير.
🔗 API: https://api-staging.mp3quran.net/v4
📚 Documentation: https://docs-staging.mp3quran.net
✨ أبرز ما جاء في v4
- معرّفات ثابتة ومعيارية وواضحة للقراء والتلاوات، مثل:
/v4/reciters/mishary-alafasy
- دعم المصطلحات القرآنية المعيارية للقراءات والروايات والطرق والأوجه.
- ملفات صوتية عبر CDN بثلاث صيغ وجودات:
Original / MP3 64kbps / Opus 48kbps
- دعم Byte-Range Requests للتنقل داخل الملفات الصوتية وتحسين التخزين المؤقت.
- توقيتات للآيات والكلمات والحروف، بالإضافة إلى Phoneme Timings بشكل تجريبي.
- إمكانية تنزيل إصدارات التوقيت الكاملة عبر:
/v4/timing-releases
- بحث موحد في القراء والسور والروايات والإذاعات:
/v4/search?q=…
- دعم 21 لغة باستخدام:
?locale=
- Cursor Pagination لجميع القوائم.
- أخطاء JSON موحدة مع HTTP Status Codes صحيحة.
- دعم
ETag وCache-Control لتحسين التخزين المؤقت.
- توفير وصف كامل وفق معيار OpenAPI 3 عبر:
/v4/openapi.json
🧪 جرّبه الآن
يمكنك تجربة الـ API مباشرة باستخدام:
curl https://api-staging.mp3quran.net/v4/reciters/mishary-alafasy
curl "https://api-staging.mp3quran.net/v4/search?q=husary"
curl https://api-staging.mp3quran.net/v4/recitations/majed-anazi/r1/surahs/20/word-timings
⚠️ ملاحظة مهمة حول النسخة التجريبية
هذه نسخة Preview، ولذلك قد تتغير بعض تفاصيل الاستجابات قبل الإصدار النهائي.
نعمل حاليًا على تصغير حجم الاستجابات وتبسيط بعض الحقول، وقد يتغير شكل عدد من الاستجابات خلال فترة الاختبار.
لذلك، إذا كنت ستبني مشروعًا باستخدام v4 في هذه المرحلة، فتوقع وجود تغييرات بسيطة، وراجع التوثيق بشكل مستمر لمعرفة الصيغة الحالية.
نود أيضًا أن نسمع اقتراحاتكم حول شكل الاستجابات وما ترونه مناسبًا أو أكثر فائدة للمطورين.
⏱️ بيانات التوقيتات (Timings)
تم إنشاء بيانات التوقيتات باستخدام مشروع خاص بنا مبني على Zipformer من QuranLab.
وسيتم — بإذن الله — نشر هذا المشروع لاحقًا بشكل مفتوح المصدر، ليستفيد منه المطورون والباحثون ويسهموا في تطويره وتحسينه.
🔎 معاينة جودة التوقيتات
تم إنشاء صفحة لمعاينة جودة التوقيتات باستخدام نسخة سابقة من النموذج:
https://mp3quran-preview.quran.ws/
ملاحظة: بيانات التوقيتات الموجودة حاليًا في الموقع لا تمثل أحدث نموذج قمنا بتحسينه، وإنما وضعت لأغراض الاختبار وجمع الملاحظات فقط.
لذلك نرجو عدم تخزين هذه البيانات أو الاعتماد عليها في مشاريع حقيقية في الوقت الحالي.
🙏 نحتاج ملاحظاتكم
نرحب بتجربة الـ API في مشاريع حقيقية أو نماذج أولية، مثل:
- مشغلات القرآن.
- تطبيقات الحفظ والتسميع.
- أدوات التجويد.
- تظليل الكلمات والآيات أثناء التشغيل.
- تطبيقات التحميل والاستخدام دون اتصال (Offline).
ونرحب بأي ملاحظات حول:
- أي شيء غير واضح في التوثيق.
- Endpoint أو Filter أو Field تحتاجونه.
- أخطاء أو مشاكل في التوقيتات.
- روابط صوتية لا تعمل.
- بيانات قارئ أو رواية غير صحيحة.
- أي Endpoint بطيء أو سلوكه غير متوقع.
- أي اقتراح يمكن أن يجعل الـ API أكثر سهولة وفائدة للمطورين.
عند الإبلاغ عن مشكلة، يرجى إرسال URL الطلب المستخدم مع وصف مختصر للمشكلة.
كل ملاحظة، مهما كانت بسيطة، تساعدنا على تحسين v4 قبل إطلاقه رسميًا. 🚀
📌 تنبيه أخير
جميع الروابط والبيانات المذكورة في هذا المنشور مؤقتة، وقد يتم تغييرها أو حذفها بعد الإطلاق الرسمي.
وبالأخص بيانات التوقيتات الحالية، فهي مخصصة للاختبار وجمع الملاحظات فقط، ولا ينبغي الاعتماد عليها أو تخزينها في هذه المرحلة.
