نشر Rendervid - العرض في المتصفح وNode.js والسحابة وDocker

مقدمة

تم تصميم Rendervid للعرض في أي مكان يتطلبه سير عملك. سواء كنت بحاجة إلى معاينات فورية في المتصفح، أو ترميز فيديو بجودة إنتاجية على الخادم، أو عرض متوازٍ بشكل كبير عبر البنية التحتية السحابية، يوفر Rendervid حزمة مخصصة لكل بيئة. تشترك جميع أهداف النشر في نفس نظام القوالب ومكتبة المكونات ، لذا فإن القالب الذي يعمل في المتصفح يعمل بشكل مماثل على AWS Lambda أو في حاوية Docker.

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

                        +---------------------+
                        |   JSON Template     |
                        +----------+----------+
                                   |
              +--------------------+--------------------+
              |                    |                    |
     +--------v--------+  +-------v--------+  +-------v---------+
     |     Browser      |  |    Node.js     |  |     Cloud       |
     | @rendervid/      |  | @rendervid/    |  | @rendervid/     |
     | renderer-browser |  | renderer-node  |  | cloud-rendering |
     +---------+--------+  +-------+--------+  +-------+---------+
               |                   |                    |
        Canvas / WebM         FFmpeg / Playwright   Parallel Workers
               |                   |                    |
     +---------v--------+  +------v---------+  +-------v---------+
     | MP4, WebM, PNG,  |  | MP4, WebM, MOV,|  | AWS Lambda      |
     | JPEG, WebP       |  | GIF, H.265     |  | Azure Functions |
     +------------------+  +----------------+  | GCP Functions   |
                                               | Docker          |
                                               +-----------------+

العرض في المتصفح

تتعامل حزمة @rendervid/renderer-browser مع العرض من جانب العميل بالكامل داخل متصفح المستخدم. لا يلزم وجود بنية تحتية للخادم. هذا يجعلها أسرع مسار من القالب إلى المعاينة.

متى تستخدم العرض في المتصفح

• المعاينات في الوقت الفعلي أثناء تحرير القالب في المحرر المرئي
• تطبيقات الويب التي تحتاج إلى إنشاء أصول فيديو أو صورة بشكل فوري
• النماذج الأولية للقوالب الجديدة قبل الالتزام بالعرض من جانب الخادم
• الصادرات خفيفة الوزن حيث يكون إخراج MP4 أو WebM أو PNG أو JPEG أو WebP كافيًا

التثبيت

npm install @rendervid/renderer-browser

كيف يعمل

يستخدم العرض في المتصفح HTML Canvas API لرسم كل إطار من القالب. يمر العارض عبر كل مشهد وطبقة، ويطبق الرسوم المتحركة ووظائف التخفيف، ويركب النتيجة على عنصر canvas، ويلتقط كل إطار. لإخراج الفيديو، يتم ترميز الإطارات باستخدام واجهة برمجة التطبيقات MediaRecorder المدمجة في المتصفح (WebM) أو مشفر MP4 القائم على WebAssembly.

تنسيقات الإخراج المدعومة

مثال على الكود

import { BrowserRenderer } from "@rendervid/renderer-browser";

const renderer = new BrowserRenderer();

const template = {
  width: 1920,
  height: 1080,
  fps: 30,
  scenes: [
    {
      duration: 5,
      layers: [
        {
          type: "text",
          text: "Hello from the Browser",
          fontSize: 72,
          color: "#ffffff",
          position: { x: 960, y: 540 },
          animation: {
            entrance: { type: "fadeIn", duration: 1 },
          },
        },
      ],
    },
  ],
};

// العرض على عنصر canvas للمعاينة
const canvas = document.getElementById("preview") as HTMLCanvasElement;
await renderer.preview(template, canvas);

// التصدير كـ MP4
const mp4Blob = await renderer.render(template, {
  format: "mp4",
  quality: "standard",
});

// تصدير إطار واحد كـ PNG
const pngBlob = await renderer.renderFrame(template, {
  format: "png",
  frameNumber: 0,
});

قيود العرض في المتصفح

• لا يوجد وصول إلى FFmpeg، لذا فإن H.265/HEVC وMOV غير متاحين
• يتطلب تصدير GIF عارض Node.js لتحسين اللوحة
• تعتمد الدقة القصوى على حدود حجم Canvas في المتصفح (عادةً 4096x4096 أو 8192x8192)
• تعتمد سرعة العرض على وحدة المعالجة المركزية ووحدة معالجة الرسومات لجهاز العميل

عرض Node.js

توفر حزمة @rendervid/renderer-node العرض من جانب الخادم مع تكامل FFmpeg الكامل. تستخدم Playwright أو Puppeteer لعرض كل إطار في متصفح بدون رأس، ثم توجه الإطارات إلى FFmpeg لترميز فيديو بجودة احترافية.

متى تستخدم عرض Node.js

• ترميز فيديو الإنتاج مع دعم codec كامل (H.264، H.265، VP9)
• معالجة الدفعات لمئات أو آلاف القوالب في خطوط أنابيب آلية
• واجهات برمجة التطبيقات REST التي تقبل قالب JSON وتعيد فيديو معروض
• خطوط أنابيب CI/CD لإنشاء المحتوى التلقائي
• تصدير GIF مع تحسين اللوحة والتحكم في التدرج

التثبيت

# تثبيت العارض
npm install @rendervid/renderer-node

# تثبيت Playwright (يشمل ملفات المتصفح الثنائية)
npx playwright install chromium

# تثبيت FFmpeg (مطلوب لترميز الفيديو)
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows (عبر Chocolatey)
choco install ffmpeg

تنسيقات الإخراج المدعومة

إعدادات الجودة المسبقة للعرض

يوفر Rendervid أربعة إعدادات مسبقة للجودة تتحكم في معلمات الترميز:

تسريع GPU

يدعم عارض Node.js التسريع بالأجهزة لتفريغ الترميز على GPU. هذا يقلل بشكل كبير من وقت العرض للقوالب المعقدة ذات الطبقات المتعددة والدقة العالية والتأثيرات.

const result = await renderer.render(template, {
  format: "mp4",
  quality: "high",
  outputPath: "/output/video.mp4",
  hardwareAcceleration: true,
});

يتوفر تسريع GPU على الأنظمة ذات أجهزة NVIDIA (NVENC) أو AMD (AMF) أو Intel (Quick Sync) المتوافقة. يجب تجميع FFmpeg مع دعم المشفر المقابل.

مثال على الكود

import { NodeRenderer } from "@rendervid/renderer-node";

const renderer = new NodeRenderer();

const template = {
  width: 1920,
  height: 1080,
  fps: 60,
  scenes: [
    {
      duration: 10,
      layers: [
        {
          type: "video",
          src: "/assets/background.mp4",
          fit: "cover",
        },
        {
          type: "text",
          text: "{{headline}}",
          fontSize: 64,
          color: "#ffffff",
          fontFamily: "Inter",
          position: { x: 960, y: 540 },
          animation: {
            entrance: { type: "slideInUp", duration: 0.8 },
            exit: { type: "fadeOut", duration: 0.5 },
          },
        },
      ],
    },
  ],
  inputs: {
    headline: {
      type: "text",
      label: "Headline",
      default: "Your Product, Elevated",
    },
  },
};

// العرض مع مدخلات مخصصة
const result = await renderer.render(template, {
  format: "mp4",
  quality: "high",
  outputPath: "/output/promo.mp4",
  renderWaitTime: 2000, // انتظر ثانيتين لتحميل الوسائط
  inputs: {
    headline: "Summer Sale — 50% Off Everything",
  },
});

console.log(`Rendered: ${result.outputPath}`);
console.log(`Duration: ${result.duration}s`);
console.log(`File size: ${(result.fileSize / 1024 / 1024).toFixed(2)} MB`);

معالجة الدفعات

لمعالجة العديد من القوالب بالتسلسل، استخدم واجهة برمجة التطبيقات للدفعات:

import { NodeRenderer } from "@rendervid/renderer-node";

const renderer = new NodeRenderer();

const templates = [
  { template: socialTemplate, inputs: { name: "Alice" }, output: "alice.mp4" },
  { template: socialTemplate, inputs: { name: "Bob" }, output: "bob.mp4" },
  { template: socialTemplate, inputs: { name: "Carol" }, output: "carol.mp4" },
];

for (const job of templates) {
  await renderer.render(job.template, {
    format: "mp4",
    quality: "standard",
    outputPath: `/output/${job.output}`,
    inputs: job.inputs,
  });
}

للعرض المتوازي الحقيقي على جهاز واحد، راجع قسم العرض المحلي بـ Docker أدناه.

العرض السحابي

تتيح حزمة @rendervid/cloud-rendering العرض الموزع والمتوازي عبر البنية التحتية السحابية. بدلاً من عرض الإطارات بشكل تسلسلي على جهاز واحد، يقسم العرض السحابي العمل عبر العديد من وظائف العمال التي تعرض الإطارات في وقت واحد، ثم يدمجها في الإخراج النهائي.

متى تستخدم العرض السحابي

• خطوط أنابيب عالية الإنتاجية تعالج مئات مقاطع الفيديو في الساعة
• محتوى طويل حيث يكون العرض التسلسلي بطيئًا جدًا
• أحمال عمل حساسة للوقت حيث يهم التسريع بمقدار 10-50 مرة
• التوسع التلقائي للتعامل مع ارتفاعات الطلب غير المتوقعة

البنية

+------------------+
|   Your App       |
|  (Coordinator)   |
+--------+---------+
         |
         | 1. Split video into frame chunks
         v
+--------+---------+
|   Chunk Splitter |
+--------+---------+
         |
         |  2. Distribute chunks to workers
         v
+--------+---+---+---+---+--------+
|  Worker 1  | Worker 2  | Worker N |
|  (Lambda/  | (Lambda/  | (Lambda/ |
|   Azure/   |  Azure/   |  Azure/  |
|   GCP)     |  GCP)     |  GCP)    |
+-----+------+----+------+----+----+
      |            |           |
      | 3. Each worker renders its frames
      v            v           v
+-----+------+----+------+----+----+
|  Frames    |  Frames   |  Frames |
|  001-030   |  031-060  |  061-090|
+-----+------+----+------+----+----+
      |            |           |
      +------+-----+-----+----+
             |
             v
     +-------+--------+
     |     Merger      |
     | (FFmpeg concat) |
     +-------+---------+
             |
             | 4. Combine into final video
             v
     +-------+---------+
     |  Object Storage  |
     |  S3 / Blob / GCS |
     +------------------+
             |
             | 5. Download or serve
             v
     +-------+---------+
     |   Final Output   |
     |   video.mp4      |
     +------------------+

كيف يعمل خطوة بخطوة:

1. يحلل المنسق القالب ويحدد عدد الإطارات التي يجب عرضها بناءً على المدة الإجمالية وFPS.
2. يقسم مقسم الأجزاء إجمالي عدد الإطارات إلى أجزاء (مثلاً، 30 إطارًا لكل جزء لفيديو 30fps = ثانية واحدة لكل جزء).
3. تتلقى كل وظيفة عامل تعيين جزء (إطار البداية، إطار النهاية)، وتعرض تلك الإطارات باستخدام عارض Node.js، وتحمل المقطع المعروض إلى تخزين الكائنات.
4. يقوم الدامج بتنزيل جميع المقاطع ودمجها في الفيديو النهائي باستخدام FFmpeg.
5. يتم تخزين الإخراج النهائي في تخزين الكائنات لمزود السحابة (S3 أو Azure Blob أو GCS) ويتم تنزيله اختياريًا إلى نظام الملفات المحلي.

تكوين السحابة

import { CloudRenderer } from "@rendervid/cloud-rendering";

const cloudRenderer = new CloudRenderer({
  provider: "aws", // "aws" | "azure" | "gcp" | "docker"
  quality: "standard", // "draft" | "standard" | "high"
  downloadToLocal: true,
  outputPath: "/output/final.mp4",
});

واجهة التكوين الكاملة:

interface CloudRenderConfig {
  provider: "aws" | "azure" | "gcp" | "docker";
  quality: "draft" | "standard" | "high";
  downloadToLocal: boolean;
  outputPath: string;

  awsConfig?: {
    region: string;
    s3Bucket: string;
    s3Prefix: string;
  };

  azureConfig?: {
    resourceGroup: string;
    storageAccount: string;
    containerName: string;
  };

  gcpConfig?: {
    projectId: string;
    bucketName: string;
    region: string;
  };

  dockerConfig?: {
    volumePath: string;
    workersCount: number;
  };
}

إعداد AWS Lambda

AWS Lambda هو هدف النشر السحابي الأكثر شيوعًا. تعمل كل وظيفة عامل في استدعاء Lambda منفصل، مما يتيح التوازي الهائل.

المتطلبات الأساسية:

• حساب AWS مع وصول Lambda وS3
• تكوين AWS CLI
• بيئة تشغيل Node.js 18+ Lambda

التكوين:

import { CloudRenderer } from "@rendervid/cloud-rendering";

const renderer = new CloudRenderer({
  provider: "aws",
  quality: "high",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  awsConfig: {
    region: "us-east-1",
    s3Bucket: "my-rendervid-output",
    s3Prefix: "renders/",
  },
});

const result = await renderer.render(template);
console.log(`Rendered in ${result.renderTime}ms`);
console.log(`Workers used: ${result.workersUsed}`);
console.log(`Output: ${result.outputUrl}`);

تكوين AWS Lambda النموذجي:

• الذاكرة: 1024-3008 ميجابايت (المزيد من الذاكرة = المزيد من وحدة المعالجة المركزية = عرض أسرع)
• المهلة: 300 ثانية (5 دقائق)
• التخزين المؤقت: 512 ميجابايت - 10 جيجابايت
• التزامن: 100-1000 (اضبط بناءً على حمل العمل)

إعداد Azure Functions

const renderer = new CloudRenderer({
  provider: "azure",
  quality: "standard",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  azureConfig: {
    resourceGroup: "rendervid-rg",
    storageAccount: "rendervidstore",
    containerName: "renders",
  },
});

const result = await renderer.render(template);

إعداد Google Cloud Functions

const renderer = new CloudRenderer({
  provider: "gcp",
  quality: "standard",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  gcpConfig: {
    projectId: "my-project-id",
    bucketName: "rendervid-output",
    region: "us-central1",
  },
});

const result = await renderer.render(template);

مقارنة التكلفة

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

معايير الأداء

يحقق العرض السحابي تسريعًا بمقدار 10-50 مرة مقارنة بالعرض التسلسلي على جهاز واحد. يعتمد التسريع الدقيق على عدد العمال وتعقيد القالب ومدة الفيديو.

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

العرض المحلي بـ Docker

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

متى تستخدم عرض Docker

• عرض متوازٍ مجاني بدون حسابات مزود سحابي
• بنية تحتية مستضافة ذاتيًا خلف جدار حماية
• التطوير والاختبار لسير عمل العرض السحابي محليًا
• أحمال عمل صغيرة إلى متوسطة تستفيد من التوازي ولكن لا تحتاج إلى توسع تلقائي

التثبيت

# تأكد من تثبيت Docker وتشغيله
docker --version

# تثبيت حزمة العرض السحابي
npm install @rendervid/cloud-rendering

التكوين

import { CloudRenderer } from "@rendervid/cloud-rendering";

const renderer = new CloudRenderer({
  provider: "docker",
  quality: "high",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  dockerConfig: {
    volumePath: "/tmp/rendervid-work",
    workersCount: 8, // عدد حاويات Docker للتشغيل بالتوازي
  },
});

const result = await renderer.render(template);
console.log(`Rendered in ${result.renderTime}ms using ${result.workersUsed} workers`);

اختيار workersCount: اضبط هذا على عدد أنوية وحدة المعالجة المركزية المتاحة على جهازك. على سبيل المثال، يعمل جهاز بـ 8 أنوية بشكل جيد مع 8 عمال. الذهاب إلى ما بعد عدد الأنوية يضيف تكلفة من تبديل السياق دون تحسين الإنتاجية.

بنية Docker

+------------------+
|   Coordinator    |
|  (your process)  |
+--------+---------+
         |
   +-----+-----+-----+-----+
   |     |     |     |     |
+--v--+ +--v-+ +-v--+ +-v--+
| C1  | | C2 | | C3 | | C4 |  ... Docker containers
+--+--+ +--+-+ +-+--+ +-+--+
   |      |     |      |
   v      v     v      v
+--+------+-----+------+--+
|    Shared Volume          |
|    /tmp/rendervid-work    |
+-------------+-------------+
              |
              v
      +-------+--------+
      |     Merger      |
      +-------+---------+
              |
              v
      +-------+---------+
      |  /output/video  |
      +-----------------+

كل حاوية Docker هي عامل مستقل مع Node.js وPlaywright وFFmpeg مثبتة مسبقًا. يقرأ العمال تعييناتهم من الإطارات من المجلد المشترك، ويعرضون الإطارات، ويكتبون النتائج مرة أخرى. ثم يدمج المنسق جميع المقاطع في الإخراج النهائي.

ضبابية الحركة

يدعم Rendervid ضبابية الحركة من خلال العينات الفائقة الزمنية. بدلاً من عرض لحظة واحدة لكل إطار، يلتقط العارض إطارات فرعية متعددة في نقاط زمنية مختلفة قليلاً ويمزجها معًا. ينتج عن هذا الضبابية الطبيعية التي تنشئها الكاميرات عندما تتحرك الكائنات أثناء التعرض.

إعدادات الجودة المسبقة

التكوين

const result = await renderer.render(template, {
  format: "mp4",
  quality: "high",
  outputPath: "/output/cinematic.mp4",
  motionBlur: {
    enabled: true,
    quality: "high", // 16 عينة لكل إطار
  },
});

كيف تعمل العينات الفائقة الزمنية

Frame N (no motion blur):          Frame N (with motion blur, 5 samples):

  Single instant:                    5 sub-frames blended:

  +--------+                         +--------+   +--------+   +--------+
  |    O   |                         |   O    | + |    O   | + |     O  |  ...
  +--------+                         +--------+   +--------+   +--------+
                                              |
                                              v
                                     +--------+
                                     |  ~O~   |  <- Blended result
                                     +--------+

يدفع كل إطار فرعي الجدول الزمني للرسوم المتحركة بزيادة صغيرة (1/fps مقسومًا على عدد العينات). ثم يتم مزج الإطارات الفرعية بألفا لإنتاج الإطار النهائي. تظهر الكائنات التي تحركت بين الإطارات الفرعية ضبابية على طول مسار حركتها، بينما تظل العناصر الثابتة حادة.

اعتبارات الأداء

تضاعف ضبابية الحركة وقت العرض بشكل متناسب مع عدد العينات. يحتوي فيديو مدته 10 ثوانٍ بمعدل 30 إطارًا في الثانية على 300 إطار. مع جودة high (16 عينة)، يجب على العارض إنشاء 4,800 إطار فرعي بدلاً من 300. استخدم جودة draft أثناء التطوير وانتقل إلى high أو ultra للصادرات النهائية فقط.

يعمل العرض السحابي وعرض Docker المتوازي بشكل جيد مع ضبابية الحركة لأن تكلفة كل إطار يتم توزيعها عبر العمال. زيادة 16 مرة لكل إطار مقسومة على 16 عاملاً تؤدي إلى نفس وقت العرض الإجمالي تقريبًا كعرض غير ضبابي على جهاز واحد.

تصدير GIF

يتجاوز تصدير GIF في Rendervid مجرد تحويل إطار إلى GIF بسيط. يستخدم خط أنابيب توليد اللوحة في FFmpeg لإنتاج صور GIF متحركة محسّنة عالية الجودة مع تدرج قابل للتكوين وأعداد ألوان وقيود حجم الملف.

كيف يعمل تحسين GIF

يستخدم ترميز GIF القياسي لوحة عالمية واحدة من 256 لونًا، مما يؤدي غالبًا إلى شرائط وإعادة إنتاج ألوان ضعيفة. يستخدم Rendervid نهجًا من مرحلتين:

1. المرحلة 1 (palettegen): تحليل جميع الإطارات لإنشاء لوحة مثلى من 256 لونًا تمثل نطاق الألوان الكامل للفيديو بشكل أفضل.
2. المرحلة 2 (paletteuse): إعادة ترميز كل إطار باستخدام اللوحة المحسّنة مع تدرج اختياري للتدرجات السلسة.

إعدادات التحسين المسبقة

خيارات التدرج

التكوين

const result = await renderer.render(template, {
  format: "gif",
  outputPath: "/output/animation.gif",
  gif: {
    preset: "social",       // دقة 480x480
    colors: 256,            // لوحة ألوان 2-256
    dithering: "floyd_steinberg",
    targetSizeKB: 5000,     // تحسين تلقائي للبقاء تحت 5 ميجابايت
    fps: 15,                // FPS أقل = ملف أصغر
  },
});

console.log(`GIF size: ${(result.fileSize / 1024).toFixed(0)} KB`);
console.log(`Estimated size was: ${result.estimatedSizeKB} KB`);

تقدير حجم الملف والتحسين التلقائي

عندما تعين targetSizeKB، يقدر Rendervid حجم ملف الإخراج قبل العرض ويضبط المعلمات تلقائيًا (عدد الألوان، الدقة، FPS) لتلبية الهدف. هذا مفيد بشكل خاص للمنصات ذات حدود حجم الملف (مثل حد Slack البالغ 50 ميجابايت، قيد البريد الإلكتروني النموذجي البالغ 10 ميجابايت).

// تحسين تلقائي للتناسب ضمن قيد البريد الإلكتروني البالغ 2 ميجابايت
const result = await renderer.render(template, {
  format: "gif",
  outputPath: "/output/email-banner.gif",
  gif: {
    preset: "email",
    targetSizeKB: 2000,
  },
});

بنية الحزمة

تم تنظيم Rendervid كمستودع أحادي مع 13 حزمة. كل حزمة لها مسؤولية مركزة، وتتكون معًا لدعم كل سيناريو نشر.

@rendervid/
├── core                    المحرك، الأنواع، التحقق، نظام الرسوم المتحركة
│   ├── محلل ومدقق القالب (AJV + JSON Schema)
│   ├── محرك الرسوم المتحركة (أكثر من 40 إعدادًا مسبقًا، أكثر من 30 وظيفة تخفيف)
│   ├── نظام الطبقات (نص، صورة، فيديو، شكل، صوت، مجموعة، lottie، مخصص)
│   └── إدارة المشهد والانتقالات (17 نوعًا)
│
├── renderer-browser        العرض من جانب العميل
│   ├── عرض إطار قائم على Canvas
│   ├── MediaRecorder لتصدير WebM
│   └── مشفر MP4 WebAssembly
│
├── renderer-node           العرض من جانب الخادم
│   ├── متصفح بدون رأس Playwright/Puppeteer
│   ├── تكامل FFmpeg (fluent-ffmpeg)
│   ├── تسريع GPU
│   └── خط أنابيب تحسين GIF
│
├── cloud-rendering         تنسيق متعدد السحابة
│   ├── مزود AWS Lambda
│   ├── مزود Azure Functions
│   ├── مزود Google Cloud Functions
│   ├── مزود Docker المحلي
│   ├── مقسم الأجزاء والدامج
│   └── محولات تخزين الكائنات (S3، Blob، GCS)
│
├── player                  مكون مشغل الفيديو/القالب
├── editor                  محرر القالب المرئي (حالة Zustand)
├── components              مكونات React مسبقة الصنع
│   ├── AnimatedLineChart
│   ├── AuroraBackground
│   ├── WaveBackground
│   ├── SceneTransition
│   └── TypewriterEffect
│
├── templates               تعريفات القوالب والأمثلة (أكثر من 100)
├── testing                 أدوات الاختبار
│   ├── مطابقات Vitest المخصصة
│   ├── مساعدي اختبار اللقطة
│   └── أدوات الانحدار البصري
│
├── editor-playground       بيئة تطوير المحرر
├── player-playground       بيئة تطوير المشغل
├── mcp                     خادم بروتوكول سياق النموذج
└── docs                    موقع توثيق VitePress

كيف تتصل الحزم

• @rendervid/core هو الأساس. تعتمد كل حزمة أخرى عليه لأنواع القوالب والتحقق ونظام الرسوم المتحركة.
• @rendervid/renderer-browser و**@rendervid/renderer-node** كلاهما يستهلك قوالب أساسية ولكن يخرج من خلال خطوط أنابيب مختلفة (Canvas مقابل FFmpeg).
• @rendervid/cloud-rendering يلف renderer-node ويوزع عمله عبر وظائف السحابة أو حاويات Docker.
• @rendervid/player و**@rendervid/editor** هما حزم واجهة مستخدم قائمة على React للتشغيل والتحرير المرئي. يستخدم المحرر Zustand لإدارة الحالة.
• @rendervid/components يوفر المكونات المسبقة الصنع من React (AnimatedLineChart، AuroraBackground، إلخ) التي يمكن استخدامها في القوالب.
• @rendervid/testing يوفر مطابقات Vitest ومساعدي اختبار اللقطة للتحقق من صحة القوالب.
• mcp هي طبقة تكامل الذكاء الاصطناعي التي تعرض قدرات Rendervid لوكلاء الذكاء الاصطناعي عبر بروتوكول سياق النموذج.

مجموعة التكنولوجيا

تم بناء Rendervid على مجموعة TypeScript حديثة تم اختيارها للموثوقية والأداء وتجربة المطور.

الاختبار

يتضمن Rendervid حزمة اختبار مخصصة (@rendervid/testing) توفر مطابقات Vitest المخصصة ومساعدي اختبار اللقطة وأدوات الانحدار البصري للتحقق من صحة القوالب.

مطابقات Vitest المخصصة

import { describe, it, expect } from "vitest";
import "@rendervid/testing/matchers";

describe("Product Showcase Template", () => {
  it("should be a valid template", () => {
    expect(template).toBeValidTemplate();
  });

  it("should have the correct dimensions", () => {
    expect(template).toHaveResolution(1920, 1080);
  });

  it("should contain at least one text layer", () => {
    expect(template).toContainLayerOfType("text");
  });

  it("should have animations on the headline", () => {
    expect(template.scenes[0].layers[0]).toHaveAnimation("entrance");
  });
});

اختبار اللقطة

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

import { describe, it } from "vitest";
import { renderSnapshot } from "@rendervid/testing";

describe("Template Visual Regression", () => {
  it("should match the reference snapshot at frame 0", async () => {
    const snapshot = await renderSnapshot(template, { frame: 0 });
    expect(snapshot).toMatchImageSnapshot();
  });

  it("should match the reference snapshot at the midpoint", async () => {
    const totalFrames = template.fps * template.scenes[0].duration;
    const snapshot = await renderSnapshot(template, {
      frame: Math.floor(totalFrames / 2),
    });
    expect(snapshot).toMatchImageSnapshot();
  });
});

اختبار الانحدار البصري في CI

دمج اختبارات الانحدار البصري في خط أنابيب CI/CD الخاص بك لاكتشاف تغييرات العرض قبل وصولها إلى الإنتاج:

# .github/workflows/visual-regression.yml
name: Visual Regression Tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npx playwright install chromium
      - run: npm ci
      - run: npm run test:visual

تحسين الأداء

الحصول على أسرع أوقات العرض الممكنة يتطلب فهم أين يتم قضاء الوقت وأي الرافعات يمكنك سحبها. فيما يلي استراتيجيات التحسين الأكثر تأثيرًا.

1. اختر هدف النشر الصحيح

2. تحسين تعقيد القالب

• تقليل عدد الطبقات. يتم عرض كل طبقة بشكل مستقل. طبقات أقل تعني عمليات رسم أقل لكل إطار.
• استخدم جودة draft أثناء التطوير والاختبار. انتقل إلى high أو lossless فقط للصادرات النهائية.
• تبسيط الرسوم المتحركة أثناء المعاينة. تضيف تسلسلات الإطار الرئيسي المعقدة مع العديد من وظائف التخفيف حسابًا لكل إطار.

3. استخدم renderWaitTime بحكمة

يوقف خيار renderWaitTime العرض للسماح بتحميل الوسائط الخارجية (الصور، مقاطع الفيديو، الخطوط). اضبط هذا على الحد الأدنى من القيمة التي تضمن تحميل جميع الأصول. قيمة 500-2000 ميلي ثانية نموذجية. تعيينها عالية جدًا يضيع الوقت على كل إطار.

await renderer.render(template, {
  renderWaitTime: 1000, // ثانية واحدة عادة ما تكون كافية
});

4. استفد من العرض المتوازي

لأي فيديو أطول من 10 ثوانٍ، سيكون العرض المتوازي (Docker أو السحابة) أسرع من العرض التسلسلي. تعتمد نقطة التعادل على أجهزتك وتكوين السحابة، ولكن كقاعدة عامة:

• < 10 ثوانٍ: عارض Node.js واحد جيد
• 10-60 ثانية: Docker مع 4-8 عمال
• 1-10 دقائق: Docker مع 8-16 عاملاً أو السحابة
• > 10 دقائق: العرض السحابي مع أكثر من 50 عاملاً

5. تحسين إخراج GIF

صور GIF كبيرة بطبيعتها. للحفاظ على أحجام الملفات قابلة للإدارة:

• خفض FPS إلى 10-15. تبدو معظم صور GIF جيدة بمعدلات إطارات مخفضة.
• تقليل الدقة باستخدام الإعدادات المسبقة (social، web، email).
• تحديد الألوان إلى 128 أو أقل للرسوم المتحركة البسيطة.
• استخدم targetSizeKB للسماح لـ Rendervid بتحسين المعلمات تلقائيًا.
• تجنب التدرج (none) إذا كان حجم الملف أهم من جودة التدرج.

6. تمكين تسريع GPU

على الأجهزة ذات وحدات معالجة الرسومات المتوافقة، يمكن أن يقلل الترميز المسرع بالأجهزة من أوقات العرض بمقدار 2-5 مرات لخطوة الترميز. هذا هو الأكثر تأثيرًا للدقة العالية (4K+) والإخراج عالي معدل البت.

7. تحميل الأصول مسبقًا

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

الخطوات التالية

• ابدأ مع Rendervid: قم بزيارة نظرة عامة على Rendervid للتثبيت والعرض الأول
• تعلم نظام القوالب: اقرأ توثيق نظام القوالب لبنية قالب JSON والمتغيرات والمشاهد والطبقات والرسوم المتحركة
• استكشف المكونات: تصفح مكتبة المكونات للمكونات المسبقة الصنع من React مثل AnimatedLineChart وAuroraBackground
• إعداد تكامل الذكاء الاصطناعي: راجع دليل تكامل الذكاء الاصطناعي لتوصيل Claude Code أو Cursor أو Windsurf بـ Rendervid عبر MCP
• عرض المصدر: قم بزيارة مستودع Rendervid على GitHub للحصول على الكود المصدري الكامل وأكثر من 100 قالب مثال