سطر الأوامر

كل أوامر screenpilot وأهم خياراتها مجمّعة حسب المهمة: التسجيل والتحرير والتصيير ودمج التسجيلات والتحكم بسطح المكتب والإعداد، مع الخطوات كاملة في كتلة واحدة.

سطر الأوامر ينفّذ الخطوات نفسها التي تنفّذها أدوات MCP. شغّله بالاسم screenpilot، أو بالأمر node dist/cli.js من نسخة المصدر. أغلب المستخدمين لا يحتاجونه، لأن تطبيق الذكاء الاصطناعي عندهم يستدعي الأدوات بدلًا منهم. استخدم سطر الأوامر لأتمتة عملية التصيير، أو لفحص جهاز، أو لإصلاح الإعداد.

نفّذ screenpilot --help لعرض قائمة الأوامر، وscreenpilot <command> --help لعرض خيارات أمر واحد. تطبع الأوامر نتيجتها بصيغة JSON على stdout، ورسائل التقدّم على stderr.

سير العمل كاملًا#

هذه الكتلة توصلك من التسجيل إلى الفيديو النهائي. بدّل المسارات والصوت بما يناسبك.

# 1. Record the screen. Press Enter or Ctrl+C to stop.
screenpilot record

# 2. Find idle time and clicks, and get a contact sheet image.
screenpilot analyze sessions/2026-10-27_14-02

# 3. Look closer at moments, with a 0..1 coordinate grid.
screenpilot frames sessions/2026-10-27_14-02/video.mkv --at 1,4.5,10 --grid

# 4. Write a starter storyboard (idle time cut, click zooms filled in).
screenpilot init sessions/2026-10-27_14-02 --suggest --voice ar-EG-SalmaNeural

# 5. Edit storyboard.json, then check it.
screenpilot validate sessions/2026-10-27_14-02/storyboard.json

# 6. Render a fast draft and look at frames of the result.
screenpilot render sessions/2026-10-27_14-02/storyboard.json -q draft
screenpilot check sessions/2026-10-27_14-02/storyboard.mp4 --at 2,8,15

# 7. Render the final video.
screenpilot render sessions/2026-10-27_14-02/storyboard.json -q delivery -o demo.mp4

الأزمنة في الـ storyboard وفي frames --at هي ثوانٍ في المصدر (التسجيل الخام). الأمر check --at وحده يستخدم ثواني الخرج (الفيديو المصيَّر). راجع مرجع الـ storyboard.

التسجيل والمعاينة#

record#

يسجّل الشاشة ويحفظ أحداث المؤشر. اضغط Enter أو Ctrl+C للإيقاف، أو استخدم --duration. يطبع مسار مجلد الجلسة وفيه الفيديو والملفان events.jsonl وwindows.jsonl. التسجيل أصلي افتراضيًا، فلا حاجة إلى OBS.

الخيار	وظيفته
`-d, --dir <dir>`	مجلد الجلسة. الافتراضي: `sessions/<timestamp>`.
`--duration <s>`	يتوقف التسجيل تلقائيًا بعد هذا العدد من الثواني.
`--screen <name>`	الشاشة المسجَّلة، مثل `eDP-1`. الافتراضي: الشاشة التي عليها المؤشر.
`--screens <list>`	تسجيل عدة شاشات جنبًا إلى جنب: `all` أو أسماء مثل `HDMI-A-5,eDP-1`.
`--fit-window <match>`	يضبط النافذة التي يحتوي صنفها أو عنوانها على هذا النص بنسبة 16:9 أثناء التسجيل، ثم يعيدها كما كانت.
`--recorder <how>`	`native` (بدون OBS) أو `obs`. الافتراضي: native عندما يتوفر.
`--input <adapter>`	التقاط المؤشر والنقرات: `auto` (افتراضي) أو `kwin` أو `uiohook` أو `none`.
`--obs-url <url>`, `--obs-password <pw>`	اتصال obs-websocket عند التسجيل عبر OBS. القيم الافتراضية تُقرأ من إعدادات OBS، وإلا `ws://127.0.0.1:4455`.
`--map <pairs>`	ربط مصدر OBS بشاشة، مثل `"PC Screen=eDP-1"`. يُحفظ الربط للمرات القادمة.

remap#

الأمر screenpilot remap <session> --screen <name> يعيد ربط أحداث المؤشر في جلسة بشاشة أخرى. استخدمه عندما ينبّه record إلى أنه خمّن الشاشة التي يسجّلها OBS وكان التخمين خاطئًا. أسماء الشاشات موجودة في meta.json الخاص بالجلسة تحت المفتاح screens.

analyze#

الأمر screenpilot analyze <session-dir|video> يكتشف فترات الخمول والنقرات، ويقترح segments وzooms، ويكتب صورة contact sheet فيها مصغّرات مرقّمة بالزمن. افتح الصورة أولًا لتفهم قصة التسجيل.

الخيار	وظيفته
`--frames <n>`	عدد المصغّرات في الصورة. الافتراضي 12.

frames#

الأمر screenpilot frames <video> يحفظ لقطات من التسجيل الخام لتراه بعينك. الأزمنة بثواني المصدر.

الخيار	وظيفته
`--at <times>`	ثوانٍ مفصولة بفواصل، مثل `1,4.5,10`.
`--every <n>`	بدل `--at`: هذا العدد من اللقطات موزعة بالتساوي. الافتراضي 12.
`--grid`	يرسم شبكة إحداثيات من 0 إلى 1. اقرأ منها مواضع zoom وhighlight وcallout.
`-w, --width <px>`	عرض اللقطة. الافتراضي 1280.
`-o, --out <dir>`	مجلد الإخراج. الافتراضي `frames`.

التحرير#

init#

الأمر screenpilot init <session-dir|video> يكتب ملف storyboard.json مبدئيًا. يحفظه في مجلد الجلسة أو بجوار الفيديو، ويقرأ events.jsonl إن وُجد.

الخيار	وظيفته
`--suggest`	يملأ segments وzooms وزوايا الكاميرا مسبقًا من نتيجة `analyze`.
`--voice <name>`	اسم الصوت الافتراضي: صوت Edge، أو نموذج محلي (`voicetut:Sarah` أو `namaa`)، أو مفتاح صوت `command`. الافتراضي `en-US-AndrewNeural`.
`--provider <id>`	مزوّد الصوت الذي يُكتب في الـ storyboard: `edge` (افتراضي) أو `local` أو `command`. انظر الأصوات.
`--frame <how>`	الكاميرا في الزوايا المقترحة: `window` (افتراضي) أو `screen` أو `all`.
`-o, --out <file>`	مسار ملف الـ storyboard.
`-f, --force`	يستبدل storyboard موجودًا.

validate#

الأمر screenpilot validate <storyboard> يفحص الملف مقابل الـ schema والفيديو المصدر. إما يفشل ويعرض قائمة مشكلات الـ schema، وإما يطبع valid: true مع تحذيرات مثل تداخل segments، أو عناصر بعد نهاية الفيديو، أو callout بلا x وy.

schema#

الأمر screenpilot schema يطبع JSON Schema الخاص بالـ storyboard. هو المرجع النهائي لكل حقل.

voices#

الأمر screenpilot voices يعرض أصوات مزوّد واحد. مع edge (الافتراضي) يحتاج إلى اتصال بالشبكة. ومع local يعرض النماذج المثبّتة وأصواتها. ومع command يعرض الأصوات المعرّفة في voices.json. شرح المزوّدين في الأصوات.

الخيار	وظيفته
`--lang <prefix>`	تصفية ببادئة اللغة، مثل `ar` أو `ar-EG` أو `en-US`.
`--provider <id>`	مزوّد الصوت: `edge` (افتراضي) أو `local` أو `command`.

screenpilot voices --provider local
screenpilot voices --provider edge --lang ar

voice-setup#

الأمر screenpilot voice-setup [voicetut|namaa] يثبّت نموذج صوت محليًا. الافتراضي voicetut. يحتاج إلى uv وهو يجلب Python 3.11 أيضًا. ينشئ بيئة Python، ويثبّت PyTorch وكودًا من أطراف أخرى مثبّتًا على إصدارات مجرَّبة، وينزّل النموذج، وينطق سطر اختبار واحدًا، ويحفظ مسار Python في voices.json. نفّذه في الطرفية: ينزّل عدة غيغابايت، ولا توجد أداة MCP له عمدًا. الأحجام والمجلدات والخطوات في الأصوات.

الخيار	وظيفته
`--dir <path>`	مجلد البيئة والنماذج. الافتراضي: بجوار مجلد التطبيق.
`-y, --yes`	لا يسأل قبل التنزيل.

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

render#

الأمر screenpilot render <storyboard> يولّد الصوت ويقصّ الفيديو ويصيّر ملف MP4. يستغرق دقائق. يطبع مسار الملف والمدة وفترات التجميد التي أضافها (autoHolds) والتحذيرات. إذا كان سطر التعليق الصوتي أطول من مكانه، يجمّد التصيير الفيديو كي لا تتداخل الأسطر.

الخيار	وظيفته
`-o, --output <file>`	ملف الفيديو الناتج. الافتراضي `<storyboard>.mp4`.
`-q, --quality <q>`	`draft` أو `looks` أو `delivery`. الافتراضي `looks`.
`--png-frames`	يستخدم إطارات مصدر بلا فقدان: نص الواجهة المسجَّلة أوضح، والتصيير أبطأ.
`--workers <n>`	عدد المصيّرات المتوازية، وكل واحد منها متصفح Chrome بلا واجهة. الافتراضي 2.
`--from <s>`, `--to <s>`	يصيّر هذه النافذة فقط، بثواني الخرج. انظر التصيير الجزئي.
`--formats <list>`	يصيّر مرة لكل صيغة، مثل `16:9,9:16,1:1`. انظر عدة صيغ.
`--build-dir <dir>`	المجلد الذي يُكتب فيه مشروع HyperFrames. غير مسموح مع `--formats`.

التصيير الجزئي#

لمراجعة مقطع واحد من فيديو طويل، صيّر تلك النافذة فقط بالخيارين --from و--to. كلاهما بثواني الخرج، وهي الثواني نفسها التي يستخدمها check: انظر إلى المسودة، وجد المشكلة عند الثانية 12 إلى 20، أصلحها، ثم صيّر تلك النافذة وحدها من جديد. يمكنك كتابة --from فقط (حتى النهاية) أو --to فقط (من البداية).

screenpilot render storyboard.json -q draft --from 12 --to 20

الملف الناتج هو <storyboard>.part-12-20.mp4 (أو part-12-end إذا لم تكتب --to)، ويُبنى في <storyboard>.part-12-20.build. هو تصيير قصير لتلك النافذة فقط، فهو أسرع كثيرًا من الفيديو كاملًا. العناصر خارج النافذة تُترك، ومستوى الموسيقى، بما فيه الـ ducking، ينتقل إليها.

عدة صيغ#

الخيار --formats يصيّر الـ storyboard نفسه مرة لكل حجم خرج، فيعطيك تعديل واحد نسخة لـ YouTube ونسخة لـ Reels ونسخة للخلاصات. ويُولَّد الصوت مرة واحدة لها كلها.

screenpilot render storyboard.json --formats 16:9,9:16,1:1 -o demo

الصيغة	الحجم	الملف
`16:9`	1920x1080	`<name>.16x9.mp4`
`9:16`	1080x1920	`<name>.9x16.mp4`
`1:1`	1080x1080	`<name>.1x1.mp4`
`WxH`، مثل `1280x720`	كما كُتب	`<name>.1280x720.mp4`

يجب أن يكون العرض والارتفاع زوجيين. والصيغ المكررة تُحذف.
الخيار -o يصبح الاسم الأساسي: -o demo يكتب demo.16x9.mp4 وهكذا. وبدونه يكون الأساس اسم الـ storyboard.
لا يجوز الجمع بين --build-dir و--formats. لكل صيغة مجلدها <name>.<format>.build.
يعمل --from و--to مع --formats معًا: تصبح الملفات <name>.9x16.part-12-20.mp4.

التصدير الطولي أو المربع لتسجيل عرضي يقصّ الصورة. الـ views التي تؤطر نافذة تملأ الإطار، فيُقتطع الضلع الأطول للنافذة. أما views الشاشة فتُظهر الشاشة كاملة. انظر إلى مسودة 9:16 قبل أن تسلّمها.

مستويات الجودة#

المستوى	متى تستخدمه
`draft`	تصيير سريع أثناء التحرير. استخدمه في كل دورة مراجعة.
`looks`	تصيير عادي. هو الافتراضي.
`delivery`	الملف النهائي فقط. هو الأبطأ.

build#

الأمر screenpilot build <storyboard> ينفّذ كل شيء عدا التصيير النهائي: يولّد الصوت ويقصّ الفيديو ويكتب مشروع HyperFrames. يطبع مجلد البناء ومدة الخرج وفترات التجميد التلقائية والتحذيرات. يقبل الخيار --build-dir <dir>.

preview#

الأمر screenpilot preview <storyboard> يبني الـ storyboard ويفتح HyperFrames Studio لتتنقل داخل الفيديو.

check#

الأمر screenpilot check <video> يستخرج لقطات من فيديو مصيَّر لتراجع النتيجة. الأزمنة بثواني الخرج. يطبع المدة، وهل في الفيديو صوت، وملفات اللقطات.

الخيار	وظيفته
`--at <times>`	ثوانٍ مفصولة بفواصل، بزمن الخرج.
`--every <n>`	لقطات موزعة بالتساوي. الافتراضي 8.
`-o, --out <dir>`	مجلد الإخراج. الافتراضي `<video>.check` بجوار الفيديو.

دمج التسجيلات#

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

sequence#

الأمر screenpilot sequence <sequence.json> يصيّر كل جزء ثم يجمعها في ملف MP4 واحد. الأجزاء التي لم تتغير يُعاد استخدامها من التشغيل السابق. يطبع مسار الملف والمدة وطريقة جمع الأجزاء وكل جزء.

الخيار	وظيفته
`-o, --output <file>`	ملف الفيديو الناتج. الافتراضي `<sequence>.mp4`.
`-q, --quality <q>`	`draft` أو `looks` أو `delivery`. الافتراضي `looks`.
`--png-frames`	يستخدم إطارات مصدر بلا فقدان، والتصيير أبطأ.
`--workers <n>`	عدد المصيّرات المتوازية، وكل واحد منها متصفح Chrome بلا واجهة. الافتراضي 2.
`--build-dir <dir>`	المجلد الذي تُبنى فيه الأجزاء. الافتراضي `<sequence>.build`.

sequence-validate#

الأمر screenpilot sequence-validate <sequence.json> يفحص الـ sequence وكل storyboard يستخدمه. إما يفشل ويعرض مشكلات الـ schema (وكل مشكلة تذكر الجزء، مثل parts[1] (feature.json))، وإما يطبع valid: true مع تحذيرات كل جزء.

sequence-schema#

الأمر screenpilot sequence-schema يطبع JSON Schema الخاص بـ sequence.json.

رؤية سطح المكتب والتحكم فيه#

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

screenshot#

الأمر screenpilot screenshot يحفظ صورة لكل شاشة.

الخيار	وظيفته
`--screen <name>`	هذه الشاشة فقط.
`--grid`	يضع شبكة إحداثيات من 0 إلى 1 فوق الصورة.
`-w, --width <px>`	عرض الصورة. الافتراضي 1280.
`-o, --out <dir>`	مجلد الإخراج. الافتراضي `screens`.

windows#

الأمر screenpilot windows يعرض النوافذ المفتوحة ومواضعها. على أنظمة سطح المكتب التي لا تتيح التحكم بالنوافذ (GNOME وغيره من أنظمة Wayland) تكون القائمة فارغة.

browser#

الأمر screenpilot browser يفتح متصفح العرض النظيف أو يعيد استخدامه، ويضعه على شاشة. الخيارات: --screen <name> و--url <url>.

drive#

للأمر screenpilot drive أربعة أوامر فرعية. المواضع بصيغة screen,x,y حيث x وy بين 0 و1، مثل eDP-1,0.5,0.5.

الأمر	وظيفته
`drive move <screen,x,y>`	يحرّك المؤشر.
`drive click <target>`	ينقر. الهدف `screen,x,y` أو `web:<selector>` لعنصر داخل متصفح العرض. الخيارات: `--button left\|right\|middle` (الافتراضي left) و`--count <n>` (2 لنقرة مزدوجة).
`drive type <text>`	يكتب نصًا في الحقل الذي عليه التركيز.
`drive key <combo>`	يضغط تركيبة مفاتيح مثل `"ctrl+l"`. على macOS استخدم `cmd`.

perform#

الأمر screenpilot perform <take.json> ينفّذ take على سطح المكتب الفعلي أثناء التسجيل، ثم يكتب مجلد جلسة فيه الفيديو والأحداث وstoryboard جاهز. إذا فشلت خطوة، يطبع رقم الخطوة ونصها والخطأ. اضغط Ctrl+C لإيقاف التنفيذ.

الخيار	وظيفته
`--dry-run`	ينفّذ الخطوات على سطح المكتب بدون تسجيل. جرّب بهذا الخيار دائمًا قبل التسجيل.
`-d, --dir <dir>`	مجلد الجلسة. الافتراضي `sessions/<timestamp>`.

take-schema#

الأمر screenpilot take-schema يطبع JSON Schema الخاص بملف take.json.

إعداد الجهاز وفحصه#

setup#

الأمر screenpilot setup ينسخ التطبيق إلى مجلده، ويضيف ScreenPilot إلى كل تطبيق ذكاء اصطناعي يجده، ويجهّز متصفح التصيير. أعد تشغيل تطبيق الذكاء الاصطناعي بعد ذلك. تُنسخ ملفات الإعداد احتياطيًا قبل تعديلها.

الخيار	وظيفته
`--list`	يعرض التطبيقات التي يعرفها setup، وهل كل منها مثبّت على هذا الجهاز.
`--clients <ids>`	هذه التطبيقات فقط، بمعرّفاتها، مثل `claude-desktop,claude-code,codex,opencode,cursor`.
`--remove`	يزيل ScreenPilot من هذه التطبيقات بدل إضافته.
`--output <dir>`	مكان حفظ الفيديوهات. الافتراضي `~/Videos/ScreenPilot`.
`--in-place`	يسجّل الحزمة في مكانها بدون نسخها.
`--skip-prepare`	لا ينزّل متصفح التصيير ولا ينفّذ التصيير التجريبي.
`--allow-tools`	لـ Claude Code فقط: يسمح للوكيل باستخدام كل أدوات ScreenPilot بدون سؤال في كل مرة. يضيف قاعدة إلى `~/.claude/settings.json`.
`--print`	يطبع الإعداد فقط لتلصقه بيدك في تطبيق الذكاء الاصطناعي.

doctor#

الأمر screenpilot doctor يفحص هذا الجهاز: ffmpeg وسطح المكتب والشاشات وOBS ومتصفح العرض والأصوات، ومنها فحص "local voice" الذي يُتخطّى إذا لم تُعدّ صوتًا محليًا (فهو اختياري). يطبع تقريرًا بصيغة JSON وسطر ملخص. رمز الخروج دائمًا 0، فاقرأ التقرير. أضف --input لاختبار حقن الإدخال أيضًا، وهو يحرّك المؤشر الفعلي لحظة.

نفّذ screenpilot doctor أولًا على أي جهاز جديد، وأعد تنفيذه كلما فشل التسجيل أو التحكم.