Quran Resolve Kitمشروع من 1LineArt
English

دليل التثبيت والاستخدام

Quran Resolve Kit، مشروع من 1LineArt

ثلاث خطوات: ثبّت مرة واحدة، وأعطِ الحقيبة تلاوة، ثم اعتمد النتيجة. تجد الحقيبة الآيات وتجلب الترجمة وتثبّت الخط القرآني وتنسّق النصوص لمقاسات 16:9 و9:16 و1:1. ليس عليك إلا المراجعة والاعتماد.

ابدأ التثبيتتنزيل الحقيبة (ZIP)
المخرجات
16:9 و9:16 و1:1، طبقات ProRes 4444 وملفات MP4
النص العربي
الرسم العثماني من Tanzil دون إعادة كتابته
الخط
Amiri Quran
جُرّبت على
Linux مع Python 3.13
خط عربي ذهبي يقرأ «القرآن الكريم» داخل إطار دائري مزخرف
القرآن الكريمTanzil Uthmani16:9 · 9:16 · 1:1

آلية العمل

ثلاث خطوات، ولا تقرر إلا في النهاية. يأتي النص العربي من ملف موثّق واحد ولا يُحرَّر بيدٍ أبدًا.

  1. ١. التثبيت (مرة واحدة)

    يثبّت setup حزم بايثون وChromium وFFmpeg وخط Amiri Quran ثم يفحصها. لا شيء آخر يُثبَّت يدويًّا.

  2. ٢. الإنتاج make

    أعطِ make تلاوتك. يصغي إليها ويطابق كلماتها مع نص Tanzil كاملًا ليعرف السورة وأول آية وآخر آية، وهل تبدأ بالاستعاذة والبسملة. ثم يجلب الترجمة، ويقسّم الآيات الطويلة إلى شاشات بقاعدة واحدة في كل المقاسات، ويقدّر زمن كل آية، ويبني الخلفيات والطبقات، ويفحص كل شيء، ويصنع فيديوهات مسودة صغيرة.

  3. مراجعتك

    افتح build/review.html: شاهد المسودات الثلاث، وقارن النص العربي بمصحف مطبوع، وصحّح الأزمنة أو النص عند الحاجة.

  4. ٣. الاعتماد approve

    يعيد approve ما غيّرتَه فقط، ويصدّر ملفات MP4 النهائية لـ 16:9 و9:16 و1:1، ويتحقق منها، ويكتب الخطوط الزمنية لـ Resolve.

  5. التجميع في Resolve (اختياري)

    استورد الخطوط الزمنية بالأمر File › Import › Timeline وأضف شعارك، وصدّر من Resolve إن شئت. ويستطيع Resolve Studio بناء المشروع برمجيًّا.

نماذج من المخرجات

نموذج إطار بنسبة 16:9: سطر عربي مع تمييز الكلمات وتحته سطر إنجليزي، فوق خلفية هندسية خضراء داكنة

إطارات من تجربة اختبارية بتوقيتات وترجمة تجريبية. تعتمد مخرجاتك على نصك وصوتك وقالبك.

المتطلبات

كل ما هنا مجاني عدا DaVinci Resolve Studio، ولا تحتاج إليه إلا لبناء المشروع برمجيًّا. يثبّت setup الباقي عنك؛ تحتاج فقط إلى بايثون.

Python 3.9 أو أحدث

جُرّبت الحقيبة على Python 3.13. يثبّت setup الحزم المذكورة في requirements.txt (Playwright وPillow وfaster-whisper وstatic-ffmpeg) في .venv خاص.

Chromium وFFmpeg والخط

يثبّتها setup: يشكّل Chromium الحروف العربية، ويرمّز FFmpeg الفيديو (تُجلب نسخة جاهزة إن لم تكن لديك)، ويُنزَّل خط Amiri Quran ويُفحص ويُثبَّت إن كان ناقصًا.

الإنترنت في المرة الأولى

للحزم ولنموذج التعرّف على الكلام (مئات الميغابايتات، عند أول make فقط) ولنص Tanzil وللترجمة. بعد ذلك يمكن إعادة بناء المشروع دون اتصال.

DaVinci Resolve

تصلح أي نسخة لاستيراد الخطوط الزمنية. تحتاج طبقات ProRes إلى Resolve 19.1.4 أو أحدث في Windows وLinux. البناء التلقائي يحتاج Studio.

تلاوتك

ملف MP3 أو WAV أو M4A. لا شيء غيره: تُوجد الآيات والنص والترجمة والأزمنة عنك.

بُنيت الحقيبة وجُرّبت على Linux. لم تُجرَّب على Windows وmacOS. وخطوتان لم يمكن تجربتهما هنا أيضًا: التعرّف على الكلام في تسجيل حقيقي، وتنزيل نص Tanzil. وكلتاهما تبلّغ بوضوح إن فشلت.

التثبيت (الخطوة ١)

فك ضغط الحقيبة وشغّل setup. ينشئ بيئة بايثون خاصة ويثبّت الحزم وChromium، ويجلب FFmpeg والخط القرآني إن كانا مفقودين، ثم يفحص كل شيء.

  1. فك ضغط الحقيبة

    انقر بزر الفأرة الأيمن على quran-resolve-kit.zip واختر Extract All، ثم افتح الطرفية داخل المجلد الجديد.

    cd quran-resolve-kit

  2. شغّل setup

    أمر واحد. ينشئ مجلد .venv داخل الحقيبة ويثبّت فيه كل شيء، ويجلب FFmpeg والخط، ثم يجري الفحوص. لا شيء يحتاج إلى تفعيل: تستخدمه الأوامر اللاحقة تلقائيًّا.

    py quran_kit.py setup
استخدم python3 في macOS وLinux وpy في Windows في كل أمر بهذا الدليل (يكتب الدليل python). يُظهر python quran_kit.py doctor ما هو جاهز، ويعيد doctor --fix جلب FFmpeg والخط.

مشروع يدوي (اختياري)

لا تحتاج إلى هذا القسم إن استخدمت make، فهو ينشئ مجلد المشروع ويجلب النص والترجمة ويجد الآيات بنفسه. اقرأه حين تريد تحرير project.json أو تقديم أزمنتك أو العمل دون التعرّف على الكلام.

  1. أنشئ مجلد المشروع

    شغّل init من داخل مجلد الحقيبة. ينشئ project.json وtimings.csv وdata/ وmedia/. اضبط السورة ونطاق الآيات على تلاوتك. ضع المسار بين علامتي اقتباس دائمًا.

    python quran_kit.py init "../my-surah" --surah 112 --from 1 --to 4 --fps 25

  2. نزّل نص القرآن من Tanzil

    في الصفحة tanzil.net/download اختر نوع القرآن Uthmani والإخراج Text (with aya numbers)، وأبقِ علامات الوقف وعلامات السجدة، واحفظ الملف باسم data/quran-uthmani.txt. اقرأ شروط Tanzil: يجب أن يبقى النص دون تعديل، وأن يُنسب إلى مصدره.

  3. أضف الترجمات (اختياري)

    تستخدم الترجمات من tanzil.net/trans التنسيق surah|ayah|text، وكذلك ملف النص العادي من The Clear Quran (انظر «مصادر قرآنية»). احفظ كل ترجمة في data/ وأدرجها ضمن translations في project.json.

  4. أضف التلاوة

    ضع ملف MP3 أو WAV في media/. والأفضل ملف WAV للمونتاج.

  5. اكتب أو قدّر التوقيتات

    افتح timings.csv واستعن بالمثال أدناه. الآية 0 هي البسملة، وتُستخدم فقط إذا تضمنتها التلاوة ولم تكن السورة الفاتحة أو التوبة. أضف صفوفًا برقم word (يبدأ من 1) للحصول على توقيت دقيق للكلمات؛ وبدونها تُوزَّع أوقات الكلمات تقريبيًا ويُنبَّه إلى ذلك. أو تخطَّ ذلك: يقدّر run --also align --apply-align أزمنة الآيات من تسجيلك (استخدم ayah -1 للاستعاذة إن بدأت بها التلاوة، واضبط istiadha على true). راجع النتيجة وصحّحها قبل النشر.

  6. راجع project.json

    افتحه في محرر شيفرة وتأكد من أسماء الملفات ومعدل الإطارات. استخدم معدل إطارات مصدر التلاوة، ولا تخلط بين المعدلات. انظر العمل مع ملفات JSON أدناه.

  7. تحقق من النص

    شغّله مع وضع المسار بين علامتي اقتباس. توقع أن يعرض الأمر السورة وعدد الآيات والبصمة. إن لم يوجد ملف النص حاول الأمر تنزيله، وإلا طبع خطوات التنزيل اليدوي.

    python quran_kit.py text -c "../my-surah/project.json"
شغّل كل الأوامر من داخل مجلد الحقيبة. تُقرأ المسارات بعد -c نسبةً إلى هذا المجلد، والمسار الذي يحتوي مسافات يحتاج علامتي اقتباس.
بنية المجلد
my-surah/
  project.json
  timings.csv
  data/
    quran-uthmani.txt
    eng-ummmuhammad.txt   (translation fetched by make)
  media/
    recitation.wav
  build/                  (created by the kit)
project.json
{
  "name": "Surah_Ikhlas",
  "surah": 112,
  "ayah_start": 1,
  "ayah_end": 4,
  "text_file": "data/quran-uthmani.txt",
  "audio": "media/recitation.wav",
  "timing_input": "timings.csv",
  "fps": 25,
  "formats": ["16x9", "9x16", "1x1"],
  "istiadha": false,
  "highlight": "progressive",
  "ayah_marker": true,
  "translation_mode": "overlay",
  "translations": [
    {"id": "en", "file": "data/eng-ummmuhammad.txt", "label": "Saheeh International", "lang": "en", "dir": "ltr", "enabled": true}
  ],
  "caption_chunks": "auto",
  "align": {"backend": "auto"},
  "audio_enhance": {"enabled": false, "preset": "recitation"},
  "export": {"video_bitrate_mbps": {"16x9": 12, "9x16": 12, "1x1": 10}, "audio_kbps": 192},
  "corrections": "corrections.json",
  "theme": "theme.default.json",
  "out_dir": "build"
}
timings.csv
# ayah -1 = isti'adha, 0 = Basmala. Or let the kit estimate this file: run ... --also align --apply-align
surah,ayah,start,end,word
112,0,0.000,3.000,
112,1,3.400,7.000,
112,2,7.400,10.000,
112,3,10.400,14.000,
112,4,14.400,19.000,

العمل مع ملفات JSON

  • ما هو. ملف JSON نص عادي بترميز UTF-8 وامتداده .json. والملف project.json وملف القالب كلاهما بهذه الصيغة.
  • الفتح والتحرير. اسحب الملف إلى أي محرر شيفرة: Visual Studio Code أو Sublime Text أو Notepad++. وفعّل تلوين صيغة JSON أثناء التحرير.
  • التحقق. قبل تشغيل الحقيبة، افحص تعديلك بأداة JSONLint أو JSON Editor Online أو منسّق محررك المدمج. يكفي نقص فاصلة أو علامة اقتباس ليصبح الملف غير صالح، فتحقق دائمًا.
النص العربي المخزَّن في master_text.json هو النص العربي الوحيد الذي تعرضه الحقيبة. لا تلصق نصًا عربيًا من أداة توقيت أو من صفحة ويب في المشروع أبدًا.

الإنتاج والاعتماد (الخطوتان ٢ و٣)

ينفّذ make كل شيء حتى مراجعتك، ويُتمّ approve العمل. وبقية الأوامر تعيد مرحلة واحدة. تُتخطى المراحل المنتهية التي لم تتغير مدخلاتها؛ أضف --force للإعادة. استبدل NAME باسم مشروعك.

الأمروظيفتهالمخرجات
setupتثبيت لمرة واحدة: .venv خاص والحزم وChromium وFFmpeg وخط Amiri Quran، ثم الفحوص..venv with the packages, Chromium, ffmpeg and the font (once)
make RECITATION [--translation ur --reciter NAME --portrait FILE --fps 24 --formats 9x16]الخطوة ٢. تدخل التلاوة. يثبّت ما ينقص، ويجد الآيات بالإصغاء، وينزّل نص Tanzil والترجمة (الافتراضية Saheeh International؛ وتستطيع --translation ur أو en.clear أو ar.jalalayn وغيرها)، وينسّق النصوص، ويبني الخلفيات والطبقات، ويفحصها، ويكتب المسودات وصفحة المراجعة. --surah N --from A --to B يتجاوز الإصغاء.projects/NAME/: project.json, CREDITS.txt, build/review.html, build/preview/NAME_preview_*.mp4
approve [PROJECT]الخطوة ٣. بعد مراجعتك: يصدّر ملفات MP4 ويتحقق منها ويكتب الخطوط الزمنية لـ Resolve. يلتقط ما غيّرتَه في صفحة المراجعة. --package يضغط المشروع أيضًا.build/final/NAME_*.mp4 and build/NAME_*.fcpxml
translations [LANGUAGE]يعرض الترجمات وكتب التفسير التي يقبلها --translation، مثل translations urdu.the list of translation and tafsir editions
run [--from X --to Y --only X --also align --force]ينفّذ المراحل بالترتيب ويتوقف عند أول إخفاق. يضيف --also align التوقيت التلقائي، ويضيف --also export --also verify ملفات MP4.all stages up to check; finished stages are skipped
statusيعرض المراحل المحدّثة وغير المحدّثة وغير المنفَّذة.which stages are up to date
textيتحقق من ملف Tanzil ويبني النص المرجعي لمدى آياتك، مع SHA-256 لكل آية.build/master_text.json
enhance [--compare --bypass]تحسين صوت اختياري لا يمسّ الأصل. يكتب --compare ملف مقارنة A/B، ويُبقي --bypass الصوت الأصلي.build/NAME_enhanced.wav, NAME_ab_compare.wav
align [--apply]أزمنة الآيات: من أزمنة كلمات مُعرِّف الكلام حين تطابق النص (auto وهو الافتراضي)، وإلا فتقدَّر من الوقفات (energy)؛ ومنها أيضًا asr-json وwhisper. ينسخ --apply النتيجة إلى timings.csv مع نسخة احتياطية. هو تقدير: استمع إلى كل آية.build/timings.auto.csv
reviewيبني صفحة دون اتصال فيها الموجة الصوتية وتعديل زمن كل آية ونصها وموضعها ومحاذاتها وقائمة بكل التصحيحات. صدّر منها timings.csv وcorrections.json.build/review.html (with the draft videos)
timing [--snap]يستورد CSV أو SRT عربيًا ويتحقق منه ويكتب ملفات SRT. ينقل --snap حدود الآيات إلى أقرب صمت.build/timing.json, NAME_arabic.srt, NAME_en.srt, timing_report.txt
background / bgpreviewيولّد حلقة خلفية متكررة بكل نسبة (40 ثانية افتراضيًا). يعرض bgpreview صورًا لكل زخرفة دون ترميز فيديو.build/NAME_bg_16x9.mov, _9x16, _1x1 / preview PNGs
renderيرسم كل حالة نصية في Chromium ويبني الطبقات الشفافة مضبوطة على الإطار لكل نسبة.build/NAME_overlay_16x9.mov, _9x16, _1x1
preview [--full]يصنع مسودات H.264 صغيرة لكل مقاس من أجل المراجعة. --full للحجم الكامل.build/preview/NAME_preview_16x9.mp4, _9x16, _1x1
checkيتحقق من بصمات النص وترتيب الآيات والأزمنة والتباين والخطوط وعدد إطارات الطبقة. يخرج بخطأ إن أخفق شيء.build/check_report.txt
exportيكتب ملف MP4 النهائي لكل نسبة: H.264 وAAC بسرعة 192 كيلوبت، و10–12 ميغابت/ث افتراضيًا، ومعدل الإطارات مثل المشروع.build/final/NAME_16x9.mp4, _9x16, _1x1
verify [--file X --format F]يفحص ملف MP4: الحاوية والترميز والحجم ومعدل الإطارات وعددها وطول الصوت وإزاحته وظهور النص وتباينه، مع صفحة لقطات. يفحص --file فيديو صُدّر من Resolve.build/final/NAME_FORMAT_verify.txt, contact sheet
timelineيكتب خطًّا زمنيًّا FCPXML لكل نسبة لاستيراده عبر File › Import › Timeline في Resolve (يعمل في الإصدار المجاني).build/NAME_16x9.fcpxml, _9x16, _1x1
resolve [--dry-run] [--render]يبني مشروع Resolve بالبرمجة (Studio فقط). يطبع --dry-run الخطة.Resolve project (Studio only)
package [--with-video --drb F]يضغط كل ما يلزم لإعادة فتح المشروع وإعادة تصديره، مع قائمة SHA-256.NAME_project_bundle.zip
audio / rendertest / svgpageأدوات مساعدة: قائمة الصمت، ومعاينة H.264 سريعة، وورقة تشكيل للمقارنة مع Text+، وصفحات المصحف من Quran SVG.helpers: silences, shaping sheet, mushaf pages
جلسة نموذجية
python quran_kit.py setup
python quran_kit.py make recitation.mp3
python quran_kit.py approve
استغرقت تلاوة مدتها دقيقة نحو 14 دقيقة لكل المقاسات الثلاثة على حاسوب بأربع أنوية، ومعظم الوقت في رسم الخلفيات والنصوص. وينزّل أول make نموذج التعرّف على الكلام أيضًا. يمكنك تركه يعمل.

الحصول على توقيتات دقيقة

الأتمتة تقترح أرقامًا، ولا تقدّم كلمات أبدًا. استمع دائمًا إلى بداية كل آية ونهايتها.

المحاذاة المدمجة

يجد align الوقفات ويلائم أطوال الآيات فيعمل دون اتصال. أعطى على الفاتحة أزمنة معقولة، لكنه تقدير مع درجة ثقة لكل آية. أزمنة الكلمات مستنتَجة.

صفحة المراجعة

تعرض review الموجة وكل آية. اسحب الأزمنة أو اكتبها، واستمع إلى كل آية، وصحّح النص أو الموضع، ثم صدّر الملفات. لا يُطبَّق شيء حتى تحفظ وتعيد التشغيل.

Quran Caption

تطبيق مكتبي مجاني ومفتوح المصدر. يذكر ملف README الخاص به تقسيم التلاوة آية بآية، واكتشاف الصمت والبسملة، وقصّ الترجمة بحسب المقطع. راجع وثائقه لمعرفة تصدير SRT، فلم أتمكن من تأكيده.

AyahFlow

خدمة ويب تعلن اكتشاف الآيات تلقائيًا ومزامنة الكلمات. لم أتمكن من التحقق من دقتها ولا من صيغ التصدير، فقارن نتائجها بسمعك على سورة واحدة أولًا.

  • يُطابَق ملف SRT العربي مع الآيات بمقارنة هياكل الحروف. وتُسرد المطابقات الضعيفة أو المفقودة في التقرير.
  • بدون صفوف word تُوزَّع أوقات الكلمات على الآية بحسب عدد الحروف. وهي تقريبية ويُنبَّه إلى ذلك.
  • تُوقف أخطاء التوقيت خط المعالجة: آيات متداخلة، أو آية تتجاوز نهاية الصوت، أو آية أقصر من إطارين، أو آية ناقصة، أو كلمات غير مرتبة.
  • يطابق asr-json كلمات مُعرِّف الكلام بكلمات Tanzil. اختُبر على نصوص تجريبية فقط، ولم يُشغَّل whisper هنا.
  • استخدم ayah = -1 للاستعاذة و0 للبسملة. نص الاستعاذة ثابت داخل الحقيبة وليس من Tanzil: قارنه بمصحف مطبوع.

مصادر قرآنية

مصادر للحصول على النص والترجمات والبيانات لاستخدامها مع الحقيبة. اقرأ شروط كل موقع قبل استخدام نصه أو صوته أو بياناته.

Tanzil: تنزيل نص القرآن

النص العثماني الموثّق الذي تعتمد عليه الحقيبة في كل ما هو عربي. اختر Uthmani وText (with aya numbers)، وأبقِ النص دون تعديل.

نزّل نص القرآن

QUL: المكتبة القرآنية الشاملة

مركز مفتوح المصدر من Tarteel للمواد القرآنية الرقمية: نصوص بالرسم العثماني والمدني موحّدة، ومخططات للمصحف، وتسجيلات صوتية بتوقيتات زمنية، ومجموعات بيانات في قواعد اللغة القرآنية، متاحة بصيغتي JSON وSQLite.

استخدم نصوصه وتوقيتاته للمقارنة، أو مصدرًا ثانيًا للتوقيتات. تقرأ الحقيبة ملفات CSV وSRT، فحوّل التوقيتات إلى التنسيق المعروض في تجهيز مشروع. افحص صيغة كل ملف أولًا؛ فلم تُجرَّب بيانات QUL مع الحقيبة.

زيارة qul.tarteel.ai

The Clear Quran

ترجمة إنجليزية حديثة معتمدة من العلماء، للدكتور مصطفى خطاب، مع سرد صوتي إنجليزي خاشع للترجمة، ودروس قائمة على التفسير.

ملفات النص العادي بتنسيق surah|ayah|text الذي تقرؤه الحقيبة: احفظ أحدها في data/ وأدرجه في project.json. لا يذكر الموقع ترخيصًا لإعادة استخدام نصه أو صوته، فاحصل على إذن أو راجع شروطه قبل استخدام الترجمة في فيديو.

التنزيلات

زيارة theclearquran.org

Quran JSON

نص القرآن وحروفه اللاتينية (transliteration) وترجماته بصيغة JSON، في حزمة npm.

مفيد للمقارنة أو للترجمات. تقرأ الحقيبة ملفات نصية بتنسيق Tanzil، فحوّل JSON أولًا، وخذ النص العربي نفسه من Tanzil وحده.

عرض على npm
لا يُرفق أي منها مع الحقيبة، ولكلٍّ منها شروطه الخاصة.

التجميع في DaVinci Resolve

استورد الخطوط الزمنية التي تكتبها الحقيبة، أو ابنِ المشروع برمجيًّا مع Resolve Studio.

  1. اسمح بالبرمجة النصية الخارجية

    في Resolve افتح Preferences › System › General واضبط External scripting using على Local. يذكر دعم Blackmagic أن هذه الميزة خاصة بإصدار Studio. أبقِ Resolve قيد التشغيل.

  2. عاين الخطة

    يطبع التشغيل التجريبي ما سيُنشأ ويسرد الملفات الناقصة. إن لم يُعثر على Resolve فاضبط RESOLVE_SCRIPT_API على مجلد البرمجة النصية فيه.

    python quran_kit.py resolve -c ../my-surah/project.json --dry-run
python quran_kit.py resolve -c ../my-surah/project.json
    export RESOLVE_SCRIPT_API="/path/to/Developer/Scripting"

  3. ابنِ المشروع

    تنشئ الحقيبة خطًا زمنيًا لكل نسبة، وتستورد الملفات إلى مجلدات، وتضع المقاطع، وتضيف علامة عند بداية كل آية. إذا كان اسم المشروع موجودًا أُضيفت إليه لاحقة، فلا يُستبدل شيء. أضف --render لوضع مهام التصدير في الطابور.

  4. راجع

    شغّل كل خط زمني بالصوت وقارن كل علامة بالتلاوة.

  5. التصدير

    تحاول الحقيبة أيضًا حفظ ملف مشروع .drb وضبط صوت AAC ومعدل البت لكل مهمة تصيير. إعدادات Deliver هذه غير مؤكدة: إن رفض Resolve أحدها أخبرتك الحقيبة وضبطته أنت في صفحة Deliver.

تخطيط الخط الزمني

المسارالمحتوى
V2الطبقة النصية الشفافة NAME_overlay_16x9.mov
V1حلقة الخلفية NAME_bg_16x9.mov
A1التلاوة NAME_audio_48k.wav
الحالة: اختُبر البناء التلقائي ومفاتيح Deliver وتصدير .drb واستيراد FCPXML على نسخ محاكاة أو ملفات سليمة البنية، لا على Resolve حقيقي. شغّل التجربة أولًا وراقب أول بناء. الطريقة اليدوية تعمل دائمًا.
هل تريد كتابة النص العربي في Text+ بدل ذلك؟ اختبره أولًا: شغّل rendertest والصق نصًا من الورقة في Text+ بخط Amiri Quran، وقارن اتصال الحروف والتشكيل وترتيب الكلمات بالصورة. ويذكر أحد منشورات المنتدى أن النص العربي قد يختفي من مسارات الترجمة عند تفعيل الحد الخارجي (الموضوع). وإذا اختلف أي شيء فاستمر في استخدام الطبقة المولَّدة.

تخصيص المظهر

انسخ config/theme.default.json واحتفظ فيه بما غيّرته فقط، ثم وجّه theme في project.json إلى ملفك. يُدمج فوق الافتراضيات. كل المفاتيح مذكورة في docs/CONFIG.md.

my-theme.json
{
  "arabic": {
    "color": "#FFFFFF",
    "sizes": { "16x9": 110, "9x16": 96, "1x1": 92 }
  },
  "animation": { "style": "elastic", "in_frames": 14, "out_frames": 14 },
  "background": {
    "layers": { "a": { "pattern": "khatam", "rotation": { "enabled": true, "degrees_per_second": 2 } } }
  }
}
الإعدادما يتحكم فيهالقيمة الافتراضية
highlight (project.json)تظليل verse أو word أو progressive.progressive
arabic.sizesحجم الخط العربي بالبكسل لكل نسبة. تصغر الآيات الطويلة تلقائيًا.16x9: 124, 9x16: 108, 1x1: 104
captions.auto_max_lettersعدد الحروف العربية في الشاشة الواحدة عند تقسيم الآيات الطويلة (القاعدة نفسها لكل مقاس). وتُقسَّم الترجمة في الموضع المقابل.16x9: 36, 9x16: 26, 1x1: 30
header.enabledصندوق العنوان: اسم السورة بالعربية ونقله الحرفي ومعناه (واسم القارئ إن أعطيته). enabled: false يزيله.true (title box with the surah name)
arabic.color / highlight_colorلون النص، ولون الكلمة التي تُتلى.#F6EFD9 / #FFD36B
arabic.upcoming_opacityمدى خفوت الكلمات التي لم تُتلَ بعد (من 0 إلى 1).0.6
translation.size_ratioحجم الترجمة كنسبة من حجم العربية.0.38
translation.position / alignموضع الترجمة (below أو above) ومحاذاتها. يمكن لكل ترجمة تجاوزهما وإيقافها بـ enabled.below / center
layout.16x9.margin_xالهامش الجانبي كنسبة من عرض الإطار. الإزاحة الرأسية والمحاذاة تُضبطان لكل نسبة في الكتلة نفسها.0.10
animation.styleنمط الدخول والخروج: elastic أو fade أو rise أو none.elastic
animation.in_frames / out_framesمدة الدخول والخروج بالإطارات.14 / 10
background.layers.a.patternزخرفة الطبقة A: octagram أو khatam أو rosette أو lattice أو interlace. الطبقة B مستقلة.octagram
background.layers.a.opacityمدى ظهور الزخرفة. اللون والمقياس والإزاحة والمحاذاة تُضبط لكل طبقة.0.16
background.layers.a.rotationسرعة الدوران واتجاهه. تقرّب الحقيبة السرعة إلى أقرب قيمة تتكرر بلا فاصل وتخبرك بذلك.off (degrees_per_second, direction)
background.gradientتدرّج لوني اختياري خلف الزخارف، أو مقطعك الخاص عبر background.footage.off (from, to, angle)
background.balance.caption_scrimمنطقة داكنة ناعمة خلف النص تُبقيه مقروءًا فوق الزخرفة. التعتيم وظهور الزخرفة يُضبطان في الكتلة نفسها.on
background.loop_secondsثواني كل حلقة خلفية. يتحرك التمرير عددًا صحيحًا من البلاطات في كل حلقة.40
marker.colorلون علامة نهاية الآية.#C9A24B

صفحات المصحف (اختياري)

يجلب الأمر svgpage صفحات من Quran SVG ويزيل لون خلفية الصفحة الفاتح لتستقر الصفحة فوق خلفيتك. الصفحات مسارات مفرَّغة، فيمكن تغيير ألوانها لكن لا يمكن تنسيقها كنص. راجع شروط استخدام الرسوم قبل أي استعمال تجاري.

الفحص والتصدير

شغّل check ثم راجع هذه القائمة. ضع علامة على البنود أثناء العمل؛ وتبقى علاماتك محفوظة في هذا المتصفح.

0 / 10

التصدير والتحقق

  • شغّل export: يكتب MP4 (H.264 وAAC) بمقاسات 1920 × 1080 و1080 × 1920 و1080 × 1080 بمعدل إطارات المشروع. نطاق شائع للعمل هو 10–16 ميغابت/ث؛ وهو عادة لا قاعدة منصة، فراجع نصيحة منصتك الحالية.
  • شغّل verify. يفحص الحاوية والترميز والحجم وعدد الإطارات وإزاحة الصوت وظهور كل آية، ثم يكتب صفحة لقطات. اقرأ العربية على الصفحة بنفسك.
  • تصدّر من Resolve بدلًا من ذلك؟ استخدم صفحة Deliver بـ H.264 في MP4 وصوت AAC ومعدل إطارات الخط الزمني والمقاسات نفسها، ثم شغّل verify --file FILE.mp4 --format 16x9.
  • شغّل package لحفظ المشروع القابل للتحرير والصوت الأصلي والمعالَج والنص وملفات SRT والطبقات والخلفيات والقالب والخطوط والإعدادات والتقارير معًا.

حل المشكلات

الملف ليس نص الرسم العثماني مع أرقام الآيات، أو أن بعض الأسطر ناقصة. نزّله من Tanzil مرة أخرى بالخيارات الواردة في قسم تجهيز مشروع، وأبقِ الملف دون تعديل.

يسرد الأمر text كل حرف خارج نطاقات الحروف العربية. افحص ملف المصدر. لا تحذف أحرفًا من النص المرجعي؛ بل أصلح المصدر.

اقرأ build/timing_report.txt. الأخطاء هي آيات متداخلة، أو آية تتجاوز نهاية الصوت، أو آية أقصر من إطارين، أو آية ناقصة، أو أوقات كلمات غير مرتبة. أصلح ملف CSV أو SRT ثم شغّل timing من جديد.

أوقات الكلمات مُوزَّعة بحسب عدد الحروف ما لم تقدّم صفوف word. أضف توقيتات حقيقية للكلمات، أو اضبط highlight على verse.

هذه هي الملاءمة التلقائية، ويبلّغ عنها الأمر render. ارفع arabic.sizes إن سمحت الشاشة، أو قلّل الهوامش، أو قسّم الآية عند وقفة طبيعية.

تحتاج ProRes إلى Resolve 19.1.4 أو أحدث على Windows وLinux. وإلا فحوّل الطبقة إلى سلسلة صور PNG بالأمر أدناه واستوردها بوصفها سلسلة صور.

تحتاج النصوص البرمجية الخارجية إلى Resolve Studio، مع ضبط External scripting using على Local وتشغيل Resolve. وفي الإصدار المجاني استخدم الطريقة اليدوية.

تعتمد معالجة العربية في Resolve (وصل الحروف والتشكيل) على إصداره. استخدم الطبقة المولَّدة للنص العربي، واستخدم نص Resolve نفسه للترجمات فقط.

شغّل python quran_kit.py setup من جديد: يعيد تثبيت Chromium في .venv الخاص بالحقيبة ثم يشغّل doctor. وعلى Debian أو Ubuntu شغّل أيضًا أمر install-deps الظاهر تحت «التثبيت».

شغّل python quran_kit.py doctor --fix: يجلب نسخة FFmpeg جاهزة إلى بيئة الحقيبة. وإن تعذّر ذلك (لا إنترنت، أو نظام غير مدعوم) فثبّت FFmpeg بنفسك: brew install ffmpeg في macOS (وHomebrew من brew.sh)، أو winget install Gyan.FFmpeg في Windows (ثم افتح طرفية جديدة)، أو sudo apt install ffmpeg في Linux. واستنساخ شيفرة FFmpeg بـ Git لا يثبّت شيئًا.

أنت تشغّل نسخة قديمة من الحقيبة. نزّل أحدث ملف ZIP وفك ضغطه، ثم شغّل python quran_kit.py --help؛ يجب أن تظهر فيها الأوامر setup وmake وdoctor.

لُصق محتوى ملفات في الطرفية فنُفّذ كل سطر منه كأنه أمر. أنشئ ملفات مثل project.json وtimings.csv في محرر نصوص أو محرر شيفرة، لا في الطرفية أبدًا. اكتب أو الصق فقط الأوامر الواردة في صناديق الشيفرة.

هذا المتغير اختياري ولا يُستخدم إلا مع Resolve Studio. لا تضبطه على المسار الوهمي الوارد في الأمثلة. ألغِ ضبطه بالأمر unset RESOLVE_SCRIPT_API أو وجّهه إلى مجلد Scripting الحقيقي.

المسار الذي يلي -c لا يشير إلى ملف موجود. يُقرأ المسار نسبةً إلى المجلد الذي تشغّل منه الأمر. أسهل حل هو make الذي ينشئ projects/NAME/project.json عنك. وإلا فشغّل init (الخطوة 1 في «تجهيز مشروع»)، ثم مرّر المسار الكامل لملف project.json الجديد، بين علامتي اقتباس إن احتوى اسم أي مجلد مسافات.

قصّر مقاطع الفيديو أو أطلها، ولا تغيّر سرعة الصوت أبدًا. أبقِ الصوت والطبقة على مساريهما، ثم شغّل render من جديد إن تغيرت التوقيتات.

align تقدير من الوقفات وطول الآيات. شغّل review واستمع إلى كل آية وصحّح الأزمنة وصدّر timings.csv ثم شغّل timing وrender من جديد. تُعاد المراحل المعتمدة على التغيير فقط.

تتتبع المراحل الملفات والإعدادات التي تستخدمها. شغّل status لترى المراحل التي أصبحت قديمة، أو أضف --force لإعادة مرحلة.

تُرسم كل طبقة دوّارة في كل إطار. استخدم loop_seconds أقصر، أو تمريرًا بدل الدوران، أو bgpreview لتحكم على الشكل أولًا. تُتخطّى الخلفيات التي لم تتغير في التشغيلات اللاحقة.

تأكد أن معدل إطارات الخط الزمني يساوي fps وأن الحجم يطابق النسبة. شغّل verify --file FILE.mp4 --format 16x9 واقرأ الرسالة: تسمّي الخاصية المختلفة.

تصغي الحقيبة بنموذج كلام وتطابق الكلمات مع القرآن. قد تفشل التسجيلات المشوشة أو القصيرة جدًّا؛ عندها تخبرك وتعرض درجة ثقتها. استخدم نموذجًا أكبر (--model medium) أو أعطِ الآيات بنفسك: make recitation.mp3 --surah 1 --from 1 --to 7. وراجع النطاق دائمًا في صفحة المراجعة.

ينزّل التشغيل الأول نموذج الكلام ونص Tanzil والترجمة. يحتاج إلى الإنترنت ومساحة قرص؛ أعد الأمر نفسه بعد انقطاع الشبكة. وإن تعذّر الوصول إلى Tanzil تطبع الحقيبة خطوة التنزيل اليدوي.

شغّل python quran_kit.py doctor --fix. يفحص أن ملف Amiri Quran يرسم الحروف العربية والعلامات القرآنية، وينزّله ويثبّته من جديد إن لم يفعل. أعد تشغيل Resolve بعد ذلك إن كنت تستخدم الخط في Text+.

بديل سلسلة صور PNG
ffmpeg -i build/NAME_overlay_16x9.mov build/overlay_16x9/%06d.png

هل أنت مستعد لكتابة أول سورة؟

نزّل الحقيبة واتبع خطوات التثبيت وشغّل خط المعالجة على سورة قصيرة أولًا.

تنزيل الحقيبة (ZIP)العودة إلى خطوات التثبيت