Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Test and document scene types

Bitti6e278378b3e2
diff --git a/docs/scene-types.md b/docs/scene-types.md
new file mode 100644
index 0000000..caa9fe7
--- /dev/null
+++ b/docs/scene-types.md
@@ -0,0 +1,13 @@
+# Scene types
+
+The Scene panel saves a type on each scene:
+
+- **First & Last Frame** keeps the existing shot descriptions, speech, Look, sound, music and optional frame anchors. Older scenes without a type use this type.
+- **Animate** uses an Animate generator, one driving video and one repainted scene frame. It does not send a text prompt.
+- **Character Replace** gives each shot a source video selector, a new character reference selector and an optional description identifying the character to replace. The character reference must contain an image. Blank target descriptions mean the main character.
+
+Character Replace sends only references selected by its shots, in project order. Frame anchors, continuation, old action text and style settings are inactive in this mode. Switching back retains the shot descriptions and character selections. The video reference's saved trim and soundtrack setting apply to generation.
+
+The generated prompt follows the [MiniMax H3 full-reference guide](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md): six sections, a video-editing task prefix, independently numbered image/video/audio payloads, and explicit retention instructions. It replaces the target's appearance while retaining motion, timing, camera work, environment and other characters. Character images define the replacement identity rather than anchoring a frame. Enabled soundtracks are reused in the corresponding shots.
+
+Generation requires both references for every shot and respects the existing limits of three video references, nine images and 15 seconds of total video reference material. The generator picker still selects the active engine for the queue: incompatible scenes are excluded from Generate All. Changing a scene type selects a compatible downloaded generator when one is available. Character Replace requires reference-capable MiniMax weights, such as References or Singularity; known First/Last Frame weights are rejected.
diff --git a/src/components/workspace/GeneratorView.test.tsx b/src/components/workspace/GeneratorView.test.tsx
index 2038577..9310891 100644
--- a/src/components/workspace/GeneratorView.test.tsx
+++ b/src/components/workspace/GeneratorView.test.tsx
@@ -6,7 +6,7 @@ import { useState } from "react";
import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { createDraftGenerationJob, createProjectConfig, parseProjectConfig, sceneShots, type ProjectConfig } from "../../lib/project";
import { cancelSlopfabGeneration, getEngineStatus, type SlopfabStatus } from "../../lib/runtime";
-import { GeneratorView } from "./GeneratorView";
+import { GeneratorView, templateSceneBlocker } from "./GeneratorView";
import { minimaxOriginalTemplate, viggleAnimateTemplate, saveDebugOptionsEnabled } from "../../lib/settings";
vi.mock("../../lib/runtime", async (importOriginal) => ({
@@ -42,7 +42,7 @@ it("animates a blank scene only with a video and repainted frame", () => {
localStorage.setItem("slopus.loras.v1", JSON.stringify([{ id: template.loras![0].loraId, name: "Viggle", path: "distillation.safetensors", stepOverride: 4 }]));
localStorage.setItem("slopus.generator-templates.v1", JSON.stringify({ templates: [template], defaultTemplateId: template.id, catalogVersion: 7 }));
const initial = project();
- initial.generationJobs = [createDraftGenerationJob("", { id: "blank", title: "Blank scene" })];
+ initial.generationJobs = [createDraftGenerationJob("", { id: "blank", title: "Blank scene", sceneType: "animate" })];
initial.references = [{ id: "motion", kind: "video", name: "Motion", description: "", intendedUse: [],
sourcePath: "C:/motion.mp4", createdAt: "2026-09-15T00:00:00.000Z",
video: { startSeconds: 1, durationSeconds: 3, includeAudio: false } },
@@ -86,6 +86,72 @@ const readyRuntime: SlopfabStatus = {
models: [],
};
+it("saves scene types and submits Character Replace with the exact selected references", () => {
+ const initial = project();
+ initial.generationJobs = [createDraftGenerationJob("", { id: "replace", title: "Replace scene" })];
+ initial.references = [
+ { id: "motion", kind: "video", name: "Motion", description: "", intendedUse: [], sourcePath: "C:/motion.mp4",
+ video: { startSeconds: 1, durationSeconds: 3, includeAudio: false }, createdAt: "2026-09-21T00:00:00.000Z" },
+ { id: "hero", kind: "image", name: "New hero", description: "", intendedUse: [], relativePath: "references/hero.png", createdAt: "2026-09-21T00:00:00.000Z" },
+ ];
+ let latest = initial;
+ const submitted = vi.fn();
+ function Harness() {
+ const [config, setConfig] = useState(initial);
+ latest = config;
+ return <GeneratorView config={config} folderPath="C:/project" runtime={readyRuntime}
+ onChange={setConfig} onGenerate={submitted} onOpenTimeline={() => undefined} />;
+ }
+ render(<Harness />);
+ expect(screen.getByLabelText("Scene type")).toHaveValue("first-last-frame");
+ fireEvent.change(screen.getByLabelText("Scene type"), { target: { value: "character-replace" } });
+ expect(latest.generationJobs[0].sceneType).toBe("character-replace");
+ expect(screen.queryByLabelText("Start frame for this scene")).toBeNull();
+ const generate = within(screen.getByRole("region", { name: "Replace scene" })).getByRole("button", { name: "Generate" });
+ expect(generate).toBeDisabled();
+ fireEvent.click(screen.getByRole("button", { name: "Shot 1 of Replace scene" }));
+ expect(screen.queryByLabelText("Describe shot 1")).toBeNull();
+ fireEvent.change(screen.getByLabelText("Video reference for this shot"), { target: { value: "motion" } });
+ expect(generate).toBeDisabled();
+ fireEvent.change(screen.getByLabelText("New character reference for this shot"), { target: { value: "hero" } });
+ fireEvent.change(screen.getByLabelText("Character to replace in this shot"), { target: { value: "the person on the left" } });
+ expect(generate).toBeEnabled();
+ fireEvent.click(generate);
+ expect(submitted).toHaveBeenCalledWith([expect.objectContaining({ request: expect.objectContaining({
+ prompt: expect.stringContaining("replace the person on the left with <Subject 1>"),
+ referencePaths: ["C:/project/references/hero.png"],
+ referenceVideos: [{ name: "Motion", sourcePath: "C:/motion.mp4", startSeconds: 1, durationSeconds: 3, includeAudio: false }],
+ }) })]);
+ expect(parseProjectConfig(JSON.parse(JSON.stringify(latest))).generationJobs[0].shots![0]).toMatchObject({ videoReferenceId: "motion", characterReferenceId: "hero" });
+ fireEvent.click(screen.getByRole("button", { name: "Select scene Replace scene" }));
+ fireEvent.change(screen.getByLabelText("Scene type"), { target: { value: "first-last-frame" } });
+ expect(screen.getByLabelText("Start frame for this scene")).toBeInTheDocument();
+ fireEvent.change(screen.getByLabelText("Scene type"), { target: { value: "character-replace" } });
+ expect(generate).toBeEnabled();
+ fireEvent.click(screen.getByRole("button", { name: "Shot 1 of Replace scene" }));
+ expect(screen.getByLabelText("New character reference for this shot")).toHaveValue("hero");
+ fireEvent.change(screen.getByLabelText("New character reference for this shot"), { target: { value: "" } });
+ expect(generate).toBeDisabled();
+});
+
+it("keeps an explicitly selected scene type independent of the global generator", () => {
+ const initial = project();
+ initial.generationJobs[0].sceneType = "animate";
+ const state = setup(initial);
+ expect(screen.getByLabelText("Scene type")).toHaveValue("animate");
+ expect(screen.getByLabelText("Reference video for this scene")).toBeInTheDocument();
+ const first = within(screen.getByRole("region", { name: "First scene" })).getByRole("button", { name: "Generate" });
+ expect(first).toHaveAttribute("title", "Select an Animate generator for this scene.");
+ fireEvent.click(screen.getByRole("button", { name: "Generate All" }));
+ expect(state.latest().generationJobs[0].status).toBe("draft");
+ expect(state.latest().generationJobs[1].status).toBe("queued");
+});
+
+it("refuses known first/last-frame weights for Character Replace", () => {
+ expect(templateSceneBlocker("character-replace", minimaxOriginalTemplate())).toContain("References or Singularity");
+ expect(templateSceneBlocker("character-replace", viggleAnimateTemplate())).toContain("MiniMax prompt");
+});
+
const project = (): ProjectConfig => {
const base = createProjectConfig({
name: "Drag test",
diff --git a/src/lib/project.character-replace.test.ts b/src/lib/project.character-replace.test.ts
new file mode 100644
index 0000000..caa48a9
--- /dev/null
+++ b/src/lib/project.character-replace.test.ts
@@ -0,0 +1,107 @@
+import { expect, it } from "vitest";
+import { characterReplaceBlocker, compileGenerationJobPrompt, createDraftGenerationJob, generationJobSchema,
+ sceneFrameInputs, sceneGenerationReferences, sceneGenerationSnapshot, createProjectConfig, usableReferenceImages,
+ type ProjectReference } from "./project";
+
+const reference = (id: string, kind: "image" | "video"): ProjectReference => ({
+ id, kind, name: id, description: "", intendedUse: [], createdAt: "2026-09-21T00:00:00.000Z",
+ sourcePath: `C:/references/${id}.${kind === "video" ? "mp4" : "png"}`,
+ ...(kind === "video" ? { video: { startSeconds: 1, durationSeconds: 3, includeAudio: false } } : {}),
+});
+const job = () => createDraftGenerationJob("", { sceneType: "character-replace", shots: [
+ { id: "shot-a", startSeconds: 0, action: "Old scene text", videoReferenceId: "motion", characterReferenceId: "hero", characterTarget: "the person in the red jacket" },
+] });
+
+it("round trips scene types and each shot's replacement choices without changing legacy jobs", () => {
+ const scene = job();
+ expect(generationJobSchema.parse(JSON.parse(JSON.stringify(scene)))).toEqual(scene);
+ expect(createDraftGenerationJob("Legacy")).not.toHaveProperty("sceneType");
+ expect(generationJobSchema.safeParse({ ...job(), sceneType: "unknown" }).success).toBe(false);
+});
+
+it("compiles an edit from the selected references and excludes stale anchors, prose and look", () => {
+ const scene = { ...job(), referenceIds: ["unrelated"], startFrameReferenceId: "unrelated", usePreviousSceneLastFrame: true };
+ const references = [reference("unrelated", "image"), reference("motion", "video"), reference("hero", "image")];
+ const config = createProjectConfig({ name: "Test", prompt: "", aspectRatio: "16:9", resolution: "416p", targetDurationSeconds: 6 });
+ config.generationJobs = [scene];
+ config.references = references;
+ const inputs = sceneFrameInputs(scene, config);
+ expect(inputs).not.toHaveProperty("previousSceneId");
+ expect(inputs.references.map(({ id }) => id)).toEqual(["motion", "hero"]);
+ const prompt = compileGenerationJobPrompt(scene, inputs.references, "watercolor");
+ expect(prompt).toContain("[video editing + reference generation]");
+ expect(prompt).toContain("replace the person in the red jacket with <Subject 1>");
+ expect(prompt).toContain("<Subject 1> is the replacement character shown in <Picture 1>");
+ expect(prompt).toContain("<Video 1> ([Shot 1]): partially_preserved");
+ expect(prompt).toContain("motion, pose, expression, gaze and timing");
+ expect(prompt).not.toMatch(/Old scene text|Watercolor|first frame|<Audio/);
+ expect(prompt.match(/^\w+:/gm)).toEqual(["subject_definitions:", "summary:", "retention_analysis:", "detailed_description:", "overall_soundscape:", "non_diegetic_music:"]);
+});
+
+it("keeps numbering aligned across reordered references, multi-image characters and multiple shots", () => {
+ const scene = job();
+ scene.shots!.push({ id: "shot-b", startSeconds: 3, action: "", videoReferenceId: "motion2", characterReferenceId: "hero2" });
+ const hero = reference("hero", "image");
+ hero.images = [{ id: "profile", name: "Profile", sourcePath: "C:/profile.png" }];
+ const references = [reference("hero2", "image"), reference("motion2", "video"), hero, reference("motion", "video")];
+ references[1].images = [{ id: "video-still", name: "Video still", sourcePath: "C:/still.png" }];
+ const bound = sceneGenerationReferences(scene, references);
+ const pictures = usableReferenceImages(bound);
+ const prompt = compileGenerationJobPrompt(scene, bound);
+ const heroPicture = pictures.findIndex((image) => image.sourcePath === "C:/references/hero.png") + 1;
+ expect(prompt).toContain(`<Subject 2> is the replacement character shown in <Picture ${heroPicture}>, <Picture ${heroPicture + 1}>`);
+ expect(prompt).toContain("[Shot 1] In <Video 2>, replace the person in the red jacket with <Subject 2>");
+ expect(prompt).toContain("[Shot 2] At 00:03.000, In <Video 1>, replace the main character with <Subject 1>");
+});
+
+it("includes only enabled soundtracks with independent audio numbering", () => {
+ const scene = job();
+ scene.shots!.push({ id: "shot-b", startSeconds: 3, action: "", videoReferenceId: "motion2", characterReferenceId: "hero" });
+ const motion2 = reference("motion2", "video");
+ motion2.video!.includeAudio = true;
+ const prompt = compileGenerationJobPrompt(scene, [reference("motion", "video"), motion2, reference("hero", "image")]);
+ expect(prompt).toContain("<Audio 1> is the enabled soundtrack of <Video 2>");
+ expect(prompt).toContain("[video editing + reference generation + audio reuse]");
+ expect(prompt).not.toContain("<Audio 2>");
+});
+
+it("blocks missing, unusable and wrongly typed references but accepts blank action text", () => {
+ const scene = job();
+ const references = [reference("motion", "video"), reference("hero", "image")];
+ expect(characterReplaceBlocker(scene, references)).toBeNull();
+ expect(characterReplaceBlocker(scene, references.slice(1))).toContain("video reference for shot 1");
+ expect(characterReplaceBlocker(scene, [references[0], { ...references[1], intendedUse: ["audio"] }])).toContain("character reference");
+ expect(characterReplaceBlocker(scene, [references[0], reference("hero", "video")])).toContain("character reference");
+ scene.shots!.push({ id: "blank", startSeconds: 3, action: "" });
+ expect(characterReplaceBlocker(scene, references)).toContain("shot 2");
+});
+
+it("changes the generation snapshot when the replacement or target changes", () => {
+ const scene = job();
+ const references = [reference("motion", "video"), reference("hero", "image"), reference("hero2", "image")];
+ const snapshot = () => sceneGenerationSnapshot(scene, { prompt: compileGenerationJobPrompt(scene, references), frames: 144,
+ steps: 20, seed: 1, canvasWidth: 736, canvasHeight: 416, referencePaths: [] });
+ const original = snapshot();
+ scene.shots![0].characterTarget = "the person on the left";
+ expect(snapshot()).not.toBe(original);
+ scene.shots![0].characterReferenceId = "hero2";
+ expect(sceneGenerationReferences(scene, references).map(({ id }) => id)).toEqual(["motion", "hero2"]);
+});
+
+it("blocks payloads beyond the model's video and image limits", () => {
+ const scene = job();
+ const motion = reference("motion", "video");
+ const hero = reference("hero", "image");
+ const references = [motion, hero];
+ for (let index = 2; index <= 4; index++) {
+ references.push(reference(`motion${index}`, "video"));
+ scene.shots!.push({ id: `shot-${index}`, startSeconds: index, action: "", videoReferenceId: `motion${index}`, characterReferenceId: "hero" });
+ }
+ expect(characterReplaceBlocker(scene, references)).toContain("three video");
+ scene.shots!.pop();
+ motion.video!.durationSeconds = 10;
+ expect(characterReplaceBlocker(scene, references)).toContain("15 seconds");
+ motion.video!.durationSeconds = 3;
+ hero.images = Array.from({ length: 9 }, (_, index) => ({ id: `image-${index}`, name: "Angle", sourcePath: `C:/angle-${index}.png` }));
+ expect(characterReplaceBlocker(scene, references)).toContain("nine reference images");
+});