> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Venice Video Harness

> شغّل Venice من Claude Code أو Cursor عبر أداة محسّنة لـ Venice لإنشاء فيديوهات متسقة الشخصيات، وقصص مصورة، ومقاطع دعائية، وسرد طويل.

[Venice Video Harness](https://github.com/jordanurbs/venice-video-harness) هو مجموعة أدوات مجتمعية، مبنية على الوكلاء ومحسّنة لـ Venice، تستهدف **إنشاء الفيديو بالاتساق أولًا وبأي طول**. تحوّل وكيل IDE (Claude Code أو Cursor أو Codex أو غيرها) إلى مشغّل لنظام إنتاج Venice قابل لإعادة الاستخدام يغطي أكثر من 50 نموذج فيديو وصورة وصوت وموسيقى من Venice.

<Card title="GitHub: venice-video-harness" icon="github" href="https://github.com/jordanurbs/venice-video-harness">
  مرخّص MIT. مُدار من قِبل المجتمع.
</Card>

<CardGroup cols={3}>
  <Card title="فيديو متّسق الشخصيات" icon="users">
    ثبّت الشخصيات والأصوات والجماليات عبر سلسلة كاملة
  </Card>

  <Card title="من اللوحة القصصية إلى الفيديو" icon="film">
    توليد لوحات بمرورين مع تحسين متعدد عبر Venice multi-edit
  </Card>

  <Card title="تحرير قائم على النص" icon="scissors">
    تفريغ نصي محلي عبر whisper.cpp، والقص من حزمة بحجم 12KB، مع تقييم ذاتي عند كل حد قص
  </Card>
</CardGroup>

## ما هذا

معظم تكاملات Venice هي أغلفة رقيقة حول استدعاءات API. أما Venice Video Harness فهو **الطبقة الأعلى** التي تقع بين الوكيل وVenice API:

* **قواعد التنسيق** في `CLAUDE.md`
* **سجلات تشغيل قابلة لإعادة الاستخدام** في `.claude/commands/` (19 أمر سير عمل)
* **وكلاء متخصّصون** في `.claude/agents/` (مخرج فني، مهندس طلبات، فحص جودة القص، وغيرهم)
* **مهارات إنتاج Venice** في `.claude/skills/` (متوافقة مع تنسيق [Agent Skills](/guides/integrations/venice-skills))
* **طبقة تنفيذ TypeScript** في `src/`
* **سجل نماذج شامل** يغطي أكثر من 50 نموذج فيديو وصورة وصوت وموسيقى من Venice

مبنيّ للمبدعين الذين ينتجون:

* مشاريع فيديو متّسقة الشخصيات (أي نوع وأي طول)
* سلاسل أو حملات بأسلوب بصري مثبّت
* سير عمل من اللوحة القصصية إلى الفيديو
* محتوى سردي قصير وطويل
* تسلسلات سينمائية ذات علامة تجارية، وترويجات، ومقاطع تشويقية
* سلاسل اجتماعية متكرّرة الشخصيات

## البدء

### المتطلبات

<CardGroup cols={3}>
  <Card title="Node.js 20+" icon="node-js" href="https://nodejs.org/">
    يُوصى بأحدث إصدار LTS
  </Card>

  <Card title="ffmpeg + ffprobe" icon="terminal" href="https://ffmpeg.org/">
    على متغير PATH لديك
  </Card>

  <Card title="مفتاح Venice API" icon="key" href="/guides/getting-started/generating-api-key">
    من [venice.ai/settings/api](https://venice.ai/settings/api)
  </Card>
</CardGroup>

اختياري، لخط أنابيب التحرير: ثبّت `whisper-cpp` للتفريغ النصي المحلي.

```bash theme={"system"}
brew install whisper-cpp
mkdir -p ~/.cache/whisper.cpp
curl -L -o ~/.cache/whisper.cpp/ggml-base.en.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
```

### الإعداد

<Steps>
  <Step title="استنسخ الـ harness">
    ```bash theme={"system"}
    git clone https://github.com/jordanurbs/venice-video-harness.git
    cd venice-video-harness
    ```
  </Step>

  <Step title="اضبط مفتاح API">
    ```bash theme={"system"}
    cp .env.example .env
    # أضف VENICE_API_KEY إلى .env
    ```
  </Step>

  <Step title="ثبّت وابنِ">
    ```bash theme={"system"}
    npm install
    npm run build
    ```
  </Step>

  <Step title="افتح في وكيلك">
    افتح المشروع في Cursor أو Claude Code أو أي IDE يدعم الدردشة الوكيلية. يقرأ الوكيل ملف `CLAUDE.md` وسجلات التشغيل تلقائيًا.

    جرّب إحدى هذه الرسائل الأولى:

    * "Set up this Venice video harness for first use"
    * "Create a new character-consistent video series"
    * "Generate a 30-second branded video sequence"
    * "Build a multi-episode narrative with locked characters"
    * "Create a product launch trailer with consistent visual style"
  </Step>
</Steps>

## ما الذي يجعله محسّنًا لـ Venice

* **طلبات الصور مضبوطة لنماذج صور Venice** مثل `seedream-v5-lite` و`nano-banana-pro` و`flux-2-pro/max` وغيرها
* **توليد اللوحات بمرورين** مع تحسين متعدد عبر Venice multi-edit لتصحيح الشخصيات
* **منطق توجيه النماذج** لطبقات الحركة والأجواء واتساق الشخصيات
* **توليد فيديو مدرك للمراجع** يستخدم `elements` و`reference_image_urls` و`scene_image_urls` بشكل صحيح لكل نموذج
* **تكييف الطلبات وفق البيئة** للتعامل مع المشاهد النهارية مقابل الليلية
* **مسارات صوتية أصلية لـ Venice** لـ TTS (Kokoro، Qwen3، ElevenLabs) والمؤثرات الصوتية والموسيقى
* **تقدير التكلفة** قبل التوليد عبر `/video/quote` و`/audio/quote`
* **بناء معاملات مدرك للنموذج** يتجاوز تلقائيًا المعاملات التي لا يدعمها النموذج المستهدف

## افتراضيات توجيه النماذج

افتراضيات الـ harness ذات رأي واضح لأن الاتساق هو الهدف. التوجيه الحالي (أبريل 2026):

**Seedance 2.0 R2V افتراضيًا. Kling O3 R2V كبديل احتياطي لمشاهد 3+ شخصيات. Seedance 2.0 i2v للقطات التأسيسية.**

| الدور                      | النموذج الافتراضي                      | متى يُستخدم                                                                                  |
| -------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------- |
| لقطات الشخصيات (1-2 شخصية) | `seedance-2-0-reference-to-video`      | R2V افتراضي مع `reference_image_urls` مسطّحة، ووسوم `@Image`، حتى 15 ثانية، وصوت ستيريو أصلي |
| لقطات الشخصيات (3+ شخصيات) | `kling-o3-standard-reference-to-video` | بديل احتياطي تلقائي مع `elements` مهيكلة لهوية متعدّدة الشخصيات                              |
| تأسيسي / مزاجي / حركة      | `seedance-2-0-image-to-video`          | بدون شخصيات؛ جودة سينمائية ملحمية، حتى 15 ثانية                                              |

يمكن تجاوز هذه القيم لكل مشروع عبر `series.json → videoDefaults`. لاستهداف عائلة غير Seedance (مثل الحسابات التي تفتقر إلى وصول Seedance)، اضبط `videoDefaults` إلى `kling-o3-standard-reference-to-video` و`veo3.1-fast-image-to-video`.

<Note>
  **قاعدة وجوه Seedance:** يحجب Seedance 2.0 صور الإدخال التي تحتوي على وجوه ولم يُنتجها `seedream-v5-lite` أو `seedream-v5-lite-edit`. يتعامل الـ harness مع ذلك تلقائيًا بتوجيه أعمال الصور الحاملة للشخصيات عبر Seedream وتشغيل بوابة قبل الإقلاع قبل كل استدعاء Seedance.
</Note>

## نماذج Venice المدعومة

### الفيديو (أبريل 2026)

| العائلة                   | i2v                        | t2v                   | الحد الأقصى للمدة | الصوت                                | ملاحظات                                                            |
| ------------------------- | -------------------------- | --------------------- | ----------------- | ------------------------------------ | ------------------------------------------------------------------ |
| **Seedance 2.0**          | i2v, R2V                   | t2v                   | 15 ث              | نعم (ستيريو، مزامنة شفاه لـ 8+ لغات) | المرتبة الأولى. R2V: `reference_image_urls` مسطّحة، وسوم `@Image`. |
| **Kling V3**              | Pro, Standard              | Pro, Standard         | 15 ث              | نعم                                  | `end_image_url` لاستهداف الإطار                                    |
| **Kling O3**              | Pro, Std, Pro R2V, Std R2V | Pro, Standard         | 15 ث              | نعم                                  | R2V: `elements` و`reference_image_urls` و`scene_image_urls`        |
| **Kling 2.6 / 2.5 Turbo** | Pro                        | Pro                   | 10 ث              | 2.6: نعم / 2.5: لا                   | `end_image_url`                                                    |
| **Veo 3.1**               | Fast, Full                 | Fast, Full            | 8 ث               | نعم                                  | حتى دقة 4K                                                         |
| **Sora 2**                | Standard, Pro              | Standard, Pro         | 12 ث              | نعم                                  | حتى 1080p                                                          |
| **Wan 2.6 / 2.5**         | Std, Flash / نعم           | Std / نعم             | 15 ث / 10 ث       | نعم                                  | إدخال `audio_url`                                                  |
| **LTX Video 2.0**         | Fast, Full, v2.3, 19B      | Fast, Full, v2.3, 19B | 20 ث              | نعم                                  | حتى 4K، أطول مزامنة                                                |
| **Longcat**               | Std, Distilled             | Std, Distilled        | **30 ث**          | لا                                   | الأطول بلقطة واحدة                                                 |
| **Vidu Q3**               | نعم                        | نعم                   | 16 ث              | نعم                                  | `reference_image_urls`                                             |
| **PixVerse v5.6**         | Std, Transition            | Standard              | 8 ث               | نعم                                  | Transition: `end_image_url`                                        |
| **Grok Imagine**          | نعم                        | نعم                   | 15 ث              | نعم                                  | دعم نسب عرض واسعة                                                  |

### الصورة والصوت والموسيقى

* **الصورة (22+ نموذج):** `nano-banana-pro/2`، `gpt-image-2`، `flux-2-pro/max`، `grok-imagine`، `qwen-image-2-pro`، `recraft-v4-pro`، `seedream-v4` / `v5-lite`، `lustify-sdxl/v7`، `wai-Illustrious`، وغيرها
* **Multi-edit:** `qwen-edit`، `flux-2-max-edit`، `nano-banana-pro-edit`، `seedream-v5-lite-edit`، `gpt-image-2-edit`، وغيرها
* **TTS:** `tts-kokoro` (أكثر من 50 صوتًا)، `tts-qwen3-0-6b/1-7b`، `elevenlabs-tts-v3`، `elevenlabs-tts-multilingual-v2`
* **الموسيقى:** `elevenlabs-music`، `minimax-music-v2`، `ace-step-15`، `stable-audio-25`
* **المؤثرات الصوتية:** `elevenlabs-sound-effects-v2`، `mmaudio-v2-text-to-audio`

## خطوط الإنتاج

### خط أنابيب التوليد

فيديو سردي شامل (سيناريو → لوحة قصصية → فيديو → صوت → تجميع):

```bash theme={"system"}
npm run dev -- produce-episode -p output/my-series -e 1
```

تنفيذ مرجعي في `src/mini-drama/` يغطي:

* إدارة السلاسل / الشخصيات / الحلقات
* ورش كتابة سيناريو مدعومة بـ LLM
* توليد لوحة قصصية بمرورين (توليد + تحسين متعدد)
* فحص جودة اللوحات قائم على الرؤية
* توليد الفيديو مع تسلسل الإطارات
* ما بعد إنتاج صوتي طبقي
* حرق الترجمة والتجميع النهائي

### خط أنابيب التحرير

قص الوسائط الموجودة مسبقًا (لقطات مولّدة من Venice أو لقطات خام حقيقية). **النص أولًا**: يقرأ الـ LLM ملف `takes_packed.md` مدمجًا (\~12KB لكل 40 دقيقة من الصوت) بدلًا من تفريغ إطارات الفيديو.

الخطوات الخمس:

<Steps>
  <Step title="التفريغ النصي">
    يُنتج whisper.cpp محليًا `*.words.json` + `takes_packed.md` لكل مصدر.
  </Step>

  <Step title="قراءة الحزمة">
    يضع الـ LLM استراتيجية قصّ من النص وحده.
  </Step>

  <Step title="التأكيد">
    يقترح الاستراتيجية وينتظر "yes / revise / cancel".
  </Step>

  <Step title="عرض الـ EDL">
    قائمة قص JSON ← دمج ffmpeg مع تلاشي صوتي 30 مللي ثانية. الأرشيف أولًا، فلا يُكتب فوق الأصول أبدًا.
  </Step>

  <Step title="التقييم الذاتي">
    يجري وكيل `cut-qa` 6 فحوصات برمجية عند كل حد قص؛ بحد أقصى 3 تكرارات إصلاح.
  </Step>
</Steps>

تكتشف فحوصات `cut-qa` انحدارات نسبة العرض إلى الارتفاع، وقفزات تجزئة الإطار داخل كلمة، واقتطاع التعليق الصوتي، وتغيّر الإضاءة، وذرّ الصوت فوق -6 dBFS، وتداخل الترجمة مع نص داخل الإطار.

<Tip>
  استلهم خط أنابيب التحرير من [browser-use/video-use](https://github.com/browser-use/video-use). فكرتهم الجوهرية، *"الـ LLM لا يشاهد الفيديو أبدًا، بل يقرؤه"*، هي ما يجعل التحرير الموجّه بالوكلاء يعمل دون الغرق في توكنات تفريغ الإطارات.
</Tip>

## الأوامر والوكلاء والمهارات

يكشف الـ harness عن 19 أمر سير عمل، و10 وكلاء متخصّصين، و7 مهارات إنتاج. أبرزها:

| أمر سير العمل                      | الغرض                                          |
| ---------------------------------- | ---------------------------------------------- |
| `new-series`                       | إنشاء سلسلة جديدة بجماليات مثبّتة              |
| `add-character` / `lock-character` | تثبيت الشخصية + الصوت                          |
| `workshop-episode`                 | كتابة حلقة بشكل تعاوني                         |
| `storyboard-episode`               | عمل لوحة قصصية لحلقة واحدة                     |
| `produce-episode`                  | خط الأنابيب الكامل في أمر واحد                 |
| `generate-trailer`                 | خط أنابيب ترويج كامل                           |
| `edit-footage`                     | خط أنابيب تحرير قائم على النص للوسائط الموجودة |
| `ingest-screenplay`                | استيراد سيناريو Fountain أو PDF                |

| الوكيل المتخصّص    | الدور                                                        |
| ------------------ | ------------------------------------------------------------ |
| `art-director`     | قرارات الجماليات واللوحة اللونية والإضاءة والتكوين           |
| `prompt-engineer`  | طلبات صور Venice، واتساق الشخصيات                            |
| `storyboard-qa`    | فحص جودة اللوحات للاستمرارية والشخصيات                       |
| `cut-qa`           | بوابة جودة بعد التصيير (6 فحوصات لكل قص، بحد أقصى 3 تكرارات) |
| `overlay-designer` | رسوميات متحركة بعلامة تجارية، وكلاء فرعيون متوازيون          |
| `trailer-curator`  | اختيار لقطات الترويج وقواعد منع الحرق                        |

| مهارة الإنتاج                | الغرض                                                   |
| ---------------------------- | ------------------------------------------------------- |
| `venice-api`                 | استخدام Venice REST API والافتراضيات                    |
| `venice-video-model-routing` | توجيه R2V أولًا، أشجار قرار                             |
| `character-consistency`      | إرشادات اتساق الشخصية عبر لقطات متعدّدة                 |
| `shot-composition`           | إرشادات تكوين اللقطة والكاميرا                          |
| `screenplay-parsing`         | سير عمل تحليل السيناريو                                 |
| `video-editing`              | فلسفة التحرير القائم على النص، وتنسيق EDL، وحلقة cut-qa |

## دورة كاملة مع NLE

بعد التصيير، صدّر الجدول الزمني المُجمَّع كـ XML للتحرير الدقيق في محرّرك المفضّل. كل مقطع فيديو ومقطع حوار ومقطع مؤثر صوتي وموسيقى يحطّ على مساره الخاص.

```bash theme={"system"}
mini-drama export-timeline -p output/<project> -e 1 --format fcpxml      # Final Cut Pro X
mini-drama export-timeline -p output/<project> -e 1 --format premiere    # Premiere Pro
mini-drama export-timeline -p output/<project> -e 1 --format davinci     # DaVinci Resolve
```

## الاستخدام البرمجي

يمكنك أيضًا استدعاء وحدات الـ harness مباشرة من شيفرة TypeScript الخاصة بك:

```typescript theme={"system"}
import { VeniceClient } from './src/venice/client.js';
import { generateVideo, quoteVideo } from './src/venice/video.js';
import { listVideoModels } from './src/venice/models.js';

const client = new VeniceClient();

const quote = await quoteVideo(client, {
  model: 'kling-v3-pro-image-to-video',
  duration: '8s',
  audio: true,
});
console.log(`Estimated cost: $${quote.quote}`);

const result = await generateVideo(client, {
  model: 'kling-v3-pro-image-to-video',
  prompt: 'A slow dolly shot pushes forward...',
  duration: '8s',
  imageUrl: 'data:image/png;base64,...',
  audio: true,
  outputPath: 'output/shot-001.mp4',
});

const longModels = listVideoModels({ minDurationSec: 20 });
```

## المصادر

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/jordanurbs/venice-video-harness">
    الشيفرة المصدرية والمشاكل والإصدارات
  </Card>

  <Card title="توليد الفيديو في Venice" icon="film" href="/guides/media/video-generation">
    الـ API الأساسي الذي يقوده الـ harness
  </Card>

  <Card title="من المرجع إلى الفيديو" icon="image" href="/guides/media/reference-to-video">
    دليل R2V لاتساق الشخصيات
  </Card>

  <Card title="Seedance 2.0" icon="bolt" href="/guides/media/seedance-2-0">
    عائلة الفيديو الافتراضية للـ harness
  </Card>
</CardGroup>

<Note>
  مُدار من قِبل المجتمع ويُقدَّم كما هو. للمشاكل الخاصة بالـ harness، أبلغ عنها في [مستودع المشروع على GitHub](https://github.com/jordanurbs/venice-video-harness/issues).
</Note>