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

Music video: a fitted shot's storyboard panel art guides its frame (#13261)

[._.]/8961d0efcc91
diff --git a/client/src/components/musicVideo/SceneCard.jsx b/client/src/components/musicVideo/SceneCard.jsx
index 669a30a7fa..68dc65407c 100644
--- a/client/src/components/musicVideo/SceneCard.jsx
+++ b/client/src/components/musicVideo/SceneCard.jsx
@@ -569,7 +569,7 @@ export default function SceneCard({
{/* This shot's piece of the composed final render: cached or not, Render shot, its film look. */}
{project?.composition?.mode === 'composed' && <ShotFinalRender project={project} scene={scene} onChange={applyPatch} fieldId={fieldId} />}
<ShotStoryboardPanel projectId={project?.id} storyboardId={storyboardId} scene={scene} linked={storyboardShot}
- onSceneUpdated={onEditLocal} onUnlink={() => applyPatch({ panelId: null, panelRev: null })} onBoard={onStoryboardBoard} />
+ onSceneUpdated={onEditLocal} onUnlink={() => applyPatch({ panelId: null, panelRev: null, panelArt: null })} onBoard={onStoryboardBoard} />
{(scene.visualIntent || scene.direction || scene.direction?.actionContract) && (
<details className="group/direction rounded border border-port-border">
<summary className="flex min-h-[44px] cursor-pointer items-center gap-2 px-2 text-xs marker:content-none sm:min-h-[32px] [&::-webkit-details-marker]:hidden">
diff --git a/client/src/components/musicVideo/SceneFrameReferences.jsx b/client/src/components/musicVideo/SceneFrameReferences.jsx
index 8ee866ba35..00599c8d37 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 { musicVideoCastGuideReferences, musicVideoConditioningReferences, musicVideoReferenceChoices, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES } from '../../../../server/lib/musicVideoConditioning.js';
+import { musicVideoCastGuideReferences, musicVideoConditioningReferences, musicVideoPanelArtReferences, 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.
@@ -24,7 +24,7 @@ export default function SceneFrameReferences({ project, scene, castMedia = null,
const pressTimer = useRef(null);
const longPressed = useRef(false);
useEffect(() => () => clearTimeout(pressTimer.current), []);
- const choices = [...musicVideoCastGuideReferences(project, scene, castMedia), ...musicVideoReferenceChoices(project)];
+ const choices = [...musicVideoCastGuideReferences(project, scene, castMedia), ...musicVideoPanelArtReferences(scene), ...musicVideoReferenceChoices(project)];
if (!choices.length) return null;
const chosen = musicVideoConditioningReferences(project, scene, castMedia);
const ids = chosen.map((ref) => ref.id);
diff --git a/client/src/components/musicVideo/ShotStoryboardPanel.jsx b/client/src/components/musicVideo/ShotStoryboardPanel.jsx
index c8384d7279..5b1a21ec9e 100644
--- a/client/src/components/musicVideo/ShotStoryboardPanel.jsx
+++ b/client/src/components/musicVideo/ShotStoryboardPanel.jsx
@@ -9,8 +9,8 @@ const imageName = (ref) => (typeof ref === 'string' ? ref.split(/[?#]/)[0].split
/**
* A fitted shot's storyboard panel: which panel it came from, a notice when the
- * panel was edited since (Update copies its action to the shot's intent; a locked
- * shot changes only then) or deleted (Unlink), and Use as panel art, which sends
+ * panel was edited since (Update copies its action to the shot's intent and its
+ * art to the shot's frame reference; a locked shot changes only then) or deleted (Unlink), and Use as panel art, which sends
* the shot's still back to the panel as its selected take.
*/
export default function ShotStoryboardPanel({ projectId, storyboardId, scene, linked, onSceneUpdated, onUnlink, onBoard }) {
@@ -28,10 +28,11 @@ export default function ShotStoryboardPanel({ projectId, storyboardId, scene, li
};
const update = async () => {
const res = await run('update', () => updateShotFromStoryboardPanel(projectId, scene.sceneId, { silent: true }));
- if (res?.scene) onSceneUpdated(scene.sceneId, { visualIntent: res.scene.visualIntent, panelRev: res.scene.panelRev });
+ if (res?.scene) onSceneUpdated(scene.sceneId, { visualIntent: res.scene.visualIntent, panelRev: res.scene.panelRev, panelArt: res.scene.panelArt ?? null });
};
const sendArt = async () => {
const res = await run('art', () => sendShotStillToStoryboardPanel(projectId, scene.sceneId, { silent: true }));
+ if (res?.scene) onSceneUpdated(scene.sceneId, { panelArt: res.scene.panelArt ?? null });
if (res?.board) onBoard(res.board);
};
const still = imageName(scene.referenceImageId);
@@ -62,7 +63,9 @@ export default function ShotStoryboardPanel({ projectId, storyboardId, scene, li
</div>
{state === 'changed' && (
<div className="flex flex-wrap items-center gap-2 rounded border border-port-warning/40 bg-port-warning/10 p-1.5">
- <p className="min-w-0 flex-1 break-words text-port-warning">Storyboard changed: {panel.action || 'the panel has no action now'}</p>
+ <p className="min-w-0 flex-1 break-words text-port-warning">
+ Storyboard changed: {panel.action || 'the panel has no action now'}{linked.artChanged ? ' (new panel art)' : ''}
+ </p>
<button type="button" onClick={update} disabled={!!busy} className={actionButton}>
{busy === 'update' ? <Loader2 size={14} className="animate-spin" aria-hidden="true" /> : <RefreshCw size={14} aria-hidden="true" />} Update
</button>
diff --git a/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx b/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx
index c81a1b56e4..6641c80ac9 100644
--- a/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx
+++ b/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx
@@ -31,7 +31,7 @@ describe('ShotStoryboardPanel', () => {
expect(screen.getByRole('link', { name: /Arrival · panel 1/ }).getAttribute('href')).toBe('/storyboards/sb-1/panel/panel-1');
expect(screen.getByText(`Storyboard changed: ${panel.action}`)).toBeTruthy();
fireEvent.click(screen.getByRole('button', { name: /Update/ }));
- await waitFor(() => expect(onSceneUpdated).toHaveBeenCalledWith('mvs-1', { visualIntent: panel.action, panelRev: 'new' }));
+ await waitFor(() => expect(onSceneUpdated).toHaveBeenCalledWith('mvs-1', { visualIntent: panel.action, panelRev: 'new', panelArt: null }));
fireEvent.click(screen.getByRole('button', { name: /Use as panel art/ }));
await waitFor(() => expect(onBoard).toHaveBeenCalledWith(board));
diff --git a/docs/API.md b/docs/API.md
index 44ccfa08b7..d0f99844b0 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -808,7 +808,7 @@ Every mounted API prefix (see `server/index.js` for the authoritative list). Dom
| `/api/music-video` | Music video projects; [one-prompt autonomous runs](./features/music-video-autonomous.md) at `/api/music-video/autonomous` |
| `/api/music-video/character-styles` | Built-in character styles a project loads via `concept.characterStyleId`: list with each style's sheet prompt and this install's sheet (`GET /`), full style (`GET /:id`), set or clear the install's character sheet (`PUT /:id/reference` `{ imageId }`) |
| `/api/mood-boards` | Mood boards; `POST /:id/generate` writes 1–4 prompts with the chosen LLM and queues new image items using saved imagegen settings (1024×576 default). Body: `requestId` (UUID), `providerId`, optional `model`, `effort`, `direction`, `count`, `render` (`mode`, `model`, `width`, `height`), `retry`. `GET /:id/generate` restores transient status; `mood-board:generate` pushes progress. Retry reuses the original batch and only queues unfinished slots. Prompt writing uses stored text, not pixels; saved prompts and references survive navigation and server restart, while transient batch status and recent request receipts reset on restart. |
-| `/api/storyboards` | Storyboards (Create › Storyboards): `GET`/`POST /`, `GET`/`PATCH`/`DELETE /:id`; beats at `/:id/beats` (`POST`, `PATCH`/`DELETE /:beatId`, `POST /:beatId/move`); panels at `/:id/beats/:beatId/panels` (`POST`) and `/:id/panels/:panelId` (`PATCH`, `DELETE`, `POST /move` with `{ beatId?, index }`); panel art takes at `/:id/panels/:panelId/takes` (`POST` `{ source, image \| sketchKey }`, `POST /:takeId/select`, `DELETE /:takeId`); the panel maker at `PUT /:id/recipe` (`{ recipe \| null }`, null = default), `GET /:id/panels/:panelId/make` (linked catalog reference images), `PATCH /:id/panels/:panelId/make/:nodeId` (`{ text?, excludedRefs?, extraRefs? }`) and `POST /:id/panels/:panelId/make/:nodeId/run` (an LLM node answers when done; an image node once its frames are queued, with `storyboard:make` socket events after). Beats from a plot summary: `POST /:id/beats/extract` (`{ plot, providerId?, model?, effort? }` → `{ board, beats, sentPrompt, promptAdditions }`: the plot and pick are saved, the beats are a preview) and `POST /:id/beats/add` (`{ beats }`, appended). Make empty panels: `GET /:id/make-empty` (`{ batch, panelCount, steps }`: the panels with no art and each node it runs with its model) and `POST /:id/make-empty` (202, one batch per board, `storyboard:make-batch` progress). The saved recipe library: `GET`/`POST /recipes` (`{ name, recipe }`) and `DELETE /recipes/:recipeId`. The animatic's temp track is `PATCH /:id` `{ tempTrack: { filename, name?, sections?, lines? } \| null }`, naming an audio file already in `/api/uploads`, with its song marks (`sections` `{ id?, label, at }`, lyric `lines` `{ id?, text, at \| null }`); a beat starts at one with `PATCH …/beats/:beatId` `{ pin }`. Make storyboard from a music video: `POST /from-music-video/:projectId` (201 `{ board, project }`: one beat per song section, one panel per shot, and the project's `storyboardId` set; 409 while it links a live board). Fit to song: `POST /fit-music-video/:projectId` (`{ boardUpdatedAt, starts? }`, `starts` = beat id → picked start seconds → `{ project, shots, replaced }`: the linked board's panels written as the video's shots, each with `panelId`/`panelRev`; 409 when the board changed since `boardUpdatedAt`, the song is not analyzed, or a shot is locked). A fitted shot and its panel: `POST /music-video/:projectId/shots/:sceneId/update-from-panel` (`{ scene }`: the edited panel's action becomes the shot's intent and its `panelRev` is refreshed) and `POST /music-video/:projectId/shots/:sceneId/panel-art` (`{ board }`: the shot's still becomes the panel's selected take); both 409 `PANEL_MISSING` when the panel is gone. Every write returns the whole board; over-limit text is refused. Beat extraction, a node run and `POST /:id/make-empty` are host control (they run a caller-chosen provider or queue renders); the rest store records. |
+| `/api/storyboards` | Storyboards (Create › Storyboards): `GET`/`POST /`, `GET`/`PATCH`/`DELETE /:id`; beats at `/:id/beats` (`POST`, `PATCH`/`DELETE /:beatId`, `POST /:beatId/move`); panels at `/:id/beats/:beatId/panels` (`POST`) and `/:id/panels/:panelId` (`PATCH`, `DELETE`, `POST /move` with `{ beatId?, index }`); panel art takes at `/:id/panels/:panelId/takes` (`POST` `{ source, image \| sketchKey }`, `POST /:takeId/select`, `DELETE /:takeId`); the panel maker at `PUT /:id/recipe` (`{ recipe \| null }`, null = default), `GET /:id/panels/:panelId/make` (linked catalog reference images), `PATCH /:id/panels/:panelId/make/:nodeId` (`{ text?, excludedRefs?, extraRefs? }`) and `POST /:id/panels/:panelId/make/:nodeId/run` (an LLM node answers when done; an image node once its frames are queued, with `storyboard:make` socket events after). Beats from a plot summary: `POST /:id/beats/extract` (`{ plot, providerId?, model?, effort? }` → `{ board, beats, sentPrompt, promptAdditions }`: the plot and pick are saved, the beats are a preview) and `POST /:id/beats/add` (`{ beats }`, appended). Make empty panels: `GET /:id/make-empty` (`{ batch, panelCount, steps }`: the panels with no art and each node it runs with its model) and `POST /:id/make-empty` (202, one batch per board, `storyboard:make-batch` progress). The saved recipe library: `GET`/`POST /recipes` (`{ name, recipe }`) and `DELETE /recipes/:recipeId`. The animatic's temp track is `PATCH /:id` `{ tempTrack: { filename, name?, sections?, lines? } \| null }`, naming an audio file already in `/api/uploads`, with its song marks (`sections` `{ id?, label, at }`, lyric `lines` `{ id?, text, at \| null }`); a beat starts at one with `PATCH …/beats/:beatId` `{ pin }`. Make storyboard from a music video: `POST /from-music-video/:projectId` (201 `{ board, project }`: one beat per song section, one panel per shot, and the project's `storyboardId` set; 409 while it links a live board). Fit to song: `POST /fit-music-video/:projectId` (`{ boardUpdatedAt, starts? }`, `starts` = beat id → picked start seconds → `{ project, shots, replaced }`: the linked board's panels written as the video's shots, each with `panelId`/`panelRev` and the panel's art as `panelArt`, a frame reference that keeps one slot; 409 when the board changed since `boardUpdatedAt`, the song is not analyzed, or a shot is locked). A fitted shot and its panel: `POST /music-video/:projectId/shots/:sceneId/update-from-panel` (`{ scene }`: the edited panel's action becomes the shot's intent, its art the shot's `panelArt` frame reference, and its `panelRev` is refreshed) and `POST /music-video/:projectId/shots/:sceneId/panel-art` (`{ board, scene }`: the shot's still becomes the panel's selected take and the shot's `panelArt`); both 409 `PANEL_MISSING` when the panel is gone. Every write returns the whole board; over-limit text is refused. Beat extraction, a node run and `POST /:id/make-empty` are host control (they run a caller-chosen provider or queue renders); the rest store records. |
| `/api/decks` | Decks (playing-card / tarot designer) |
| `/api/writers-room` | Writers Room |
| `/api/universe-builder` | Universe Builder |
diff --git a/server/lib/README.md b/server/lib/README.md
index fc35265e2e..8fa76b0d37 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -197,7 +197,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `castIntegrityPrompt.js` | The prompt-facing render of a `characterIntegrity.js` report (#6415): `renderCastIntegrity` (gap rows first, header always kept, so a budget-truncated block can never read as a clean cast) and `INTEGRITY_DEPTH_NOTES` (the `explained` / `light` / `full` rulings in the reviewer's own words). Shared by the Series foundation judge and the FableLoom whole-series editor so the two cannot drift on what a `light` character owes. |
| `bibleLimits.js` | `BIBLE_LIMITS` — the canon field length/count caps every story-bible sanitizer, Zod schema, and catalog payload upgrade measures against. A pure leaf split out of `storyBible.js` (which pulls `crypto` + `fileUtils`) so `catalogTypes.js` and the browser bundle can read the numbers alone. |
| `storyboardBeatExtract.js` | Beats from a plot summary: `beatExtractInstructions` (the visible block sent ahead of the plot), `beatExtractPrompt`, `parseExtractedBeats` (a model's JSON answer reduced to beats and panels a board holds), `BEAT_EXTRACT_LIMITS`. Browser-safe. |
-| `storyboardFit.js` | Fit to song: `fitStoryboardToSong` places a storyboard's beats on a music video's analyzed song (snapped to sections, sung lines or downbeats; picked starts win) and returns one shot per panel with its `panelId`/`panelRev`; `storyboardFitSong` reads the song from a project; `storyboardPanelRev` fingerprints a panel and `storyboardShotPanel` reads a fitted shot's panel as current, changed or missing; `STORYBOARD_FIT_MIN_SHOT_SEC`. Shared by the Plan step preview and the write. Browser-safe. |
+| `storyboardFit.js` | Fit to song: `fitStoryboardToSong` places a storyboard's beats on a music video's analyzed song (snapped to sections, sung lines or downbeats; picked starts win) and returns one shot per panel with its `panelId`/`panelRev`; `storyboardFitSong` reads the song from a project; `storyboardPanelRev` fingerprints a panel, `storyboardPanelArt` gives its selected art as a gallery image (the shot's frame reference), and `storyboardShotPanel` reads a fitted shot's panel as current, changed or missing; `STORYBOARD_FIT_MIN_SHOT_SEC`. Shared by the Plan step preview and the write. Browser-safe. |
| `storyboardSongBrief.js` | A storyboard's beats as a song map: `storyboardSongSections` (role, target length, energy, mood, lyric theme per beat), `storyboardSongBriefText` (the paste-ready brief), `storyboardTimeline` (the animatic's timing: panel holds, beats pinned to temp-track marks, the runs before them fitted) / `STORYBOARD_DEFAULT_HOLD_SEC`. No model call. Browser-safe. |
| `storyboardRecipe.js` | Storyboard panel maker recipes: node types and ports (`RECIPE_NODE_PORTS`: text, system, llm, references, image, panel), `defaultPanelRecipe` (Text → Prompt writer + System prompt → Image + References → Panel), `sanitizeRecipe` (edges join matching ports, no cycles), `recipeRunOrder`, `nodeInputValue` / `nodeOutputValue` (what flows into a node for one panel), `sanitizePanelMake` (per-panel run state), `STORYBOARD_RENDER_SIZES`. Browser-safe. |
| `storyboardRecord.js` | Shared Storyboard record (Create › Storyboards): `sanitizeStoryboard` (beats → panels → art takes, catalog refs by id), `sanitizeTake`, `summarizeStoryboard` (with runtime), `sanitizeSavedRecipe` (a saved recipe library entry). |
@@ -911,7 +911,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, 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. |
+| `musicVideoConditioning.js` | `musicVideoStyleImages`, `musicVideoStylePrompt`, `musicVideoStyleBasis`, and `musicVideoStyleReferenceCapacity` supply bounded moodboard conditioning and text fallback; `musicVideoPanelArtReferences(scene)` turns a fitted shot's storyboard panel art into a reference that keeps one slot; `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 e09b327420..52d83d2551 100644
--- a/server/lib/musicVideoConditioning.js
+++ b/server/lib/musicVideoConditioning.js
@@ -96,17 +96,29 @@ export function musicVideoCastGuideReferences(project, scene, castMedia) {
*/
export function musicVideoConditioningReferences(project, scene, castMedia = null) {
const guides = musicVideoCastGuideReferences(project, scene, castMedia);
+ const panel = musicVideoPanelArtReferences(scene);
// 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 = [...guides, ...musicVideoReferenceChoices(project)];
+ const choices = [...guides, ...panel, ...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);
+ const chosen = guides.length ? [...guides, ...automatic] : automatic;
+ const unique = chosen.filter((ref, i) => chosen.findIndex((r) => r.imageId === ref.imageId) === i);
+ if (!panel.length) return unique.slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES);
+ // The storyboard panel keeps a slot; identities fill the rest.
+ return [...unique.filter((ref) => ref.imageId !== panel[0].imageId).slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES - 1), ...panel];
+}
+
+/**
+ * A shot fitted from a storyboard panel conditions on the panel's art as a
+ * composition guide (never its start frame), as a chip the References row
+ * shows and can drop.
+ */
+export function musicVideoPanelArtReferences(scene) {
+ if (typeof scene?.panelArt !== 'string' || !SENDABLE_REFERENCE_FILE.test(scene.panelArt)) return [];
+ return [{ id: `mvr-panel-${scene.panelId || 'art'}`.slice(0, 128), imageId: scene.panelArt, role: 'mood', label: 'Storyboard panel', panelArt: true }];
}
function automaticConditioningReferences(project, scene) {
diff --git a/server/lib/musicVideoConditioning.test.js b/server/lib/musicVideoConditioning.test.js
index b8570b845c..8b923498c6 100644
--- a/server/lib/musicVideoConditioning.test.js
+++ b/server/lib/musicVideoConditioning.test.js
@@ -63,4 +63,15 @@ describe('musicVideoConditioningReferences with Casting guides', () => {
expect(ids(musicVideoConditioningReferences(project(authored), scene, castMedia))).toEqual(['set.png', 'child.png']);
expect(ids(musicVideoConditioningReferences(project(authored), scene))).toEqual(['set.png']);
});
+
+ // Uniquely catches a fitted shot's storyboard panel losing its slot to identities, or an explicit pick ignoring it.
+ it('keeps a slot for a fitted shot\'s storyboard panel art, after the identities', () => {
+ const scene = { characterVariant: { ingredientId: CAST_ID, age: 7 }, panelId: 'panel-1', panelArt: 'panel.png' };
+ const refs = musicVideoConditioningReferences(project(authored), scene, castMedia);
+ expect(ids(refs)).toEqual(['child.png', 'teen.png', 'adult.png', 'panel.png']);
+ expect(refs[3]).toMatchObject({ id: 'mvr-panel-panel-1', label: 'Storyboard panel' });
+ expect(ids(musicVideoConditioningReferences(project(authored), { ...scene, frameReferenceIds: ['set'] }))).toEqual(['set.png']);
+ expect(ids(musicVideoConditioningReferences(project(authored), { ...scene, frameReferenceIds: ['mvr-panel-panel-1'] }))).toEqual(['panel.png']);
+ expect(ids(musicVideoConditioningReferences(project(authored), { panelId: 'panel-1', panelArt: 'sketch.gif' }))).toEqual(['lead.png', 'set.png']);
+ });
});
diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.js
index a6d60b9d0f..d5e333a101 100644
--- a/server/lib/musicVideoValidation.js
+++ b/server/lib/musicVideoValidation.js
@@ -1557,6 +1557,7 @@ export const musicVideoProductionProofSchema = z.object({
const scenePanelFields = {
panelId: z.string().regex(/^panel-[A-Za-z0-9-]{1,80}$/, 'Invalid panel id').nullable().optional(),
panelRev: z.string().regex(/^[0-9a-z]{1,16}$/, 'Invalid panel revision').nullable().optional(),
+ panelArt: z.string().regex(/^[^/\\]+\.(png|jpe?g|webp)$/i, 'Panel art must be a gallery image').nullable().optional(),
};
export const musicVideoSceneCreateSchema = z.object({
diff --git a/server/lib/schemaVersions.js b/server/lib/schemaVersions.js
index ed874baca6..3aa49cf60d 100644
--- a/server/lib/schemaVersions.js
+++ b/server/lib/schemaVersions.js
@@ -750,8 +750,10 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({
// migration or backfill.
// v23 = a shot's storyboard panel link (`scene.panelId`/`panelRev`, Fit to
// song), which a v22 re-plan or split rebuilds without. Optional, no backfill.
- // A field added to these normalizers later needs v24.
- musicVideoProjects: 23,
+ // v24 = the panel's art as the shot's frame reference (`scene.panelArt`),
+ // which a v23 re-plan or split rebuilds without. Optional, no backfill.
+ // A field added to these normalizers later needs v25.
+ musicVideoProjects: 24,
// v1 = Creative Commission FEEDBACK federation (PostgreSQL `commission_feedback`)
// via the per-record peer-sync push pipeline (record kind `commissionFeedback`,
// sync category `commissionFeedback`, #2686 — split-record follow-up to #2657).
diff --git a/server/lib/schemaVersions.test.js b/server/lib/schemaVersions.test.js
index 4eae079afe..384eee4443 100644
--- a/server/lib/schemaVersions.test.js
+++ b/server/lib/schemaVersions.test.js
@@ -91,15 +91,15 @@ describe('PORTOS_SCHEMA_VERSIONS', () => {
describe('buildPortosMeta', () => {
it('rejects repair, timing, narrative event, lyric warning, title/ending/subject/tool metadata and panel links on older music-video peers', async () => {
const meta = await buildPortosMeta();
- expect(meta.schemaVersions.musicVideoProjects).toBe(23);
+ expect(meta.schemaVersions.musicVideoProjects).toBe(24);
// Older builds re-normalize the newer fields away; the gate must stop that peer receiving them.
- for (const receiverV of [13, 14, 15, 16, 17, 18, 19, 20, 21, 22]) {
+ for (const receiverV of [13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]) {
expect(compareSchemaVersions(meta.schemaVersions, { ...meta.schemaVersions, musicVideoProjects: receiverV }).ahead)
- .toContainEqual({ category: 'musicVideoProjects', senderV: 23, receiverV });
+ .toContainEqual({ category: 'musicVideoProjects', senderV: 24, receiverV });
}
- const olderPeer = { ...meta.schemaVersions, musicVideoProjects: 22 };
+ const olderPeer = { ...meta.schemaVersions, musicVideoProjects: 23 };
expect(scopeVersionDiff(compareSchemaVersions(meta.schemaVersions, olderPeer), RECORD_KIND_SCHEMA_CATEGORIES.musicVideoProject))
- .toMatchObject({ compatible: false, ahead: [{ category: 'musicVideoProjects', senderV: 23, receiverV: 22 }] });
+ .toMatchObject({ compatible: false, ahead: [{ category: 'musicVideoProjects', senderV: 24, receiverV: 23 }] });
});
it('advertises lyric provenance to pause track transfers to caption-only peers', async () => {
diff --git a/server/lib/storyboardFit.js b/server/lib/storyboardFit.js
index 41255b6b1d..659c00f2af 100644
--- a/server/lib/storyboardFit.js
+++ b/server/lib/storyboardFit.js
@@ -77,11 +77,22 @@ export function storyboardShotPanel(board, scene) {
for (const panel of beat.panels) {
number += 1;
if (panel.id === scene.panelId) {
- return { state: storyboardPanelRev(panel) === scene.panelRev ? 'current' : 'changed', panel, beat, beatIndex, number };
+ const artChanged = storyboardPanelArt(panel) !== (scene.panelArt ?? null);
+ const changed = artChanged || storyboardPanelRev(panel) !== scene.panelRev;
+ return { state: changed ? 'changed' : 'current', artChanged, panel, beat, beatIndex, number };
}
}
}
- return { state: 'missing', panel: null, beat: null, beatIndex: null, number: null };
+ return { state: 'missing', artChanged: false, panel: null, beat: null, beatIndex: null, number: null };
+}
+
+/**
+ * A panel's selected art as a gallery image, the shot's frame reference (a
+ * composition guide, never its start frame). A sketch take has no gallery file
+ * and gives none.
+ */
+export function storyboardPanelArt(panel) {
+ return panel?.takes?.find((take) => take.id === panel.selectedTakeId)?.image || null;
}
const roleMatches = (role, label) => {
@@ -181,6 +192,7 @@ export function fitStoryboardToSong(board, song, { starts = {}, minShotSec = STO
beatId: beat.id,
panelId: panel?.id || null,
panelRev: panel ? storyboardPanelRev(panel) : null,
+ panelArt: storyboardPanelArt(panel),
label: `${title.slice(0, LABEL_MAX - suffix.length)}${suffix}`,
sectionIndex,
sectionLabel,
diff --git a/server/lib/storyboardFit.test.js b/server/lib/storyboardFit.test.js
index 064ceaaa90..1bc998c68b 100644
--- a/server/lib/storyboardFit.test.js
+++ b/server/lib/storyboardFit.test.js
@@ -75,6 +75,11 @@ describe('fitStoryboardToSong', () => {
const edited = { beats: board.beats.map((b) => ({ ...b, panels: b.panels.map((p) => (p.id === 'panel-b1' ? { ...p, action: 'New' } : p)) })) };
expect(storyboardShotPanel(edited, shot).state).toBe('changed');
expect(storyboardShotPanel({ beats: [] }, shot).state).toBe('missing');
+ // New panel art reads as changed too, since the art is the shot's frame reference.
+ const art = { beats: board.beats.map((b) => ({ ...b, panels: b.panels.map((p) => (p.id === 'panel-b1'
+ ? { ...p, takes: [{ id: 'take-1', source: 'gallery', image: 'b1.png' }], selectedTakeId: 'take-1' } : p)) })) };
+ expect(storyboardShotPanel(art, shot)).toMatchObject({ state: 'changed', artChanged: true });
+ expect(storyboardShotPanel(art, fitStoryboardToSong(art, song()).shots[1])).toMatchObject({ state: 'current', artChanged: false });
expect(storyboardShotPanel(board, { sceneId: 'mvs-hand' })).toBeNull();
});
diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.js
index d0b9e0de54..82948bf3aa 100644
--- a/server/services/musicVideo/projectsLogic.js
+++ b/server/services/musicVideo/projectsLogic.js
@@ -549,7 +549,7 @@ function buildScene(input, { order }) {
shotMode: input.shotMode ?? 'cutaway',
...(input.performanceSpeaker ? { performanceSpeaker: input.performanceSpeaker } : {}),
...(input.performanceStyle === 'music' ? { performanceStyle: 'music' } : {}),
- ...(input.panelId ? { panelId: input.panelId, panelRev: input.panelRev ?? null } : {}),
+ ...(input.panelId ? { panelId: input.panelId, panelRev: input.panelRev ?? null, panelArt: input.panelArt ?? null } : {}),
referenceImageId: null,
videoHistoryId: null,
// #8965 — immutable candidate takes; the two slot fields above are the
@@ -650,7 +650,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', 'characterVariant', 'panelId', 'panelRev'];
+ 'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds', 'characterVariant', 'panelId', 'panelRev', 'panelArt'];
/**
* Apply a patch to a single scene. Returns `{ project, updated }`. Throws if the
@@ -838,7 +838,7 @@ export function splitScene(project, sceneId, { backend = null, atSec = null } =
performanceSpeaker: scene.performanceSpeaker ?? null,
performanceStyle: scene.performanceStyle ?? null,
...(scene.camera ? { camera: scene.camera } : {}),
- ...(scene.panelId ? { panelId: scene.panelId, panelRev: scene.panelRev ?? null } : {}),
+ ...(scene.panelId ? { panelId: scene.panelId, panelRev: scene.panelRev ?? null, panelArt: scene.panelArt ?? null } : {}),
...timing,
}),
}, { order: 0 });
diff --git a/server/services/musicVideo/projectsLogic.test.js b/server/services/musicVideo/projectsLogic.test.js
index 948d02d8eb..9746a42ed1 100644
--- a/server/services/musicVideo/projectsLogic.test.js
+++ b/server/services/musicVideo/projectsLogic.test.js
@@ -599,9 +599,9 @@ describe('scene board operations', () => {
// Uniquely catches a split still's later pieces losing the Move, or the storyboard panel, the shot set.
it('keeps a still\'s Move and its storyboard panel on every piece of a split', () => {
- const { project, scene } = addScene(baseProject(), { prompt: 'a', visualLayer: 'still', stillMove: 'push', camera: { move: 'handheld' }, startSec: 0, endSec: 8, panelId: 'panel-example-1', panelRev: 'abc' });
+ const { project, scene } = addScene(baseProject(), { prompt: 'a', visualLayer: 'still', stillMove: 'push', camera: { move: 'handheld' }, startSec: 0, endSec: 8, panelId: 'panel-example-1', panelRev: 'abc', panelArt: 'panel-art.png' });
const split = splitScene(project, scene.sceneId, { atSec: 4 });
- expect(split.project.scenes.map((s) => [s.stillMove, s.panelId, s.panelRev])).toEqual([['push', 'panel-example-1', 'abc'], ['push', 'panel-example-1', 'abc']]);
+ expect(split.project.scenes.map((s) => [s.stillMove, s.panelId, s.panelRev, s.panelArt])).toEqual([['push', 'panel-example-1', 'abc', 'panel-art.png'], ['push', 'panel-example-1', 'abc', 'panel-art.png']]);
});
// Catches the split text disagreeing with its storyboard anchors during an instrumental lead-in.
@@ -1108,6 +1108,7 @@ describe('create-schema parity', () => {
performanceStyle: 'music',
panelId: 'panel-example-1',
panelRev: 'abc123',
+ panelArt: 'panel-art.png',
};
it('stores every accepted video setting key on the project record', () => {
diff --git a/server/services/storyboards/fitMusicVideo.js b/server/services/storyboards/fitMusicVideo.js
index 3ca5249ad4..64e1020ed0 100644
--- a/server/services/storyboards/fitMusicVideo.js
+++ b/server/services/storyboards/fitMusicVideo.js
@@ -7,15 +7,16 @@
* the user's tap; no model call.
*
* After the fit, a shot whose panel was edited shows it (storyboardShotPanel)
- * and waits: Update copies the panel's action to the shot's intent, so even a
- * locked shot only changes on that tap. Use as panel art sends the shot's
- * still back to its panel as the selected take.
+ * and waits: Update copies the panel's action to the shot's intent and its art
+ * to the shot's frame reference, so even a locked shot only changes on that
+ * tap. Use as panel art sends the shot's still back to its panel as the
+ * selected take.
*/
import { ServerError } from '../../lib/errorHandler.js';
import { localImageFilename } from '../../lib/localImageFilename.js';
import { sungLyricTextWithin } from '../../lib/musicVideoLyricAnchors.js';
-import { fitStoryboardToSong, storyboardFitSong, storyboardPanelRev, storyboardShotPanel } from '../../lib/storyboardFit.js';
+import { fitStoryboardToSong, storyboardFitSong, storyboardPanelArt, storyboardPanelRev, storyboardShotPanel } from '../../lib/storyboardFit.js';
import { addPanelTake, getStoryboard, selectPanelTake } from './index.js';
export async function fitMusicVideoToStoryboard(projectId, { boardUpdatedAt, starts = {} } = {}) {
@@ -72,11 +73,13 @@ async function shotAndPanel(projectId, sceneId) {
return { project, scene, board, panel: found.panel };
}
-/** Update: the shot takes its panel's action as its intent and records the panel as seen. */
+/** Update: the shot takes its panel's action as its intent and its art as its frame reference. */
export async function updateShotFromPanel(projectId, sceneId) {
const { panel } = await shotAndPanel(projectId, sceneId);
const { updateScene } = await import('../musicVideo/projects.js');
- const scene = await updateScene(projectId, sceneId, { visualIntent: panel.action.trim() || null, panelRev: storyboardPanelRev(panel) });
+ const scene = await updateScene(projectId, sceneId, {
+ visualIntent: panel.action.trim() || null, panelRev: storyboardPanelRev(panel), panelArt: storyboardPanelArt(panel),
+ });
return { scene };
}
@@ -86,8 +89,11 @@ export async function sendShotStillToPanel(projectId, sceneId) {
const image = localImageFilename(scene.referenceImageId);
if (!image) throw new ServerError('This shot has no still in the gallery yet.', { status: 409, code: 'NO_STILL' });
const existing = panel.takes.find((take) => take.source === 'gallery' && take.image === image);
- if (existing) return { board: await selectPanelTake(board.id, panel.id, existing.id) };
- const { board: next } = await addPanelTake(board.id, panel.id, { source: 'gallery', image });
+ const next = existing ? await selectPanelTake(board.id, panel.id, existing.id)
+ : (await addPanelTake(board.id, panel.id, { source: 'gallery', image })).board;
+ // The panel's art is now this still, so the shot's reference follows and it does not read as changed.
+ const { updateScene } = await import('../musicVideo/projects.js');
+ const updated = await updateScene(projectId, sceneId, { panelArt: image });
console.log(`🎬 Shot ${sceneId} still → storyboard ${board.id} panel ${panel.id}`);
- return { board: next };
+ return { board: next, scene: updated };
}
diff --git a/server/services/storyboards/fitMusicVideo.test.js b/server/services/storyboards/fitMusicVideo.test.js
index 89ebf4ce67..be53ed86d4 100644
--- a/server/services/storyboards/fitMusicVideo.test.js
+++ b/server/services/storyboards/fitMusicVideo.test.js
@@ -100,6 +100,8 @@ describe('fit a music video to its storyboard', () => {
expect(art.status).toBe(200);
const panel = art.body.board.beats[0].panels.find((p) => p.id === panelId);
expect(panel.takes.find((take) => take.id === panel.selectedTakeId)).toMatchObject({ source: 'gallery', image: 'still-a.png' });
+ // The panel's art is now the shot's own still, so the shot keeps it as its frame reference and reads as current.
+ expect(art.body.scene.panelArt).toBe('still-a.png');
// Sending it again reselects the same take rather than adding another.
const again = await request(app).post(`/api/storyboards/music-video/${project.id}/shots/${first.sceneId}/panel-art`);
expect(again.body.board.beats[0].panels.find((p) => p.id === panelId).takes).toHaveLength(1);