أشارككم في هذا الموضوع تجربتي في تطوير تطبيق راديو التلاوات، وهو تطبيق ويب يعتمد اعتمادًا كاملًا على الواجهة البرمجية لنظام إدارة المحتوى القرآني من إتقان
Itqan Quranic CMS APIs
لاختبار إمكانية بناء نماذج تطبيقات عملية وقابلة للاستخدام عليها.
يقدّم المشروع تجربة استماع قرآنية متتابعة (Radio / Playlist)، بواجهة عصرية سهلة الاستخدام، ومناسبة لعرض المحتوى القرآني، مع التركيز على البساطة وسلاسة التجربة.
فكرة التطبيق
جاءت فكرة التطبيق بعد اطلاعي على موضوع سابق في المجتمع حول إعلان إطلاق الإصدار التجريبي الثاني من نظام إدارة المحتوى القرآني (Quranic CMS)
والذي استعرض التطويرات الجوهرية للنظام، وأبرزها:
- إتاحة تلاوات قرآنية رسمية عالية الجودة
- توفيرها من خلال المركز السعودي للتلاوات القرآنية
- إتاحتها للمطورين عبر واجهة برمجية منظمة
- ترخيصها برخصة CC BY-NC-ND
من هنا نشأت فكرة بناء تطبيق يجرب الواجهة البرمجية ويختبرها من خلال إتاحة الاستماع إلى هذه التلاوات عبر واجهة أنيقة تشبه تطبيقات البث الحديثة (مثل Spotify)، مع دعم الوضعين الداكن والفاتح، وإمكانية تشغيل سور المصحف كاملة بالترتيب دون تدخل المستخدم.
استدعاءات الواجهة البرمجية
يعتمد التطبيق على Quranic CMS APIs لجلب البيانات الصوتية القرآنية، بما يشمل:
- الروايات
- القرّاء
- التلاوات الكاملة لسور المصحف
الرابط الأساسي (بعد التحديث)
https://api.cms.itqan.dev
ملاحظة:
الرابط القديم
https://api.cms.itqan.dev/developers-api
ما زال مدعومًا حاليًا، لكنه سيتم إيقافه لاحقًا.
تم بناء جميع الاستدعاءات باستخدام مسارات نسبية (Relative Paths)، ومن أهم نقاط الوصول التي استخدمتها:
GET /riwayahs/
GET /reciters/
- جلب التلاوات المرتبطة برواية وقارئ
GET /recitations/?riwayah_id=1&reciter_id=12
- جلب الملفات الصوتية لسور المصحف
GET /recitations/{recitation_id}/
اللغة وبنية البيانات
مع التحديثات الجديدة في الواجهة البرمجية:
- تم توحيد الحقول النصية لتصبح بالشكل:
{
"id": 1,
"name": "حفص عن عاصم"
}
- أسماء السور تُعاد عبر الحقل:
"surah_name": "الفاتحة"
- يتم التحكم بلغة الاستجابة عبر ترويسة HTTP:
Accept-Language: ar | en
- اللغة العربية هي الافتراضية في حال عدم تحديد اللغة
خطوات التنفيذ
تم تنفيذ التطبيق وفق الخطوات التالية:
- جلب قوائم الروايات والقرّاء من الواجهة البرمجية وعرضها للمستخدم.
- عند اختيار الرواية والقارئ، يتم جلب التلاوة المرتبطة بهما (
recitation_id).
- جلب جميع المسارات الصوتية لسور المصحف المرتبطة بهذه التلاوة، مع دعم التصفح عبر الصفحات (Pagination).
- التحقق من توفر رقم السورة ورابط الملف الصوتي لكل مسار.
- ترتيب السور تصاعديًا وبناء قائمة تشغيل (Playlist) كاملة.
- توفير واجهة راديو تفاعلية تتيح التشغيل، الإيقاف المؤقت، والانتقال التلقائي بين السور.
طريقة جلب كامل التلاوات (Pagination)
لاحظت أثناء التنفيذ أن استدعاء المسار:
GET /recitations/{recitation_id}/
يعيد عددًا محدودًا من العناصر في كل صفحة (100 عنصر)، حتى وإن كان العدد الكلي أكبر (114 سورة)، بينما يعكس الحقل count العدد الحقيقي.
لذلك تم التعامل مع الأمر برمجيًا عبر تنفيذ طلبات متتالية باستخدام المعامل page حتى يتم جلب جميع السور:
async function fetchAllTracks(recitationId) {
let page = 1;
let all = [];
let total = Infinity;
while (all.length < total) {
const r = await fetch(
`${API}/recitations/${recitationId}/?page=${page}`,
{
headers: { "Accept-Language": "ar" }
}
);
const d = await r.json();
all.push(...d.results);
total = d.count;
page++;
}
return all;
}
تشغيل التطبيق
التطبيق عبارة عن تطبيق ويب ستاتيكي مفتوح المصدر مبني باستخدام:
- HTML
- CSS (دعم الوضع الداكن والفاتح)
- JavaScript (Vanilla)
يمكن تشغيله من خلال تحميل الكود المصدري من مستودع جبيتهب وفتح ملف index.html مباشرة في المتصفح.
كما يمكن تجربة التطبيق من خلال رابط النسخة المباشرة:
https://engsaleh.github.io/Itqan-cms-tilawah-radio/
عند اختيار الرواية والقارئ، يتم جلب جميع التلاوات الخاصة بهما، ويبدأ التشغيل تلقائيًا من سورة الفاتحة حتى سورة الناس دون انقطاع، لتوفير تجربة استماع متواصلة.
أفكار مستقبلية
من الأفكار التطويرية للمشروع:
- تحويل التطبيق إلى راديو مرئي يعرض نص الآيات متزامنًا مع الصوت
- دعم تعدد الروايات داخل التطبيق
- الاستفادة منتزمين الآيات Ayah-level timestamps عند توفرها في الواجهة البرمجية مستقبلًا
أدعوكم لتجربة التطبيق، ومشاركة أي مقترحات أو تحسينات، أو الإبلاغ عن أي ملاحظات تظهر أثناء الاستخدام.
