AI media harness for planning, generating, and editing locally
TypeScript
Add scene types and character replacement
Bittice5493516b42
diff --git a/src-tauri/src/agent/tests.rs b/src-tauri/src/agent/tests.rsindex 125fedf..bdddd7e 100644--- a/src-tauri/src/agent/tests.rs+++ b/src-tauri/src/agent/tests.rs@@ -135,6 +135,9 @@ fn agent_scene_fixture() -> (ProjectConfig, ProjectConfig) {Some("Quiet workshop ventilation under the click of metal tools on the bench.".into());job.music = Some("Sparse felt piano at a slow tempo with restrained dynamics.".into());job.shots = Some(vec![SceneShot {+ video_reference_id: None,+ character_reference_id: None,+ character_target: None,id: "shot-mara-turns".into(),name: Some("Mara turns".into()),start_seconds: 0.0,@@ -185,6 +188,9 @@ fn agent_scene_conventions_reject_dialogue_in_action_and_broken_reference_bindin#[test]fn agent_shot_settings_reject_unknown_ids_and_invalid_camera_combinations() {let shot = |id: &str, settings: BTreeMap<String, Vec<String>>| SceneShot {+ video_reference_id: None,+ character_reference_id: None,+ character_target: None,id: id.into(),name: None,start_seconds: 0.0,diff --git a/src-tauri/src/project/commands/shots.rs b/src-tauri/src/project/commands/shots.rsindex eb97396..a082af6 100644--- a/src-tauri/src/project/commands/shots.rs+++ b/src-tauri/src/project/commands/shots.rs@@ -25,6 +25,9 @@ pub(super) fn apply(return Err(format!("shot '{id}' already exists in scene '{scene}'"));}shots.push(SceneShot {+ video_reference_id: None,+ character_reference_id: None,+ character_target: None,id: id.clone(),name: name.clone(),start_seconds: *start_seconds,diff --git a/src-tauri/src/project/scenes.rs b/src-tauri/src/project/scenes.rsindex 420d9bd..7590012 100644--- a/src-tauri/src/project/scenes.rs+++ b/src-tauri/src/project/scenes.rs@@ -11,6 +11,12 @@ use std::collections::BTreeMap;#[serde(rename_all = "camelCase")]pub(crate) struct SceneShot {pub(crate) id: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub(crate) video_reference_id: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub(crate) character_reference_id: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub(crate) character_target: Option<String>,/// Added after scenes shipped. An absent name keeps the numbered Shot N/// label, and is skipped so older project files do not grow a new key.#[serde(default, skip_serializing_if = "Option::is_none")]@@ -35,6 +41,8 @@ pub(crate) struct SceneShot {#[serde(rename_all = "camelCase")]pub(crate) struct GenerationJob {pub(crate) id: String,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub(crate) scene_type: Option<String>,#[serde(default)]pub(crate) title: String,/// A MIRROR of the scene's shot lines for a scene-shaped job, and the user's@@ -128,6 +136,7 @@ impl GenerationJob {let now = timestamp.to_string();Self {id: id.to_string(),+ scene_type: None,title: title.to_string(),prompt: String::new(),status: "draft".into(),diff --git a/src-tauri/src/project/validation/scenes.rs b/src-tauri/src/project/validation/scenes.rsindex e1d5443..3561a82 100644--- a/src-tauri/src/project/validation/scenes.rs+++ b/src-tauri/src/project/validation/scenes.rs@@ -4,6 +4,11 @@ use crate::project::*;use std::collections::BTreeSet;pub(super) fn validate(config: &mut ProjectConfig) -> Result<(), String> {for job in &mut config.generation_jobs {+ if job.scene_type.as_deref().is_some_and(|value| {+ !matches!(value, "first-last-frame" | "animate" | "character-replace")+ }) {+ return Err(format!("Scene '{}' has an unsupported scene type.", job.id));+ }let limits = crate::generation::models::for_scene(job.provider_id.as_deref()).unwrap_or_else(crate::generation::models::default_model).capabilities;@@ -19,6 +24,12 @@ pub(super) fn validate(config: &mut ProjectConfig) -> Result<(), String> {if let Some(shots) = job.shots.as_mut() {let mut seen: BTreeSet<String> = BTreeSet::new();for shot in shots.iter_mut() {+ if [&shot.video_reference_id, &shot.character_reference_id]+ .iter()+ .any(|id| id.as_deref() == Some(""))+ {+ return Err(format!("Shot '{}' has an empty reference id.", shot.id));+ }if shot.id.trim().is_empty() {return Err(format!("Scene '{}' has a shot with an empty id.", job.id));}diff --git a/src-tauri/src/tests/scenes.rs b/src-tauri/src/tests/scenes.rsindex c76c891..a7bf8ff 100644--- a/src-tauri/src/tests/scenes.rs+++ b/src-tauri/src/tests/scenes.rs@@ -227,6 +227,9 @@ fn an_empty_scene_survives_the_round_trip_the_plus_button_creates() {job.creative_brief = String::new();job.reference_ids = Vec::new();job.shots = Some(vec![SceneShot {+ video_reference_id: None,+ character_reference_id: None,+ character_target: None,id: "scene-walk-shot-1".into(),name: None,start_seconds: 0.0,@@ -260,6 +263,35 @@ fn a_shot_name_survives_the_project_round_trip() {);}+#[test]+fn scene_types_and_character_replacement_inputs_survive_save_and_reopen() {+ for scene_type in ["first-last-frame", "animate", "character-replace"] {+ let mut config = scene_fixture();+ let job = &mut config.generation_jobs[0];+ job.scene_type = Some(scene_type.into());+ let shot = &mut job.shots.as_mut().unwrap()[0];+ shot.video_reference_id = Some("source-video".into());+ shot.character_reference_id = Some("new-character".into());+ shot.character_target = Some("the person on the left".into());+ let normalized = validate_and_normalize_config(config).unwrap();+ let saved = serde_json::to_string(&normalized).unwrap();+ let restored: ProjectConfig = serde_json::from_str(&saved).unwrap();+ assert_eq!(+ restored.generation_jobs[0].scene_type.as_deref(),+ Some(scene_type)+ );+ assert_eq!(+ normalized.generation_jobs[0].shots,+ restored.generation_jobs[0].shots+ );+ assert!(saved.contains("\"videoReferenceId\":\"source-video\""));+ assert!(saved.contains("\"characterReferenceId\":\"new-character\""));+ }+ let mut config = scene_fixture();+ config.generation_jobs[0].scene_type = Some("unknown".into());+ assert!(validate_and_normalize_config(config).is_err());+}+#[test]fn shot_speech_and_custom_languages_survive_the_project_round_trip() {let mut config = scene_fixture();diff --git a/src/components/workspace/GeneratorView.tsx b/src/components/workspace/GeneratorView.tsxindex a57562d..4cc26f9 100644--- a/src/components/workspace/GeneratorView.tsx+++ b/src/components/workspace/GeneratorView.tsx@@ -1,7 +1,7 @@import type { GenerationSubmission } from "../../lib/workQueue";import { loadLoras, subscribeLoras } from "../../lib/loras";import { refreshDownloadedLoras } from "../../lib/weightDownloads";-import { usableVideoReferences } from "../../lib/project";+import { characterReplaceBlocker, usableVideoReferences, type SceneType } from "../../lib/project";import { referenceRefmodInputs } from "../../lib/project";import { ChevronDown, Plus, Square, Trash2, WandSparkles } from "lucide-react";import { invoke } from "@tauri-apps/api/core";@@ -52,7 +52,7 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCoconst jobs = config.generationJobs;const [templateSettings, setTemplateSettings] = useState(loadGeneratorTemplateSettings);const selectedTemplate = defaultGeneratorTemplate(templateSettings);- const animate = selectedTemplate.mode === "animate";+ const sceneTypeFor = (job: GenerationJob): SceneType => job.sceneType ?? "first-last-frame";const defaultGenerationSteps = selectedTemplate.defaultSteps;const [generatorRuntime, setGeneratorRuntime] = useState<SlopfabStatus | null>(runtime);const [runtimeError, setRuntimeError] = useState<string | null>(null);@@ -122,6 +122,7 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCo/* A scene can be deleted, and a shot can be removed, from under the panel.Falling back to the first scene beats a panel pointing at nothing. */const selected = jobs.find((job) => job.id === selection.jobId) ?? jobs[0];+ const animate = selected ? sceneTypeFor(selected) === "animate" : false;const selectedShots = useMemo(() => (selected ? sceneShots(selected) : []), [selected]);const shotIndex = selectedShots.findIndex((shot) => shot.id === selection.shotId);const openShot = !animate && shotIndex >= 0 ? selectedShots[shotIndex] : null;@@ -161,6 +162,17 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCoconst updateScene = (job: GenerationJob, updates: Partial<GenerationJob>) =>updateJob(job.id, mergeSceneUpdates(job, updates));+ const changeSceneSettings = (job: GenerationJob, updates: Partial<GenerationJob>) => {+ updateScene(job, updates);+ if (updates.sceneType && templateSceneBlocker(updates.sceneType, selectedTemplate)) {+ const candidates = templateSettings.templates.filter((template) => !templateNeedsDownload(template)+ && !templateSceneBlocker(updates.sceneType!, template));+ const compatible = (updates.sceneType === "character-replace"+ ? candidates.find((template) => /ref2v/i.test(template.paths.transformer)) : undefined) ?? candidates[0];+ if (compatible) chooseGeneratorTemplate(compatible.id);+ }+ };+const addFrame = async (job: GenerationJob, edge: "start" | "end") => {if (!isTauri()) return;setStartFrameError(null);@@ -302,7 +314,7 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCo// retimed shot reach the engine, rather than sending a prompt frozen at// draft-creation time. This is the ONE string slopfab is given, and it is// the same string the compiled-prompt panel shows.- prompt: animate ? "" : compileGenerationJobPrompt(inputs.job, bound, configRef.current.settings.defaultLook),+ prompt: sceneTypeFor(job) === "animate" ? "" : compileGenerationJobPrompt(inputs.job, bound, configRef.current.settings.defaultLook),...(inputs.previousSceneId ? { previousSceneId: inputs.previousSceneId } : {}),...(inputs.continuationRelativePath ? { continuationRelativePath: inputs.continuationRelativePath } : {}),// The scene's own length, not a fixed six seconds.@@ -354,7 +366,8 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCoreferences steer a scene is decided by writing them into a line or by thereferences already named by its shots. */const newScene = () => {- const job = createDraftGenerationJob("", { steps: defaultGenerationSteps });+ const job = createDraftGenerationJob("", { steps: defaultGenerationSteps,+ sceneType: selectedTemplate.mode === "animate" ? "animate" : "first-last-frame" });onChange({ ...config, generationJobs: [...jobs, job] });setSelection({ jobId: job.id, shotId: null });};@@ -385,8 +398,8 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCoconst batchScenesReady: GenerationJob[] = [];for (const [index, job] of jobs.entries()) {if (job.status === "queued" || job.status === "generating" || job.status === "ready") continue;- if (job.usePreviousSceneLastFrame && index === 0) continue;- if (sendBlocker(job, config.references, animate)) continue;+ if (job.sceneType !== "character-replace" && job.usePreviousSceneLastFrame && index === 0) continue;+ if (templateSceneBlocker(sceneTypeFor(job), selectedTemplate) || sendBlocker(job, config.references)) continue;const previous = jobs[index - 1];const previousWillRender = job.usePreviousSceneLastFrame && previous &&(batchScenesReady.includes(previous) || ["queued", "generating", "ready"].includes(previous.status));@@ -402,8 +415,8 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCoconst generationBlocker = (job: GenerationJob): string | null => {if (!runtimeReady) return runtimeError ?? generatorRuntime?.detail ?? "The video generator is not ready.";if (job.status === "ready") return "This scene is being saved now.";- if (job.usePreviousSceneLastFrame && jobs[0]?.id === job.id) return "This scene needs a previous scene to continue.";- return sendBlocker(job, config.references, animate);+ if (job.sceneType !== "character-replace" && job.usePreviousSceneLastFrame && jobs[0]?.id === job.id) return "This scene needs a previous scene to continue.";+ return templateSceneBlocker(sceneTypeFor(job), selectedTemplate) ?? sendBlocker(job, config.references);};const changedJobIds = new Set(jobs@@ -559,7 +572,7 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCo<div className="panel-scroll"><SceneInspectorkey={selected.id}- animate={animate}+ sceneType={sceneTypeFor(selected)}job={selected}shots={selectedShots}defaultSteps={defaultGenerationSteps}@@ -571,7 +584,7 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCopreviousScene={jobs[jobs.findIndex((job) => job.id === selected.id) - 1]}onAddStartFrame={() => void addFrame(selected, "start")}onAddEndFrame={() => void addFrame(selected, "end")}- onChange={(updates) => updateScene(selected, updates)}+ onChange={(updates) => changeSceneSettings(selected, updates)}onShots={(next) => setShots(selected, next)}/></div>@@ -614,8 +627,14 @@ export function GeneratorView({ config, folderPath, runtime = null, generationCo}/** Validate the inputs required by the selected generator before submission. */-function sendBlocker(job: GenerationJob, references: ProjectReference[], animate = false): string | null {+function sendBlocker(job: GenerationJob, references: ProjectReference[]): string | null {const shots = sceneShots(job);+ const animate = job.sceneType === "animate";+ const characterReplace = job.sceneType === "character-replace";+ if (characterReplace) {+ const blocker = characterReplaceBlocker(job, references);+ if (blocker) return blocker;+ }if (animate) {const bound = sceneGenerationReferences(job, references);if (usableVideoReferences(bound).length !== 1) return "Select exactly one reference video for this scene before animating.";@@ -624,19 +643,26 @@ function sendBlocker(job: GenerationJob, references: ProjectReference[], animatereturn "Animate does not support scene continuation or refmods.";}}- if (!animate && shots.every((shot) => shot.action.trim().length === 0 && !(shot.speech ?? "").trim())) {+ if (!animate && !characterReplace && shots.every((shot) => shot.action.trim().length === 0 && !(shot.speech ?? "").trim())) {return "Describe what happens or add speech in at least one shot before this scene can be generated.";}if (sceneDurationSeconds(job) <= 0) {return "This scene is nought seconds long, so there are no frames to render. Give it a length first.";}const dangling = danglingReferenceTokens(shots, references);- if (!animate && dangling.length > 0) {+ if (!animate && !characterReplace && dangling.length > 0) {return "A reference named in one of the lines can no longer be used, and would be left out of the prompt. Swap it for another one or take it out of the line first.";}return null;}+export function templateSceneBlocker(type: SceneType, template: GeneratorTemplate): string | null {+ if (type === "animate" && template.mode !== "animate") return "Select an Animate generator for this scene.";+ if (type !== "animate" && template.mode === "animate") return "Select a MiniMax prompt generator for this scene.";+ if (type === "character-replace" && /fl2v/i.test(template.paths.transformer)) return "Select a References or Singularity generator for Character Replace.";+ return null;+}+const boardSummary = (active: number, waiting: number, total: number) => {if (total === 0) return "Nothing here yet";if (active > 0) return `${active} rendering · ${waiting} waiting`;diff --git a/src/components/workspace/SceneBoard.tsx b/src/components/workspace/SceneBoard.tsxindex 885413f..2d71747 100644--- a/src/components/workspace/SceneBoard.tsx+++ b/src/components/workspace/SceneBoard.tsx@@ -268,8 +268,9 @@ function ShotCard({ job, shot, index, endsAt, folderPath, estimatedCompletionAt,onDragStart: (event: React.DragEvent<HTMLDivElement>) => void;}) {const parts = splitActionText(shot.action);- const written = shot.action.trim().length > 0;- const chosen = selectedShotTagOptions(shot.settings ?? {});+ const characterReplace = job.sceneType === "character-replace";+ const written = characterReplace ? Boolean(shot.videoReferenceId && shot.characterReferenceId) : shot.action.trim().length > 0;+ const chosen = characterReplace ? [] : selectedShotTagOptions(shot.settings ?? {});return <divclassName={`shot-card ${open ? "shot-card--open" : ""}`}@@ -291,7 +292,9 @@ function ShotCard({ job, shot, index, endsAt, folderPath, estimatedCompletionAt,<em>{seconds(shot.startSeconds)} – {seconds(endsAt)}</em></span><span className={`shot-card__line ${written ? "" : "shot-card__line--empty"}`}>- {written+ {characterReplace+ ? written ? `${named.get(shot.videoReferenceId!) ?? "Unavailable video"} → ${named.get(shot.characterReferenceId!) ?? "Unavailable character"}` : "Choose a video and replacement character for this shot."+ : written? parts.map((part, at) => part.kind === "text"? <span key={at}>{part.value}</span>: <em key={at} className="shot-card__ref">{named.get(part.value) ?? `Reference ${order.indexOf(part.value) + 1}`}</em>)@@ -299,7 +302,7 @@ function ShotCard({ job, shot, index, endsAt, folderPath, estimatedCompletionAt,</span><span className="shot-card__tags">{chosen.map(({ group, option }) => <em key={`${group.id}-${option.id}`} className="shot-card__tag">{option.label}</em>)}- {chosen.length === 0 && <em className="shot-card__tag shot-card__tag--none">No settings</em>}+ {chosen.length === 0 && <em className="shot-card__tag shot-card__tag--none">{characterReplace ? "Character Replace" : "No settings"}</em>}</span></button></div>;diff --git a/src/components/workspace/SceneEditor.tsx b/src/components/workspace/SceneEditor.tsxindex b14c823..82ee43e 100644--- a/src/components/workspace/SceneEditor.tsx+++ b/src/components/workspace/SceneEditor.tsx@@ -21,6 +21,7 @@ import {type GenerationJob,type ProjectReference,type SceneShot,+ type SceneType,} from "../../lib/project";import {hasCameraMovement,@@ -180,6 +181,7 @@ export function ShotInspector({ job, shots, shot, index, endsAt, duration, refer</label></div>+ {job.sceneType === "character-replace" ? <CharacterReplaceInputs shot={shot} references={references} disabled={disabled} onChange={onChange} /> : <><div className="shot-card__action"><label className="shot-card__sublabel" htmlFor={`shot-action-${shot.id}`}>Describe the shot</label><div className="shot-action-editor">@@ -259,16 +261,54 @@ export function ShotInspector({ job, shots, shot, index, endsAt, duration, refershotNumber={shotNumber}onChange={(next) => onChange({ settings: normalizeShotTagSelection(next) })}/>+ </>}</section>;}+function CharacterReplaceInputs({ shot, references, disabled, onChange }: {+ shot: SceneShot; references: ProjectReference[]; disabled: boolean;+ onChange: (updates: Partial<SceneShot>) => void;+}) {+ const videos = usableVideoReferences(references);+ const characters = references.filter((reference) => reference.kind !== "video" && isVisualReference(reference)+ && isReferenceUsable(reference) && referenceImages(reference).length > 0);+ return <div className="scene-settings">+ <label className="scene-settings__field">+ <span>Video reference</span>+ <select aria-label="Video reference for this shot" value={shot.videoReferenceId ?? ""} disabled={disabled}+ onChange={(event) => onChange({ videoReferenceId: event.target.value || null })}>+ <option value="">Select a video</option>+ {shot.videoReferenceId && !videos.some((reference) => reference.id === shot.videoReferenceId) && <option value={shot.videoReferenceId}>Unavailable video reference</option>}+ {videos.map((reference) => <option key={reference.id} value={reference.id}>{reference.name}</option>)}+ </select>+ <small>Uses the clip range and soundtrack setting saved under References.</small>+ </label>+ <label className="scene-settings__field">+ <span>New character reference</span>+ <select aria-label="New character reference for this shot" value={shot.characterReferenceId ?? ""} disabled={disabled}+ onChange={(event) => onChange({ characterReferenceId: event.target.value || null })}>+ <option value="">Select a character</option>+ {shot.characterReferenceId && !characters.some((reference) => reference.id === shot.characterReferenceId) && <option value={shot.characterReferenceId}>Unavailable character reference</option>}+ {characters.map((reference) => <option key={reference.id} value={reference.id}>{reference.name}</option>)}+ </select>+ </label>+ <label className="scene-settings__field">+ <span>Character to replace</span>+ <input aria-label="Character to replace in this shot" value={shot.characterTarget ?? ""} disabled={disabled}+ placeholder="The main character" onChange={(event) => onChange({ characterTarget: event.target.value || null })} />+ <small>If several characters appear, identify one, for example “the person in the red jacket”.</small>+ </label>+ <p>The replacement follows the original performance. Camera movement, background, lighting and other characters are preserved.</p>+ </div>;+}+/* --- The scene, opened from its own line ---------------------------------- *//** Scene-wide render controls, the look the description opens with (base guide* §4.1), and the two sound fields defined per prompt (§4.6, §4.7). Length* lives in the scene header where it stays visible. */-export function SceneInspector({ job, shots, references, previousScene, defaultSteps, defaultLook, disabled, importAvailable, importError, onAddStartFrame, onAddEndFrame, onChange, onShots, animate = false }: {- animate?: boolean;+export function SceneInspector({ job, shots, references, previousScene, defaultSteps, defaultLook, disabled, importAvailable, importError, onAddStartFrame, onAddEndFrame, onChange, onShots, sceneType = job.sceneType ?? "first-last-frame" }: {+ sceneType?: SceneType;defaultLook?: string | null;job: GenerationJob;shots: SceneShot[];@@ -283,6 +323,8 @@ export function SceneInspector({ job, shots, references, previousScene, defaultSonChange: (updates: Partial<GenerationJob>) => void;onShots: (next: SceneShot[]) => void;}) {+ const animate = sceneType === "animate";+ const characterReplace = sceneType === "character-replace";const look = SHOT_TAG_GROUPS.find((group) => group.id === "visualStyle")!;// The style is read off the first shot that carries one, so that is where it// is written. One place, never a second field that could disagree with it.@@ -295,6 +337,18 @@ export function SceneInspector({ job, shots, references, previousScene, defaultSreturn <section className="scene-inspector" aria-label="This scene"><section className="scene-settings" aria-labelledby={`${job.id}-scene-settings`}><h3 id={`${job.id}-scene-settings`}>Scene</h3>+ <label className="scene-settings__field">+ <span>Scene type</span>+ <select aria-label="Scene type" value={sceneType} disabled={disabled}+ onChange={(event) => onChange({ sceneType: event.target.value as SceneType, usePreviousSceneLastFrame: undefined,+ ...(event.target.value === "animate" ? { endFrameReferenceId: undefined } : {}) })}>+ <option value="first-last-frame">First & Last Frame</option>+ <option value="animate">Animate</option>+ <option value="character-replace">Character Replace</option>+ </select>+ </label>+ {characterReplace && <p>Open a shot to select its source video and new character reference.</p>}+ {!characterReplace && <>{animate && <label className="scene-settings__field"><span>Reference video</span><select aria-label="Reference video for this scene" disabled={disabled}@@ -398,6 +452,7 @@ export function SceneInspector({ job, shots, references, previousScene, defaultSonChange={(event) => onChange({ music: event.target.value })}/></label></>}+ </>}</section><section className="scene-settings" aria-labelledby={`${job.id}-generation-settings`}><h3 id={`${job.id}-generation-settings`}>Generation</h3>diff --git a/src/lib/project.ts b/src/lib/project.tsindex c64dc61..3929ce6 100644--- a/src/lib/project.ts+++ b/src/lib/project.ts@@ -356,8 +356,15 @@ export const SCENE_MIN_SECONDS = 0;* length is read as — the length every shot has always been generated at. */export const DEFAULT_SCENE_SECONDS = 6;+export const sceneTypeSchema = z.enum(["first-last-frame", "animate", "character-replace"]);+export type SceneType = z.infer<typeof sceneTypeSchema>;+export const sceneShotSchema = z.object({id: idSchema,+ videoReferenceId: idSchema.nullish(),+ characterReferenceId: idSchema.nullish(),+ /** Identifies the source character when a video contains several people. */+ characterTarget: z.string().nullish(),/** Optional so every project written before shots could be named keeps* round-tripping unchanged. The UI falls back to its numbered Shot N label. */name: z.string().min(1).nullish(),@@ -426,6 +433,7 @@ export function actionReferenceIds(action: string): string[] {export const generationJobSchema = z.object({id: idSchema,+ sceneType: sceneTypeSchema.nullish(),title: z.string().min(1),// Not `.min(1)` any more, and neither is `creativeBrief`: a scene the user has// emptied out has no text to mirror here, and inventing one would put words in@@ -797,6 +805,10 @@ export function usableVideoReferences(references: ProjectReference[]): ProjectRe* order. Frame anchors use their first image, even on a multi-image reference;* the same anchor selected for both ends is sent only once. */export function sceneGenerationReferences(job: GenerationJob, references: ProjectReference[]): ProjectReference[] {+ if (job.sceneType === "character-replace") {+ const ids = sceneShots(job).flatMap((shot) => [shot.videoReferenceId, shot.characterReferenceId]);+ return references.filter((reference) => ids.includes(reference.id));+ }const start = references.find((reference) => reference.id === job.startFrameReferenceId && referenceImages(reference).length > 0 && isReferenceUsable(reference));const end = references.find((reference) => reference.id === job.endFrameReferenceId && referenceImages(reference).length > 0 && isReferenceUsable(reference));const anchors = [start, end].filter((reference, index, all): reference is ProjectReference => Boolean(reference) && all.indexOf(reference) === index)@@ -807,7 +819,7 @@ export function sceneGenerationReferences(job: GenerationJob, references: Projec/** Resolve the adjacent scene when preparing a request; queued work captures* its id so subsequent board edits cannot change the source of that run. */export function sceneFrameInputs(job: GenerationJob, config: ProjectConfig) {- if (!job.usePreviousSceneLastFrame) return { job, references: sceneGenerationReferences(job, config.references) };+ if (job.sceneType === "character-replace" || !job.usePreviousSceneLastFrame) return { job, references: sceneGenerationReferences(job, config.references) };const previous = config.generationJobs[config.generationJobs.findIndex((candidate) => candidate.id === job.id) - 1];const resolved = { ...job, startFrameReferenceId: undefined };return { job: resolved, references: sceneGenerationReferences(resolved, config.references),@@ -922,6 +934,7 @@ export function sceneGenerationSnapshot(job: GenerationJob, input: SceneGenerati.map(([group, values]) => [group, [...values].sort()]),}));return JSON.stringify({+ ...(job.sceneType ? { sceneType: job.sceneType } : {}),prompt: input.prompt,frames: input.frames,steps: input.steps,@@ -967,9 +980,79 @@ export function compileMiniMaxH3PromptSegments(}export function compileGenerationJobSegments(job: GenerationJob, references: ProjectReference[] = [], defaultLook?: string | null): PromptSegment[] {+ if (job.sceneType === "character-replace") return compileCharacterReplaceSegments(job, references);return compileScenePromptSegments({ shots: sceneShots(job), startFrameReferenceId: job.startFrameReferenceId, endFrameReferenceId: job.endFrameReferenceId, soundscape: job.soundscape, music: job.music }, references, defaultLook);}+export function characterReplaceBlocker(job: GenerationJob, references: ProjectReference[]): string | null {+ const videos = usableVideoReferences(references);+ const characters = usableImageReferences(references).filter((reference) => reference.kind !== "video");+ for (const [index, shot] of sceneShots(job).entries()) {+ if (!videos.some((reference) => reference.id === shot.videoReferenceId)) return `Select a video reference for shot ${index + 1}.`;+ if (!characters.some((reference) => reference.id === shot.characterReferenceId)) return `Select a character reference with an image for shot ${index + 1}.`;+ }+ const bound = sceneGenerationReferences(job, references);+ if (usableVideoReferences(bound).length > 3) return "Character Replace supports up to three video references per scene.";+ if (usableReferenceImages(bound).length > 9) return "Character Replace supports up to nine reference images per scene.";+ if (usableVideoReferences(bound).reduce((total, reference) => total + (reference.video?.durationSeconds ?? 2), 0) > 15) return "The selected video clips must total no more than 15 seconds.";+ return null;+}++/** H3's six-section editing contract. Numbering follows the actual payload,+ * including every image of a character reference and stills attached to videos.+ * https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md */+function compileCharacterReplaceSegments(job: GenerationJob, references: ProjectReference[]): PromptSegment[] {+ const bound = sceneGenerationReferences(job, references);+ const videos = usableVideoReferences(bound);+ const characters = usableImageReferences(bound).filter((reference) => reference.kind !== "video");+ const pictures = usableImageReferences(bound).flatMap((reference) => referenceImages(reference).map(() => reference.id));+ const videoLabel = (id: string | null | undefined) => {+ const index = videos.findIndex((reference) => reference.id === id);+ return index < 0 ? "the missing video reference" : `<Video ${index + 1}>`;+ };+ const characterLabel = (id: string | null | undefined) => {+ const index = characters.findIndex((reference) => reference.id === id);+ return index < 0 ? "the missing character reference" : `<Subject ${index + 1}>`;+ };+ const shots = sceneShots(job);+ const appearances = (id: string, field: "videoReferenceId" | "characterReferenceId") => shots+ .flatMap((shot, index) => shot[field] === id ? [`[Shot ${index + 1}]`] : []).join(", ");+ const audioVideos = videos.filter((reference) => reference.video?.includeAudio !== false);+ const audioLabel = (id: string) => `<Audio ${audioVideos.findIndex((reference) => reference.id === id) + 1}>`;+ const definitions = [+ ...videos.map((reference) => frame(`${videoLabel(reference.id)} is the source video to edit in ${appearances(reference.id, "videoReferenceId")}.\n`)),+ ...characters.flatMap((reference): PromptSegment[] => {+ const sources = pictures.flatMap((id, index) => id === reference.id ? [`<Picture ${index + 1}>`] : []).join(", ");+ const detail = referenceDefinition(reference).trim();+ return [frame(`${characterLabel(reference.id)} is the replacement character shown in ${sources}.`),+ ...(detail ? [frame(" "), own(detail), ...addedStop(detail)] : []), frame("\n")];+ }),+ ...audioVideos.map((reference) => frame(`${audioLabel(reference.id)} is the enabled soundtrack of ${videoLabel(reference.id)}.\n`)),+ ];+ const replacement = (shot: SceneShot): PromptSegment[] => [+ frame(`In ${videoLabel(shot.videoReferenceId)}, replace `),+ ...(shot.characterTarget?.trim() ? [own(shot.characterTarget.trim())] : [frame("the main character")]),+ frame(` with ${characterLabel(shot.characterReferenceId)}. Match the replacement's face, hair, body proportions, clothing and identifying features to the character reference. Preserve the source character's motion, pose, expression, gaze and timing. Keep the camera movement, framing, background, lighting, objects and other characters unchanged. Maintain consistent identity, natural contact, shadows and occlusion throughout the shot.`),+ ];+ const retention = [+ ...videos.map((reference) => `${videoLabel(reference.id)} (${appearances(reference.id, "videoReferenceId")}): partially_preserved - change only the selected character's appearance; retain the performance and surrounding scene.`),+ ...characters.map((reference) => `${characterLabel(reference.id)} (appears in ${appearances(reference.id, "characterReferenceId")}): fully_preserved - retain the replacement character's visual identity from its reference images.`),+ ...audioVideos.map((reference) => `${audioLabel(reference.id)}: partially_copy - reuse the source soundtrack during ${appearances(reference.id, "videoReferenceId")}, synchronized to the source performance.`),+ ];+ return [+ frame("subject_definitions:\n"), ...definitions,+ frame(`\nsummary:\n[video editing + reference generation${audioVideos.length ? " + audio reuse" : ""}] The target video is an edited version of ${videos.map((reference) => videoLabel(reference.id)).join(", ") || "the selected source videos"}. Replace the selected character in each shot with its assigned replacement character.\n\nretention_analysis:\n${retention.join("\n")}\n\ndetailed_description:\nRetain the visual style of each source video.\n`),+ ...shots.flatMap((shot, index): PromptSegment[] => {+ const timestamp = `${String(Math.floor(shot.startSeconds / 60)).padStart(2, "0")}:${(shot.startSeconds % 60).toFixed(3).padStart(6, "0")}`;+ const sourceAudio = audioVideos.find((reference) => reference.id === shot.videoReferenceId);+ return [frame(`${index ? "\n" : ""}[Shot ${index + 1}] ${index ? `At ${timestamp}, ` : ""}`), ...replacement(shot),+ ...(sourceAudio ? [frame(` Reuse ${audioLabel(sourceAudio.id)} in sync with this shot.`)] : [frame(" Do not reuse the source soundtrack.")])];+ }),+ frame(`\n\noverall_soundscape:\n${audioVideos.length ? `Reuse the ambience, physical sounds and speech from ${audioVideos.map((reference) => audioLabel(reference.id)).join(", ")} in their corresponding shots.` : "Use only ambience and physical sounds consistent with the source scene; no added speech."}`),+ frame(`\n\nnon_diegetic_music:\n${audioVideos.length ? "Retain only music already present in the reused source soundtrack. Add no new score." : "N/A"}`),+ ];+}+export function compileGenerationJobPrompt(job: GenerationJob, references: ProjectReference[] = [], defaultLook?: string | null): string {return compileGenerationJobSegments(job, references, defaultLook).map((segment) => segment.value).join("");}@@ -1256,6 +1339,7 @@ export function createDraftGenerationJob(creativeBrief: string,options: {id?: string;+ sceneType?: SceneType;title?: string;referenceIds?: string[];startFrameReferenceId?: string | null;@@ -1286,6 +1370,7 @@ export function createDraftGenerationJob(const text = sceneBriefText(shots);return generationJobSchema.parse({id,+ ...(options.sceneType ? { sceneType: options.sceneType } : {}),// Their own words, cut short — and only ever their words. See UNTITLED_SCENE.title: options.title ?? (text.split(/\s+/).filter(Boolean).slice(0, 6).join(" ") || UNTITLED_SCENE),prompt: text,