Open source CapCut alternative.
TypeScript
import { describe, expect, test } from "bun:test";
import {
clipAnimFx,
crossHandles,
duckGainAt,
heldSpans,
overlayPlan,
overlayTransitionFx,
prerollLead,
PREROLL_LEAD_S,
soundCrossGain,
trackZeroAt,
trackZeroPlan,
} from "./framePlan";
import { heldFrames } from "./frameGrid";
import { TRANSITION_BLUR, TRANSITION_ZOOM } from "./types";
import type { AudioClip, ClipSpan, MediaAsset, VideoClip } from "./types";
const asset: MediaAsset = {
id: "asset",
fileName: "a.mp4",
name: "a",
type: "video",
duration: 100,
url: "blob:a",
};
let nextId = 0;
const videoClip = (over: Partial<VideoClip> = {}): VideoClip => ({
id: `clip-${nextId++}`,
assetId: "asset",
track: 0,
start: 0,
in: 0,
out: 4,
muted: false,
...over,
});
/** Spans laid end to end, each dissolving into the next by `transitions[i]`. */
function spansOf(count: number, len = 4, transitions: number[] = []): ClipSpan[] {
const spans: ClipSpan[] = [];
let at = 0;
for (let i = 0; i < count; i++) {
const transitionOut = transitions[i] ?? 0;
spans.push({
clip: videoClip({ start: at, out: len, transitionStyle: undefined }),
asset,
start: at,
len,
transitionOut,
soundOut: 0,
soundAhead: 0,
soundBack: 0,
});
at += len; // clips abut — a transition is a blend at the cut, never overlap
}
return spans;
}
/** The same run, handing over on the sound: the picture cuts, and each cut's
* crossing runs `crosses[i]` either side of it. Both clips are trimmed out of
* a longer source, so each has the handle its side of a crossing reaches
* into. */
function soundSpansOf(count: number, len = 4, crosses: number[] = []): ClipSpan[] {
const spans = spansOf(count, len);
return spans.map((sp, i) => ({
...sp,
soundOut: crosses[i] ?? 0,
soundAhead: crosses[i] ?? 0,
soundBack: crosses[i - 1] ?? 0,
}));
}
describe("soundCrossGain", () => {
test("crosses the level over the cut while the picture stays a cut", () => {
const spans = soundSpansOf(2, 4, [2]);
const cut = spans[1].start;
// Nothing moves until the window opens, and it is done when it closes.
expect(soundCrossGain(spans, spans[0], cut - 2.5)).toBeCloseTo(1, 5);
expect(soundCrossGain(spans, spans[1], cut - 2)).toBeCloseTo(0, 5);
expect(soundCrossGain(spans, spans[0], cut + 2)).toBeCloseTo(0, 5);
expect(soundCrossGain(spans, spans[1], cut + 2.5)).toBeCloseTo(1, 5);
// The two sides meet on the cut itself, each at equal power's half.
expect(soundCrossGain(spans, spans[0], cut)).toBeCloseTo(Math.SQRT1_2, 5);
expect(soundCrossGain(spans, spans[1], cut)).toBeCloseTo(Math.SQRT1_2, 5);
// The picture never blends: no overlap, no incoming picture.
expect(trackZeroPlan(spans[0], spans, cut - 1).p).toBe(0);
expect(trackZeroPlan(spans[0], spans, cut - 1).incoming).toBe(null);
expect(trackZeroPlan(spans[0], spans, cut - 1).masterAlpha).toBe(1);
});
test("holds one loudness across the crossing", () => {
const spans = soundSpansOf(2, 4, [2]);
const cut = spans[1].start;
// Equal power: the two gains square to one everywhere in the window, so
// the mix neither dips nor swells through the join.
for (const t of [cut - 2, cut - 1.3, cut - 0.4, cut, cut + 0.6, cut + 1.7, cut + 2]) {
const going = soundCrossGain(spans, spans[0], t);
const coming = soundCrossGain(spans, spans[1], t);
expect(going * going + coming * coming).toBeCloseTo(1, 5);
}
});
test("both sides of a crossing sound past their own footprint", () => {
const spans = soundSpansOf(2, 4, [2]);
const cut = spans[1].start;
// The outgoing clip is still playing — on its handle — after the picture
// has cut, and the incoming one before it.
const after = crossHandles(spans, cut + 1);
expect(after.map((h) => h.span.clip.id)).toEqual([spans[0].clip.id]);
expect(after[0].gain).toBeCloseTo(Math.cos((0.75 * Math.PI) / 2), 5);
const before = crossHandles(spans, cut - 1);
expect(before.map((h) => h.span.clip.id)).toEqual([spans[1].clip.id]);
expect(before[0].gain).toBeCloseTo(Math.sin((0.25 * Math.PI) / 2), 5);
// Outside the crossing nothing sounds past its own footprint.
expect(crossHandles(spans, cut + 2.5)).toEqual([]);
});
test("a clip with no handle keeps its side of the crossing inside itself", () => {
// Both clips run to the ends of their sources: nothing to reach into, so
// the ramps stay put and only the ramps play.
const spans = soundSpansOf(2, 4, [2]).map((sp) => ({
...sp,
soundAhead: 0,
soundBack: 0,
}));
expect(crossHandles(spans, spans[1].start + 1)).toEqual([]);
expect(soundCrossGain(spans, spans[0], spans[1].start)).toBeCloseTo(Math.SQRT1_2, 5);
});
test("leaves a run with no cross dissolve at full level", () => {
const spans = soundSpansOf(2, 4);
expect(soundCrossGain(spans, spans[0], 3.9)).toBe(1);
expect(soundCrossGain(spans, spans[1], 4.1)).toBe(1);
});
});
describe("overlayTransitionFx", () => {
test("an upper-track cross dissolve moves the level and not the picture", () => {
const spans = soundSpansOf(2, 4, [2]);
const cut = spans[1].start;
const out = overlayTransitionFx(spans[0], undefined, spans[1], cut - 1);
expect(out.gain).toBeCloseTo(Math.cos((0.25 * Math.PI) / 2), 5);
expect(out.alpha).toBe(1);
const inc = overlayTransitionFx(spans[1], spans[0], undefined, cut + 1);
expect(inc.gain).toBeCloseTo(Math.sin((0.75 * Math.PI) / 2), 5);
expect(inc.alpha).toBe(1);
});
});
describe("trackZeroPlan", () => {
test("reports no transition in the middle of a clip", () => {
const spans = spansOf(2);
const plan = trackZeroPlan(spans[0], spans, 2);
expect(plan.p).toBe(0);
expect(plan.incoming).toBe(null);
expect(plan.masterAlpha).toBe(1);
expect(plan.masterZoom).toBe(1);
});
test("ramps a dissolve from 0 to 1 across the blend window before the cut", () => {
const spans = spansOf(2, 4, [2]);
const cut = spans[1].start;
expect(trackZeroPlan(spans[0], spans, cut - 2).p).toBeCloseTo(0, 5);
expect(trackZeroPlan(spans[0], spans, cut - 1).p).toBeCloseTo(0.5, 5);
expect(trackZeroPlan(spans[0], spans, cut - 0.001).p).toBeCloseTo(1, 2);
});
test("names the incoming clip only while its blend window is live", () => {
const spans = spansOf(2, 4, [2]);
const cut = spans[1].start;
expect(trackZeroPlan(spans[0], spans, cut - 2.1).incoming).toBe(null);
expect(trackZeroPlan(spans[0], spans, cut - 0.1).incoming).toBe(spans[1]);
});
test("fades the outgoing sound across the blend window", () => {
const spans = spansOf(2, 4, [2]);
const cut = spans[1].start;
expect(trackZeroPlan(spans[0], spans, cut - 2).gain).toBeCloseTo(1, 5);
expect(trackZeroPlan(spans[0], spans, cut - 1).gain).toBeCloseTo(0.5, 5);
});
test("pushes the outgoing clip in, holds the incoming one pushed, settles it after the cut", () => {
const spans = spansOf(2, 4, [2]);
spans[0].clip.transitionStyle = "crosszoom";
const cut = spans[1].start;
const mid = trackZeroPlan(spans[0], spans, cut - 1);
expect(mid.masterZoom).toBeCloseTo(1 + (TRANSITION_ZOOM - 1) * 0.5, 5);
expect(mid.incZoom).toBeCloseTo(TRANSITION_ZOOM, 5);
// Past the cut the incoming clip is the master, settling over its head.
const after = trackZeroPlan(spans[1], spans, cut + 1);
expect(after.masterZoom).toBeCloseTo(TRANSITION_ZOOM - (TRANSITION_ZOOM - 1) * 0.5, 5);
});
test("veils a fade-in from black at the head of the timeline", () => {
const spans = spansOf(1);
spans[0].clip.animIn = { style: "fade", seconds: 1 };
expect(trackZeroPlan(spans[0], spans, 0).veil).toBeCloseTo(1, 5);
expect(trackZeroPlan(spans[0], spans, 0.5).veil).toBeCloseTo(0.5, 5);
expect(trackZeroPlan(spans[0], spans, 1).veil).toBe(0);
});
test("holds an animation on the side a transition already owns", () => {
const spans = spansOf(2, 4, [2]);
// The second clip's entrance sits inside the dissolve, so the dissolve
// plays there and the animation stands down.
spans[1].clip.animIn = { style: "fade", seconds: 1 };
const plan = trackZeroPlan(spans[1], spans, spans[1].start + 0.2);
expect(plan.veil).toBe(0);
expect(plan.masterAlpha).toBe(1);
});
test("puts the previous clip's frame behind a fade at an abutting cut", () => {
const spans = spansOf(2);
spans[1].clip.animIn = { style: "fade", seconds: 1 };
const plan = trackZeroPlan(spans[1], spans, spans[1].start + 0.2);
expect(plan.backdrop?.span).toBe(spans[0]);
// With something behind it the fade blends by alpha rather than to black.
expect(plan.masterAlpha).toBeLessThan(1);
expect(plan.veil).toBe(0);
});
test("has no backdrop for a zoom, which covers the frame anyway", () => {
const spans = spansOf(2);
spans[1].clip.animIn = { style: "zoom", seconds: 1 };
expect(trackZeroPlan(spans[1], spans, spans[1].start + 0.2).backdrop).toBe(null);
});
test("flags the next clip once it is close enough to warm", () => {
const spans = spansOf(2);
expect(trackZeroPlan(spans[0], spans, 1).upcoming).toBe(null);
expect(trackZeroPlan(spans[0], spans, spans[1].start - 0.2).upcoming).toBe(spans[1]);
});
});
describe("clipAnimFx", () => {
test("leaves a clip alone outside its animation windows", () => {
const fx = clipAnimFx(videoClip({ animIn: { style: "fade", seconds: 1 } }), 2, 4);
expect(fx).toEqual({ alpha: 1, zoom: 1, gain: 1, veil: 0, dxFrac: 0, dyFrac: 0 });
});
test("drops the audio with the picture through a fade", () => {
const fx = clipAnimFx(videoClip({ animIn: { style: "fade", seconds: 2 } }), 0.5, 4);
expect(fx.gain).toBeCloseTo(0.25, 5);
expect(fx.veil).toBeCloseTo(0.75, 5);
});
test("slides the frame in from the right and out to the left", () => {
const clip = videoClip({
animIn: { style: "slideleft", seconds: 1 },
animOut: { style: "slideleft", seconds: 1 },
});
// Enters a full frame to the right, settles at 0, then leaves to the left.
expect(clipAnimFx(clip, 0, 4).dxFrac).toBeCloseTo(1, 5);
expect(clipAnimFx(clip, 1, 4).dxFrac).toBeCloseTo(0, 5);
expect(clipAnimFx(clip, 3.5, 4).dxFrac).toBeCloseTo(-0.5, 5);
expect(clipAnimFx(clip, 4, 4).dxFrac).toBeCloseTo(-1, 5);
});
test("defocuses an open-edge blur through the middle of its ramp as it fades", () => {
const clip = videoClip({ animIn: { style: "blur", seconds: 1 } });
const mid = clipAnimFx(clip, 0.5, 4);
expect(mid.blur).toBeCloseTo(TRANSITION_BLUR, 5);
expect(mid.veil).toBeCloseTo(0.5, 5);
expect(mid.gain).toBeCloseTo(0.5, 5);
expect(clipAnimFx(clip, 0.25, 4).blur).toBeCloseTo(TRANSITION_BLUR / 2, 5);
expect(clipAnimFx(clip, 2, 4).blur).toBeUndefined();
});
test("treats a style it does not know as a fade", () => {
const fx = clipAnimFx(
videoClip({ animIn: { style: "kaleidoscope" as never, seconds: 2 } }),
0,
4
);
expect(fx.veil).toBeCloseTo(1, 5);
});
test("clamps an animation longer than the clip to the clip", () => {
const fx = clipAnimFx(videoClip({ animIn: { style: "fade", seconds: 10 } }), 1, 2);
expect(fx.veil).toBeCloseTo(0.5, 5);
});
});
describe("duckGainAt", () => {
const voice = (over: Partial<AudioClip> = {}): AudioClip => ({
id: "vo",
assetId: "asset",
start: 1,
in: 0,
out: 3,
volume: 1,
duck: 0.2,
...over,
});
test("is 1 with no ducking clip live", () => {
expect(duckGainAt([voice()], 0)).toBe(1);
expect(duckGainAt([voice()], 5)).toBe(1);
});
test("drops to the duck while the voiceover speaks", () => {
expect(duckGainAt([voice()], 2)).toBeCloseTo(0.2, 5);
});
test("takes the deepest duck when two overlap", () => {
expect(duckGainAt([voice(), voice({ id: "b", duck: 0.05 })], 2)).toBeCloseTo(0.05, 5);
});
test("ignores a hidden clip", () => {
expect(duckGainAt([voice({ hidden: true })], 2)).toBe(1);
});
});
describe("prerollLead", () => {
// The roll seats the element `lead × speed` of source before the in-point and
// plays forward for `lead` of timeline, so it arrives exactly at `in` as the
// cut lands. Both halves come from this one number: hold the roll at a fixed
// length and the seat has to clamp at 0, which lands the element past `in` and
// makes the handoff seek backwards — a decoder restart at every join.
const cases: [number, number][] = [
[0, 1],
[0.2, 1],
[3, 1],
[0.6, 2],
[4, 0.5],
];
test("gives a trimmed clip the full lead", () => {
expect(prerollLead(3, 1)).toBeCloseTo(PREROLL_LEAD_S, 5);
});
test("gives an untrimmed clip none — there is no source to roll through", () => {
expect(prerollLead(0, 1)).toBe(0);
});
test("shortens the roll to the source a barely-trimmed clip has", () => {
expect(prerollLead(0.2, 1)).toBeCloseTo(0.2, 5);
});
test("scales with the clip's speed", () => {
// At 2×, half a second of timeline eats a second of source, so a clip with
// 0.6s ahead of its in-point can only roll for 0.3s.
expect(prerollLead(0.6, 2)).toBeCloseTo(0.3, 5);
expect(prerollLead(4, 2)).toBeCloseTo(PREROLL_LEAD_S, 5);
});
test("seats the roll inside the source and lands it on the in-point", () => {
for (const [inPoint, speed] of cases) {
const lead = prerollLead(inPoint, speed);
const seat = inPoint - lead * speed;
expect(seat).toBeGreaterThanOrEqual(0);
expect(seat + lead * speed).toBeCloseTo(inPoint, 5);
}
});
});
describe("one-frame clips on a 30 fps export", () => {
/** Spans of the given lengths laid end to end from `from`. */
const laid = (from: number, lens: number[], track = 0): ClipSpan[] => {
let at = from;
return lens.map((len) => {
const span = { clip: videoClip({ start: at, out: len, track }), asset, start: at, len, transitionOut: 0, soundOut: 0, soundAhead: 0, soundBack: 0 };
at += len;
return span;
});
};
test("a track-0 flash between two output frames shows its first picture on the next one", () => {
const spans = laid(0, [0.01, 1 / 60, 2]);
const held = heldFrames(spans.map((sp) => ({ start: sp.start, end: sp.start + sp.len })), 30);
expect(trackZeroAt(spans, held, 1 / 30)).toEqual({ span: spans[1], at: spans[1].start });
expect(trackZeroAt(spans, held, 2 / 30)?.span).toBe(spans[2]);
});
test("a clip whose summed end lands a hair past the next one's start yields the cut's frame", () => {
// 1.8333… + 0.7666… sums to 2.6000000000000005, a hair past the next start.
const spans = laid(1.8333333333333333, [14.766666666666667 - 14, 0.9666666666666666]);
spans[1] = { ...spans[1], start: 2.6 };
expect(spans[0].start + spans[0].len).toBeGreaterThan(2.6);
const held = heldFrames(spans.map((sp) => ({ start: sp.start, end: sp.start + sp.len })), 30);
expect(trackZeroAt(spans, held, 78 / 30)?.span).toBe(spans[1]);
expect(trackZeroAt(spans, held, 77 / 30)?.span).toBe(spans[0]);
});
test("an upper-track flash between two output frames holds the next one", () => {
const spans = laid(0.01, [1 / 60, 2], 1);
const held = heldSpans(spans, 30);
const live = (t: number) => overlayPlan([1], () => spans, t, held);
expect(live(1 / 30).map((l) => [l.span, l.at])).toEqual([[spans[0], spans[0].start]]);
expect(live(2 / 30).map((l) => l.span)).toEqual([spans[1]]);
});
});