reelkit-cli 0.1.3 → 0.3.0

package/src/project/chromakey.ts

@@ -0,0 +1,51 @@
+import { execFile } from "node:child_process";
+import { rmSync } from "node:fs";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+const PURE_GREEN = "0x00FF00";
+
+export type KeyOptions = {
+  // Keep the clip's sound in the transparent copy (a person talking on green). Generated clips have none worth keeping.
+  keepAudio?: boolean;
+  // Fail when the frame's corners are not green, instead of keying on pure green anyway. For footage a person supplied.
+  requireGreen?: boolean;
+};
+
+const NOT_GREEN = "This video does not have a green background in its corners, so there is nothing to key out. Film the subject in front of an evenly lit green background that fills the frame.";
+
+// The colour to key on, read from the first frame's four corners. A real green screen, filmed or generated, is never exactly
+// #00FF00: it is whatever green the light and the encoder made of it, and keying on the wrong green leaves a haze. Undefined when
+// the corners are not green.
+async function cornerGreen(input: string): Promise<string | undefined> {
+  const corner = (x: string, y: string) => `crop=24:24:${x}:${y},scale=1:1:flags=area`;
+  const picks = ["0:0", "iw-24:0", "0:ih-24", "iw-24:ih-24"].map((c) => { const [x, y] = c.split(":") as [string, string]; return corner(x, y); });
+  const colours: [number, number, number][] = [];
+  for (const vf of picks) {
+    const { stdout } = await run("ffmpeg", ["-v", "error", "-i", input, "-frames:v", "1", "-vf", vf, "-pix_fmt", "rgb24", "-f", "rawvideo", "-"], { encoding: "buffer", maxBuffer: 1 << 16 });
+    if (stdout.length >= 3) colours.push([stdout[0]!, stdout[1]!, stdout[2]!]);
+  }
+  const green = colours.filter(([r, g, b]) => g > 60 && g > r * 1.3 && g > b * 1.3);
+  // Most corners must agree: a subject may reach one corner, but not three.
+  if (green.length < 3) return undefined;
+  const avg = (i: 0 | 1 | 2) => Math.round(green.reduce((sum, c) => sum + c[i], 0) / green.length);
+  return `0x${[avg(0), avg(1), avg(2)].map((n) => n.toString(16).padStart(2, "0")).join("")}`;
+}
+
+// Turns the green of a green-screen clip into transparency: VP9 with an alpha channel, which Remotion plays with `transparent`.
+// The key is on the green found in the frame's corners, with some give for noise and uneven light; the despill pulls the green glow
+// off the subject's edges. The original is left alone.
+export async function keyGreen(input: string, output: string, opts: KeyOptions = {}): Promise<void> {
+  try {
+    const found = await cornerGreen(input);
+    if (!found && opts.requireGreen) throw new Error(NOT_GREEN);
+    const filter = `chromakey=color=${found ?? PURE_GREEN}:similarity=0.16:blend=0.08,despill=type=green:mix=0.5:expand=0,format=yuva420p`;
+    const audio = opts.keepAudio ? ["-c:a", "libopus", "-b:a", "96k"] : ["-an"];
+    await run("ffmpeg", ["-v", "error", "-y", "-i", input, "-vf", filter, "-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-b:v", "0", "-crf", "30", ...audio, output]);
+  } catch (e) {
+    rmSync(output, { force: true });
+    if (e instanceof Error && e.message === NOT_GREEN) throw e;
+    if ((e as NodeJS.ErrnoException)?.code === "ENOENT") throw new Error("ffmpeg was not found. Install ffmpeg (macOS: `brew install ffmpeg`) and run the command again.");
+    throw new Error("ffmpeg could not key the green out of the clip. The original clip is saved; run the command again to retry.");
+  }
+}

package/src/project/manifest.ts

@@ -5,6 +5,10 @@ import { FILES, type Project } from "./project";
 // What a scene was recorded from is stored with it, so a changed script or voice is noticed.
 export type Voiceover = { key: string; durationSec: number; words: WordTiming[]; text?: string; voiceId?: string; speed?: number };
 
+// A scene's video clip: the original, and the transparent copy when it was filmed on green and keyed out, or cut out on the server (`cutoutId` is
+// that cutout while it is still being made). Stored in assets/clips.json by scene id.
+export type ClipRecord = { key: string; greenScreen: boolean; durationSec: number; keyedKey?: string; cutoutId?: string };
+
 // True when the stored recording no longer matches what the plan asks for. An entry from before this was tracked counts as different.
 export function voiceoverStale(vo: Voiceover, scene: ScenePlan["scenes"][number], plan: ScenePlan): boolean {
   return vo.text !== scene.narration || vo.voiceId !== plan.voiceId || vo.speed !== PACE_SPEED[plan.pace ?? "normal"];
@@ -16,6 +20,7 @@ export function buildManifest(project: Project, plan: ScenePlan): AssetManifest
   const voiceovers = project.readJsonOr<Record<string, Voiceover>>(FILES.voiceovers, {});
   if (plan.scenes.some((s) => !voiceovers[s.id])) return undefined;
   const images = project.readJsonOr<Record<string, string>>(FILES.images, {});
+  const clips = project.readJsonOr<Record<string, ClipRecord>>(FILES.clips, {});
   const footage = project.footage();
   const byId = new Map(project.assets().map((a) => [a.id, a]));
 
@@ -41,6 +46,7 @@ export function buildManifest(project: Project, plan: ScenePlan): AssetManifest
       voiceoverKey: voiceovers[scene.id].key,
       words: voiceovers[scene.id].words,
       ...(scene.treatment === "illustration" && images[scene.id] ? { imageKey: images[scene.id] } : {}),
+      ...(scene.treatment === "clip" && clips[scene.id] ? { clipKey: clips[scene.id].key, ...(clips[scene.id].keyedKey ? { clipKeyedKey: clips[scene.id].keyedKey } : {}) } : {}),
       userAssetKeys: scene.userAssetIds.map((id) => {
         const a = byId.get(id);
         if (!a) throw new Error(`Scene ${scene.id} references unknown asset ${id}. Add it with \`reelkit assets upload\`.`);
@@ -56,6 +62,7 @@ export function buildManifest(project: Project, plan: ScenePlan): AssetManifest
 export function missingAssets(project: Project, plan: ScenePlan): string[] {
   const voiceovers = project.readJsonOr<Record<string, Voiceover>>(FILES.voiceovers, {});
   const images = project.readJsonOr<Record<string, string>>(FILES.images, {});
+  const clips = project.readJsonOr<Record<string, ClipRecord>>(FILES.clips, {});
   const problems: string[] = [];
   for (const s of plan.scenes) {
     if (!voiceovers[s.id]) problems.push(`Scene ${s.id} has no voiceover.`);
@@ -66,6 +73,11 @@ export function missingAssets(project: Project, plan: ScenePlan): string[] {
       if (!images[s.id]) problems.push(`Scene ${s.id} has no image.`);
       else if (!project.exists(images[s.id])) problems.push(`Missing file: ${images[s.id]}`);
     }
+    if (s.treatment === "clip") {
+      const clip = clips[s.id];
+      if (!clip) problems.push(`Scene ${s.id} has no clip. Run \`reelkit assets gen clip --scene ${s.id}\`.`);
+      else for (const key of [clip.key, ...(clip.keyedKey ? [clip.keyedKey] : [])]) if (!project.exists(key)) problems.push(`Missing file: ${key}`);
+    }
   }
   return problems;
 }

package/src/project/project.ts

@@ -5,7 +5,7 @@ import { AspectSchema, type AssetRecord } from "../pipeline/schema";
 
 export const FILES = {
   config: "reelkit.json", plan: "plan.json", manifest: "manifest.json",
-  assetIndex: "assets/index.json", voiceovers: "assets/voiceovers.json", images: "assets/images.json", library: "assets/library.json",
+  assetIndex: "assets/index.json", voiceovers: "assets/voiceovers.json", images: "assets/images.json", clips: "assets/clips.json", library: "assets/library.json",
 } as const;
 
 // "path: message", or just the message for a problem at the root of the file.

package/src/remotion/kit/ClipLayer.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { useMedia } from "./media";
+import { AbsoluteFill, OffthreadVideo } from "remotion";
+
+// A generated or library video clip as a scene's picture. Place it inside the scene's SceneFrame, as the bottom layer, so it starts with the scene.
+// When the scene runs longer than the clip, the clip holds its last frame (it does not loop: a looped person or animal jumps back and shows the seam).
+export const ClipLayer: React.FC<{ src: string; muted?: boolean; dim?: number }> = ({ src, muted = true, dim = 0 }) => (
+  <AbsoluteFill>
+    <OffthreadVideo src={useMedia(src)} muted={muted} style={{ width: "100%", height: "100%", objectFit: "cover" }} />
+    {dim > 0 ? <AbsoluteFill style={{ backgroundColor: `rgba(0,0,0,${dim})` }} /> : null}
+  </AbsoluteFill>
+);

package/src/remotion/kit/KeyedClip.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+import { useMedia } from "./media";
+import { AbsoluteFill, OffthreadVideo } from "remotion";
+
+// A green-screen clip with its green keyed out (the transparent .webm that `--green` makes), laid over whatever is beneath it.
+// x and y are where the clip's bottom-centre sits, as fractions of the frame (x 0 is the left edge, y 1 the bottom edge); scale is the clip's
+// width as a fraction of the frame width. The clip has the frame's own shape, so it is as tall as the frame is, times scale.
+// Like ClipLayer it holds its last frame when the scene is longer.
+export const KeyedClip: React.FC<{ src: string; x?: number; y?: number; scale?: number; muted?: boolean }> = ({ src, x = 0.5, y = 1, scale = 1, muted = true }) => (
+  <AbsoluteFill style={{ pointerEvents: "none" }}>
+    <div style={{ position: "absolute", left: `${x * 100}%`, top: `${y * 100}%`, width: `${scale * 100}%`, transform: "translate(-50%, -100%)" }}>
+      <OffthreadVideo src={useMedia(src)} muted={muted} transparent style={{ width: "100%", display: "block" }} />
+    </div>
+  </AbsoluteFill>
+);

package/src/remotion/kit/docs.ts

@@ -32,6 +32,14 @@ FootageLayer { src: string; muted?: boolean; dim?: number }
   Full-frame user footage. Place it once, outside the scenes, as the bottom layer. dim (0-1) darkens it for legibility.
   <FootageLayer src={urls[manifest.footageKey]} dim={0.25} />
 
+ClipLayer { src: string; muted?: boolean; dim?: number }
+  Full-frame generated or library video clip as a scene's picture (treatment "clip"). Place it inside the scene's SceneFrame as the bottom layer, so it starts with the scene. When the scene is longer than the clip it holds the last frame; it never loops. dim (0-1) darkens it for legibility.
+  <ClipLayer src={urls[s.clipKey]} dim={0.2} />
+
+KeyedClip { src: string; x?: number; y?: number; scale?: number; muted?: boolean }
+  A green-screen clip with the green keyed out (the transparent .webm, s.clipKeyedKey). Lay it over your own background or screenshot, below the captions. x and y place its bottom centre as fractions of the frame (default x 0.5, y 1: bottom centre); scale is its width as a fraction of the frame width (default 1). Holds its last frame when the scene is longer.
+  <KeyedClip src={urls[s.clipKeyedKey]} x={0.5} y={1} scale={0.8} />
+
 BgMesh { bg: string; hero: string; accent?: string }
   The bottom layer of the video: the base colour with two slow-drifting soft colour fields. Use it instead of a flat background.
   <BgMesh bg={palette.bg} hero={palette.hero} accent={palette.accent} />

package/src/remotion/kit/index.ts

@@ -1,4 +1,5 @@
 export { Captions } from "./Captions";
+export { ClipLayer } from "./ClipLayer";
 export { Counter } from "./Counter";
 export { Entrance, WordReveal } from "./Entrance";
 export { FootageLayer } from "./FootageLayer";
@@ -6,6 +7,7 @@ export { brandColor, Icon } from "./Icon";
 export type { GlyphName, IconName } from "./Icon";
 export type { BrandName } from "./brand-icons";
 export { KenBurnsImage } from "./KenBurnsImage";
+export { KeyedClip } from "./KeyedClip";
 export { BgMesh, Grade, Grain, Vignette } from "./Layers";
 export { LowerThird } from "./LowerThird";
 export { SceneFrame } from "./SceneFrame";

package/src/testing/conformance.ts

@@ -15,8 +15,16 @@ export type Harness = {
   // What the website does when a signed-in user enters the code.
   approve(userCode: string): unknown;
   close(): void | Promise<void>;
+  // Optional, for the clip tests. A prompt that makes a clip job fail (the fake fails any prompt containing "clip-fail"); without it the
+  // failing-job case is skipped.
+  clipFailPrompt?: string;
+  // How long to wait between two asks for a clip's status, in milliseconds: a server whose fake provider needs a moment sets it. Default 20.
+  clipPollMs?: number;
+  // Optional, for the cutout tests. A file name that makes a cutout job fail (the fake fails any name containing "cutout-fail"); without
+  // it the failing-job case is skipped. The cutout tests wait between status asks for `clipPollMs` too.
+  cutoutFailFilename?: string;
 };
-export type StartOptions = { voiceoverChars?: number; images?: number };
+export type StartOptions = { voiceoverChars?: number; images?: number; clips?: number; cutoutSeconds?: number };
 
 const PNG = new Uint8Array(Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "base64"));
 const DATE = /\d{4}-\d{2}-\d{2}/;
@@ -75,6 +83,10 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         expect(me.handle.length).toBeGreaterThan(0);
         expect(me.quota.voiceoverChars.used).toBe(0);
         expect(me.quota.images.used).toBe(0);
+        expect(me.quota.clips.used).toBe(0);
+        expect(me.quota.clips.limit).toBeGreaterThan(0);
+        expect(me.quota.cutoutSeconds.used).toBe(0);
+        expect(me.quota.cutoutSeconds.limit).toBeGreaterThan(0);
         expect(me.quota.voiceoverChars.limit).toBeGreaterThan(0);
         expect(me.contributions).toBe(0);
         const resets = new Date(me.quota.resetsAt);
@@ -222,6 +234,10 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         ["a voiceover text over 5000 characters", (api: Api) => api("voiceover", { text: "a".repeat(5001) })],
         ["a speed over 1.3", (api: Api) => api("voiceover", { text: "hi", speed: 1.4 })],
         ["an unknown aspect", (api: Api) => api("images", { prompt: "a", aspect: "4:3" as never, shareable: false, tags: [] })],
+        ["a clip with no prompt", (api: Api) => api("clipStart", { prompt: "", aspect: "9:16", shareable: false, tags: [] })],
+        ["a clip of 7 seconds", (api: Api) => api("clipStart", { prompt: "a", aspect: "9:16", durationSec: 7 as never, shareable: false, tags: [] })],
+        ["a clip prompt with a NUL", (api: Api) => api("clipStart", { prompt: "a\u0000b", aspect: "9:16", shareable: false, tags: [] })],
+        ["a clip status id with a slash", (api: Api) => api("clipStatus", { id: "../x" })],
       ])("refuses %s as invalid_request", async (_what, call) => {
         expect((await failure(call(await as("user-bad000001")))).code).toBe("invalid_request");
       });
@@ -269,6 +285,8 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
       it("generation needs a login", async () => {
         expect((await failure(anon("voiceover", { text: "hi" }))).code).toBe("unauthenticated");
         expect((await failure(anon("images", { prompt: "a", aspect: "9:16", shareable: false, tags: [] }))).code).toBe("unauthenticated");
+        expect((await failure(anon("clipStart", { prompt: "a", aspect: "9:16", shareable: false, tags: [] }))).code).toBe("unauthenticated");
+        expect((await failure(anon("clipStatus", { id: "clip-x" }))).code).toBe("unauthenticated");
       });
 
       it("images: a private one is only a file; a shareable one also enters the library for review, owned by the caller", async () => {
@@ -296,6 +314,214 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
       });
     });
 
+    describe("clips", () => {
+      // Asks until the job is no longer pending: at most 20 times, with the harness's pause between asks.
+      const settle = async (api: Api, id: string) => {
+        for (let i = 0; i < 20; i++) {
+          const st = await api("clipStatus", { id });
+          if (st.status !== "pending") return st;
+          await new Promise((r) => setTimeout(r, h.clipPollMs ?? 20));
+        }
+        throw new Error(`clip ${id} was still pending after 20 asks`);
+      };
+      const ask = { aspect: "9:16" as const, shareable: false, tags: [] as string[] };
+
+      it("start answers pending at once, the job ends done with a file that downloads, and the clip is charged to this user only", async () => {
+        const api = await as("user-clip00001"), other = await as("user-clip00002");
+        const started = await api("clipStart", { ...ask, prompt: "a dog running on a beach" });
+        expect(started.status).toBe("pending");
+        expect(started.id).toBeTruthy();
+        // The clip is reserved at the start, before it is finished.
+        expect((await api("me", {})).quota.clips.used).toBe(1);
+        const done = await settle(api, started.id);
+        expect(done).toMatchObject({ id: started.id, status: "done", ext: "mp4" });
+        expect(done.url).toBeTruthy();
+        expect(done.contentType).toMatch(/^video\//);
+        expect(done.message).toBeUndefined();
+        await download(done.url!, join(dest, "clip.mp4"));
+        expect(readFileSync(join(dest, "clip.mp4")).length).toBeGreaterThan(0);
+        expect((await api("me", {})).quota.clips.used).toBe(1);
+        expect((await other("me", {})).quota.clips.used).toBe(0);
+      });
+
+      it("a clip id belongs to its caller: another user, or an unknown id, is not_found", async () => {
+        const api = await as("user-clip00003"), other = await as("user-clip00004");
+        const started = await api("clipStart", { ...ask, prompt: "a quiet harbour at dawn" });
+        expect((await failure(other("clipStatus", { id: started.id }))).code).toBe("not_found");
+        expect((await failure(api("clipStatus", { id: "clip-nosuchjob" }))).code).toBe("not_found");
+      });
+
+      it("a green-screen clip is accepted and finishes like any other", async () => {
+        const api = await as("user-clip00005");
+        const started = await api("clipStart", { ...ask, prompt: "a person waving, flat green background", greenScreen: true, durationSec: 10 });
+        const done = await settle(api, started.id);
+        expect(done.status).toBe("done");
+        await download(done.url!, join(dest, "green.mp4"));
+        expect(readFileSync(join(dest, "green.mp4")).length).toBeGreaterThan(0);
+      });
+
+      it("a shareable clip enters the library in review, owned by the caller, and is not found by search", async () => {
+        const api = await as("user-clip00006"), other = await as("user-clip00007");
+        const started = await api("clipStart", { ...ask, prompt: "a clipshare lighthouse in a storm", shareable: true, tags: ["lighthouse"] });
+        const done = await settle(api, started.id);
+        expect(done.status).toBe("done");
+        expect(done.libraryId).toBeTruthy();
+        expect((await api("libraryPull", { id: done.libraryId! })).item).toMatchObject({ kind: "clip", visibility: "review" });
+        expect((await api("librarySearch", { q: "clipshare lighthouse" })).items.map((i) => i.id)).not.toContain(done.libraryId);
+        expect((await failure(other("libraryPull", { id: done.libraryId! }))).code).toBe("not_found");
+        const plain = await settle(api, (await api("clipStart", { ...ask, prompt: "a private clip" })).id);
+        expect(plain.libraryId).toBeUndefined();
+      });
+
+      it("a failed job says why in one line and is not charged", async () => {
+        if (!h.clipFailPrompt) return;
+        const api = await as("user-clip00008");
+        const started = await api("clipStart", { ...ask, prompt: h.clipFailPrompt });
+        const st = await settle(api, started.id);
+        expect(st.status).toBe("failed");
+        expect(st.message?.length).toBeGreaterThan(0);
+        expect(st.message).not.toContain("\n");
+        expect(st.url).toBeUndefined();
+        expect((await api("me", {})).quota.clips.used).toBe(0);
+      });
+
+      it("at the limit a new clip is quota_exceeded with the reset date, charged nothing; other users are unaffected", async () => {
+        const t = await start({ clips: 1 });
+        try {
+          const api = createClient({ baseUrl: t.baseUrl, token: await t.login("user-clipq0001") });
+          const other = createClient({ baseUrl: t.baseUrl, token: await t.login("user-clipq0002") });
+          await api("clipStart", { ...ask, prompt: "first" });
+          const e = await failure(api("clipStart", { ...ask, prompt: "second" }));
+          expect(e.code).toBe("quota_exceeded");
+          expect(e.message).toMatch(DATE);
+          const me = await api("me", {});
+          expect(me.quota.clips).toEqual({ used: 1, limit: 1 });
+          expect(e.message).toContain(me.quota.resetsAt.slice(0, 10));
+          expect((await other("me", {})).quota.clips.used).toBe(0);
+          await other("clipStart", { ...ask, prompt: "third" });
+        } finally { await t.close(); }
+      });
+    });
+
+    describe("cutouts", () => {
+      const VIDEO = new Uint8Array([0, 0, 0, 24, 102, 116, 121, 112, 105, 115, 111, 109, ...new Array(2000).fill(7)]);
+      const meta = (over: Record<string, unknown> = {}) => ({ filename: "me.mp4", contentType: "video/mp4" as const, bytes: VIDEO.length, durationSec: 2.4, ...over });
+      const settleCutout = async (api: Api, id: string) => {
+        for (let i = 0; i < 20; i++) {
+          const st = await api("cutoutStatus", { id });
+          if (st.status !== "pending") return st;
+          await new Promise((r) => setTimeout(r, h.clipPollMs ?? 20));
+        }
+        throw new Error(`cutout ${id} was still pending after 20 asks`);
+      };
+      // Starts a job and sends its file, as a client does before asking for the run.
+      const uploaded = async (api: Api, over: Record<string, unknown> = {}) => {
+        const started = await api("cutoutStart", meta(over) as never);
+        await put(started.uploadUrl, VIDEO, (over.contentType as string | undefined) ?? "video/mp4");
+        return started;
+      };
+
+      it("start, upload, run: pending at once, then done with a transparent webm that downloads; charged in whole seconds to this user only", async () => {
+        const api = await as("user-cut000001"), other = await as("user-cut000002");
+        const started = await api("cutoutStart", meta());
+        expect(started.id).toBeTruthy();
+        expect(started.uploadUrl).toBeTruthy();
+        // Starting charges nothing.
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(0);
+        expect((await put(started.uploadUrl, VIDEO, "video/mp4")).ok).toBe(true);
+        expect(await api("cutoutRun", { id: started.id })).toEqual({ id: started.id, status: "pending" });
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(3);
+        const done = await settleCutout(api, started.id);
+        expect(done).toMatchObject({ id: started.id, status: "done", ext: "webm", contentType: "video/webm" });
+        expect(done.url).toBeTruthy();
+        expect(done.message).toBeUndefined();
+        await download(done.url!, join(dest, "cutout.webm"));
+        expect(readFileSync(join(dest, "cutout.webm")).length).toBeGreaterThan(0);
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(3);
+        expect((await other("me", {})).quota.cutoutSeconds.used).toBe(0);
+      });
+
+      it("a run before the file arrived is invalid_request and charges nothing", async () => {
+        const api = await as("user-cut000003");
+        const started = await api("cutoutStart", meta());
+        const e = await failure(api("cutoutRun", { id: started.id }));
+        expect(e.code).toBe("invalid_request");
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(0);
+        // The upload can still be sent and the job run afterwards.
+        await put(started.uploadUrl, VIDEO, "video/mp4");
+        expect((await api("cutoutRun", { id: started.id })).status).toBe("pending");
+      });
+
+      it("running a job twice answers its pending state again and charges once", async () => {
+        const api = await as("user-cut000004");
+        const started = await uploaded(api);
+        await api("cutoutRun", { id: started.id });
+        expect(await api("cutoutRun", { id: started.id })).toEqual({ id: started.id, status: "pending" });
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(3);
+        expect((await settleCutout(api, started.id)).status).toBe("done");
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(3);
+      });
+
+      it("a cutout id belongs to its caller: another user, or an unknown id, is not_found for run and status", async () => {
+        const api = await as("user-cut000005"), other = await as("user-cut000006");
+        const started = await uploaded(api);
+        await api("cutoutRun", { id: started.id });
+        expect((await failure(other("cutoutRun", { id: started.id }))).code).toBe("not_found");
+        expect((await failure(other("cutoutStatus", { id: started.id }))).code).toBe("not_found");
+        expect((await failure(api("cutoutRun", { id: "cutout-nosuchjob" }))).code).toBe("not_found");
+        expect((await failure(api("cutoutStatus", { id: "cutout-nosuchjob" }))).code).toBe("not_found");
+        expect((await other("me", {})).quota.cutoutSeconds.used).toBe(0);
+      });
+
+      it("a failed job says why in one line and is not charged", async () => {
+        if (!h.cutoutFailFilename) return;
+        const api = await as("user-cut000007");
+        const started = await uploaded(api, { filename: h.cutoutFailFilename });
+        await api("cutoutRun", { id: started.id });
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(3);
+        const st = await settleCutout(api, started.id);
+        expect(st.status).toBe("failed");
+        expect(st.message?.length).toBeGreaterThan(0);
+        expect(st.message).not.toContain("\n");
+        expect(st.url).toBeUndefined();
+        expect((await api("me", {})).quota.cutoutSeconds.used).toBe(0);
+      });
+
+      it("at the limit a run is quota_exceeded with the reset date, charged nothing; other users are unaffected", async () => {
+        const t = await start({ cutoutSeconds: 3 });
+        try {
+          const api = createClient({ baseUrl: t.baseUrl, token: await t.login("user-cutq00001") });
+          const other = createClient({ baseUrl: t.baseUrl, token: await t.login("user-cutq00002") });
+          const send = async (c: Api) => { const s = await c("cutoutStart", meta({ durationSec: 2 })); await put(s.uploadUrl, VIDEO, "video/mp4"); return s; };
+          const first = await send(api);
+          await api("cutoutRun", { id: first.id });
+          const second = await send(api);
+          const e = await failure(api("cutoutRun", { id: second.id }));
+          expect(e.code).toBe("quota_exceeded");
+          expect(e.message).toMatch(DATE);
+          const me = await api("me", {});
+          expect(me.quota.cutoutSeconds).toEqual({ used: 2, limit: 3 });
+          expect(e.message).toContain(me.quota.resetsAt.slice(0, 10));
+          const third = await send(other);
+          expect((await other("cutoutRun", { id: third.id })).status).toBe("pending");
+        } finally { await t.close(); }
+      });
+
+      it("refuses a video over 20 seconds, a type that is not a video, a size out of range and a missing login", async () => {
+        const api = await as("user-cut000008");
+        for (const bad of [{ durationSec: 20.5 }, { durationSec: 0 }, { durationSec: -1 }, { contentType: "audio/mpeg" }, { contentType: "image/png" }, { bytes: 0 }, { bytes: MAX_UPLOAD_BYTES + 1 }, { filename: "a\u0000b.mp4" }]) {
+          expect((await failure(api("cutoutStart", meta(bad) as never))).code, JSON.stringify(bad)).toBe("invalid_request");
+        }
+        for (const ok of [{ durationSec: 20 }, { contentType: "video/quicktime" as const }, { contentType: "video/webm" as const }, { bytes: MAX_UPLOAD_BYTES }]) {
+          expect((await api("cutoutStart", meta(ok))).id).toBeTruthy();
+        }
+        expect((await failure(api("cutoutRun", { id: "../x" }))).code).toBe("invalid_request");
+        expect((await failure(anon("cutoutStart", meta()))).code).toBe("unauthenticated");
+        expect((await failure(anon("cutoutRun", { id: "cutout-x" }))).code).toBe("unauthenticated");
+        expect((await failure(anon("cutoutStatus", { id: "cutout-x" }))).code).toBe("unauthenticated");
+      });
+    });
+
     describe("quota", () => {
       it("passes exactly at the limit; one over is quota_exceeded with the reset date; other users are unaffected", async () => {
         const t = await start({ voiceoverChars: 10, images: 1 });