ازالة خلفية الفيديو باستخدام JavaScript و Node.js

JavaScript خيار مناسب لاتمتة ازالة خلفية الفيديو. بدلا من رفع كل مقطع يدويا، يمكنك ارسال الفيديو من Node.js، ثم يزيل Unscreen الخلفية، وبعدها تحمل النتيجة من سكربت، مسار backend، worker، او نظام معالجة محتوى.

يوضح هذا الدليل استخدام @unscreen/video-background-remover من التثبيت حتى طريقتين اساسيتين:

• الانتظار حتى يكتمل العمل باستخدام wait
• ارسال العمل بدون انتظار واستقبال النتيجة عبر webhook

1. تثبيت المكتبة

المكتبة منشورة كحزمة npm Node.js وتحتاج Node.js 20 او احدث.

npm install @unscreen/video-background-remover

احفظ مفتاح API في متغير بيئة:

export UNSCREEN_API_KEY="your_api_key_here"

في الانتاج، ضع هذا المتغير في اعدادات الخادم او اسرار الاستضافة او CI. لا تضع مفتاح API في JavaScript يعمل داخل المتصفح.

2. انشاء العميل

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

يمكنك اعادة استخدام هذا العميل داخل كود الخادم الذي يرسل الاعمال.

3. ابسط طريقة مع الانتظار

الدالة removeBackground هي اسرع مسار. عند عدم تمرير webhookUrl، تنتظر انتهاء العمل بشكل افتراضي.

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

await unscreen.removeBackground({
  input: "./input.mp4",
  output: "./output.mp4",
  mode: "auto",
});

console.log("تم حفظ الملف في ./output.mp4");

هذا المسار ينشئ العمل، يرفع الفيديو المحلي، يبدأ المعالجة، ينتظر الحالة النهائية، ثم يكتب فيديو الخرج.

خيار mode يقبل auto او human_only. استخدم auto عندما تريد من Unscreen اكتشاف العنصر الامامي تلقائيا، واستخدم human_only عندما يجب ان يركز المقطع على الاشخاص فقط كعنصر امامي.

4. التحكم اليدوي باستخدام "jobs.wait"

اذا اردت التحكم في كل خطوة، استخدم jobs.submit ثم jobs.wait ثم jobs.download.

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

const started = await unscreen.jobs.submit({
  input: "./input.mp4",
  mode: "auto",
});

console.log(`تم بدء العمل: ${started.jobId}`);

const completed = await unscreen.jobs.wait(started.jobId, {
  intervalMs: 2000,
  timeoutMs: 10 * 60 * 1000,
});

await unscreen.jobs.download(completed, {
  asset: "outputVideo",
  path: "./output.mp4",
});

تقوم jobs.wait بفحص الحالة حتى تصبح completed او failed. اذا فشل العمل، ترمي المكتبة UnscreenError. اذا تجاوز الانتظار الحد المحدد، ترمي UnscreenTimeoutError.

5. استخدام رابط فيديو بدلا من ملف محلي

الحقل input يقبل مسارا محليا، رابط HTTP(S)، او Blob، او ArrayBuffer، او Uint8Array.

await unscreen.removeBackground({
  input: "https://example.com/videos/demo.mp4",
  output: "./demo-no-background.mp4",
  mode: "auto",
});

اذا لم يرسل الرابط نوع فيديو واضحا، مرر contentType يدويا:

await unscreen.jobs.submit({
  input: "https://example.com/download?id=123",
  contentType: "video/mp4",
});

6. تحميل انواع مختلفة من النتائج

الاصل الافتراضي هو outputVideo، ويمكن طلب اصول اخرى عند توفرها:

await unscreen.jobs.download(completed, {
  asset: "alphaVideo",
  path: "./alpha.webm",
});

await unscreen.jobs.download(completed, {
  asset: "mask",
  path: "./mask.mp4",
});

الاصول المدعومة:

• outputVideo
• alphaVideo
• mask
• previewImage
• metadata

7. الارسال بدون انتظار باستخدام webhook

في تطبيقات الويب، لا يفضل ابقاء الطلب مفتوحا حتى تنتهي معالجة الفيديو. استخدم webhookUrl لاستقبال النتيجة لاحقا.

import { Unscreen } from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

const started = await unscreen.removeBackground({
  input: "./input.mp4",
  mode: "auto",
  webhookUrl: "https://example.com/api/webhooks/unscreen",
});

console.log(`تم ارسال ${started.jobId}; سيتم انتظار webhook`);

عند تمرير webhookUrl، لا تنتظر removeBackground بشكل افتراضي. تنتظر فقط اذا مررت wait: true.

8. استقبال webhook في Node.js

مثال بسيط باستخدام Express:

import express from "express";
import { writeFile } from "node:fs/promises";

const app = express();

app.use(express.json());

app.post("/api/webhooks/unscreen", async (req, res) => {
  const event = req.body;

  if (event.eventType === "video.completed") {
    console.log(`اكتمل العمل: ${event.jobId}`);

    if (event.resultUrl) {
      const response = await fetch(event.resultUrl);
      const arrayBuffer = await response.arrayBuffer();

      await writeFile(
        `./downloads/${event.jobId}.mp4`,
        Buffer.from(arrayBuffer)
      );
    }
  }

  if (event.eventType === "video.failed") {
    console.error(`فشل العمل: ${event.jobId}`);
  }

  res.sendStatus(200);
});

app.listen(3000);

في تطبيق حقيقي، احفظ jobId عند ارسال العمل، ثم حدث نفس السجل في قاعدة البيانات عندما يصل webhook.

9. استخدام نوع WebhookEvent

import type { WebhookEvent } from "@unscreen/video-background-remover";

export async function handleUnscreenWebhook(event: WebhookEvent) {
  if (event.eventType === "video.completed") {
    console.log(event.jobId, event.resultUrl);
    return;
  }

  if (event.eventType === "video.failed") {
    console.error(`فشل عمل Unscreen: ${event.jobId}`);
  }
}

اسماء الاحداث هي video.completed و video.failed.

10. اجبار الانتظار مع webhook

اذا احتجت webhook ونتيجة متزامنة في نفس الوقت، استخدم wait: true.

const completed = await unscreen.removeBackground({
  input: "./input.mp4",
  output: "./output.mp4",
  webhookUrl: "https://example.com/api/webhooks/unscreen",
  wait: true,
  waitOptions: {
    intervalMs: 3000,
    timeoutMs: 15 * 60 * 1000,
  },
});

console.log(completed.status);

هذا مفيد للادوات الداخلية، لكن اغلب تطبيقات المستخدمين تكون افضل مع webhook بدون انتظار.

11. فحص الرصيد قبل المعالجة

const balance = await unscreen.credits.getBalance();

console.log(`الرصيد المتبقي: ${balance.credits}`);

استخدم ذلك قبل ارسال عدد كبير من الفيديوهات الى queue.

12. التعامل مع الاخطاء

import {
  Unscreen,
  UnscreenError,
  UnscreenTimeoutError,
} from "@unscreen/video-background-remover";

const unscreen = new Unscreen({
  apiKey: process.env.UNSCREEN_API_KEY,
});

try {
  await unscreen.removeBackground({
    input: "./input.mp4",
    output: "./output.mp4",
    waitOptions: {
      timeoutMs: 10 * 60 * 1000,
    },
  });
} catch (error) {
  if (error instanceof UnscreenTimeoutError) {
    console.error("العمل ما زال يعمل. افحص الحالة لاحقا.");
  } else if (error instanceof UnscreenError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

الخلاصة: اختر wait للسكربتات والعمال المحددين. اختر webhooks للتطبيقات، الفيديوهات الطويلة، والمعالجة غير المتزامنة.