مرجع الـ storyboard

صيغة storyboard.json: segments وholds وzooms وcaptions وhighlights وnarration وcards وoverlays وmusic وextends وtheme وحجم الخرج، مع مثال كامل.

الـ storyboard ملف JSON يصف المونتاج. يكتبه لك تطبيق الذكاء الاصطناعي، لكن يمكنك قراءته وتعديله وتصييره بنفسك. الأمر screenpilot schema (أو الأداة storyboard_schema) يطبع JSON Schema المعتمد. وتشرح هذه الصفحة كل حقل.

القواعد الثلاث#

• الأزمنة بثواني المصدر. تُحسب من بداية التسجيل الخام، لا من الفيديو المصيَّر. القص وتغيير السرعة لا يحرّكانها. الأمر screenpilot check والأداة check_output وحدهما يستخدمان ثواني الخرج.
• المواضع مُطبَّعة بين 0 و1. تُقاس x من الحافة اليسرى للتسجيل وy من حافته العليا. اقرأها من لقطة باستخدام frames --grid.
• المسارات نسبية إلى ملف الـ storyboard. ينطبق هذا على source وevents وextends وmusic.src وoverlays[].src.

كل الحقول اختيارية عدا source. نفّذ screenpilot validate storyboard.json بعد كل تعديل. يعرض أخطاء الـ schema والتحذيرات: segments متداخلة، أو عناصر بعد نهاية المصدر، أو views تذكر شاشة غير معروفة، أو callout بلا x وy. ويقدّم أيضًا نصائح أسلوب: انظر تحذيرات الأسلوب.

حقول المستوى الأعلى#

Segments#

الحقل segments يسرد الأجزاء المحتفَظ بها من المصدر بالترتيب. كل ما بين segment وأخرى يُقصّ. القائمة الفارغة تُبقي الفيديو كله. ويجب ألا تتداخل الـ segments.

إذا وقع سطر تعليق صوتي داخل منطقة مقصوصة، يُحذف مع تحذير. وvolume وmute لهما أثر فقط عندما يبقى صوت المصدر: بدون keepSourceAudio: true وتسجيل فيه صوت، ينبّهك التصيير إلى أنهما بلا أثر.

Holds#

الـ holds تجمّد الفيديو عند إطار واحد، لتعطي caption أو سطرًا صوتيًا وقتًا كافيًا.

نادرًا ما تحتاج إلى كتابة holds. إذا كان سطر التعليق أطول من مكانه، يضيف التصيير تجميدًا تلقائيًا كي لا تتداخل الأسطر. وتظهر هذه في النتيجة باسم autoHolds.

Zooms#

Captions#

أنماط الـ caption#

• pill: مربع يشبه الترجمة. استخدمه لمعظم الـ captions.
• title: نص كبير للحظة تشبه بداية فصل.
• callout: فقاعة تشير إلى x وy. أعطِ القيمتين دائمًا. بدونهما تشير الفقاعة إلى المنتصف ويحذّرك validate.

Highlights#

الـ highlight يرسم مربعًا حول جزء من الشاشة.

Narration#

يقرأ كل سطر صوتُ الـ storyboard ويُمزج في الفيديو. الافتراضي صوت Edge؛ انظر الأصوات للنماذج المحلية ولبرامجك الخاصة. التعليق الصوتي لا يتداخل أبدًا: إذا تجاوز سطر مكانه، يتجمد الفيديو ليفسح له.

اعرض الأصوات بالأمر screenpilot voices --lang ar-EG. أمثلة: ar-EG-SalmaNeural وar-EG-ShakirNeural وen-US-AndrewNeural وen-US-AriaNeural.

Intro وoutro#

الحقلان intro وoutro بطاقتا عنوان قبل الفيديو وبعده. لهما الحقول نفسها.

بطاقات الفصول#

الحقل cards بطاقات عنوان في منتصف الفيديو، لبداية فصل جديد. كل بطاقة تجمّد الصورة عند at وتعرض بطاقة كاملة بظهور واختفاء تدريجيين، ثم يكمل الفيديو من الإطار نفسه.

البطاقة التي يقع at الخاص بها في منطقة مقصوصة تُحذف، ويحذّرك validate. وتستخدم البطاقات المظهر نفسه الخاص بـ intro وoutro (theme.motion.cards وـ CSS الخاص بـ .card).

Overlays#

الحقل overlays يضع صورة أو فيديو فوق إطار الخرج: شعارًا، أو علامة مائية، أو مقطعًا صغيرًا داخل الصورة. وعلى خلاف zooms وhighlights، الموضع هنا كسر من إطار الخرج لا من التسجيل، فيبقى الشعار في الزاوية نفسها مهما تحركت الكاميرا.

"overlays": [
  { "src": "assets/logo.png", "x": 0.88, "y": 0.04, "w": 0.08, "h": 0.08, "opacity": 0.8 },
  { "src": "assets/webcam.mp4", "at": 5, "dur": 12, "x": 0.72, "y": 0.66, "w": 0.24, "h": 0.28, "fit": "cover", "radius": 16, "shadow": true }
]

Music#

الـ ducking يجعل الموسيقى أهدأ تحت كل سطر تعليق ثم يعيدها بعده. أعطِ duck أيًّا من الحقول التالية، أو كائنًا فارغًا {} للقيم الافتراضية:

مشاركة المظهر بـ extends#

الحقل extends يشير إلى storyboard أساسي، نسبيًا إلى هذا الملف. استخدمه حين تريد أن تتشابه عدة فيديوهات في المظهر والصوت: يمتد كل منها من الأساس نفسه ويضيف تسجيله الخاص. وبه يأخذ مقطع الميزة مظهر العرض الذي ينضم إليه داخل sequence.

• تُورَّث خمسة حقول: theme وvoice وoutput وmusic وkeepSourceAudio. أما الباقي (source وsegments وzooms وcaptions وnarration وintro وoutro وغيرها) فلا يُورَّث أبدًا.
• الابن يتغلب. الكائنات تُدمج مفتاحًا مفتاحًا، فالابن الذي يضبط theme.accent فقط يحتفظ بباقي حقول القالب من الأساس. أما المصفوفات فتُستبدل ولا تُدمج، مثل theme.fonts.
• السلاسل تعمل. يمكن للأساس أن يمتد من storyboard آخر. والدورة (cycle) خطأ يذكر السلسلة.
• المسارات تبقى صحيحة. يُعاد كتابة music.src القادم من الأساس ليشير إلى الملف نفسه انطلاقًا من مجلد الابن.

{
  "extends": "../demo.json",
  "source": "rec.mp4",
  "narration": [{ "at": 1, "text": "Invoices can now repeat on a schedule." }]
}

الشاشات والزوايا#

في تسجيل لعدة شاشات، يحدد screens موضع كل شاشة داخل التسجيل، ويحدد views الجزء الذي تعرضه الكاميرا ابتداءً من كل زمن. الأمر init --suggest يملأ الاثنين لك.

الخرج والصوت#

الحقل voice الخاص بسطر التعليق يعمل داخل المزوّد نفسه. فمثلًا مع "provider": "local" يمكن لسطر أن يستخدم namaa ولآخر أن يستخدم voicetut:Sarah. الإعداد والحدود والأمثلة في الأصوات.

اختر حجم الخرج بحسب مكان العرض: 1920x1080 ليوتيوب أو README أو الشرائح؛ 1080x1920 لـ Reels وTikTok وShorts؛ 1080x1080 للخلاصات.

القالب (theme)#

يحدد القالب مظهر الفيديو كله. لا يوجد نمط ثابت: اختره بحسب الجمهور، وخذ الألوان والخطوط من المنتج الذي تعرضه.

CSS مخصص#

العناصر التي يمكنك تنسيقها بـ theme.css:

• #root: الإطار كله وخلفيته.
• #frame: الصندوق الذي يحمل التسجيل.
• .card و.card-inner و.card h1 و.card p: بطاقتا intro وoutro.
• .text: الـ captions. أنواعها .text.pill و.text.subtitle و.text.title. المربع المرئي هو .text.<style> > span، و.text .ln سطر واحد من caption متعدد الأسطر.
• .pos-bottom و.pos-top و.pos-center: مواضع الـ caption.
• .hl و.hl span: الـ highlights.
• .callout span: فقاعات callout.
• .ripple: تموّجات النقر.

الحركة (motion)#

تتحكم الحركة في كيفية دخول النص وخروجه. اضبط الافتراضي في theme.motion.captions وtheme.motion.cards، وتجاوزه بـ motion على caption واحد. كل الحقول اختيارية.

الأنماط: none وfade وrise وdrop وslide-left وslide-right وpop وzoom وblur وwipe وwords وlines. النمط wipe يكشف النص باتجاه القراءة. وwords يُظهر كلمة كلمة، وlines سطرًا سطرًا؛ وكلاهما يعمل مع أي كتابة، ومنها العربية.

مثال كامل#

يحتفظ هذا الـ storyboard بتسجيل واحد، ويسرّع مقطع تحميل، ويقرّب على نقرتين، ويضيف ثلاثة captions وhighlight، وينطق ثلاثة أسطر (الأخير بالعربية). المسارات نسبية إلى ملف الـ storyboard. ينجح في screenpilot validate؛ والتحذير الذي يظهر عند غياب الملفات هو فقط أن فيديو المصدر غير موجود.

{
  "version": 1,
  "source": "sessions/2026-10-27_14-02/video.mkv",
  "events": "sessions/2026-10-27_14-02/events.jsonl",
  "output": { "width": 1920, "height": 1080, "fps": 30 },
  "voice": { "name": "en-US-AndrewNeural", "rate": "+0%", "subtitles": false, "gap": 0.3 },
  "theme": {
    "background": "linear-gradient(135deg, #0f172a 0%, #1d4ed8 100%)",
    "padding": 0.05,
    "radius": 16,
    "accent": "#facc15",
    "font": "'Space Grotesk', 'Cairo', sans-serif",
    "fonts": ["Space Grotesk:wght@500;700"],
    "css": ".text.pill > span { letter-spacing: 0.01em; }",
    "motion": {
      "captions": { "in": "rise", "out": "fade", "duration": 0.35, "ease": "power3.out" },
      "cards": { "in": "words", "stagger": 0.08 }
    }
  },
  "intro": { "title": "Acme Invoices", "subtitle": "Send an invoice in 20 seconds", "dur": 3 },
  "outro": { "title": "Try it today", "subtitle": "acme.example", "dur": 3 },
  "segments": [
    { "in": 0, "out": 6, "speed": 1 },
    { "in": 6, "out": 19, "speed": 6 },
    { "in": 19, "out": 41, "speed": 1 }
  ],
  "holds": [{ "at": 30.5, "dur": 1.5 }],
  "zooms": [
    { "at": 2.5, "dur": 3, "x": 0.18, "y": 0.22, "scale": 2 },
    { "at": 24, "dur": 4, "x": 0.82, "y": 0.9, "scale": 1.8 }
  ],
  "captions": [
    { "at": 1, "dur": 3, "text": "Start from the dashboard", "position": "bottom", "style": "pill" },
    { "at": 22, "dur": 3, "text": "One click to send", "style": "callout", "x": 0.82, "y": 0.9 },
    { "at": 36, "dur": 3, "text": "Done", "position": "center", "style": "title", "motion": { "in": "pop", "ease": "back.out(1.7)" } }
  ],
  "highlights": [{ "at": 31, "dur": 2.5, "x": 0.3, "y": 0.4, "w": 0.3, "h": 0.12, "label": "Total" }],
  "narration": [
    { "at": 1, "text": "We start on the dashboard." },
    { "at": 22, "text": "One click and the invoice is sent." },
    { "at": 36, "text": "هذا كل شيء.", "voice": "ar-EG-SalmaNeural", "caption": true }
  ],
  "music": { "src": "assets/bgm.mp3", "volume": 0.12 }
}

تحذيرات الأسلوب#

الأمر validate (والأداة storyboard_validate) يحذّر أيضًا حين يخالف الـ storyboard إرشادات الأسلوب أدناه. هذه تحذيرات فقط: لا تمنع التصيير أبدًا. وتذكر كل رسالة العنصر، مثل captions[2].

إرشادات الأسلوب#

• التعليق الصوتي: جملة واحدة، أقل من 12 كلمة تقريبًا، وفكرة واحدة. قل ما يراه المشاهد أو لماذا يهم، لا أي زر يُضغط. اجعل الأسطر قصيرة: السطر الطويل يجمّد الفيديو.
• الـ zooms: قرّب على ما سيُنقر عليه. ابدأ التقريب قبل النقرة بنحو نصف ثانية، وأبقِه من 2 إلى 4 ثوانٍ، واستخدم scale بين 1.6 و2.2. خذ x وy من لقطة --grid. ارجع إلى المشهد الكامل بين التقريبات، ولا تقرّب عندما تهم الشاشة كلها.
• الـ captions: من 2 إلى 6 كلمات، وفكرة واحدة لكل caption. استخدم callout فقط للإشارة إلى عنصر صغير واحد، وtitle للحظات الشبيهة ببدايات الفصول، وpill لما عدا ذلك. لا تكرر في caption ما يقوله التعليق.
• وقت الخمول: اقصصه أو سرّعه من 4 إلى 8 مرات. التحميل والانتظار والأخطاء لا مكان لها بالسرعة العادية.
• الإيقاع: ابدأ سطر التعليق مع الحدث الذي يصفه، واترك نحو 0.3 ثانية بين الأسطر. استهدف من 30 إلى 90 ثانية في المجموع.
• لا تكدّس المؤثرات: zoom وhighlight وcallout على نقرة واحدة كثير. اختر ما يشير أفضل.
• الـ captions بلغتين: استخدم caption واحدًا بسطرين ("English\nعربي"). تجنّب حرف الواو وحده بين كلمات لاتينية؛ استخدم فاصلة عربية بدلًا منه.