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: link a storyboard in the Plan step, or make one from the shots (#12943)

[._.]/5816975ba9af
diff --git a/client/src/components/musicVideo/StoryboardLinkPanel.jsx b/client/src/components/musicVideo/StoryboardLinkPanel.jsx
new file mode 100644
index 0000000000..60250601d4
--- /dev/null
+++ b/client/src/components/musicVideo/StoryboardLinkPanel.jsx
@@ -0,0 +1,117 @@
+import { useEffect, useState } from 'react';
+import { Link } from 'react-router';
+import { ExternalLink, LayoutPanelLeft, Loader2, Unlink } from 'lucide-react';
+import { getStoryboard, listStoryboards, makeStoryboardFromMusicVideo } from '../../services/api';
+import { formatCount, formatTimecode } from '../../utils/formatters';
+import { selectedTake, takeSrc } from '../storyboards/storyboardArt';
+
+const actionButton = 'min-h-[44px] inline-flex items-center justify-center gap-1.5 rounded-lg border border-port-border px-3 text-sm text-gray-200 hover:border-port-accent/60 hover:text-white disabled:opacity-40';
+const plural = (n, word) => `${formatCount(n)} ${word}${n === 1 ? '' : 's'}`;
+const STRIP_PANELS = 8;
+
+/**
+ * The Plan step's link to a Create › Storyboards board: pick one, or make one
+ * from this video's shots, then see it at a glance and open it. Linking
+ * changes no shot.
+ */
+export default function StoryboardLinkPanel({ project, onLink }) {
+ const linkedId = project.storyboardId || null;
+ // undefined = loading, null = missing on this machine.
+ const [board, setBoard] = useState(undefined);
+ // null = not read yet, undefined = reading.
+ const [boards, setBoards] = useState(null);
+ const [listError, setListError] = useState(false);
+ const [making, setMaking] = useState(false);
+
+ useEffect(() => {
+ if (!linkedId) return undefined;
+ let active = true;
+ setBoard(undefined);
+ getStoryboard(linkedId, { silent: true })
+ .then((next) => { if (active) setBoard(next); })
+ .catch(() => { if (active) setBoard(null); });
+ return () => { active = false; };
+ }, [linkedId]);
+
+ // The board list is read when the picker is first touched, not on every Plan visit.
+ const loadBoards = () => {
+ if (boards !== null) return;
+ setBoards(undefined);
+ setListError(false);
+ listStoryboards({ silent: true })
+ .then((rows) => setBoards(Array.isArray(rows) ? rows : []))
+ // A failed read says so; it must not look like there are no boards.
+ .catch(() => { setBoards(null); setListError(true); });
+ };
+
+ const makeFromVideo = async () => {
+ setMaking(true);
+ const res = await makeStoryboardFromMusicVideo(project.id).catch(() => null);
+ setMaking(false);
+ if (res?.board) {
+ setBoard(res.board);
+ onLink(res.board.id, { saved: true });
+ }
+ };
+
+ if (linkedId) {
+ if (board === undefined) return <p role="status" className="text-xs text-gray-500">Reading the storyboard…</p>;
+ if (board === null) {
+ return (
+ <div className="flex flex-wrap items-center gap-2">
+ <p role="status" className="flex-1 text-xs text-port-warning">The linked storyboard isn't on this machine, or was deleted.</p>
+ <button type="button" onClick={() => onLink(null)} className={actionButton}><Unlink size={16} aria-hidden="true" /> Unlink</button>
+ </div>
+ );
+ }
+ const panels = board.beats.flatMap((beat) => beat.panels);
+ const runtime = panels.reduce((sum, panel) => sum + (panel.seconds || 0), 0);
+ return (
+ <div className="space-y-2">
+ <div className="flex flex-wrap items-center gap-2">
+ <LayoutPanelLeft size={16} className="shrink-0 text-port-accent" aria-hidden="true" />
+ <div className="min-w-0 flex-1">
+ <p className="truncate text-sm text-white">{board.name}</p>
+ <p className="text-[11px] text-gray-400 tabular-nums">{plural(board.beats.length, 'beat')} · {plural(panels.length, 'panel')} · {formatTimecode(runtime)}</p>
+ </div>
+ <Link to={`/storyboards/${board.id}`} className={actionButton}><ExternalLink size={16} aria-hidden="true" /> Open</Link>
+ <button type="button" onClick={() => onLink(null)} className={actionButton}><Unlink size={16} aria-hidden="true" /> Unlink</button>
+ </div>
+ {panels.length > 0 && (
+ <ol className="flex gap-1 overflow-x-auto" aria-label="Storyboard panels">
+ {panels.slice(0, STRIP_PANELS).map((panel, index) => {
+ const src = takeSrc(selectedTake(panel));
+ return (
+ <li key={panel.id} className="h-12 w-20 shrink-0 overflow-hidden rounded bg-port-bg">
+ {src ? <img src={src} alt={panel.action || `Panel ${index + 1}`} loading="lazy" className="h-full w-full object-cover" />
+ : <p className="p-1 text-[10px] leading-tight text-gray-500 line-clamp-3">{panel.action || `Panel ${index + 1}`}</p>}
+ </li>
+ );
+ })}
+ {panels.length > STRIP_PANELS && <li className="flex h-12 shrink-0 items-center px-1 text-[11px] text-gray-500">+{formatCount(panels.length - STRIP_PANELS)}</li>}
+ </ol>
+ )}
+ </div>
+ );
+ }
+
+ return (
+ <div className="space-y-2">
+ <p className="text-xs text-gray-400">Plan the story on a storyboard: beats and panels you can sketch and play before the song is final.</p>
+ <div className="flex flex-wrap items-center gap-2">
+ <label htmlFor="mv-storyboard-link" className="sr-only">Link a storyboard</label>
+ <select id="mv-storyboard-link" value="" onFocus={loadBoards} onPointerDown={loadBoards} onChange={(e) => e.target.value && onLink(e.target.value)}
+ className="min-h-[44px] min-w-0 flex-1 bg-port-bg border border-port-border rounded px-2 text-sm text-white">
+ <option value="">{boards === undefined ? 'Reading storyboards…' : boards && !boards.length ? 'No storyboards yet' : 'Link a storyboard…'}</option>
+ {(boards || []).map((row) => <option key={row.id} value={row.id}>{row.name} ({plural(row.panelCount, 'panel')})</option>)}
+ </select>
+ {(project.scenes || []).length > 0 && (
+ <button type="button" onClick={makeFromVideo} disabled={making} className={actionButton}>
+ {making ? <Loader2 size={16} className="animate-spin" aria-hidden="true" /> : <LayoutPanelLeft size={16} aria-hidden="true" />} Make storyboard from this video
+ </button>
+ )}
+ </div>
+ {listError && <p role="status" className="text-xs text-port-warning">Storyboards could not be read. Tap the picker to try again.</p>}
+ </div>
+ );
+}
diff --git a/client/src/components/musicVideo/StoryboardLinkPanel.test.jsx b/client/src/components/musicVideo/StoryboardLinkPanel.test.jsx
new file mode 100644
index 0000000000..1fe9f4349c
--- /dev/null
+++ b/client/src/components/musicVideo/StoryboardLinkPanel.test.jsx
@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import StoryboardLinkPanel from './StoryboardLinkPanel';
+
+const api = vi.hoisted(() => ({ getStoryboard: vi.fn(), listStoryboards: vi.fn(), makeStoryboardFromMusicVideo: vi.fn() }));
+vi.mock('../../services/api', () => api);
+
+const board = {
+ id: 'sb-1', name: 'Example Story',
+ beats: [{ id: 'beat-1', panels: [{ id: 'panel-1', action: 'Wide of the gym', seconds: 4, takes: [], selectedTakeId: null }] }],
+};
+const renderPanel = (project, onLink = vi.fn()) => {
+ render(<MemoryRouter><StoryboardLinkPanel project={project} onLink={onLink} /></MemoryRouter>);
+ return onLink;
+};
+
+beforeEach(() => {
+ for (const fn of Object.values(api)) fn.mockReset();
+});
+
+describe('StoryboardLinkPanel', () => {
+ it('links a picked board, or makes one from the video shots', async () => {
+ api.listStoryboards.mockResolvedValue([{ id: 'sb-1', name: 'Example Story', panelCount: 1 }]);
+ api.makeStoryboardFromMusicVideo.mockResolvedValue({ board: { ...board, id: 'sb-2' } });
+ const onLink = renderPanel({ id: 'mv-1', storyboardId: null, scenes: [{ sceneId: 'mvs-1' }] });
+
+ const picker = screen.getByLabelText('Link a storyboard');
+ expect(api.listStoryboards).not.toHaveBeenCalled();
+ fireEvent.focus(picker);
+ expect(await screen.findByRole('option', { name: 'Example Story (1 panel)' })).toBeTruthy();
+ fireEvent.change(picker, { target: { value: 'sb-1' } });
+ expect(onLink).toHaveBeenCalledWith('sb-1');
+
+ fireEvent.click(screen.getByRole('button', { name: /Make storyboard from this video/ }));
+ await waitFor(() => expect(onLink).toHaveBeenCalledWith('sb-2', { saved: true }));
+ expect(api.makeStoryboardFromMusicVideo).toHaveBeenCalledWith('mv-1');
+ });
+
+ it('shows the linked board at a glance and unlinks it', async () => {
+ api.getStoryboard.mockResolvedValue(board);
+ const onLink = renderPanel({ id: 'mv-1', storyboardId: 'sb-1', scenes: [] });
+ expect(await screen.findByText('Example Story')).toBeTruthy();
+ expect(screen.getByText('1 beat · 1 panel · 0:04.00')).toBeTruthy();
+ expect(screen.getByRole('link', { name: /Open/ }).getAttribute('href')).toBe('/storyboards/sb-1');
+ fireEvent.click(screen.getByRole('button', { name: /Unlink/ }));
+ expect(onLink).toHaveBeenCalledWith(null);
+ });
+});
diff --git a/client/src/components/musicVideo/stages/PlanStage.jsx b/client/src/components/musicVideo/stages/PlanStage.jsx
index 512958b63f..f1fc800d3c 100644
--- a/client/src/components/musicVideo/stages/PlanStage.jsx
+++ b/client/src/components/musicVideo/stages/PlanStage.jsx
@@ -3,37 +3,48 @@ import TreatmentPanel, { treatmentSummary } from '../TreatmentPanel.jsx';
import StageSection from '../StageSection.jsx';
import { PlanActions } from '../ProjectActionGroups.jsx';
import ShotPacingFields from '../ShotPacingFields.jsx';
+import StoryboardLinkPanel from '../StoryboardLinkPanel.jsx';
/**
* Plan: the shot list before any shot is made — planning tools, the
* treatment (the brief the planner reads, then per-shot
- * direction) and the beat timeline. Each shot's still, clip and locks are on
- * Shots.
+ * direction), the beat timeline and the linked storyboard. Each shot's
+ * still, clip and locks are on Shots.
*/
export default function PlanStage({ board }) {
const { project, locked, busy, treatment } = board;
const scenes = project.scenes || [];
+ // Linking a board changes no shot, so it stays usable while shots are locked.
+ const linkStoryboard = (storyboardId, { saved = false } = {}) => {
+ board.editProjectLocal({ storyboardId });
+ if (!saved) board.saveProjectFields({ storyboardId });
+ };
return (
- <fieldset disabled={locked} className="min-w-0 space-y-3">
- <StageSection title="Planning tools">
- <PlanActions project={project} busy={busy} onPlan={board.onPlan} onAutoArrange={board.onAutoArrange} />
- <ShotPacingFields project={project} onEditLocal={board.editProjectLocal} onSave={board.saveProjectFields} />
- </StageSection>
-
- {/* The brief feeds the shot planner; the direction is applied per shot once they exist. */}
- <StageSection id="mv-board-treatment" title="Treatment" summary={scenes.length ? treatmentSummary(project) : 'Write the brief the shot planner follows'}>
- <div id="mv-setup-treatment">
- <TreatmentPanel key={`treatment-${project.id}`} project={project} treatment={treatment}
- storyboardApproved={!!board.productionReadiness?.storyboard?.approved} />
- </div>
- </StageSection>
+ <div className="min-w-0 space-y-3">
+ <fieldset disabled={locked} className="min-w-0 space-y-3">
+ <StageSection title="Planning tools">
+ <PlanActions project={project} busy={busy} onPlan={board.onPlan} onAutoArrange={board.onAutoArrange} />
+ <ShotPacingFields project={project} onEditLocal={board.editProjectLocal} onSave={board.saveProjectFields} />
+ </StageSection>
- {project.audioAnalysis && scenes.length > 0 && (
- <StageSection title="Beat timeline">
- <BeatTimeline audioAnalysis={project.audioAnalysis} scenes={scenes} lyricCues={project.lyricCues} narrativeEvents={project.composition?.narrativeEvents}
- onSeek={(startSec) => board.seekToScene({ startSec })} onCommit={board.commitSceneTiming} />
+ {/* The brief feeds the shot planner; the direction is applied per shot once they exist. */}
+ <StageSection id="mv-board-treatment" title="Treatment" summary={scenes.length ? treatmentSummary(project) : 'Write the brief the shot planner follows'}>
+ <div id="mv-setup-treatment">
+ <TreatmentPanel key={`treatment-${project.id}`} project={project} treatment={treatment}
+ storyboardApproved={!!board.productionReadiness?.storyboard?.approved} />
+ </div>
</StageSection>
- )}
- </fieldset>
+
+ {project.audioAnalysis && scenes.length > 0 && (
+ <StageSection title="Beat timeline">
+ <BeatTimeline audioAnalysis={project.audioAnalysis} scenes={scenes} lyricCues={project.lyricCues} narrativeEvents={project.composition?.narrativeEvents}
+ onSeek={(startSec) => board.seekToScene({ startSec })} onCommit={board.commitSceneTiming} />
+ </StageSection>
+ )}
+ </fieldset>
+ <StageSection id="mv-board-storyboard" title="Storyboard" summary={project.storyboardId ? 'Linked' : 'Plan the story as beats and panels'}>
+ <StoryboardLinkPanel project={project} onLink={linkStoryboard} />
+ </StageSection>
+ </div>
);
}
diff --git a/client/src/services/README.md b/client/src/services/README.md
index f6a6ae06f2..e020bfe8a0 100644
--- a/client/src/services/README.md
+++ b/client/src/services/README.md
@@ -87,7 +87,7 @@ toasts on throw). **Custom catch ⇒ `silent: true`** — otherwise toasts fire
| `apiMeatspace.js` | MeatSpace health, genome, POST, memory-practice, and atomic POST training-run APIs. |
| `apiMortalLoom.js` | Mortality tracking. |
| `apiMoodBoard.js` | Mood boards (inspiration canvas + items), `listMoodBoardNames()` for pickers, `composeMoodBoardPrompt()` which stores the board's composite style prompt. |
-| `apiStoryboards.js` | Storyboards (Create › Storyboards): board/beat/panel CRUD and moves, panel art takes (add, select, remove), the panel maker (board recipe, per-panel node values, node runs, Make empty panels), beats from a plot summary (preview, then add) and the saved recipe library; every board write returns the whole board. |
+| `apiStoryboards.js` | Storyboards (Create › Storyboards): board/beat/panel CRUD and moves, panel art takes (add, select, remove), the panel maker (board recipe, per-panel node values, node runs, Make empty panels), beats from a plot summary (preview, then add), the saved recipe library and Make storyboard from a music video; every board write returns the whole board. |
| `apiTribe.js` | Tribe people (relationship rings + contacts), plus `getTribeDuplicateIdentifiers()` (`GET /tribe/duplicate-identifiers`): a non-blocking report of emails/phones shared by more than one person. |
| `apiTimeline.js` | Human-activity timeline: `/timeline/day`. |
| `apiCalendar.js` | Calendar events. |
diff --git a/client/src/services/apiStoryboards.js b/client/src/services/apiStoryboards.js
index 6a4f2577b8..8323863089 100644
--- a/client/src/services/apiStoryboards.js
+++ b/client/src/services/apiStoryboards.js
@@ -74,3 +74,7 @@ export const extractStoryboardBeats = (id, input, options) =>
request(`/storyboards/${enc(id)}/beats/extract`, { ...json('POST', input), ...options });
export const addStoryboardBeats = (id, beats, options) =>
request(`/storyboards/${enc(id)}/beats/add`, { ...json('POST', { beats }), ...options });
+
+// A new board built from a music video's shots, linked to it → { board, project }.
+export const makeStoryboardFromMusicVideo = (projectId, options) =>
+ request(`/storyboards/from-music-video/${enc(projectId)}`, { method: 'POST', ...options });
diff --git a/docs/API.md b/docs/API.md
index bce8df3234..45dba37fa6 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 }`. Every write returns the whole board; over-limit text is refused. |
+| `/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). Every write returns the whole board; over-limit text is refused. |
| `/api/decks` | Decks (playing-card / tarot designer) |
| `/api/writers-room` | Writers Room |
| `/api/universe-builder` | Universe Builder |
diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.js
index 7f01d61f96..f42c5f6a25 100644
--- a/server/lib/musicVideoValidation.js
+++ b/server/lib/musicVideoValidation.js
@@ -58,6 +58,7 @@ import { BEAT_TOGGLE_OVERLAP, BEAT_TOGGLE_RATES, MUSIC_VIDEO_CUT_EFFECTS } from
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 { STORYBOARD_ID_PATTERN } from './storyboardVocabulary.js';
import { MUSIC_VIDEO_PERFORMANCE_STYLES, MUSIC_VIDEO_SHOT_MODES, SOURCE_AUDIO_LIPSYNC } from './musicVideoShotTiming.js';
import {
MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD,
@@ -1462,6 +1463,8 @@ export const musicVideoProjectUpdateSchema = z.object({
titleCard: musicVideoTitleCardSchema.nullable().optional(),
// The cutting room floor outro after the song (lib/musicVideoStatsOutro.js); null = off.
statsOutro: musicVideoStatsOutroSchema.nullable().optional(),
+ // The Create › Storyboards board this video is planned from; null unlinks.
+ storyboardId: z.string().regex(STORYBOARD_ID_PATTERN, 'storyboardId must be a storyboard id').nullable().optional(),
}).strict();
// Mark a project finished outside PortOS (or clear the marker). The server
diff --git a/server/routes/storyboards.js b/server/routes/storyboards.js
index b73baf765d..86656a9e83 100644
--- a/server/routes/storyboards.js
+++ b/server/routes/storyboards.js
@@ -20,6 +20,7 @@ import {
import {
getMakeEmptyPlan, getPanelMake, runPanelNode, startMakeEmpty, updatePanelNode, updateRecipe,
} from '../services/storyboards/make.js';
+import { makeStoryboardFromMusicVideo } from '../services/storyboards/fromMusicVideo.js';
import { addBeats, extractBeats } from '../services/storyboards/plot.js';
import { deleteSavedRecipe, listSavedRecipes, saveRecipe } from '../services/storyboards/recipeLibrary.js';
@@ -33,6 +34,11 @@ router.post('/', asyncHandler(async (req, res) => {
res.status(201).json(await createStoryboard(validateRequest(storyboardCreateSchema, req.body ?? {})));
}));
+// Make storyboard from this video: a board from the project's shots, linked to it.
+router.post('/from-music-video/:projectId', asyncHandler(async (req, res) => {
+ res.status(201).json(await makeStoryboardFromMusicVideo(req.params.projectId));
+}));
+
// The saved recipe library sits before /:id; a board id always starts "sb-".
router.get('/recipes', asyncHandler(async (_req, res) => {
res.json(await listSavedRecipes());
diff --git a/server/services/storyboards/fromMusicVideo.js b/server/services/storyboards/fromMusicVideo.js
new file mode 100644
index 0000000000..50656997c4
--- /dev/null
+++ b/server/services/storyboards/fromMusicVideo.js
@@ -0,0 +1,63 @@
+/**
+ * Make storyboard from this video: a board built from a music video's current
+ * shots, then linked to the project (`project.storyboardId`). One beat per run
+ * of shots in the same song section; one panel per shot, carrying its action,
+ * sung line, camera move, length, cast and selected still. The shots are not
+ * changed. Runs only on the user's tap; no model call.
+ */
+
+import { ServerError } from '../../lib/errorHandler.js';
+import { localImageFilename } from '../../lib/localImageFilename.js';
+import { STORYBOARD_ASPECT_RATIOS, STORYBOARD_LIMITS as L } from '../../lib/storyboardVocabulary.js';
+import { trimTo } from '../../lib/textUtils.js';
+import { createStoryboard, getStoryboard } from './index.js';
+
+// Planner section labels read "Section 3 · 2/4"; the beat takes the section part.
+const sectionTitle = (label) => trimTo(String(label || '').split(' · ')[0], L.beatTitle);
+
+function panelFromScene(scene) {
+ const seconds = Number.isFinite(scene.startSec) && Number.isFinite(scene.endSec) && scene.endSec > scene.startSec
+ ? scene.endSec - scene.startSec : null;
+ const image = localImageFilename(scene.referenceImageId);
+ const castId = trimTo(scene.characterVariant?.ingredientId, L.refId);
+ return {
+ action: trimTo(scene.visualIntent || scene.framePrompt || scene.prompt, L.panelText),
+ dialogue: trimTo(scene.lyricText, L.panelText),
+ camera: trimTo(scene.camera?.move, L.camera),
+ seconds,
+ castIds: castId ? [castId] : [],
+ takes: image ? [{ source: 'gallery', image }] : [],
+ };
+}
+
+function beatsFromScenes(scenes) {
+ const beats = [];
+ for (const scene of [...scenes].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))) {
+ const key = scene.sectionIndex ?? null;
+ const last = beats.at(-1);
+ if (!last || last.key !== key) beats.push({ key, title: sectionTitle(scene.sectionLabel), panels: [] });
+ beats.at(-1).panels.push(panelFromScene(scene));
+ }
+ return beats.map(({ key: _key, ...beat }) => beat);
+}
+
+export async function makeStoryboardFromMusicVideo(projectId) {
+ const { getProject, updateProject } = await import('../musicVideo/projects.js');
+ const project = await getProject(projectId);
+ if (!project) throw new ServerError('Music video not found', { status: 404, code: 'NOT_FOUND' });
+ if (project.storyboardId) {
+ const linked = await getStoryboard(project.storyboardId).catch(() => null);
+ if (linked) throw new ServerError(`This video is already linked to "${linked.name}"; unlink it first.`, { status: 409, code: 'STORYBOARD_LINKED' });
+ }
+ const scenes = Array.isArray(project.scenes) ? project.scenes : [];
+ if (!scenes.length) throw new ServerError('This video has no shots yet; plan the shots first.', { status: 400, code: 'NO_SHOTS' });
+ const aspect = project.treatment?.brief?.aspectRatio;
+ const board = await createStoryboard({
+ name: trimTo(project.name, L.name) || 'Untitled storyboard',
+ aspectRatio: STORYBOARD_ASPECT_RATIOS.includes(aspect) ? aspect : '16:9',
+ moodBoardId: project.visualSpec?.moodBoardId || null,
+ }, { beats: beatsFromScenes(scenes) });
+ const linked = await updateProject(projectId, { storyboardId: board.id });
+ console.log(`🎬 Storyboard ${board.id} made from music video ${projectId} (${scenes.length} shot(s))`);
+ return { board, project: linked };
+}
diff --git a/server/services/storyboards/fromMusicVideo.test.js b/server/services/storyboards/fromMusicVideo.test.js
new file mode 100644
index 0000000000..075fd5d1b2
--- /dev/null
+++ b/server/services/storyboards/fromMusicVideo.test.js
@@ -0,0 +1,73 @@
+/**
+ * Make storyboard from this video, through the real routers and file-backed
+ * stores: the board mirrors the shots and the project links it.
+ */
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import { request } from '../../lib/testHelper.js';
+import { errorMiddleware } from '../../lib/errorHandler.js';
+import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';
+
+const ROOT = () => lazyTempDataRoot('storyboard-from-mv-');
+vi.mock('../../lib/paths.js', async (importOriginal) => makePathsProxy(await importOriginal(), { dataRoot: ROOT }));
+vi.mock('../../lib/fileUtils.js', async (importOriginal) => makePathsProxy(await importOriginal(), { dataRoot: ROOT }));
+vi.mock('../settings.js', () => ({ getSettings: vi.fn(async () => ({})) }));
+
+const { default: storyboardRoutes } = await import('../../routes/storyboards.js');
+const { default: musicVideoRoutes } = await import('../../routes/musicVideo.js');
+const projects = await import('../musicVideo/projects.js');
+const { PATHS } = await import('../../lib/paths.js');
+const { mkdir, writeFile } = await import('node:fs/promises');
+
+const app = express();
+app.use(express.json());
+app.use('/api/storyboards', storyboardRoutes);
+app.use('/api/music-video', musicVideoRoutes);
+app.use(errorMiddleware);
+afterAll(cleanupTempDataRoots);
+
+const scene = (order, extra) => ({
+ sceneId: `mvs-${order}`, order, startSec: order * 4, endSec: order * 4 + 4, prompt: '', framePrompt: '', visualIntent: '', lyricText: '', takes: [], ...extra,
+});
+
+describe('make storyboard from a music video', () => {
+ it('builds beats from song sections and panels from shots, then links the project', async () => {
+ const project = await projects.createProject({ name: 'Example Song' });
+ await mkdir(PATHS.images, { recursive: true });
+ await writeFile(`${PATHS.images}/frame-a.png`, Buffer.from('89504e470d0a1a0a', 'hex'));
+ await projects.mutateProjectRecord(project.id, (record) => ({
+ project: {
+ ...record,
+ scenes: [
+ scene(0, { sectionIndex: 0, sectionLabel: 'Section 1 · 1/2', visualIntent: 'She opens the gym doors', referenceImageId: 'frame-a.png', camera: { move: 'push-in' } }),
+ scene(1, { sectionIndex: 0, sectionLabel: 'Section 1 · 2/2', framePrompt: 'Wide of the empty floor', characterVariant: { ingredientId: 'cat-example-1' } }),
+ scene(2, { sectionIndex: 1, sectionLabel: 'Section 2 · 1/1', prompt: 'She dances', lyricText: 'Here I am' }),
+ ],
+ },
+ }));
+
+ const made = await request(app).post(`/api/storyboards/from-music-video/${project.id}`);
+ expect(made.status).toBe(201);
+ const { board } = made.body;
+ expect(made.body.project.storyboardId).toBe(board.id);
+ expect(board.name).toBe('Example Song');
+ expect(board.beats.map((beat) => [beat.title, beat.panels.length])).toEqual([['Section 1', 2], ['Section 2', 1]]);
+ expect(board.beats[0].panels[0]).toMatchObject({ action: 'She opens the gym doors', camera: 'push-in', seconds: 4, takes: [expect.objectContaining({ source: 'gallery', image: 'frame-a.png' })] });
+ expect(board.beats[0].panels[1]).toMatchObject({ action: 'Wide of the empty floor', castIds: ['cat-example-1'], takes: [] });
+ expect(board.beats[1].panels[0]).toMatchObject({ action: 'She dances', dialogue: 'Here I am' });
+
+ // A second board is refused while the first stays linked; unlinking frees it.
+ expect((await request(app).post(`/api/storyboards/from-music-video/${project.id}`)).status).toBe(409);
+ const unlinked = await request(app).patch(`/api/music-video/${project.id}`).send({ storyboardId: null });
+ expect(unlinked.body.storyboardId).toBeNull();
+ const relinked = await request(app).patch(`/api/music-video/${project.id}`).send({ storyboardId: board.id });
+ expect(relinked.body.storyboardId).toBe(board.id);
+ expect((await request(app).patch(`/api/music-video/${project.id}`).send({ storyboardId: 'not-a-board' })).status).toBe(400);
+ });
+
+ it('refuses a video with no shots', async () => {
+ const project = await projects.createProject({ name: 'Empty' });
+ expect((await request(app).post(`/api/storyboards/from-music-video/${project.id}`)).status).toBe(400);
+ expect((await request(app).post('/api/storyboards/from-music-video/mv-missing')).status).toBe(404);
+ });
+});
diff --git a/server/services/storyboards/index.js b/server/services/storyboards/index.js
index f2a1c8f25b..6c4e1f2320 100644
--- a/server/services/storyboards/index.js
+++ b/server/services/storyboards/index.js
@@ -56,9 +56,10 @@ export async function getStoryboard(id) {
return board;
}
-export async function createStoryboard(input = {}) {
+/** A new board; `beats` seeds it (e.g. built from a music video's shots). */
+export async function createStoryboard(input = {}, { beats = [] } = {}) {
const now = new Date().toISOString();
- const board = sanitizeStoryboard({ ...pickFields(input, BOARD_FIELDS), id: newStoryboardId(), beats: [], createdAt: now, updatedAt: now });
+ const board = sanitizeStoryboard({ ...pickFields(input, BOARD_FIELDS), id: newStoryboardId(), beats, createdAt: now, updatedAt: now });
await writeRaw(board.id, board);
emitRecordUpdated(STORYBOARD_KIND, board.id);
autoSubscribeRecordToAllPeers(STORYBOARD_KIND, board.id).catch(() => {});