feat(react): add Raw element for ffmpeg escape hatch

[caffeinum]

Summary

• adds Raw element as an escape hatch from react layer to raw ffmpeg
• allows custom ffmpeg commands while integrating with the pipeline

Usage

import { render, Render, Clip, Video, Raw, Image } from "@vargai/react";

// apply ffmpeg filter to a video
const colorGraded = Raw({
  inputs: ["footage.mp4"],
  args: ["-vf", "colorbalance=rs=0.1:gs=-0.1:bs=0.05", "-c:a", "copy"],
});

// combine multiple inputs with filter_complex
const composited = Raw({
  inputs: ["background.mp4", "overlay.png"],
  args: [
    "-filter_complex", "[0:v][1:v]overlay=10:10[out]",
    "-map", "[out]",
    "-map", "0:a",
  ],
});

// chain Raw elements
const processed = Raw({
  inputs: [colorGraded],
  args: ["-vf", "eq=brightness=0.1", "-c:a", "copy"],
});

// use with generated elements
const generatedImage = Image({ prompt: "sunset" });
const withOverlay = Raw({
  inputs: ["video.mp4", generatedImage],
  args: ["-filter_complex", "[0:v][1:v]overlay=W-w-10:H-h-10[out]", "-map", "[out]"],
});

// use in pipeline
<Clip>
  <Video src={processed} />
</Clip>

API

interface RawProps {
  inputs: RawInput[];  // files, Uint8Arrays, or elements (Image, Video, Raw)
  args: string[];      // ffmpeg args after inputs
  output?: string;     // optional output path
}

type RawInput = string | Uint8Array | VargElement<"image"> | VargElement<"video"> | VargElement<"raw">;

Changes

• types.ts: add raw element type and RawProps
• elements.ts: add Raw() function
• renderers/raw.ts: new renderer that resolves inputs and executes ffmpeg
• renderers/video.ts: handle Raw element as src input
• index.ts: export Raw and RawProps

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch draft/raw-ffmpeg-escape-hatch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}