Skip to content

Open source CapCut alternative.

TypeScript

test(site): timebase guard over the export filtergraph's xfade joins

Claude2f4843cde75a
diff --git a/site/src/cut/server/exportPipeline.test.ts b/site/src/cut/server/exportPipeline.test.ts
new file mode 100644
index 00000000..133ce2f5
--- /dev/null
+++ b/site/src/cut/server/exportPipeline.test.ts
@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test";
+import {
+ runExport,
+ type ExportPipelineIO,
+ type ExportSpec,
+ type RenderHandle,
+} from "./exportPipeline";
+
+// Builds the real encode filtergraph for a spec by running the pipeline with
+// its edges stubbed: media exists, every stream probes present, SDR color,
+// libx264, and ffmpeg runs are captured instead of spawned.
+const graphFor = async (over: Partial<ExportSpec>): Promise<string[]> => {
+ const ffmpegCalls: string[][] = [];
+ const io: ExportPipelineIO = {
+ stat: (async () => ({ isFile: () => true })) as unknown as ExportPipelineIO["stat"],
+ writeFile: (async () => {}) as unknown as ExportPipelineIO["writeFile"],
+ hasStream: async () => true,
+ videoColorInfo: async () => null,
+ h264Encoder: async () => "libx264",
+ runFfmpeg: async (_job, args) => {
+ ffmpegCalls.push(args);
+ },
+ };
+ const clips = over.clips ?? [];
+ const spec: ExportSpec = {
+ projectId: "p",
+ width: 1080,
+ height: 1920,
+ fps: 30,
+ crf: 24,
+ preset: "veryfast",
+ duration: clips.reduce(
+ (s, c) => s + (c.out - c.in) / (c.speed && c.speed > 0 ? c.speed : 1),
+ 0
+ ),
+ clips,
+ audio: [],
+ overlays: [],
+ ...over,
+ };
+ const job: RenderHandle = {
+ tmpDir: "/tmp/graph-test",
+ outPath: "/tmp/graph-test/out.mp4",
+ progress: 0,
+ log: [],
+ };
+ await runExport(job, spec, (f) => `/media/${f}`, io);
+ const enc = ffmpegCalls[0];
+ return enc[enc.indexOf("-filter_complex") + 1].split(";");
+};
+
+type Clip = ExportSpec["clips"][number];
+const clip = (file: string, over: Partial<Clip> = {}): Clip => ({
+ file,
+ in: 0,
+ out: 4,
+ muted: false,
+ ...over,
+});
+
+// ---------------------------------------------------------------------------
+// A model of ffmpeg's link negotiation, as far as xfade cares: each stream
+// carries a timebase and a constant-frame-rate stamp. `fps` (and a `color`
+// source with `r=`) stamps 1/rate; the concat filter resets its output to the
+// microsecond timebase with no rate; `trim`/`setpts` keep the timebase but
+// clear the rate; every other filter passes its first input through. xfade
+// aborts the whole export when its two inputs differ — the mismatch this
+// model exists to catch:
+// [Parsed_xfade] First input link main timebase (1/1000000) do not match
+// the corresponding second input link xfade timebase (1/30)
+// ---------------------------------------------------------------------------
+
+type Pad = { tb: string; cfr: boolean };
+
+const argValue = (args: string, key: string) =>
+ new RegExp(`(?:^|:)${key}=([0-9.]+)`).exec(args)?.[1];
+
+/** Split a chain body on top-level commas; quoted spans (enable exprs) stay
+ * whole. */
+const splitFilters = (body: string): string[] => {
+ const parts: string[] = [];
+ let cur = "";
+ let quoted = false;
+ for (const ch of body) {
+ if (ch === "'") quoted = !quoted;
+ if (ch === "," && !quoted) {
+ parts.push(cur);
+ cur = "";
+ } else cur += ch;
+ }
+ parts.push(cur);
+ return parts.map((p) => p.trim()).filter((p) => p.length > 0);
+};
+
+const parseChain = (raw: string) => {
+ const inputs: string[] = [];
+ let rest = raw;
+ for (let m; (m = /^\[([^\]]+)\]/.exec(rest)); ) {
+ inputs.push(m[1]);
+ rest = rest.slice(m[0].length);
+ }
+ const outs: string[] = [];
+ for (let m; (m = /\[([^\]]+)\]$/.exec(rest)); ) {
+ outs.unshift(m[1]);
+ rest = rest.slice(0, -m[0].length);
+ }
+ return { raw, inputs, outs, filters: splitFilters(rest) };
+};
+
+const pad = (p: Pad) => `${p.tb}${p.cfr ? "" : " (no rate)"}`;
+
+/** Walks every chain of the graph, propagating each labeled stream's pad
+ * state, and reports every xfade whose two inputs arrive with different
+ * timebases or without a constant-rate stamp. Chains wait until all their
+ * input labels are defined, so definition order in the graph is free. */
+const xfadeMismatches = (chains: string[]): string[] => {
+ const problems: string[] = [];
+ const states = new Map<string, Pad>();
+ const inputState = (label: string): Pad | undefined =>
+ states.get(label) ??
+ (/^\d+:[va]$/.test(label) ? { tb: `source ${label}`, cfr: false } : undefined);
+ const pending = chains.map(parseChain);
+ let progressed = true;
+ while (pending.length > 0 && progressed) {
+ progressed = false;
+ for (let i = 0; i < pending.length; i++) {
+ const { raw, inputs, outs, filters } = pending[i];
+ const inStates = inputs.map(inputState);
+ if (inStates.some((s) => s === undefined)) continue;
+ pending.splice(i--, 1);
+ progressed = true;
+ let cur: Pad = inStates[0] ?? { tb: "generated", cfr: false };
+ filters.forEach((f, fi) => {
+ const eq = f.indexOf("=");
+ const name = eq === -1 ? f : f.slice(0, eq);
+ const args = eq === -1 ? "" : f.slice(eq + 1);
+ if (name === "fps") {
+ cur = { tb: `1/${argValue(args, "fps") ?? /^([\d.]+)/.exec(args)?.[1]}`, cfr: true };
+ } else if (name === "color") {
+ cur = { tb: `1/${argValue(args, "r") ?? argValue(args, "rate") ?? "25"}`, cfr: true };
+ } else if (name === "xfade") {
+ if (fi !== 0 || inputs.length !== 2) {
+ problems.push(`xfade needs two chain-leading inputs: ${raw}`);
+ } else {
+ const [a, b] = inStates as Pad[];
+ if (!a.cfr || !b.cfr || a.tb !== b.tb) {
+ problems.push(`xfade inputs mismatch — ${pad(a)} vs ${pad(b)}: ${raw}`);
+ }
+ }
+ } else if (name === "concat") {
+ cur = { tb: "1/1000000 (concat)", cfr: false };
+ } else if (name === "trim" || name === "setpts") {
+ cur = { tb: cur.tb, cfr: false };
+ }
+ });
+ for (const o of outs) states.set(o, cur);
+ }
+ }
+ for (const p of pending) problems.push(`inputs never defined: ${p.raw}`);
+ return problems;
+};
+
+describe("export filtergraph timebases", () => {
+ test("the model flags a transition joined onto a bare concat", () => {
+ const join = (cut: string) => [
+ "[0:v]fps=30[s0]",
+ "[1:v]fps=30[s1]",
+ `[s0][s1]${cut}[cut]`,
+ "[2:v]fps=30[s2]",
+ "[s2]tpad=start_duration=0.500:start_mode=clone[h2]",
+ "[cut][h2]xfade=transition=fade:duration=0.500:offset=7.500[out]",
+ ];
+ expect(xfadeMismatches(join("concat=n=2:v=1:a=0"))).toHaveLength(1);
+ expect(xfadeMismatches(join("concat=n=2:v=1:a=0,fps=30"))).toEqual([]);
+ });
+
+ test("a transition after a hard cut joins matched streams", async () => {
+ const g = await graphFor({
+ clips: [
+ clip("a.mp4"),
+ clip("b.mp4", { transition: 0.5, transitionStyle: "crossfade" }),
+ clip("c.mp4"),
+ ],
+ });
+ expect(g.join(";")).toContain("xfade=");
+ expect(xfadeMismatches(g)).toEqual([]);
+ });
+
+ test("every join transitioned, styles mixed", async () => {
+ const g = await graphFor({
+ clips: [
+ clip("a.mp4", { transition: 0.4, transitionStyle: "crossfade" }),
+ clip("b.mp4", { transition: 0.4, transitionStyle: "pushleft" }),
+ clip("c.mp4", { transition: 0.4, transitionStyle: "circleopen" }),
+ clip("d.mp4"),
+ ],
+ });
+ expect(g.filter((c) => c.includes("xfade=")).length).toBeGreaterThanOrEqual(3);
+ expect(xfadeMismatches(g)).toEqual([]);
+ });
+
+ test("a transition into a gap slot", async () => {
+ const g = await graphFor({
+ clips: [
+ clip("a.mp4", { transition: 0.5, transitionStyle: "crossfade" }),
+ clip("", { out: 2 }),
+ clip("b.mp4"),
+ ],
+ });
+ expect(g.join(";")).toContain("xfade=");
+ expect(xfadeMismatches(g)).toEqual([]);
+ });
+
+ test("cross zoom, edge animations, speed, stills, gaps, overlays, and sound", async () => {
+ const g = await graphFor({
+ clips: [
+ clip("a.mp4", {
+ transition: 0.6,
+ transitionStyle: "crosszoom",
+ animIn: { style: "slideleft", seconds: 0.4 },
+ }),
+ clip("b.mp4", { speed: 2 }),
+ clip("", { out: 2 }),
+ clip("c.png", { image: true, animOut: { style: "slideup", seconds: 0.4 } }),
+ clip("d.mp4", { transition: 0.5, transitionStyle: "dipblack" }),
+ clip("e.mp4", { animOut: { style: "pop", seconds: 0.4 } }),
+ ],
+ overlayVideos: [
+ {
+ file: "ov.mp4",
+ in: 0,
+ out: 2,
+ start: 1,
+ track: 1,
+ muted: true,
+ headFade: 0.3,
+ tailZoom: 0.3,
+ },
+ ],
+ audio: [{ file: "music.mp3", in: 0, out: 5, start: 0, volume: 0.8, fadeIn: 0.2 }],
+ captions: [{ file: "cap1.png", start: 0, end: 2 }],
+ fadeIn: 0.5,
+ });
+ expect(g.join(";")).toContain("xfade=");
+ expect(xfadeMismatches(g)).toEqual([]);
+ });
+});
diff --git a/site/src/cut/server/exportPipeline.ts b/site/src/cut/server/exportPipeline.ts
index dca268b0..c5342e51 100644
--- a/site/src/cut/server/exportPipeline.ts
+++ b/site/src/cut/server/exportPipeline.ts
@@ -194,9 +194,13 @@ function vtQuality(crf: number) {
return Math.round(Math.max(35, Math.min(80, 100 - crf * 1.8)));
}
-async function resolveMedia(mediaPathFor: (file: string) => string, file: string) {
+async function resolveMedia(
+ statFn: typeof stat,
+ mediaPathFor: (file: string) => string,
+ file: string
+) {
const p = mediaPathFor(file);
- const info = await stat(p).catch(() => null);
+ const info = await statFn(p).catch(() => null);
if (!info?.isFile()) throw new Error(`Media file missing from project: ${file}`);
return p;
}
@@ -313,6 +317,21 @@ export function runFfmpeg(
});
}
+/** The pipeline's edges into the world: staged-media checks, list-file
+ * writes, stream probes, the encoder probe, and the ffmpeg runs. `runExport`
+ * takes them as a parameter so the filtergraph tests can build the real graph
+ * for a spec with these stubbed. */
+export interface ExportPipelineIO {
+ stat: typeof stat;
+ writeFile: typeof writeFile;
+ hasStream: typeof hasStream;
+ videoColorInfo: typeof videoColorInfo;
+ h264Encoder: () => Promise<"libx264" | "h264_videotoolbox">;
+ runFfmpeg: typeof runFfmpeg;
+}
+
+const realIO: ExportPipelineIO = { stat, writeFile, hasStream, videoColorInfo, h264Encoder, runFfmpeg };
+
/** Render `spec` into `job.outPath`. `mediaPathFor` maps a spec media file
* name to its staged path on disk (the engine reads the project folder; the
* worker reads its download dir); overlay/caption PNGs are read from
@@ -320,7 +339,8 @@ export function runFfmpeg(
export async function runExport(
job: RenderHandle,
spec: ExportSpec,
- mediaPathFor: (file: string) => string
+ mediaPathFor: (file: string) => string,
+ io: ExportPipelineIO = realIO
) {
if (spec.clips.length === 0) throw new Error("Nothing to export.");
const { width: W, height: H, fps } = spec;
@@ -361,7 +381,7 @@ export async function runExport(
let nInputs = 0;
// Resolve paths in order first so ffmpeg input indices stay deterministic,
// then probe every file's streams concurrently.
- const paths = await Promise.all(mediaFiles.map((f) => resolveMedia(mediaPathFor, f)));
+ const paths = await Promise.all(mediaFiles.map((f) => resolveMedia(io.stat, mediaPathFor, f)));
mediaFiles.forEach((f, i) => {
inputIndex.set(f, nInputs++);
inputs.push("-i", paths[i]);
@@ -373,13 +393,13 @@ export async function runExport(
// video to black. Genuine absence returns false with no error, so on a
// probe error we assume the stream is present and let ffmpeg map it.
let audioProbeFailed = false;
- const hasAudio = await hasStream(paths[i], "a", () => (audioProbeFailed = true));
+ const hasAudio = await io.hasStream(paths[i], "a", () => (audioProbeFailed = true));
audioPresence.set(f, hasAudio || audioProbeFailed);
let videoProbeFailed = false;
- const hasVideo = await hasStream(paths[i], "v", () => (videoProbeFailed = true));
+ const hasVideo = await io.hasStream(paths[i], "v", () => (videoProbeFailed = true));
videoPresence.set(f, hasVideo || videoProbeFailed);
// A failed color probe (null) means no conversion — SDR passthrough.
- colorFix.set(f, sdrConvert(await videoColorInfo(paths[i])));
+ colorFix.set(f, sdrConvert(await io.videoColorInfo(paths[i])));
})
);
// Animated overlays: each is its own concat-demuxer slideshow (region-sized
@@ -405,7 +425,7 @@ export async function runExport(
lines.push(`file '${blank}'`, `duration ${num(spec.duration - cursor)}`);
}
const list = path.join(job.tmpDir, `overlay_anim_${k}.ffconcat`);
- await writeFile(list, lines.join("\n") + "\n");
+ await io.writeFile(list, lines.join("\n") + "\n");
animOverlayInput.set(k, nInputs++);
inputs.push("-f", "concat", "-safe", "0", "-i", list);
} else if (o.file) {
@@ -428,7 +448,7 @@ export async function runExport(
if (!c.image || !c.file) continue;
const dur = Math.max(0.1, (c.out - c.in) / clipRate(c));
imageClipInput.set(j, nInputs++);
- inputs.push("-loop", "1", "-t", num(dur), "-framerate", String(fps), "-i", await resolveMedia(mediaPathFor, c.file));
+ inputs.push("-loop", "1", "-t", num(dur), "-framerate", String(fps), "-i", await resolveMedia(io.stat, mediaPathFor, c.file));
}
const imageOverlayInput = new Map<(typeof overlayVideos)[number], number>();
for (const oc of overlayVideos) {
@@ -436,7 +456,7 @@ export async function runExport(
const ospeed = oc.speed && oc.speed > 0 ? oc.speed : 1;
const olen = Math.max(0.1, (oc.out - oc.in) / ospeed);
imageOverlayInput.set(oc, nInputs++);
- inputs.push("-loop", "1", "-t", num(olen), "-framerate", String(fps), "-i", await resolveMedia(mediaPathFor, oc.file));
+ inputs.push("-loop", "1", "-t", num(olen), "-framerate", String(fps), "-i", await resolveMedia(io.stat, mediaPathFor, oc.file));
}
// One concat-demuxer input per subtitle track: within a track cues never
@@ -470,7 +490,7 @@ export async function runExport(
lines.push(`file '${blank}'`, `duration ${num(spec.duration - cursor)}`);
}
const list = path.join(job.tmpDir, `captions_${lane}.ffconcat`);
- await writeFile(list, lines.join("\n") + "\n");
+ await io.writeFile(list, lines.join("\n") + "\n");
captionInputs.push(nInputs++);
inputs.push("-f", "concat", "-safe", "0", "-i", list);
}
@@ -1197,7 +1217,7 @@ export async function runExport(
aLabel = "afinal";
}
- const enc = await h264Encoder();
+ const enc = await io.h264Encoder();
const videoCodecArgs =
enc === "libx264"
? ["-c:v", "libx264", "-preset", spec.preset, "-crf", String(spec.crf)]
@@ -1207,7 +1227,7 @@ export async function runExport(
// rotation flag (see the strip pass below). Keeping the encode intermediate
// lets the second pass own faststart.
const encodePath = path.join(job.tmpDir, "encode.mp4");
- await runFfmpeg(
+ await io.runFfmpeg(
job,
[
"-y",
@@ -1238,7 +1258,7 @@ export async function runExport(
// "desktop" frame. `-display_rotation 0` overrides that matrix to identity; a
// stream copy re-emits the (already correct) pixels and audio unchanged and
// writes the faststart-optimized final file.
- await runFfmpeg(job, [
+ await io.runFfmpeg(job, [
"-y",
"-display_rotation", "0",
"-i", encodePath,