How to Record a Terminal GIF

Step-by-step guide to recording terminal sessions as GIF animations using VHS, asciinema, and AgentGIF CLI.

1. المتطلبات المسبقة

لتسجيل تسجيلات طرفية بصيغة GIF، تحتاج إلى:

VHS — a terminal recorder by Charm that converts scripted terminal sessions into GIFs
ttyd — خادم ويب طرفية (تبعية VHS، يُثبَّت تلقائياً على macOS)
ffmpeg — لترميز الفيديو (يُثبَّت تلقائياً على macOS)

يعمل VHS بقراءة ملف .tape الذي يصف ضغطات المفاتيح والأوامر والتوقيت — ثم يعيد تشغيل تلك الإجراءات في طرفية افتراضية ويلتقط المخرجات كتسجيل GIF.

2. تثبيت VHS

المنصة	أمر التثبيت
macOS	`brew install vhs`
Ubuntu/Debian	`sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://repo.charm.sh/apt/gpg.key \| sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg && echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" \| sudo tee /etc/apt/sources.list.d/charm.list && sudo apt update && sudo apt install vhs`
Arch Linux	`yay -S vhs`
Go	`go install github.com/charmbracelet/vhs@latest`

التحقق من التثبيت:

vhs --version

3. إنشاء ملف Tape

ملف tape هو سكريبت نصي عادي يُخبر VHS بما يكتب ومتى ينتظر وما الإعدادات التي يستخدمها. أنشئ ملفاً اسمه demo.tape:

Output demo.gif
Set Shell "bash"
Set FontSize 16
Set Width 1000
Set Height 580
Set Theme "Catppuccin Mocha"

Type "echo 'Hello, world!'"
Enter
Sleep 2s

Type "ls -la"
Enter
Sleep 3s

الأوامر الأساسية

الأمر	الوصف	مثال
`Output`	تعيين مسار ملف المخرجات	`Output "demo.gif"`
`Type`	كتابة نص (محاكاة ضغطات المفاتيح)	`Type "git status"`
`Enter`	الضغط على Enter	`Enter`
`Sleep`	الانتظار لمدة معينة	`Sleep 2s`
`Ctrl+C`	إرسال اختصار لوحة المفاتيح	`Ctrl+C`
`Hide`	إيقاف التسجيل (للإعداد)	`Hide`
`Show`	استئناف التسجيل	`Show`

4. ضبط الإعدادات

ضع أوامر Set في أعلى ملف tape الخاص بك، قبل أي أوامر Type.

الإعدادات الموصى بها لـ AgentGIF

Set Shell "zsh"
Set FontSize 15
Set Width 1000
Set Height 580
Set Padding 20
Set Theme "Catppuccin Mocha"
Set TypingSpeed 50ms
Set CursorBlink false

جميع الإعدادات المتاحة

الإعداد	الافتراضي	الوصف
`Shell`	`"bash"`	الشل المستخدم (bash، zsh، fish، sh)
`FontSize`	`14`	حجم الخط بالبكسل
`Width`	`800`	عرض الطرفية بالبكسل
`Height`	`600`	ارتفاع الطرفية بالبكسل
`Padding`	`0`	الحشو حول الطرفية
`Theme`	`"default"`	Color theme (see theme gallery)
`TypingSpeed`	`50ms`	التأخير بين ضغطات المفاتيح
`Framerate`	`50`	إطارات GIF في الثانية
`PlaybackSpeed`	`1`	مضاعف سرعة التشغيل
`CursorBlink`	`true`	إظهار المؤشر الوامض
`LetterSpacing`	`0`	تباعد إضافي بين الأحرف
`LineHeight`	`1.0`	مضاعف ارتفاع السطر

الثيمات

يأتي VHS مع 44 ثيماً مدمجاً. خيارات شائعة لتوثيق المطورين:

الثيم	الأسلوب
Catppuccin Mocha	داكن دافئ (نبرات باستيل)
Dracula	بنفسجي داكن
Tokyo Night	داكن بصبغة زرقاء
Nord	أزرق قطبي
One Dark	داكن مستوحى من Atom
Solarized Dark	داكن كلاسيكي بنبرات دافئة
Monokai	مستوحى من Sublime Text

تصفح جميع الثيمات مع معاينات مباشرة: معرض الثيمات.

5. تسجيل التسجيل

vhs demo.tape

يفتح VHS متصفحاً بلا رأس، ويعيد تشغيل الـ tape، ويحفظ التسجيل. يستغرق التسجيل النموذجي 10-30 ثانية.

معاينة قبل الرفع:

# macOS
open demo.gif

# Linux
xdg-open demo.gif

6. تحسين حجم الملف

يقبل AgentGIF تسجيلات تصل إلى 10 MB، لكن الملفات الأصغر تُحمَّل بشكل أسرع. نصائح للحفاظ على حجم التسجيل صغيراً:

التقنية	التأثير
تقليل الأبعاد (`Width 800`)	كبير — تنصيف العرض يُربّع حجم الملف
تقليل معدل الإطارات (`Framerate 30`)	متوسط — يُقلل الإطارات بنسبة 40%
تسجيل أقصر	كبير — استهدف 5-15 ثانية
استخدم `PlaybackSpeed 1.5`	متوسط — إجمالي إطارات أقل
تعطيل وميض المؤشر (`CursorBlink false`)	صغير — إطارات فريدة أقل
خلفية صلبة (تجنب الشفافية)	صغير — ضغط GIF أفضل

لأفضل توازن بين الجودة والحجم، تنتج الإعدادات الموصى بها أعلاه تسجيلات حول 100-300 KB لتسجيل مدته 10 ثوانٍ.

7. الرفع إلى AgentGIF

الرفع عبر CLI (الأسرع):

agentgif upload demo.gif \
  --title "Git Interactive Rebase" \
  --command "git rebase -i HEAD~3" \
  --tags git,rebase \
  --open

Or upload via the web interface — drag and drop the GIF file.

إرفاق ملف cast يُفعّل طبقة وكيل الذكاء الاصطناعي:

agentgif upload demo.gif --cast demo.cast --title "My Demo"

8. ميزات Tape المتقدمة

إخفاء/إظهار للإعداد

استخدم Hide/Show لتشغيل أوامر الإعداد دون تسجيلها:

Hide
Type "cd /tmp/demo-project"
Enter
Type "mkdir -p src"
Enter
Show

# Now recording starts
Type "ls -la"
Enter
Sleep 2s

صيغ مخرجات متعددة

يمكن لـ VHS إخراج صيغ متعددة في وقت واحد:

Output demo.gif
Output demo.mp4
Output demo.webm

متغيرات البيئة

Set Shell "bash"
Type "export PS1='$ '"
Enter
Hide
Sleep 500ms
Show

اختصارات لوحة المفاتيح

Ctrl+C     # Cancel current command
Ctrl+L     # Clear screen
Ctrl+D     # EOF / exit
Tab        # Tab completion
Up         # Previous command
Escape     # Escape key

9. أدوات تسجيل بديلة

الأداة	المخرجات	المزايا	العيوب
VHS	GIF, MP4, WebM	مبرمج، قابل للتكرار، ثيمات	يتطلب إعداداً
asciinema	.cast	تسجيل مباشر، ملفات صغيرة	لا مخرجات GIF (يحتاج تحويلاً)
Terminalizer	GIF	تسجيل مباشر، إعداد YAML	أحجام ملفات كبيرة
Peek	GIF, WebM	مسجّل شاشة ذو واجهة رسومية	غير مخصص للطرفية

نوصي بـ VHS للعروض التوضيحية المبرمجة (قابلة للتكرار والتحكم بالإصدار) وasciinema + تحويل VHS للتسجيلات المباشرة.

← جميع الأدلة · تضمين التسجيلات في GitHub README →