Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

feat([issue-12763]): condition music video frames on Casting cast guides

[._.]/ Adam Eivy3e6535d401b6
diff --git a/client/src/components/musicVideo/SceneCard.jsx b/client/src/components/musicVideo/SceneCard.jsx
index 6d5114a4b3..9c3b19ac7f 100644
--- a/client/src/components/musicVideo/SceneCard.jsx
+++ b/client/src/components/musicVideo/SceneCard.jsx
@@ -120,7 +120,7 @@ export default function SceneCard({
scene, index, shotNumber = null, isLast, generatingFrame, generatingVideo, frameProgress = null, videoProgress = null,
settingsSaving, videoBlockedReason, videoBlockedReasonFor = null, canContinueShot,
onMove, onDelete, onEditLocal, onSave,
- project = null, onGenerateFrame, onGenerateVideo, onContinueVideo, onGenerateEndFrame, generatingEndFrame = false, onContinueFromPrevious, previousHasClip = false,
+ project = null, castMedia = null, onGenerateFrame, onGenerateVideo, onContinueVideo, onGenerateEndFrame, generatingEndFrame = false, onContinueFromPrevious, previousHasClip = false,
onOpenPreview, onSelectTake, onReviewTake, onRejectUnusedTakes = null, onSwapFrames = null, onMarkTake = null, onPoolMarked = null, onImportTake, onImportClipTake, onPlacePoolItem, onTrimClip, projectId = null, aspect = '16:9', videoModels = [], defaultVideoModel = '', shotNumbers = undefined, takeBusy = false, layered = false, documentComposition = false,
lipSyncBackend = '', songDurationSec = null, onSplit, onMergeNext, onMergePrevious = null, prevStartSec = null, onMoveStart = null, nextEndSec = null, falVideoSettings = null, onSeek, performanceReview = null, onRepairPerformance, repairBusy = false,
expanded, onToggleExpand, stepShot = null, footageOptional = false, failedScenes = null, songReview = null,
@@ -451,7 +451,7 @@ export default function SceneCard({
<div className="grid gap-3 @3xl:grid-cols-2">
{/* Frames: the still this shot starts from and, optionally, the one it ends on (#11173),
each with its prompt and Render under it, then the tapped frame's takes. */}
- <SceneFrames project={project} scene={scene} index={index} endFrames={endFrames} generatingFrame={!!generatingFrame} generatingEndFrame={!!generatingEndFrame}
+ <SceneFrames project={project} castMedia={castMedia} scene={scene} index={index} endFrames={endFrames} generatingFrame={!!generatingFrame} generatingEndFrame={!!generatingEndFrame}
onGenerateFrame={onGenerateFrame} onGenerateEndFrame={onGenerateEndFrame} onEditLocal={onEditLocal} onSave={onSave}
onOpenPreview={onOpenPreview} takeBusy={takeBusy} onSelectTake={onSelectTake} onReviewTake={onReviewTake}
onSwap={onPlacePoolItem ? setSwapKind : null} onSwapFrames={onSwapFrames ? () => onSwapFrames(scene) : null} onImportTake={onImportTake}
diff --git a/client/src/components/musicVideo/SceneCastVariant.jsx b/client/src/components/musicVideo/SceneCastVariant.jsx
new file mode 100644
index 0000000000..6f602aba65
--- /dev/null
+++ b/client/src/components/musicVideo/SceneCastVariant.jsx
@@ -0,0 +1,73 @@
+import { CAST_ERAS } from '../../../../server/lib/catalogMediaLibrary.js';
+
+const FIELD = 'min-h-[44px] rounded border border-port-border bg-port-bg px-2 text-xs sm:min-h-[32px]';
+
+/**
+ * Which Casting cast member this shot features, and at what age, era or look
+ * (#12763). Saved as `scene.characterVariant`; the shot's frames then lead with
+ * that member's render guides closest to the variant (References row below).
+ * Only subjects saved to Casting (`ingredientId`) can be picked.
+ */
+export default function SceneCastVariant({ project, scene, castMedia = null, onEditLocal, onSave, disabled = false }) {
+ const cast = (project?.concept?.subjects || []).filter((s) => s?.kind === 'character' && s.ingredientId);
+ if (!cast.length) return null;
+ const variant = scene.characterVariant || null;
+ const id = (name) => `mv-scene-${scene.sceneId}-cast-${name}`;
+ const save = (next) => { onEditLocal(scene.sceneId, { characterVariant: next }); onSave(scene.sceneId, { characterVariant: next }); };
+ const withField = (key, value) => {
+ const next = { ...variant, [key]: value };
+ if (value === undefined) delete next[key];
+ return next;
+ };
+ const looks = variant
+ ? [...new Set((castMedia?.[variant.ingredientId] || []).map((m) => m.library?.variant?.wardrobeId).filter(Boolean))]
+ : [];
+ if (variant?.wardrobeId && !looks.includes(variant.wardrobeId)) looks.push(variant.wardrobeId);
+
+ return (
+ <fieldset disabled={disabled} className="flex min-w-0 flex-wrap items-end gap-2">
+ <legend className="sr-only">Cast member in this shot</legend>
+ <div className="flex min-w-0 flex-col">
+ <label htmlFor={id('member')} className="text-[11px] text-port-text-muted">Cast guides</label>
+ <select id={id('member')} className={`${FIELD} max-w-full`} value={variant?.ingredientId || ''}
+ onChange={(e) => save(e.target.value ? { ingredientId: e.target.value } : null)}>
+ <option value="">None</option>
+ {cast.map((s) => <option key={s.ingredientId} value={s.ingredientId}>{s.name}</option>)}
+ {variant && !cast.some((s) => s.ingredientId === variant.ingredientId) && <option value={variant.ingredientId}>Removed cast member</option>}
+ </select>
+ </div>
+ {variant && (
+ <>
+ <div className="flex flex-col">
+ <label htmlFor={id('age')} className="text-[11px] text-port-text-muted">Age</label>
+ {/* Keyed on the saved age so an edit elsewhere (another tab, a synced machine) shows here. */}
+ <input key={variant.age ?? ''} id={id('age')} type="number" min={0} max={150} step={1} inputMode="numeric" defaultValue={variant.age ?? ''}
+ className={`${FIELD} w-20`}
+ onBlur={(e) => {
+ const raw = e.target.value.trim();
+ const age = raw === '' ? undefined : Number(raw);
+ if (age !== undefined && (!Number.isInteger(age) || age < 0 || age > 150)) { e.target.value = variant.age ?? ''; return; }
+ if (age !== variant.age) save(withField('age', age));
+ }} />
+ </div>
+ <div className="flex flex-col">
+ <label htmlFor={id('era')} className="text-[11px] text-port-text-muted">Era</label>
+ <select id={id('era')} className={FIELD} value={variant.era || ''} onChange={(e) => save(withField('era', e.target.value || undefined))}>
+ <option value="">Any</option>
+ {CAST_ERAS.map((era) => <option key={era} value={era}>{era}</option>)}
+ </select>
+ </div>
+ {looks.length > 0 && (
+ <div className="flex min-w-0 flex-col">
+ <label htmlFor={id('look')} className="text-[11px] text-port-text-muted">Look</label>
+ <select id={id('look')} className={`${FIELD} max-w-full`} value={variant.wardrobeId || ''} onChange={(e) => save(withField('wardrobeId', e.target.value || undefined))}>
+ <option value="">Any</option>
+ {looks.map((look) => <option key={look} value={look}>{look}</option>)}
+ </select>
+ </div>
+ )}
+ </>
+ )}
+ </fieldset>
+ );
+}
diff --git a/client/src/components/musicVideo/SceneCastVariant.test.jsx b/client/src/components/musicVideo/SceneCastVariant.test.jsx
new file mode 100644
index 0000000000..92638475b8
--- /dev/null
+++ b/client/src/components/musicVideo/SceneCastVariant.test.jsx
@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import SceneCastVariant from './SceneCastVariant.jsx';
+
+const project = { concept: { subjects: [
+ { id: 'mvc-1', kind: 'character', name: 'Example Lead', ingredientId: 'cat-chr-x' },
+ { id: 'mvc-2', kind: 'character', name: 'Not in Casting' },
+] } };
+
+describe('a shot\'s Cast guides picker', () => {
+ // Uniquely catches the picker offering subjects with no Casting record, or the variant not reaching the scene PATCH.
+ it('saves the picked Casting member, then its age, era and look', () => {
+ const onSave = vi.fn();
+ const { rerender } = render(<SceneCastVariant project={project} scene={{ sceneId: 's1' }} onEditLocal={vi.fn()} onSave={onSave} />);
+ const member = screen.getByLabelText('Cast guides');
+ expect([...member.options].map((o) => o.textContent)).toEqual(['None', 'Example Lead']);
+ fireEvent.change(member, { target: { value: 'cat-chr-x' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { characterVariant: { ingredientId: 'cat-chr-x' } });
+
+ const castMedia = { 'cat-chr-x': [{ mediaKey: 'a.png', kind: 'reference', library: { variant: { wardrobeId: 'look-1' } } }] };
+ rerender(<SceneCastVariant project={project} scene={{ sceneId: 's1', characterVariant: { ingredientId: 'cat-chr-x' } }} castMedia={castMedia} onEditLocal={vi.fn()} onSave={onSave} />);
+ const age = screen.getByLabelText('Age');
+ fireEvent.change(age, { target: { value: '7' } });
+ fireEvent.blur(age);
+ expect(onSave).toHaveBeenLastCalledWith('s1', { characterVariant: { ingredientId: 'cat-chr-x', age: 7 } });
+
+ rerender(<SceneCastVariant project={project} scene={{ sceneId: 's1', characterVariant: { ingredientId: 'cat-chr-x', age: 7 } }} castMedia={castMedia} onEditLocal={vi.fn()} onSave={onSave} />);
+ fireEvent.change(screen.getByLabelText('Era'), { target: { value: 'child' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { characterVariant: { ingredientId: 'cat-chr-x', age: 7, era: 'child' } });
+ fireEvent.change(screen.getByLabelText('Look'), { target: { value: 'look-1' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { characterVariant: { ingredientId: 'cat-chr-x', age: 7, wardrobeId: 'look-1' } });
+ fireEvent.change(screen.getByLabelText('Cast guides'), { target: { value: '' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { characterVariant: null });
+ });
+
+ it('renders nothing when no subject is saved to Casting', () => {
+ const { container } = render(<SceneCastVariant project={{ concept: { subjects: [project.concept.subjects[1]] } }} scene={{ sceneId: 's1' }} onEditLocal={vi.fn()} onSave={vi.fn()} />);
+ expect(container.firstChild).toBeNull();
+ });
+});
diff --git a/client/src/components/musicVideo/SceneFrameReferences.jsx b/client/src/components/musicVideo/SceneFrameReferences.jsx
index 94322ced00..d4b92d3fb9 100644
--- a/client/src/components/musicVideo/SceneFrameReferences.jsx
+++ b/client/src/components/musicVideo/SceneFrameReferences.jsx
@@ -1,6 +1,6 @@
import { useEffect, useRef, useState } from 'react';
import { Plus, X } from 'lucide-react';
-import { musicVideoConditioningReferences, musicVideoReferenceChoices, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES } from '../../../../server/lib/musicVideoConditioning.js';
+import { musicVideoCastGuideReferences, musicVideoConditioningReferences, musicVideoReferenceChoices, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES } from '../../../../server/lib/musicVideoConditioning.js';
import { MUSIC_VIDEO_OTHER_REFERENCES_NOTE } from '../../../../server/lib/musicVideoShotPrompt.js';
// No iOS image callout or text selection, so a long-press opens the preview instead.
@@ -14,18 +14,19 @@ const nameOf = (ref) => ref.label || ref.role || 'Reference';
* end and both refines), shown as chips. Until the director changes them it is
* the automatic set (the main character, the section's set and anyone the
* prompt names); a change is kept on the shot (`frameReferenceIds`), and Auto
- * puts the automatic set back.
+ * puts the automatic set back. A shot naming a Casting cast member
+ * (`characterVariant`, #12763) leads with that member's guides, from `castMedia`.
*/
-export default function SceneFrameReferences({ project, scene, onEditLocal, onSave, disabled = false }) {
+export default function SceneFrameReferences({ project, scene, castMedia = null, onEditLocal, onSave, disabled = false }) {
const [adding, setAdding] = useState(false);
// The reference shown large: hovering a chip with a mouse, or long-pressing it on a phone.
const [preview, setPreview] = useState(null);
const pressTimer = useRef(null);
const longPressed = useRef(false);
useEffect(() => () => clearTimeout(pressTimer.current), []);
- const choices = musicVideoReferenceChoices(project);
+ const choices = [...musicVideoCastGuideReferences(project, scene, castMedia), ...musicVideoReferenceChoices(project)];
if (!choices.length) return null;
- const chosen = musicVideoConditioningReferences(project, scene);
+ const chosen = musicVideoConditioningReferences(project, scene, castMedia);
const ids = chosen.map((ref) => ref.id);
const others = choices.filter((ref) => !ids.includes(ref.id));
const auto = !Array.isArray(scene.frameReferenceIds);
diff --git a/client/src/components/musicVideo/SceneFrameReferences.test.jsx b/client/src/components/musicVideo/SceneFrameReferences.test.jsx
index c3e1d79576..334ac8305b 100644
--- a/client/src/components/musicVideo/SceneFrameReferences.test.jsx
+++ b/client/src/components/musicVideo/SceneFrameReferences.test.jsx
@@ -47,3 +47,19 @@ describe('a shot\'s References row', () => {
expect(screen.queryByRole('figure')).toBeNull();
});
});
+
+describe('a shot that names a Casting cast member', () => {
+ // Uniquely catches the References row hiding the Casting guides a frame render sends, or removing one dropping the rest.
+ it('leads with the variant\'s guides and keeps them when another reference is taken off', () => {
+ const cast = { ...project, concept: { subjects: [{ id: 'mvc-1', kind: 'character', name: 'Example Lead', ingredientId: 'cat-chr-x' }] } };
+ const castMedia = { 'cat-chr-x': [
+ { mediaKey: 'adult.png', kind: 'reference', library: { variant: { age: 30 }, guide: true } },
+ { mediaKey: 'child.png', kind: 'reference', library: { variant: { age: 7 }, guide: true } },
+ ] };
+ const onSave = vi.fn();
+ render(<SceneFrameReferences project={cast} scene={{ sceneId: 's1', characterVariant: { ingredientId: 'cat-chr-x', age: 7 } }} castMedia={castMedia} onEditLocal={vi.fn()} onSave={onSave} />);
+ expect(screen.getAllByRole('listitem').map((li) => li.getAttribute('title')).filter(Boolean)).toEqual(['Example Lead · age 7', 'Example Lead · age 30', expect.stringMatching(/^Lead/)]);
+ fireEvent.click(screen.getByRole('button', { name: /Don't send Lead/ }));
+ expect(onSave).toHaveBeenCalledWith('s1', { frameReferenceIds: ['mvr-guide-child.png', 'mvr-guide-adult.png'] });
+ });
+});
diff --git a/client/src/components/musicVideo/SceneFrames.jsx b/client/src/components/musicVideo/SceneFrames.jsx
index 32714b2457..c824fceb21 100644
--- a/client/src/components/musicVideo/SceneFrames.jsx
+++ b/client/src/components/musicVideo/SceneFrames.jsx
@@ -1,6 +1,7 @@
import { useLayoutEffect, useRef, useState } from 'react';
import { Activity, ArrowLeftRight, ArrowRight, Image as ImageIcon, ImagePlus, PencilLine, Shuffle, SkipForward, Wand2, X } from 'lucide-react';
import SceneTakeStrip from './SceneTakeStrip.jsx';
+import SceneCastVariant from './SceneCastVariant.jsx';
import SceneFrameReferences from './SceneFrameReferences.jsx';
const PRIMARY_BUTTON = 'flex items-center gap-1 bg-port-border hover:bg-port-border/70 disabled:opacity-50 rounded px-2 py-1.5 text-xs min-h-[44px] sm:min-h-0 whitespace-nowrap';
@@ -63,7 +64,7 @@ const REFERENCE_LABELS = { '': 'Prompt only', start: 'Start frame', end: 'End fr
* The References row above them picks the character and set references every frame render sends.
*/
export default function SceneFrames({
- project = null, scene, index, endFrames, generatingFrame = false, generatingEndFrame = false, onGenerateFrame, onGenerateEndFrame,
+ project = null, castMedia = null, scene, index, endFrames, generatingFrame = false, generatingEndFrame = false, onGenerateFrame, onGenerateEndFrame,
onEditLocal, onSave, onOpenPreview, takeBusy = false, onSelectTake, onReviewTake, onSwap = null, onImportTake = null,
onContinueFromPrevious = null, previousHasClip = false, clipLocked = false, onSwapFrames = null, assetMarks = null, onMarkTake = null,
}) {
@@ -186,7 +187,8 @@ export default function SceneFrames({
return (
<section aria-label="Still" className="@container min-w-0 space-y-2">
<h4 className="text-xs font-medium">{endFrames ? 'Frames' : 'Still'}</h4>
- <SceneFrameReferences project={project} scene={scene} onEditLocal={onEditLocal} onSave={onSave} />
+ <SceneCastVariant project={project} scene={scene} castMedia={castMedia} onEditLocal={onEditLocal} onSave={onSave} />
+ <SceneFrameReferences project={project} scene={scene} castMedia={castMedia} onEditLocal={onEditLocal} onSave={onSave} />
{endFrames ? (
<div role="group" aria-label="Start and end frames" className="grid gap-3 @sm:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)]">
{column('start')}
diff --git a/client/src/components/musicVideo/stages/BoardStage.jsx b/client/src/components/musicVideo/stages/BoardStage.jsx
index acc2b542ca..3b625f7057 100644
--- a/client/src/components/musicVideo/stages/BoardStage.jsx
+++ b/client/src/components/musicVideo/stages/BoardStage.jsx
@@ -280,6 +280,7 @@ export default function BoardStage({ board }) {
onEditLocal={board.editSceneLocal}
onSave={board.saveScene}
onGenerateFrame={sceneMedia.generateFrame}
+ castMedia={sceneMedia.castMedia}
onGenerateEndFrame={sceneMedia.generateEndFrame}
generatingEndFrame={sceneMedia.genEndFrameScenes?.[scene.sceneId]}
onGenerateVideo={sceneMedia.generateSceneVideo}
diff --git a/client/src/hooks/README.md b/client/src/hooks/README.md
index 5f29f6437e..03bcac8d21 100644
--- a/client/src/hooks/README.md
+++ b/client/src/hooks/README.md
@@ -276,7 +276,7 @@ grep -i "what you want to do" client/src/hooks/README.md
| `useMusicVideoPublishKit` | Music Video publishing kit (#9281): a `useSseJobSlot` build job (encodes, thumbnails, captions, chapters) whose terminal frame reloads the project, plus the one-call copy draft, per-field copy edits, the YouTube thumbnail and cover art, each applying the returned project. Returns `{ building, progress, build(), cancelBuild(), drafting, saving, draftCopy(body), saveCopy(patch), composingThumbnail, composeThumbnail(body), clearThumbnail(), addThumbnailTest(), removeThumbnailTest(filename), paintingThumbnail, paintThumbnail(body), … }` plus the cover-art actions. | The Music Video Publish stage. |
| `useMusicVideoPublishing` | Music Video posting (#9282): per-platform drafts filled in the PortOS Browser. `prepare` returns the filled draft's summary and screenshot (a sign-in-required refusal is kept as the platform's error with its login URL), `submit` posts that reviewed draft and applies the returned project, `discard` closes it. Platforms are opt-in (#9287): it loads the saved `platforms` (enabled + optional account each) and per-platform `history` (posts, reception tally, recent notes across projects); `setPlatform` toggles one optimistically and `recordPost` saves a hand-made post's link or a post's reception and notes. Returns `{ drafts, busy, errors, prepare(target, options), submit(target), discard(target), platforms, history, enabledTargets, setPlatform(target, change), recordPost(target, body) }`. | The Music Video Publish stage's posting panel. |
| `useMusicVideoModelSettings` | A project's saved render pins — video backend (local/Grok/fal.ai)/model/generation-mode/audio-reactive LoRA + the image-side frame pin — with the Video Gen catalog they read from. Optimistic-local + silent PATCH, rollback + toast on failure; `saving` gates the dependent generate buttons. Returns `{ models, modelsLoading, defaultModel, falEnabled, saving, settings, effectiveModelId, activeModel, audioReactiveModels, audioReactiveLoras, detectedAudioReactiveLora, audioReactiveReady, audioReactiveSelected, videoBlockedReason, change, changeFramePin }`. `videoBlockedReason` is the single "why can't I generate" string (an unavailable audio-reactive setup, or a fal.ai pin with no configured API key) shared by the disabled buttons, their tooltips, and the blocked-call toast. | The Music Video renderer selects and anything building a scene-clip job payload from them. |
-| `useMusicVideoSceneMedia` | Both per-scene generation lanes (reference frame + scene clip) over `useSceneRenderLifecycle`, the frame/shot prompt builders (concept-style + visual-spec direction suffix), visual-spec reference-image conditioning with explicit unsupported-backend feedback (#8965), the batch "generate the missing ones" actions, restores in-flight scene renders from the server queue on mount (`getMusicVideoSceneJobs`) so a reload doesn't invite duplicate submits, and folds the persisted `scene.lastFailure` (socket `music-video:scene-failure`) onto the scene (#10154). Returns `{ genScenes, genVideoScenes, conditioning, buildFramePrompt, buildShotPrompt, generateFrame, generateSceneVideo, continueSceneVideo, generateMissingFrames, generateMissingVideos, planMissingFrames, planMissingVideos, frameBatch, videoBatch, sceneProgress, videoSceneProgress }` (the batches run counted via `useSceneBatch`; the board confirms count + estimate before calling `generateMissing*`). | The Music Video scene board — don't re-wire the two lanes or re-derive the i2v/a2v/extend payloads. |
+| `useMusicVideoSceneMedia` | Both per-scene generation lanes (reference frame + scene clip) over `useSceneRenderLifecycle`, the frame/shot prompt builders (concept-style + visual-spec direction suffix), visual-spec reference-image conditioning with explicit unsupported-backend feedback (#8965), the batch "generate the missing ones" actions, restores in-flight scene renders from the server queue on mount (`getMusicVideoSceneJobs`) so a reload doesn't invite duplicate submits, and folds the persisted `scene.lastFailure` (socket `music-video:scene-failure`) onto the scene (#10154). Loads the Casting media of each cast member a shot names in `characterVariant` (#12763) so frame conditioning leads with their guides. Returns `{ genScenes, genVideoScenes, conditioning, castMedia, buildFramePrompt, buildShotPrompt, generateFrame, generateSceneVideo, continueSceneVideo, generateMissingFrames, generateMissingVideos, planMissingFrames, planMissingVideos, frameBatch, videoBatch, sceneProgress, videoSceneProgress }` (the batches run counted via `useSceneBatch`; the board confirms count + estimate before calling `generateMissing*`). | The Music Video scene board — don't re-wire the two lanes or re-derive the i2v/a2v/extend payloads. |
| `useMusicVideoTakes` | Scene-take review + external-asset handoff for the Music Video board (#8965): serialized select / reject / note / gallery-import take mutations folded back as scene patches, the handoff manifest download, and the handoff import (gallery upload per file, then scene association by file tag with provider provenance). Returns `{ busy, selectTake, reviewTake, importTake, exportHandoff, importHandoffFiles }`. | The Music Video board's take strips, contact sheet and handoff row — don't re-sequence take mutations per call site. |
| `useMusicVideoTreatment` | The Music Video pre-production treatment (#8980): serialized brief/arc/shot-direction saves that each carry the latest known treatment revision (a 409 from a newer copy reloads the project), explicit compile (AI or deterministic) with skip-reason feedback, the Apply review (`loadPreview` → `apply({ overwrite, addTextCues })`) and proof verdicts. Returns `{ compiling, preview, previewing, applying, save, compile, loadPreview, apply, reviewProof, clearPreview }`. | The Music Video treatment panel — don't re-derive the revision bookkeeping per call site. |
| `useMusicVideoManualTempo` | The manual-tempo fallback for a project whose auto-detected BPM is null: BPM/offset drafts (reset on project switch), tap-tempo estimation, and the persisted `setMusicVideoManualTempo` call. Returns `{ bpm, setBpm, offset, setOffset, saving, tap, submit }`. | The Music Video "No tempo detected" row. |
diff --git a/client/src/hooks/useMusicVideoSceneMedia.js b/client/src/hooks/useMusicVideoSceneMedia.js
index 837b70e6ab..2149d3bbee 100644
--- a/client/src/hooks/useMusicVideoSceneMedia.js
+++ b/client/src/hooks/useMusicVideoSceneMedia.js
@@ -2,10 +2,11 @@ import { shotActionContractProblem } from '../../../server/lib/musicVideoActionC
import { isOutsideMusicVideoReference, musicVideoConditioningReferences, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES } from '../../../server/lib/musicVideoConditioning.js';
import { sceneEndFrameRequestFields } from '../../../server/lib/musicVideoEndFrame.js';
import { authoredFramePromptText, authoredShotPrompt, musicVideoFrameModelInput, visualDirection } from '../../../server/lib/musicVideoShotPrompt.js';
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
import socket from '../services/socket';
import toast from '../components/ui/Toast';
import { addMusicVideoSceneTake, getMusicVideoSceneJobs } from '../services/apiMusicVideo.js';
+import { listCatalogIngredientMedia } from '../services/apiCatalog.js';
import { generateImage } from '../services/apiSystem.js';
import { generateVideo } from '../services/apiImageVideo.js';
import useSceneBatch from './useSceneBatch.js';
@@ -157,6 +158,20 @@ export default function useMusicVideoSceneMedia({ project, videoSettings, applyS
.catch(() => {}); // best-effort: a failed lookup just means no restored spinners
return () => { live = false; };
}, [projectId, restoreFrameJobs, restoreVideoJobs, restoreEndFrameJobs]);
+ // The Casting media of every cast member a shot names in its `characterVariant`
+ // (#12763), keyed by ingredient id. A shot's frames lead with that member's
+ // guides; until a load lands (or when it fails) the shot uses the automatic set.
+ const castIds = [...new Set((project?.scenes || []).map((scene) => scene?.characterVariant?.ingredientId).filter(Boolean))].sort().join(',');
+ const [castMedia, setCastMedia] = useState({});
+ useEffect(() => {
+ if (!castIds) return undefined;
+ let active = true;
+ Promise.all(castIds.split(',').map((id) => listCatalogIngredientMedia(id, { silent: true })
+ .then((media) => (Array.isArray(media) ? [id, media] : null), () => null)))
+ .then((entries) => { if (active) setCastMedia(Object.fromEntries(entries.filter(Boolean))); });
+ return () => { active = false; };
+ }, [castIds]);
+
const genScenes = frameLane.genScenes;
const genVideoScenes = videoLane.genScenes;
const failedScenes = { frame: frameLane.failedScenes, video: videoLane.failedScenes };
@@ -192,7 +207,7 @@ export default function useMusicVideoSceneMedia({ project, videoSettings, applyS
const generateFrame = (scene, { revisionId, onJob, referenceImageId = null, refine = null } = {}) => {
const refining = Boolean(refine?.trim() && referenceImageId);
// The shot's references (the card's References row) ride along on every frame render, a refine included.
- const conditioning = conditioningReferences(project, scene);
+ const conditioning = conditioningReferences(project, scene, castMedia);
const problem = refining ? null : shotActionContractProblem(scene.direction?.actionContract, scene);
if (problem) { toast.error(problem); return Promise.resolve({ ok: false }); }
// The director's text (or a refine's instruction); the server composes the still's
@@ -261,7 +276,7 @@ export default function useMusicVideoSceneMedia({ project, videoSettings, applyS
if (!endPrompt && !refining) { toast.error('Describe the end frame first'); return Promise.resolve({ ok: false }); }
const projectId = project.id;
// The frame it renders from leads, then the shot's references (the card's References row).
- const references = frameReferenceFiles(referenceImageId, conditioningReferences(project, scene));
+ const references = frameReferenceFiles(referenceImageId, conditioningReferences(project, scene, castMedia));
endFrameLane.startScene(scene.sceneId);
return generateImage({
// From a frame the server keeps its shot and changes what the prompt asks; with no frame it renders like a start frame.
@@ -503,6 +518,7 @@ export default function useMusicVideoSceneMedia({ project, videoSettings, applyS
frameBatch,
videoBatch,
conditioning,
+ castMedia,
generateFrame,
generateEndFrame,
generateSceneVideo,
diff --git a/server/lib/README.md b/server/lib/README.md
index e51a41f0d2..4d3d755346 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -885,7 +885,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `musicVideoAspect.js` | `musicVideoAspect(project)` (treatment brief aspect, default 16:9), `MUSIC_VIDEO_FRAME_GEN_SIZES` and `musicVideoFrameGenSize(project)`: the size every Music Video reference frame is requested at, so a backend never picks portrait for a 16:9 video. `musicVideoAtAspect(project, aspect)` re-frames the project for one render (a vertical social cut) without touching the record. `musicVideoLocalClipSize(project, model, { endFrame })` sizes a local clip to the aspect, `musicVideoRenderCanvas(aspect, lead)` the final render's frame, and `matchesMusicVideoAspect(w, h, aspect)` tests a frame's shape. Shared by `productionDispatch.js`, `documentRender.js` and the client board. |
| `musicVideoMotion.js` | `MOTION_CONTINUITY_CLAUSE`: the clause every Music Video motion (i2v) prompt ends with, pinning the reference frame's lighting, time of day and palette. Shared by `handoff.js` and the client board. `AUDIO_REACTIVE_PERFORMANCE_GUARD`: the clause an audio-reactive shot's prompt ends with. `silentMotionPrompt(prompt, { styleParts })`: the same prompt as plain physical motion (no lyric/beat cues, song times or look words) for a take that hears no audio; applied at video submit only to a request sent before `musicVideoShotPrompt.js` composed clips. |
| `musicVideoShotPrompt.js` | The model input for a Music Video shot's clip and stills (#11317): `musicVideoShotModelInput(project, scene, opts)` → `{ prompt, promptAdditions }`, the director's text plus each block PortOS adds (project look, bible, palette/camera rules, shot direction, lighting continuity, camera move, shot actions, Grok phrase timing, audio-reactive guard, song audio reference, repair notes) as a labeled addition; a take that hears no audio is composed without the look, song timing or on-beat camera clause. `musicVideoFrameModelInput(project, scene, { slot, fromFrame, refine, repairs, fixes })` does the same for a start or end frame (look, frame direction, plate actions, rework line, keep-the-shot line, refine wrapper). `authoredShotPrompt`, `authoredFramePromptText` and `visualDirection`. Shared by the shot card, the board, the production run and the image and video submits. |
-| `musicVideoConditioning.js` | `musicVideoStyleImages`, `musicVideoStylePrompt`, `musicVideoStyleBasis`, and `musicVideoStyleReferenceCapacity` supply bounded moodboard conditioning and text fallback; `musicVideoConditioningReferences(project, scene)` selects the approved character sheet, the scene's mapped set plate and the sheets of supporting cast the scene's prompt names (capped at 4), with capped project-wide fallback; shared by board and production. |
+| `musicVideoConditioning.js` | `musicVideoStyleImages`, `musicVideoStylePrompt`, `musicVideoStyleBasis`, and `musicVideoStyleReferenceCapacity` supply bounded moodboard conditioning and text fallback; `musicVideoConditioningReferences(project, scene, castMedia?)` selects the approved character sheet, the scene's mapped set plate and the sheets of supporting cast the scene's prompt names (capped at 4), with capped project-wide fallback; a scene's `characterVariant` leads with that Casting member's guides (`musicVideoCastGuideReferences`, via `catalogMediaLibrary.pickGuideMedia`) when `castMedia` is supplied; shared by board and production. |
| `musicVideoMediumPlan.js` | `normalizeMusicVideoProductionPolicy`, `planMusicVideoMedia`, `summarizeMusicVideoMediumPlan`, and `codeFirstProductionAssets`: pinned shot media, union-of-intervals video allowance, and selected-asset preflight shared by planning and Board review. `musicVideoBriefTools`, `musicVideoBriefAllowsVideo` and `musicVideoToolPolicyConflict` read the brief's selected tools against the policy (the setup warning and the video-dispatch refusal). |
| `imageLimits.js` | MAX_IMAGE_EDGE, MAX_IMAGE_PIXELS — browser-safe image generation caps shared with validation. |
diff --git a/server/lib/musicVideoConditioning.js b/server/lib/musicVideoConditioning.js
index 580c5e074f..9ba970b7d1 100644
--- a/server/lib/musicVideoConditioning.js
+++ b/server/lib/musicVideoConditioning.js
@@ -1,3 +1,4 @@
+import { pickGuideMedia } from './catalogMediaLibrary.js';
import { isEditCapableMode, maxInputImages } from './imageGenCapabilities.js';
import { RUNNER_FAMILIES } from './runners.js';
import { escapeRegExp } from './textUtils.js';
@@ -41,14 +42,63 @@ function featuredAuthoredCharacters(references, scene) {
export const musicVideoReferenceChoices = (project) => (project?.visualSpec?.references || [])
.filter((ref) => ref?.id && ref.imageId && !isOutsideMusicVideoReference(ref));
-export function musicVideoConditioningReferences(project, scene) {
- const references = project?.visualSpec?.references || [];
+/** The cast member and variant a scene asks its frames to show, or null when it names none. */
+export function sceneCastVariant(scene) {
+ const variant = scene?.characterVariant;
+ return variant && typeof variant.ingredientId === 'string' && variant.ingredientId ? variant : null;
+}
+
+/**
+ * The Casting guide images (catalogMediaLibrary.pickGuideMedia) for the cast
+ * member a scene's `characterVariant` names, as visual-spec-shaped references.
+ * `castMedia` maps an ingredient id to its live catalog media rows; a missing
+ * entry (not loaded, or the load failed) yields none, so the scene falls back
+ * to the project's references.
+ */
+export function musicVideoCastGuideReferences(project, scene, castMedia) {
+ const variant = sceneCastVariant(scene);
+ const media = variant && castMedia?.[variant.ingredientId];
+ if (!Array.isArray(media)) return [];
+ const name = (project?.concept?.subjects || []).find((s) => s?.ingredientId === variant.ingredientId)?.name || 'Cast guide';
+ return pickGuideMedia(media, { age: variant.age, era: variant.era, wardrobeId: variant.wardrobeId }, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES)
+ .filter((m) => m.mediaKey)
+ .map((m) => {
+ const v = m.library?.variant || {};
+ const detail = v.label || (Number.isInteger(v.age) ? `age ${v.age}` : v.era || '');
+ return {
+ id: `mvr-guide-${m.mediaKey}`.slice(0, 128),
+ imageId: m.mediaKey,
+ role: 'character',
+ label: `${name}${detail ? ` · ${detail}` : ''}`.slice(0, 120),
+ castGuide: true,
+ };
+ });
+}
+
+/**
+ * The references a scene's frames condition on, capped at
+ * MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES. Explicit `frameReferenceIds` win;
+ * otherwise the cast guides of the scene's `characterVariant` lead and the
+ * automatic set fills the remaining slots. `castMedia` is optional: without it
+ * (or without a variant) the result is the automatic set alone.
+ */
+export function musicVideoConditioningReferences(project, scene, castMedia = null) {
+ const guides = musicVideoCastGuideReferences(project, scene, castMedia);
// The director's own pick for this shot (the shot card's References row) wins over the automatic set.
if (Array.isArray(scene?.frameReferenceIds)) {
- const choices = musicVideoReferenceChoices(project);
+ const choices = [...guides, ...musicVideoReferenceChoices(project)];
return scene.frameReferenceIds.map((id) => choices.find((ref) => ref.id === id)).filter(Boolean)
.slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES);
}
+ const automatic = automaticConditioningReferences(project, scene);
+ if (!guides.length) return automatic;
+ const chosen = [...guides, ...automatic];
+ return chosen.filter((ref, i) => chosen.findIndex((r) => r.imageId === ref.imageId) === i)
+ .slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES);
+}
+
+function automaticConditioningReferences(project, scene) {
+ const references = project?.visualSpec?.references || [];
const stage = project?.castAndSets;
if (stage?.status === 'approved' && Number.isInteger(scene?.sectionIndex)) {
const setId = stage.direction?.songMap?.find((entry) => entry.section === scene.sectionIndex)?.setId;
diff --git a/server/lib/musicVideoConditioning.test.js b/server/lib/musicVideoConditioning.test.js
new file mode 100644
index 0000000000..0a29e4c15e
--- /dev/null
+++ b/server/lib/musicVideoConditioning.test.js
@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { musicVideoConditioningReferences, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES } from './musicVideoConditioning.js';
+
+const CAST_ID = 'cat-chr-example';
+const guide = (mediaKey, age, extra = {}) => ({ mediaKey, kind: 'reference', createdAt: '2026-01-01T00:00:00.000Z', library: { variant: { age }, guide: true }, ...extra });
+
+const project = (references) => ({
+ concept: { subjects: [{ id: 'mvc-1', kind: 'character', name: 'Example Lead', ingredientId: CAST_ID }] },
+ visualSpec: { references },
+});
+const authored = [
+ { id: 'lead', imageId: 'lead.png', role: 'character', condition: true },
+ { id: 'set', imageId: 'set.png', role: 'set', condition: true },
+ { id: 'off', imageId: 'off.png', role: 'prop', condition: false },
+];
+const castMedia = { [CAST_ID]: [guide('adult.png', 27), guide('child.png', 7), guide('teen.png', 17)] };
+const ids = (refs) => refs.map((ref) => ref.imageId);
+
+describe('musicVideoConditioningReferences with Casting guides', () => {
+ it('leads with the guide closest to the scene age, then fills from the project references', () => {
+ const scene = { characterVariant: { ingredientId: CAST_ID, age: 7 } };
+ const refs = musicVideoConditioningReferences(project(authored), scene, castMedia);
+ expect(ids(refs)).toEqual(['child.png', 'teen.png', 'adult.png', 'lead.png']);
+ expect(refs[0]).toMatchObject({ role: 'character', castGuide: true, label: 'Example Lead · age 7' });
+ expect(ids(musicVideoConditioningReferences(project(authored), { characterVariant: { ingredientId: CAST_ID, age: 27 } }, castMedia))[0])
+ .toBe('adult.png');
+ });
+
+ it('keeps the cap and drops a project reference that repeats a guide image', () => {
+ const many = { [CAST_ID]: [guide('a.png', 7), guide('lead.png', 8)] };
+ const refs = musicVideoConditioningReferences(project(authored), { characterVariant: { ingredientId: CAST_ID, age: 7 } }, many);
+ expect(ids(refs)).toEqual(['a.png', 'lead.png', 'set.png']);
+ const five = { [CAST_ID]: [1, 2, 3, 4, 5].map((n) => guide(`g${n}.png`, 7, { library: { variant: { age: 7 } } }))};
+ expect(musicVideoConditioningReferences(project(authored), { characterVariant: { ingredientId: CAST_ID } }, five))
+ .toHaveLength(MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES);
+ });
+
+ it('is unchanged without a variant or before the cast media loads', () => {
+ const today = ids(musicVideoConditioningReferences(project(authored), {}));
+ expect(today).toEqual(['lead.png', 'set.png']);
+ expect(ids(musicVideoConditioningReferences(project(authored), {}, castMedia))).toEqual(today);
+ expect(ids(musicVideoConditioningReferences(project(authored), { characterVariant: { ingredientId: CAST_ID, age: 7 } }, null))).toEqual(today);
+ });
+
+ it('lets explicit frame references win, resolving a kept guide id', () => {
+ const scene = { characterVariant: { ingredientId: CAST_ID, age: 7 }, frameReferenceIds: ['set', 'mvr-guide-child.png'] };
+ expect(ids(musicVideoConditioningReferences(project(authored), scene, castMedia))).toEqual(['set.png', 'child.png']);
+ expect(ids(musicVideoConditioningReferences(project(authored), scene))).toEqual(['set.png']);
+ });
+});
diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.js
index ad958e3874..7f01d61f96 100644
--- a/server/lib/musicVideoValidation.js
+++ b/server/lib/musicVideoValidation.js
@@ -57,6 +57,7 @@ import { MUSIC_VIDEO_SHOT_GLITCH_LIMIT, MUSIC_VIDEO_TRANSITIONS } from './musicV
import { BEAT_TOGGLE_OVERLAP, BEAT_TOGGLE_RATES, MUSIC_VIDEO_CUT_EFFECTS } from './musicVideoCutEffects.js';
import { IMAGE_EFFECT_SEC_RANGE, MUSIC_VIDEO_IMAGE_EFFECTS } from './musicVideoImageEffects.js';
import { CAMERA_FRAMINGS, CAMERA_MOVEMENT_VALUES, CAMERA_SPEEDS } from './cameraMovements.js';
+import { CAST_ERAS } from './catalogMediaLibrary.js';
import { MUSIC_VIDEO_PERFORMANCE_STYLES, MUSIC_VIDEO_SHOT_MODES, SOURCE_AUDIO_LIPSYNC } from './musicVideoShotTiming.js';
import {
MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD,
@@ -636,11 +637,21 @@ export const musicVideoSceneCameraSchema = z.object({
reason: z.string().trim().max(300).optional(),
}).strict();
+// #12763: the Casting cast member a shot features and the variant (age, era, look) its
+// frames should show. Conditioning leads with that member's render guides; null clears it.
+export const musicVideoSceneCharacterVariantSchema = z.object({
+ ingredientId: z.string().min(1).max(128),
+ age: z.number().int().min(0).max(150).optional(),
+ era: z.enum(CAST_ERAS).optional(),
+ wardrobeId: z.string().trim().min(1).max(59).optional(),
+}).strict();
+
// Per-scene visual layer (#8985) — footage, a moved still, or a title card;
// see musicVideoLayers.js. Only a composed render honors a non-footage layer.
const sceneLayerFields = {
// The references (visual spec ids) sent with this shot's frame renders; absent or null = the automatic set.
frameReferenceIds: z.array(z.string().min(1).max(128)).max(MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES).nullable().optional(),
+ characterVariant: musicVideoSceneCharacterVariantSchema.nullable().optional(),
camera: musicVideoSceneCameraSchema.nullable().optional(),
visualLayer: z.enum(MUSIC_VIDEO_VISUAL_LAYERS).optional(),
stillMove: z.enum(MUSIC_VIDEO_STILL_MOVES).optional(),
diff --git a/server/routes/musicVideoTakes.test.js b/server/routes/musicVideoTakes.test.js
index 80f7dac66e..901543549c 100644
--- a/server/routes/musicVideoTakes.test.js
+++ b/server/routes/musicVideoTakes.test.js
@@ -545,6 +545,31 @@ describe('a shot\'s frame references', () => {
await request(app).patch(`${base()}/scenes/${sceneA.sceneId}`).send({ frameReferenceIds: null });
expect(musicVideoConditioningReferences(await reload(), await sceneOf()).map((ref) => ref.id)).toEqual(['lead']);
});
+
+ // Uniquely catches a shot's Casting variant failing to save, or the server-side load not feeding conditioning.
+ it('saves a shot\'s cast variant and conditions its frames on the matching Casting guides first', async () => {
+ const { musicVideoConditioningReferences } = await import('../lib/musicVideoConditioning.js');
+ const { loadSceneCastMedia } = await import('../services/musicVideo/castGuideMedia.js');
+ await projects.mutateProjectRecord(project.id, (current) => ({ project: { ...current, visualSpec: { ...(current.visualSpec || {}), references: [
+ { id: 'lead', imageId: 'lead.png', role: 'character', label: 'Lead', condition: true },
+ ] } } }));
+ const sceneOf = async () => (await reload()).scenes.find((scene) => scene.sceneId === sceneA.sceneId);
+ expect((await request(app).patch(`${base()}/scenes/${sceneA.sceneId}`).send({ characterVariant: { ingredientId: 'cat-chr-x', era: 'nope' } })).status).toBe(400);
+ const saved = await request(app).patch(`${base()}/scenes/${sceneA.sceneId}`).send({ characterVariant: { ingredientId: 'cat-chr-x', age: 7 } });
+ expect(saved.status).toBe(200);
+ const scene = await sceneOf();
+ expect(scene.characterVariant).toEqual({ ingredientId: 'cat-chr-x', age: 7 });
+ const listMedia = async (id) => (id === 'cat-chr-x' ? [
+ { mediaKey: 'adult.png', kind: 'reference', library: { variant: { age: 30 }, guide: true } },
+ { mediaKey: 'child.png', kind: 'reference', library: { variant: { age: 7 }, guide: true } },
+ ] : []);
+ const castMedia = await loadSceneCastMedia(scene, { listMedia });
+ expect(musicVideoConditioningReferences(await reload(), scene, castMedia).map((ref) => ref.imageId)).toEqual(['child.png', 'adult.png', 'lead.png']);
+ // A failed catalog read conditions on the project's references, as before.
+ expect(await loadSceneCastMedia(scene, { listMedia: async () => { throw new Error('db down'); } })).toBeNull();
+ await request(app).patch(`${base()}/scenes/${sceneA.sceneId}`).send({ characterVariant: null });
+ expect(await loadSceneCastMedia(await sceneOf(), { listMedia })).toBeNull();
+ });
});
diff --git a/server/services/musicVideo/autoReviewDispatch.js b/server/services/musicVideo/autoReviewDispatch.js
index c69eb81eeb..2f9aa7be6e 100644
--- a/server/services/musicVideo/autoReviewDispatch.js
+++ b/server/services/musicVideo/autoReviewDispatch.js
@@ -26,6 +26,7 @@ import { getProject } from './projects.js';
import { releaseRevisionSection } from './revisionService.js';
import { dispatchProductionStep } from './productionDispatch.js';
import { loadPoolEnv, routeUnavailableReason, sceneRequirement } from './productionPool.js';
+import { loadSceneCastMedia } from './castGuideMedia.js';
const unavailable = (reason) => ({ reason });
@@ -70,7 +71,7 @@ async function planSection(project, section, env) {
const stepKind = section.kind === 'image' ? 'frame' : 'clip';
const planned = stepKind === 'frame' ? await frameRoute(project, env) : await clipRoute(project, env);
if (planned.reason) return planned;
- const refused = await routeUnavailableReason(planned.route, sceneRequirement(project, scene, stepKind), env);
+ const refused = await routeUnavailableReason(planned.route, sceneRequirement(project, scene, stepKind, stepKind === 'frame' ? await loadSceneCastMedia(scene) : null), env);
return refused ? unavailable(refused) : { scene, stepKind, route: planned.route };
}
diff --git a/server/services/musicVideo/castGuideMedia.js b/server/services/musicVideo/castGuideMedia.js
new file mode 100644
index 0000000000..178102dcd3
--- /dev/null
+++ b/server/services/musicVideo/castGuideMedia.js
@@ -0,0 +1,21 @@
+// Loads the Casting media a scene's `characterVariant` names, in the
+// `{ [ingredientId]: media[] }` shape musicVideoConditioningReferences takes.
+// The catalog lives in Postgres and is imported only for a scene that asks for
+// a cast member, so a project without variants never touches it.
+
+import { sceneCastVariant } from '../../lib/musicVideoConditioning.js';
+
+/**
+ * Null when the scene names no cast member, or when the catalog read fails: a
+ * failed read conditions on the project's own references, as before #12763.
+ */
+export async function loadSceneCastMedia(scene, { listMedia = null } = {}) {
+ const variant = sceneCastVariant(scene);
+ if (!variant) return null;
+ const list = listMedia || (await import('../catalogDB.js')).listMediaForIngredient;
+ const media = await Promise.resolve().then(() => list(variant.ingredientId)).catch((err) => {
+ console.warn(`⚠️ Cast guides for ${variant.ingredientId} unavailable, conditioning on project references: ${err.message}`);
+ return null;
+ });
+ return Array.isArray(media) ? { [variant.ingredientId]: media } : null;
+}
diff --git a/server/services/musicVideo/productionDispatch.js b/server/services/musicVideo/productionDispatch.js
index f038d64ffe..32375d483f 100644
--- a/server/services/musicVideo/productionDispatch.js
+++ b/server/services/musicVideo/productionDispatch.js
@@ -33,6 +33,7 @@ import { falSceneTake, falTakeRequestFields, grokCoverage, runwaySceneTake, runw
import { authoredShotPrompt, musicVideoFrameModelInput } from '../../lib/musicVideoShotPrompt.js';
import { sceneEndFrameRequestFields } from '../../lib/musicVideoEndFrame.js';
import { conditioningReferences, falRouteVideoSettings, runwayRouteVideoSettings } from './productionPool.js';
+import { loadSceneCastMedia } from './castGuideMedia.js';
import { musicVideoFrameGenSize } from '../../lib/musicVideoAspect.js';
const unprompted = (scene, what) => new ServerError(
@@ -54,7 +55,7 @@ async function dispatchFrame({ project, scene, route, tag, settings }) {
const fixes = typeof scene.stillFixes?.text === 'string' ? scene.stillFixes.text : '';
const { prompt, promptAdditions } = musicVideoFrameModelInput(project, scene, { repairs: unmet, fixes });
if (!prompt) throw unprompted(scene, 'frame');
- const referenceImagePaths = conditioningReferences(project, scene)
+ const referenceImagePaths = conditioningReferences(project, scene, await loadSceneCastMedia(scene))
.map((ref) => resolveGalleryImage(ref.imageId, { mustExist: false })).filter(Boolean);
const [{ resolveRenderTargetConfig }, { resolveImageCleaners }, { enqueueJob }] = await Promise.all([
import('../imageGen/cloudProviderConfig.js'),
diff --git a/server/services/musicVideo/productionPool.js b/server/services/musicVideo/productionPool.js
index e80e3b8a2a..db1c3dc4e0 100644
--- a/server/services/musicVideo/productionPool.js
+++ b/server/services/musicVideo/productionPool.js
@@ -130,10 +130,10 @@ export const poolPricing = (pool, project = null) => Object.fromEntries(pool.map
/** Shared scene-aware frame conditioning, with the legacy capped fallback. */
export const conditioningReferences = musicVideoConditioningReferences;
-/** What a scene's `kind` generation needs from a route. */
-export function sceneRequirement(project, scene, stepKind) {
+/** What a scene's `kind` generation needs from a route. `castMedia` is loadSceneCastMedia's result for the scene. */
+export function sceneRequirement(project, scene, stepKind, castMedia = null) {
return stepKind === 'frame'
- ? { kind: 'image', conditioning: conditioningReferences(project, scene).length }
+ ? { kind: 'image', conditioning: conditioningReferences(project, scene, castMedia).length }
: { kind: 'video', performance: isPerformanceScene(scene) };
}
diff --git a/server/services/musicVideo/productionService.js b/server/services/musicVideo/productionService.js
index cb8c439ac1..ee95354364 100644
--- a/server/services/musicVideo/productionService.js
+++ b/server/services/musicVideo/productionService.js
@@ -79,6 +79,7 @@ import {
stepPriceUsd,
sceneRequirement,
} from './productionPool.js';
+import { loadSceneCastMedia } from './castGuideMedia.js';
// One id per server process: a run records the process that may dispatch for it.
const PROCESS_ID = `proc-${randomUUID()}`;
@@ -291,7 +292,7 @@ async function dispatchSlot(projectId, runId, { stepKind, sceneId, revisionId =
run = findProductionRun(project, runId);
scene = project.scenes.find((entry) => entry.sceneId === sceneId);
}
- const requirement = sceneRequirement(project, scene, stepKind);
+ const requirement = sceneRequirement(project, scene, stepKind, stepKind === 'frame' ? await loadSceneCastMedia(scene) : null);
const env = await deps.loadEnv();
const choice = await deps.chooseRoute(run, requirement, env);
if (!choice?.route) {
diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.js
index 1cc569b4c1..722bd03c29 100644
--- a/server/services/musicVideo/projectsLogic.js
+++ b/server/services/musicVideo/projectsLogic.js
@@ -519,6 +519,7 @@ function buildScene(input, { order }) {
lyricText: input.lyricText ?? null,
visualIntent: input.visualIntent ?? null,
...(input.frameReferenceIds ? { frameReferenceIds: input.frameReferenceIds } : {}),
+ ...(input.characterVariant ? { characterVariant: input.characterVariant } : {}),
// #8985: what a composed render shows for this span (render.js#sceneLayer).
visualLayer: input.visualLayer ?? 'footage',
stillMove: input.stillMove ?? 'hold',
@@ -648,7 +649,7 @@ export function replaceScenes(project, sceneInputs) {
// adding a shot or lyric the storyboard approval did not cover.
const SCENE_SHOT_EDIT_FIELDS = ['startSec', 'endSec', 'beatAligned', 'label', 'prompt', 'framePrompt', 'visualIntent',
'referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit', 'speedFps', 'offsetFrames', 'reverse', 'holdLastFrame', 'filmLook', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect',
- 'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds'];
+ 'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds', 'characterVariant'];
/**
* Apply a patch to a single scene. Returns `{ project, updated }`. Throws if the
diff --git a/server/services/musicVideo/projectsLogic.test.js b/server/services/musicVideo/projectsLogic.test.js
index 9feb630507..d46279bcd1 100644
--- a/server/services/musicVideo/projectsLogic.test.js
+++ b/server/services/musicVideo/projectsLogic.test.js
@@ -1080,6 +1080,7 @@ describe('create-schema parity', () => {
lyricText: 'line one',
visualIntent: 'calm',
frameReferenceIds: ['ref-a', 'ref-b'],
+ characterVariant: { ingredientId: 'cat-chr-x', age: 7 },
camera: { move: 'slow-dolly-in' },
visualLayer: 'still',
stillMove: 'push',