Video Ad Editor

ريل من فيديو كلام — بلا برنامج مونتاج

المونتاج كله كود:

• ffmpeg يقص.
• وِسبر يفرّغ بتوقيت الكلمة.
• محرّك رسم يركّب الكابشن والموشن قرافيكس فوق الفيديو.

المخرَج: MP4 واحد جاهز للنشر.

المسارات: كل scripts/ وreferences/ وmotion/ هني من مجلد هالسكل: ${CLAUDE_SKILL_DIR}

مو فيديو كلام؟ روح للوضع الصح

لو فيه سكل منفصل لهالوضع منصّب (motion-video أو podcast-video أو montage-video)، هو أولى.

⛔ لا تسأله «أي وضع تبي؟» — قل له بجملة شنو فهمت، وكمّل.

المحرّك: دائماً الخفيف (04_render_frames.js)، وبلا ما تذكر كلمة «محرّك».

• يبي يعدّل بنفسه؟ افتح له الاستوديو ← references/studio.md
• شاشة ريموشن بس لو طلبها بالاسم ← references/remotion.md

<!-- davinci -->

🎬 وضع دافنشي: عنده دافنشي ريزولف ستوديو مربوط بالجلسة، وقال «سوّه بدافنشي» أو «أبي أعدّل بنفسي»؟

• نفس العقل: اللهجة، المشاهد، المناطق الآمنة.
• المخرج تايملاين داخل مشروعه: كابشن بفقاعة، رسومات لوتي، زوم قفزة، تمويه حركة، شبكة، مؤثرات صوتية.
• التفاصيل ← references/davinci.md (والسكربتات بـscripts/davinci/).

<!-- /davinci -->

🎞️ وضع كاب كت: قال «سوّه بكاب كت» أو «أبي أعدّل بنفسي بكاب كت»؟ بدل MP4 يطلع مشروع كاب كت قابل للتعديل (لقطات بزوم، كابشن ونصوص كاب كت، فويس، مؤثرات، خلفية صوتية، موشن شفاف) ← references/capcut.md (سكربت واحد scripts/40_capcut.py).

⛔ أسلوبك مع المستخدم

أنت اللي تجهّز، مو هو. ممنوع تعطيه قائمة أوامر ينفّذها.

• لا تسأله «عندك جذيه؟» — افحص بنفسك. ناقص شي؟ «ناقصني أداتين أجهّزهم لك الحين، ياخذ دقيقتين — أبدأ؟»
• بلا مصطلحات: «أداة ترسم الشرائح» لا «puppeteer»، «جودة الفيديو» لا «كوديك».
• قل له وين احنا كل خطوة، وقدّر الوقت: «شلت السكتات — نصف الفيديو راح. الحين أفرّغ كلامك، 3 دقايق.»
• شي واحد بكل مرة.
• لا تسلّم بلا ما تريه لقطة أو ملخص بعد كل مرحلة مهمة.

✅ وين يشتغل؟ بأي مكان — جوال · سحابة · ماك · ويندوز · لينكس · كودكس

الجهاز المحلي (ماك + Claude Code) الأسرع والأقوى، بس مو شرط. ممنوع تقول للمستخدم «هذا ما يصير على جوالك أو بالسحابة». لو أداة ما اشتغلت بالبيئة، انزل للبديل واذكر له بسطر شنو استخدمت. اقرأ references/any-environment.md — سلّم البدائل (تفريغ، قص الشخص، رسم الموشن…) وطريقة الجوال. والوصفات المجرّبة بالتفصيل (قص هادي بلا رجفة، موشن ورق مقصوص، تجميع) بـreferences/phone-cloud-playbook.md.

• على الجوال: يرفق الفيديو بالمحادثة وتشتغل بالبيئة السحابية، والجوال يقدر يقفل.
• ويندوز: python مو python3 ← references/windows.md.

ويندوز: python مو python3، والمسارات C:/… ← references/windows.md

الخطوات 0 و0.5 و1 — الأدوات والذوق والهوية

اقرأ references/start.md ونفّذه — نفس البداية لكل الأوضاع.

الخطوة 2 — خذ منه الفيديو

رابط درايف (الـID بين /d/ و/view):

curl -sL "https://drive.usercontent.google.com/download?id=<ID>&export=download&confirm=t" -o <work>/src.mov

• 4K أفضل (الزوم ينقص من الأصل). بس 1080p يشتغل — لا ترفضه ولا تطلب إعادة تصوير.
• فيديو بالعرض (مقابلة، بودكاست، حلقة تلفزيون)؟ نفس الخطوات. الخطوة 6 تقصّه بالطول حول الوجه لكل لقطة بدل ما تمطّه ← references/landscape.md
• 🪝 ريل من حلقة أو مقابلة = هوك مكتوب إلزامي. بعد 02_captions.py:
  1. python3 scripts/22_hook.py suggest <work>
  2. اكتب 3 هوكات من أقوى سطر (مو أول جملة قالها) ← check ← هو يختار ← apply
  3. preview واقرا hook_sheet.jpg قبل الرسم الكامل.
  • ريل مبني برّا محرّكاتنا (mp4 جاهز)؟ 22_hook.py overlay ← hook.mov شفاف.
  • القواعد والصيغ ← references/podcast-hook.md

تحقق من المدة:

ffprobe -v error -show_entries format=duration -of csv=p=0 <work>/src.mov

🎞️ فريمات ساقطة؟

تسجيل متصفح أو تطبيق كاميرا مو أصلي (الآيفون بالمتصفح يرمي 13-54٪). افحص الفجوات قبل القص:

ffprobe -v error -select_streams v -show_entries frame=pts_time -of csv=p=0 <work>/src.mov | python3 -c "import sys;t=[float(x) for x in sys.stdin if x.strip()];g=[(round(a,2),round(b-a,2)) for a,b in zip(t,t[1:]) if b-a>0.07];print(len(g),'فجوة',g[:8])"

فيه فجوات؟ رمّم قبل الخطوة 3:

ffmpeg -i src.mov -vf "minterpolate=fps=30:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1" -c:a copy src_fixed.mov

وقل له: «التسجيل كان ساقط فيه فريمات — رمّمته». والمرة الجاية ينصحه يصوّر بتطبيق الكاميرا.

🔬 فحص الإضاءة والألوان (ثواني، بصمت)

python3 scripts/25_scopes.py <work>

• «سليمة» ← لا تذكرها.
• فيه مشكلة (غامج، مايل للأصفر، باهت) ← جملة وحدة: «الفيديو غامج شوي ومايل للأصفر — أعدّله؟»
  • وريه قبل وبعد بلقطة وحدة.
  • وافق ← theme.json ← "grade":"auto" (يصحّح المقاس بس).
  • رفض أو سكت ← لا تلمسه (القاعدة 4).

الخطوات 3-11 — الإنتاج

3) خطة القص

python3 scripts/01_cut_plan.py <work>

قل له كم انشال: «شلت 52 ثانية سكوت — الفيديو صار 46 بدل 98.»

3.5) حسّن الصوت (اختياري): فيه صدى أو ضجيج، أو قال «حسّن الصوت»؟ ← references/audio-enhance.md

bash scripts/02b_enhance_audio.sh <work> --local

4) التفريغ بتوقيت الكلمة

ffmpeg -v error -i <work>/src.mov -vn -ac 1 -ar 16000 -y <work>/a.wav
python3 -m whisper <work>/a.wav --language ar --model medium --word_timestamps True \
  --output_format json --output_dir <work> --fp16 False --verbose False > <work>/whisper.log 2>&1

• ياخذ دقايق — شغّله بالخلفية، وقل له كم يتوقع.
• فشل؟ tail -5 <work>/whisper.log

5) التصحيح والكابشن

اقرأ a.json وصحّح كل جملة — وِسبر يغلط بالعامية الخليجية. اكتب <work>/fixes.json:

{ "fix": [["كل","شي","تشوفه"], ["الكابشن","الزوم"]], "hot": ["تشوفه","الزوم"], "fx": {"خلاص":"drop"} }

• hot = كلمات تنحبس بقرص التمييز وقت نطقها.
• fx اختياري ← references/word-fx.md
• ⛔ عدد كلمات كل جملة = عدد كلمات وِسبر لنفس الجملة. وإلا تختل التوقيتات (السكربت يوقفك).

python3 scripts/02_captions.py <work>

5.5) اعرض عليه النص، وشيل اللي ما عجبه ← إلزامي

قبل تصميم أي مشهد:

python3 scripts/10_script_edit.py <work> show

• يطبع كلامه مرقّماً بالتوقيت، ويكتب script.txt.
• ويطبع الجمل المعادة واقتراح الحذف بنفس المرة — لا تشغّل dupes بعده.
• ⛔ اطبع السكربت كامل بالشات وقل: «شنو تبي أشيل؟» — لا تكتفِ بالملف.

الجملة المعادة: الأولى غلط، والثانية التصحيح. «قلت الجملة مرتين — ‹قدرنا نحل السبب› ثم ‹قدرنا نعرف السبب›. أشيل الأولى؟»

python3 scripts/10_script_edit.py <work> drop 6 8       # يشيل الجملتين من الفيديو والصوت
python3 scripts/10_script_edit.py <work> keep 1 2 5 9   # يبقي هذي بس
python3 scripts/10_script_edit.py <work> undo

• كل اللي بعدها ينزاح، وcut.json وcaps.json وsfx.json تتحدّث.
• سوّها هني. الحذف بعد تصميم المشاهد يزيح أوقاتها كلها.
• بعد أي حذف: أعد الخطوة 6، والرسم بـ--force.

6) القص والزوم

python3 scripts/03_cut_zoom.py <work>
mkdir -p <work>/vfr && ffmpeg -v error -i <work>/cutz.mp4 -vf fps=30 -q:v 3 -y <work>/vfr/%05d.jpg

6.1) ⛔ القصّ من فوق الراس — إلزامي بأي فيديو فيه كرت (نص الشاشة، R_DOWN، R_LOWER):

python3 scripts/23_headcrop.py <work> --from <بداية أول كرت>

• يكتب studio.json ← cardTop.
• قصّ ثابت طول الفيديو — بلا تتبع، ولا كاميرا تلحقه.
• يبدأ من فوق أعلى نقطة وصلها راسه، بهامش صغير (1.5٪).
• لا ينقص راسه، ولا يطلع سقف فاضي — «مساحة كبيرة فوق راسه» غلط بنفس الدرجة.
• المستخدم نبّه عليها أكثر من مرة وزعل.
• تحقق بعينك بلقطة يقرّب فيها من الكاميرا.
• تحت جسمه نص محروق؟ قرّب بـtheme.json ← cardZoom (الافتراضي 1).

7) صمّم المشاهد ← أهم خطوة

قبل أي مشهد اقرأ:

1. references/motion-rules.md — الهوية، قائمة الحقائق facts.md، الممنوعات.
2. references/scenes.md — شلون تكتب المشهد، حزمة الموشن، الأفكار، البي-رول.

⛔ قاعدة التخطيط (معتمدة من المستخدم):

• ⛔ الكابشن ما ينكتب على وجه المتحدث أبداً. بأي وضع فيه كرت فيديو، الكابشن كله فوق الكرت، وشريط التقدّم معه.
• اختيار الوضع قرارك من معنى الكلام — الوجه أهم ولا الرسمة؟ (التفاصيل بـscenes.md)

⛔ المنطقة الآمنة (أزرار انستقرام — 08_safe_check.js يفحصها):

المحرّك مضبوط أصلاً: أسفل الكابشن 1460، وشريط التقدّم 1492 بملء الشاشة. وأول كابشن يبان بأول نص ثانية.

عاين قبل ما ترسم كل شي — ورقة وحدة بـ6 لقطات:

node scripts/04_render_frames.js <work> preview 1.2 4.6 12.3 27.6 31.0 48.4
bash scripts/07_contact_sheet.sh <work> <work>/sheet.jpg 1.2 4.6 12.3 27.6 31.0 48.4

• الورقة 3 أعمدة × صفّين بعرض 1080، وعلى كل لقطة توقيتها.
• اقرأ sheet.jpg وحدها — لا الصور فرادى، ولا أوراق كثيرة.
• اعرضها عليه قبل الرسم الكامل.

7.x) إضافات — كل وحدة بمرجعها، لا تفتحه إلا لما تحتاجه

«طبقات» للهوك:

node scripts/11_behind_text.js <work> stack 1
node scripts/04_render_frames.js <work> preview

تشيل جملة منها: drop <رقم>.

عنصر يلحق إيده:

python3 scripts/29_handtrack.py <work> <من> <إلى>

• يطلّع palm.js (مسار الكف منعّم).
• حطه بـcompose.html: <script src="palm.js"></script>، واستخدم palmAt(t) بمشهدك.
• الإحداثيات على الفيديو ملء الشاشة. المشهد كرت (R_DOWN…)؟ حوّلها بنفس مقياس الكرت.

8) المؤثرات الصوتية

{ "outro": 5.2, "whoosh_up": [3.1,11.25], "whoosh_down": [7.85], "thud": [27.27,29.47], "tap": [23.08,24.06] }

python3 scripts/05_sfx.py <work>

9) الرسم النهائي والتجميع

node scripts/04_render_frames.js <work> all
bash scripts/06_encode.sh <work> <work>/ad-final.mp4

• الرسم يكمّل من وين وقف — ما يعيد فريم جاهز.
• عدّلت مشهد بعد الرسم؟ أعد نافذته بس، ثم جمّع: node scripts/04_render_frames.js <work> range 26.4 31.2
• --force مع all يعيد الكل. والسكربت ينبّهك لو بقي فريم ناقص.

10) معايرة الصوت

bash scripts/06b_master.sh <work> <work>/ad-final.mp4 <work>/ad-master.mp4

• يرفع الصوت لـ-14 LUFS (نفس علو الفيد)، ويطبع سطر واحد بالعلو والذروة.
• فيه <work>/bg-audio.mp3؟ ينضاف وينخفض تلقائياً كل ما يتكلم.
• الصورة تنسخ بلا إعادة ترميز.