استعمل CDAF باش تعطي لوكلاء الذكاء الاصطناعي سياق فيديو سريع وموثوق

شنو كيدير CDAF

CDAF، وهو اختصار لـ Cached Descriptive Asset Files، هو فورما مفتوح جانبي للفيديو. كيخزّن وصف مكتوب بنص عادي ومربوط بالطابع الزمني حدّا الفيديو، وبنفس الاسم الأساسي. مثلا، sunset-drone.mp4 كيتقرن مع sunset-drone.cdaf.

الهدف هو توصف الفيديو مرة وحدة وتعاود تستعمل داك الوصف فمهام الذكاء الاصطناعي اللي من بعد. بلا ما تصيفط نفس اللقطات لنموذج كيفهم الفيديو مع كل سؤال، يقدر الوكيل يتحقق من ملف CDAF ويقراه، حيث هو أصغر بزاف.

footage/
sunset-drone.mp4
sunset-drone.cdaf

الفيديو الأصلي كيبقى كيف ما هو وقابل للتشغيل ببرامج الفيديو العادية. الملف الجانبي هو نص بترميز UTF-8، فيه ترويسة صغيرة ديال البيانات الوصفية ومن بعدها وصف بصيغة Markdown مهيأ للنماذج اللغوية.

علاش نقدروا نعاودوا نستعملو الملف الجانبي بأمان

ترويسة CDAF كتسجل الهاش الدقيق SHA-256 ديال الفيديو والحجم ديالو بالبايت. الأدوات المطابقة للمواصفات كتستعمل هاد القيم باش تحدد واش الوصف مازال صالح. إلا تبدل الفيديو، الملف الجانبي كيولي قديم وما خاصوش يتستعمل.

--- CDAF/1.0
video: sunset-drone.mp4
sha256: 4a7d1ed4…
bytes: 48211394
duration: 00:00:31.500
generator: gemini-2.5-flash
created: 2026-08-26T14:03:12Z
---

## الملخص
مقطع جوي بالطائرة المسيرة مدتو 31 ثانية، كيبين طريق ساحلي فالساعة الذهبية…

## المقاطع
[00:00.0-00:05.2] لقطة جوية واسعة لتقديم المشهد…
[00:05.2-00:12.8] الطائرة المسيرة كتقرب وكتنزل…

## التفريغ النصي
(ما كاين حتى كلام)

## النص اللي باين فوق الشاشة
(ما كاين والو)

## الوسوم
طائرة مسيرة، جوي، طريق ساحلي، الساعة الذهبية، غروب الشمس

المتن يقدر يعطي ملخص، ومقاطع مربوطة بالطابع الزمني، وتفريغ نصي، والنص اللي باين فوق الشاشة، ووسوم. شوف مواصفة CDAF 1.0 ديال المشروع باش تعرف الفورما المعياري، وقواعد صلاحية البيانات، والإصدارات، وقواعد أقسام المحتوى.

الخصائص الرئيسية

• إعادة استعمال موثوقة: البيانات الوصفية ديال SHA-256 والحجم بالبايت كيربطو الملف الجانبي بنفس الفيديو بالضبط اللي كيوصفو.
• فورما نصي ساهل للقراية: الوكلاء يقدرو يستعملو الأوصاف ويقلبو فيها ويعاودو يستعملوها بلا ما يفكو ترميز الفيديو من جديد.
• مقاطع مربوطة بالطابع الزمني: نطاقات المقاطع تقدر تعاون فاختيار اللقطات وإنشاء لائحة القطع.
• النواة بلا تبعيات: التحليل، والتسلسل، وحساب الهاش، والتحقق من الصلاحية، واستخراج المقاطع كاملين كيستعملو المكتبة القياسية ديال Python.
• واجهة سطر الأوامر موجهة للمعالجة الدفعية: الأداة ديال سطر الأوامر تقدر تنشئ ملفات جانبية لمجلد كامل وتتجاوز اللي مازالو صالحين.
• بروفايلات متعددة للتفاصيل: الإنشاء كيدعم الخرج brief وstandard وrich.
• مهارة للوكيل: مهارة مجهزة كتعلّم وكلاء البرمجة يقلبو على الملفات الجانبية الموثوقة قبل ما يحللو الفيديو.
• إنشاء محلي اختياري: المستودع فيه مزود --local للإنشاء باستعمال نموذج محلي وبلا مفتاح API.
• الفحص الاختياري: CDAF يقدر يستعمل ffprobe باش يجيب مدة الفيديو، والدقة، وبيانات معدل الإطارات، وكيستمر يخدم بشكل مناسب إلا ما كانش ffprobe متوفر.

ثبّت مهارة الوكيل

أسرع طريقة باش تعلّم وكيل برمجة مدعوم سير العمل اللي كيبدا بالملف الجانبي هي:

npx cdaf-skill

افتراضيا، كتتثبت المهارة فـ ~/.claude/skills/cdaf وكتولي متاحة فالمشاريع كاملين. ومن طرق التثبيت المدعومة الأخرى:

npx cdaf-skill --project
npx cdaf-skill --dir <path>
npx cdaf-skill --print

• --project كيثبت المهارة فـ ./.claude/skills/cdaf ديال المشروع الحالي.
• --dir كيثبتها فمجلد كتختارو.
• --print كيكتب المهارة فالخرج القياسي باش تقدر تلصقها فإطار عمل ديال وكيل آخر.

عاود تشغيل المثبّت آمن. المهارة اللي ما تبدلاتش كيتخلاو عليها، والمهارة اللي تبدلات كتتحفظ نسخة احتياطية منها باسم SKILL.md.bak قبل الاستبدال.

قبل ما تحلل ملف فيديو، قلب على ملف .cdaf بنفس الاسم الأساسي. إلا كانت قيم bytes وsha256 فالترويسة مطابقة للفيديو، قراه بلا ما تعالج الفيديو.

ثبّت واجهة سطر أوامر CDAF

واجهة Python كتحتاج Python 3.10 أو أحدث. ملف README الحالي كيثبتها مباشرة من المستودع حيث إصدار PyPI مازال مبرمج للمستقبل.

pip install "cdaf[generate] @ git+https://github.com/UditAkhourii/cdaf.git#subdirectory=cli"

إلا كنت خدام من مستودع مستنسخ، ثبّت الواجهة من المجلد المحلي cli:

pip install ./cli[generate]

التنفيذ ديال الإنشاء كيستعمل Gemini Files API. جيب مفتاح Gemini API من Google AI Studio، ومن بعد حطّو فبيئتك.

macOS وLinux

export GEMINI_API_KEY=your-key

Windows PowerShell

$env:GEMINI_API_KEY="your-key"

اللقطات ديالك كتتعالج باستعمال مفتاح API ديالك. الأوامر اللي غير كتقرا أو كتتحقق من الملفات الجانبية الموجودة ما كتحتاجش مفتاح API ولا تبعيات الإنشاء.

إنشاء الملفات الجانبية

حط فيديو واحد ولا أكثر فمجلد وشغّل cdaf generate على داك المجلد:

cdaf generate ./footage

CDAF كيوصف الفيديوهات وكيصايب ملفات جانبية بنفس الأسماء الأساسية. ملي كتعاود تشغلو، الإنشاء كيتجاوز الفيديوهات اللي الملفات الجانبية ديالها مازالو صالحين.

اختار بروفايل التفاصيل

استعمل --detail باش تختار واحد من بروفايلات الإنشاء الثلاثة الموثقة:

cdaf generate ./footage --detail brief
cdaf generate ./footage --detail standard
cdaf generate ./footage --detail rich

اختار بروفايل على حساب شحال ديال السياق الوصفي اللي خاص للمهام اللي من بعد. تقدر حتى تختار موديل Gemini بـ --model ولا تطلب إعادة التوليد بـ --force.

cdaf generate ./footage --model <gemini-model>
cdaf generate ./footage --force

شوف حالة مكتبة الفيديوهات

استعمل أمر الحالة باش تصنّف الملفات الجانبية على أنها FRESH أو STALE أو MISSING:

cdaf status ./footage

• FRESH: الملف الجانبي مطابق للفيديو الحالي.
• STALE: كاين ملف جانبي، ولكن الهوية المسجّلة فيه ما بقاتش مطابقة للفيديو.
• MISSING: ما كاين حتى ملف جانبي CDAF مطابق.

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

قرا وصف موثّق

استعمل cdaf read ملي بغيتي محتوى الملف الجانبي لوكيل أو سكريبت أو prompt:

cdaf read ./footage/sunset-drone.mp4

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

تحقّق من الملفات الجانبية فالأتمتة

أمر التحقق كيسالي بنجاح غير إلا كان الملف الجانبي المطابق منظم مزيان وحديث:

cdaf validate ./footage/clip.mp4

حيت الأمر كيخرج بالحالة 0 غير ملي كيكون الملف الجانبي صالح وحديث، تقدر تستعملو فالسكريبتات ولا فمسارات التكامل المستمر. التحقق ما محتاج لا لمفتاح API لا لاعتماديات التوليد الاختيارية.

استعمل CDAF من Python

واجهة Python الأساسية كتخلي التطبيقات تلقى الملف الجانبي وتحملو وتتحقق منو قبل ما تدوز المحتوى ديالو لنموذج لغوي.

from cdaf import load, check_freshness, sidecar_path_for

video = "footage/sunset-drone.mp4"
sidecar = load(sidecar_path_for(video))

if check_freshness(video, sidecar) == "fresh":
    context_for_llm = sidecar.body

هاد النمط هو التكامل الأساسي ديال CDAF: استخرج المسار المتوقع للملف الجانبي، حلّل الملف، تحقّق من الحداثة ديالو مقارنة مع الفيديو، واستعمل sidecar.body غير ملي تكون النتيجة هي fresh.

النواة ديال الحزمة كتدعم حتى التسلسل، وحساب SHA-256 على دفعات، واستخراج المقاطع. هاد العمليات كاملة كتستعمل غير المكتبة القياسية. والكود الخاص بالمولّد كيتستورد غير ملي كيكون التوليد مطلوب.

بني سيرورة عمل للوكيل كتبدأ بالملف الجانبي

1. تلقّى مسار فيديو كجزء من مهمة ديال المونتاج أو البحث أو الإجابة على الأسئلة.
2. قلّب على ملف .cdaf بنفس الاسم الأساسي.
3. تحقّق من حداثة الملف الجانبي مقارنة مع الفيديو الحالي.
4. إلا كان حديث، قرا النص ديالو بلا ما تدير جولة أخرى لفهم الفيديو.
5. إلا كان قديم ولا ناقص، عاود ولّدو قبل ما تعتمد على المحتوى ديالو.
6. استعمل الملخص والمقاطع والتفريغ النصي والنص اللي باين فالشاشة والوسوم كسياق للمهمة اللي من بعد.

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

نصائح متقدمة

قلّب فمجموعات الفيديوهات بحال إلا كانت نصوص

منين كيكونو الفيديوهات عندها ملفات جانبية، يقدرو الوكلاء وأدوات سطر الأوامر يقلّبو فملفات .cdaf بلا ما يفتحو كل فيديو. الوسوم والأوصاف يقدرو يحوّلو طلبات بحال لقطات غروب ساحلية بلا ناس لاسترجاع نصي داخل مكتبة الأصول.

حوّل المقاطع لقرارات ديال المونتاج

الأسطر اللي فيها الطوابع الزمنية بحال [00:05.2-00:12.8] كتعطي نطاقات يقدرو المحررات البرمجية يحوّلوها لمقاطع ولا لتسلسلات. ملف README كيشير بالخصوص إلى Remotion وHyperFrames وأدوات التحويل من prompt إلى مونتاج كسيرورات عمل تقدر تستافد من هاد البنية.

عاود استعمل توقيت التفريغ النصي

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

استعمل بيانات ffprobe الاختيارية

إلا كان ffprobe متوفر، مكوّن probe ديال CDAF يقدر يجمع بيانات المدة والدقة وعدد الإطارات فالثانية. والمحرك كيكمل خدمتو بشكل سلس ملي ما يكونش ffprobe حاضر، وهاد التكامل الاختياري ما كيحبسش العمليات الأساسية ديال الملفات الجانبية.

فكّر فالتوليد المحلي

المستودع فيه مزوّد محلي كيتفعّل بـ --local. مخصّص للتوليد بموديل محلي ملي ما بغيتيش تستعمل مفتاح API. راجع تنفيذ المزوّد المحلي فالمستودع باش تعرف إعداد الموديل المحلي المدعوم حاليا.

خلّي الواجهات الخلفية منفصلة على الصيغة

CDAF بحد ذاتو ما مرتبط حتى بموديل معيّن. Gemini هو الواجهة الخلفية المضمّنة للمولّد البعيد، بينما تقدر واجهات خلفية أخرى لنماذج الفيديو واللغة تخدم من ورا نفس النوع Sidecar. واجهات Claude وGPT وVLM المحلية الإضافية مذكورة فخارطة الطريق، وما خاصش نفترضو أنها متوفرة دابا.

عاود إنتاج الاختبار المعياري

المستودع فيه اختبار معياري موضوعي كينشئ فيديوهات من وصفات مبرمجة باستعمال ffmpeg. شغّل المراحل ديالو بالترتيب:

python benchmarks/bench.py make
python benchmarks/bench.py run
python benchmarks/bench.py report

الخطوة اللّولة كتحتاج ffmpeg، والتانية كتحتاج GEMINI_API_KEY، والمرحلة اللّخّرة كتكَتب benchmarks/RESULTS.md. فاختبار فيه 20 سؤال، الأجوبة الجانبية جابو 20 جواب صحيح من أصل 20، مقابل 19 من أصل 20 للفيديو المباشر، وهادشي باستعمال متوسط 303 توكنات ديال البرومبت لكل سؤال عوض 3,066. هادو نتائج ديال benchmark من المستودع، وقد يوقع اختلاف حسب اللقطات، والموديلات، والبرومبتات، والبيئات.

الحدود الحالية وخارطة الطريق

الـ README كيشير لعدة عناصر على أنها خدمة مستقبلية وماشي وظائف متاحة دابا: إصدار على PyPI، وسيرفر MCP، ومحوّل مستضاف، وbackends إضافية للتوليد، ونقل المحرك لـ Node أو TypeScript، وتوسعة benchmark باللقطات الطبيعية، وsidecars موقّعة. استعمل اليوم التثبيت الموثّق عبر Git وCLI الموجود، وما تفترضش أن مكوّنات خارطة الطريق هادي متاحة.

الخلاصة

CDAF كيحوّل تحليل الفيديو المتكرر لواحد workflow ديال التحقق والقراية. ولّد sidecar مرة وحدة، وخليه حدّ الفيديو الأصلي، وتحقق منّو كل مرة كتستعمل فيها الـ asset، وعطي المحتوى ديالو للـ agents اللي من بعد. الهاشات ديال الفورما ك تمنع الاستعمال بالغلط من بعد التعديلات، بينما الملخصات ديالو، والطوابع الزمنية، والنصوص المفرّغة، والكتابة، والوسوم كيسهلو البحث فمكتبات الفيديو وأتمتتها.

CDAF متوفر برخصة MIT. الكود المصدري، والمواصفات، والأمثلة، وتفاصيل benchmark، وagent skill متوفرين فـ مستودع CDAF على GitHub.