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

Storyboard accepts verified lyric timing and reads planned Board shots

Claude8642e7e08d2a
diff --git a/client/src/components/musicVideo/ProductionReviewContext.jsx b/client/src/components/musicVideo/ProductionReviewContext.jsx
index e2e1fa44b8..95504ffebf 100644
--- a/client/src/components/musicVideo/ProductionReviewContext.jsx
+++ b/client/src/components/musicVideo/ProductionReviewContext.jsx
@@ -12,11 +12,12 @@ const FOLD = 'min-h-[44px] cursor-pointer py-2 text-sm';
* at a time, never a wall of text above the Approve button. `onSeek(startSec)`
* plays the docked preview from a shot.
*/
-export default function ProductionReviewContext({ stage, project, onOpenArtifact, onArtReady, onSeek = null }) {
+export default function ProductionReviewContext({ stage, project, shots: reviewedShots = null, onOpenArtifact, onArtReady, onSeek = null }) {
const draft = project.productionReview?.draft || {};
const guide = project.devArtifacts?.find(a => a.id === draft.guideArtifactId && !a.deleted);
const document = draft.storyboardSource === 'document';
- const shots = draft.storyboard || [];
+ // The panel passes the Board storyboard as reviewed: draft shots plus a row for each scene without one.
+ const shots = reviewedShots || draft.storyboard || [];
const sheets = (project.devArtifacts || []).filter(a => !a.deleted && a.kind === 'storyboard');
const written = [['Cast', draft.cast], ['Environments', draft.environments], ['Visual language', draft.visualLanguage], ['Motion and energy', draft.motionLanguage]]
.filter(([, value]) => typeof value === 'string' && value.trim());
diff --git a/client/src/components/musicVideo/ProductionReviewPanel.jsx b/client/src/components/musicVideo/ProductionReviewPanel.jsx
index 982b838422..ba40a5859e 100644
--- a/client/src/components/musicVideo/ProductionReviewPanel.jsx
+++ b/client/src/components/musicVideo/ProductionReviewPanel.jsx
@@ -63,8 +63,10 @@ export default function ProductionReviewPanel({ project, review, onOpenArtifact,
const ready = review.current === false ? null : review.readiness; // approvals never act on a stale revision
const set = (key, value) => setLocal({ ...draft, [key]: value });
const documentShots = draft.storyboardSource === 'document';
+ // A Board scene with no draft shot shows the row the server derives for it (its planned action, camera and lyric lines).
const shots = documentShots ? draft.storyboard : [...draft.storyboard, ...(project.scenes || []).filter(scene => !draft.storyboard.some(s => s.sceneId === scene.sceneId)).map(scene => ({
id: scene.sceneId, sceneId: scene.sceneId, lyricCueIds: [], action: '', staging: '', camera: '', transition: '',
+ ...ready?.storyboard.shots?.find(s => s.sceneId === scene.sceneId),
}))];
const shotKey = shot => shot.id || shot.sceneId;
const setShot = (shot, key, value) => set('storyboard', shots.map(s => shotKey(s) === shotKey(shot) ? { ...s, [key]: value } : s));
@@ -101,6 +103,8 @@ export default function ProductionReviewPanel({ project, review, onOpenArtifact,
if (dirty) return 'Save your planning edits first.';
if (review.busy) return 'Working…';
const problems = shownProblems(stage);
+ // The storyboard step's checklist already lists each open item with its button, so the card only points there.
+ if (stage === 'storyboard' && problems.length) return problems.length > 1 ? `Finish the ${problems.length} open items above first.` : 'Finish the open item above first.';
// With no current proof, the Render button already says what to do; repeating it as a warning reads as required.
if (stage === 'proof' && proofNeedsRender) return null;
if (problems.length) return problems.length > 1 ? `${problems[0]} (+${problems.length - 1} more below)` : problems[0];
@@ -114,7 +118,7 @@ export default function ProductionReviewPanel({ project, review, onOpenArtifact,
// The problems listed under the help line: all of them, less the first when the help line is showing it
// (it isn't while edits are unsaved or an action is running). A proof with nothing rendered lists none.
const listedProblems = stage => {
- if (!ready || ready[stage].approved || (stage === 'proof' && proofNeedsRender)) return [];
+ if (!ready || ready[stage].approved || stage === 'storyboard' || (stage === 'proof' && proofNeedsRender)) return [];
const problems = shownProblems(stage);
return dirty || review.busy ? problems : problems.slice(1);
};
@@ -256,7 +260,7 @@ export default function ProductionReviewPanel({ project, review, onOpenArtifact,
{/* The overlay text pass (document compositions): advice too, shown before the shot list. */}
{key === 'storyboard' && ready?.storyboard.text && <OverlayTextCheck report={ready.storyboard.text} busy={review.busy}
onCheck={() => review.checkOverlayText()} onSeek={onSeek} />}
- {key === 'proof' ? proofContent : <ProductionReviewContext stage={key} project={project} onOpenArtifact={onOpenArtifact} onArtReady={available => setVisibleArt(available ? artIdentity : null)} onSeek={onSeek} />}
+ {key === 'proof' ? proofContent : <ProductionReviewContext stage={key} project={project} shots={shots} onOpenArtifact={onOpenArtifact} onArtReady={available => setVisibleArt(available ? artIdentity : null)} onSeek={onSeek} />}
</>}
{openRequests(key).length > 0 && <div role="group" aria-label={`${label} change requests`} className="mt-2 space-y-2 rounded border border-port-warning p-2">
<p className="text-sm">Resolve these change requests to approve.</p>
diff --git a/client/src/components/musicVideo/ProductionReviewPanel.test.jsx b/client/src/components/musicVideo/ProductionReviewPanel.test.jsx
index 02b5839c29..7de1aa0970 100644
--- a/client/src/components/musicVideo/ProductionReviewPanel.test.jsx
+++ b/client/src/components/musicVideo/ProductionReviewPanel.test.jsx
@@ -330,26 +330,35 @@ describe('Production proof playback evidence', () => {
describe('Approval problems with unsaved edits', () => {
it.each([
- [['Cover the master with timed shots.']],
- [['Cover the master with timed shots.', 'Resolve storyboard feedback for shot: chorus: hold longer']],
- ])('lists every storyboard problem while planning edits are unsaved (%j)', (problems) => {
+ [['Render and watch a current animated chorus proof with the master song.']],
+ [['Render and watch a current animated chorus proof with the master song.', 'Resolve proof feedback for chorus: hold longer']],
+ ])('lists every proof problem while planning edits are unsaved (%j)', (problems) => {
const review = reviewFixture();
- review.readiness.storyboard = { approved: false, problems };
+ review.readiness.proof = { ...review.readiness.proof, approved: false, problems };
function Board() {
const planning = useState({ ...project.productionReview.draft, cast: 'Edited cast' });
- return <ProductionReviewPanel project={project} review={review} onOpenArtifact={vi.fn()} stage="storyboard" planning={planning} />;
+ return <ProductionReviewPanel project={project} review={review} onOpenArtifact={vi.fn()} stage="proof" planning={planning} />;
}
render(<Board />);
expect(screen.getByText('Save your planning edits first.')).toBeTruthy();
for (const problem of problems) expect(screen.getByText(problem)).toBeTruthy();
});
- it('shows the first problem once, on the help line, when nothing is unsaved', () => {
+ it('shows the first proof problem once, on the help line, when nothing is unsaved', () => {
+ const review = reviewFixture();
+ review.readiness.proof = { ...review.readiness.proof, approved: false, problems: ['Resolve proof feedback for chorus: hold longer', 'Second problem.'] };
+ render(<ProductionReviewPanel project={project} review={review} onOpenArtifact={vi.fn()} stage="proof" />);
+ expect(screen.getAllByText(/Resolve proof feedback for chorus/)).toHaveLength(1);
+ expect(screen.getByText('Second problem.')).toBeTruthy();
+ });
+
+ it('points the storyboard card at the step checklist in one line instead of repeating its items', () => {
const review = reviewFixture();
review.readiness.storyboard = { approved: false, problems: ['Cover the master with timed shots.', 'Second problem.'] };
render(<ProductionReviewPanel project={project} review={review} onOpenArtifact={vi.fn()} stage="storyboard" />);
- expect(screen.getAllByText(/Cover the master with timed shots\./)).toHaveLength(1);
- expect(screen.getByText('Second problem.')).toBeTruthy();
+ expect(screen.getByText('Finish the 2 open items above first.')).toBeTruthy();
+ expect(screen.queryByText(/Cover the master with timed shots\./)).toBeNull();
+ expect(screen.queryByText('Second problem.')).toBeNull();
});
});
@@ -426,3 +435,22 @@ describe('storyboard camera notes (#10589)', () => {
expect(screen.queryByRole('note', { name: 'Camera variety notes' })).toBeNull();
});
});
+
+describe('Board scenes planned without draft shots', () => {
+ it('counts and lists them in the storyboard approval card with the rows the server derived', () => {
+ const planned = { ...project, scenes: [
+ { sceneId: 's1', label: 'Opening', startSec: 0, endSec: 4 },
+ { sceneId: 's2', label: 'Chorus', startSec: 4, endSec: 8 },
+ ] };
+ const review = reviewFixture();
+ review.readiness.storyboard = { approved: false, problems: [], shots: [
+ { sceneId: 's1', lyricCueIds: [], action: 'She looks up from the monitor', staging: 'Medium shot', camera: 'Handheld drift', transition: 'Cut' },
+ { sceneId: 's2', lyricCueIds: [], action: 'Film spills onto the floor', staging: 'Wide shot', camera: 'Handheld drift', transition: 'Cut' },
+ ] };
+ render(<ProductionReviewPanel project={planned} review={review} onOpenArtifact={vi.fn()} stage="storyboard" />);
+ expect(screen.getByText(/Watch the storyboard in the player, then approve\. 2 storyboard shots/)).toBeTruthy();
+ expect(screen.queryByText(/No storyboard shots to review/)).toBeNull();
+ // The card's shot list and the shot editor both start from the derived row.
+ expect(screen.getAllByText('She looks up from the monitor')).toHaveLength(2);
+ });
+});
diff --git a/client/src/pages/MusicVideo.test.jsx b/client/src/pages/MusicVideo.test.jsx
index fccb04bafe..1e42d14acd 100644
--- a/client/src/pages/MusicVideo.test.jsx
+++ b/client/src/pages/MusicVideo.test.jsx
@@ -1328,7 +1328,8 @@ describe('MusicVideo project video renderer', () => {
expect(await screen.findByText(/Split the scene on a lyric or phrase boundary/)).toBeTruthy();
fireEvent.click(await screen.findByRole('button', { name: /Split on lyric boundaries/ }));
await waitFor(() => expect(splitMusicVideoScene).toHaveBeenCalledWith('mv-2', 's1', 'fal', expect.anything()));
- expect(await screen.findByText('Verse · 2/2', { selector: ':not(option)' })).toBeTruthy();
+ // The new scene shows on the Board and in the storyboard approval's shot list.
+ expect((await screen.findAllByText('Verse · 2/2', { selector: ':not(option)' })).length).toBeGreaterThan(0);
expect(screen.queryByRole('button', { name: /Split on lyric boundaries/ })).toBeNull();
});
diff --git a/server/services/musicVideo/productionReview.js b/server/services/musicVideo/productionReview.js
index 553d920344..f1b6b0b60f 100644
--- a/server/services/musicVideo/productionReview.js
+++ b/server/services/musicVideo/productionReview.js
@@ -5,10 +5,11 @@ import { ServerError } from '../../lib/errorHandler.js';
import { musicVideoAllowsMedia } from '../../lib/musicVideoMediaPolicy.js';
import { isNonBlankStr as text } from '../../lib/textUtils.js';
-import { cameraMovementFromText, getCameraMovement } from '../../lib/cameraMovements.js';
+import { cameraMovementFromText, getCameraMovement, shotCameraLabel } from '../../lib/cameraMovements.js';
import { cameraVarietyReport } from './shotCamera.js';
import { overlayTextReport } from './overlayText.js';
import { musicVideoAspect } from '../../lib/musicVideoAspect.js';
+import { lyricCueSpan } from './timedText.js';
const artifact = (project, id) => (project.devArtifacts || []).find(a => a.id === id && !a.deleted);
const artifactBasis = a => a ? { id: a.id, version: a.version, file: a.file } : null;
const source = p => {
@@ -226,6 +227,30 @@ function castAndSetsApproval(project) {
return { approved, stale: changedFields.length ? withRevertible({ approvedAt: stage.approvedAt || null, changedFields }, stage.approvedValues) : null };
}
+/**
+ * The storyboard row a Board scene with no draft shot of its own stands for:
+ * its planned action, staging and camera, the Cast & Sets world's camera and
+ * transition language where the scene has none (unless the sheet was skipped),
+ * and the lyric lines it overlaps. Planning shots after the art approval
+ * writes scenes without draft rows, so the storyboard reads them this way
+ * until a director edits a shot; preparing the review writes the same rows.
+ */
+export function boardShotFromScene(project, scene) {
+ const world = (project.castAndSets?.status !== 'skipped' && project.castAndSets?.direction?.world) || {};
+ return {
+ sceneId: scene.sceneId,
+ lyricCueIds: (project.lyricCues || []).filter(c => c.startSec < scene.endSec && c.endSec > scene.startSec).map(c => c.id),
+ action: scene.visualIntent || scene.prompt || '', staging: scene.framePrompt || '',
+ camera: shotCameraLabel(scene.camera) || scene.direction?.camera || world.camera || '', transition: world.transitions || '',
+ };
+}
+
+/** The Board storyboard as reviewed: every draft shot, then a derived row for each scene that has none. */
+export function boardStoryboard(project, storyboard = project.productionReview?.draft?.storyboard || []) {
+ return [...storyboard, ...(project.scenes || []).filter(scene => !storyboard.some(shot => shot.sceneId === scene.sceneId))
+ .map(scene => boardShotFromScene(project, scene))];
+}
+
export function productionReadiness(project) {
const review = project.productionReview || {};
const draft = review.draft || {};
@@ -251,9 +276,10 @@ export function productionReadiness(project) {
} else {
if (!cues.length) boardProblems.push('Import lyrics and align them to the current vocal; missing lyrics are not an instrumental.');
if (draft.timingStatus !== 'verified' || review.alignmentBasis !== alignmentBasis) boardProblems.push(ALIGNMENT_UNVERIFIED_PROBLEM);
- if (cues.some(c => !(Number.isFinite(c.startSec) && c.endSec > c.startSec && c.endSec <= duration)
- || !c.words?.length || c.words.some(w => !(Number.isFinite(w.startSec) && w.endSec > w.startSec)
- || w.startSec < c.startSec || w.endSec > c.endSec))) {
+ // A line is judged on the span its words give it (lyricCueSpan), the span the renderer shows:
+ // forced-aligned words may run a little past a line window taken from the song's line timestamps.
+ if (cues.some(c => !c.words?.length || c.words.some(w => !(Number.isFinite(w.startSec) && w.endSec > w.startSec))
+ || !(lyricCueSpan(c)?.endSec <= duration))) {
boardProblems.push('Every lyric line needs bounded, positive-duration word timings; repair zero-length or missing words.');
}
}
@@ -277,7 +303,7 @@ export function productionReadiness(project) {
boardProblems.push('Storyboard shots must cover the master without unintended gaps or overlaps.');
}
for (const scene of scenes) {
- const shot = documentShots ? scene : draft.storyboard?.find(s => s.sceneId === scene.sceneId);
+ const shot = documentShots ? scene : draft.storyboard?.find(s => s.sceneId === scene.sceneId) || boardShotFromScene(project, scene);
if (!(Number.isFinite(scene.startSec) && scene.endSec > scene.startSec && scene.endSec <= duration)
|| !shot || ['action', 'staging', 'camera', 'transition'].some(key => !text(shot[key]))) {
boardProblems.push(`Complete timing, action, staging, camera and transition for ${scene.label || 'each shot'}.`);
@@ -287,7 +313,7 @@ export function productionReadiness(project) {
|| shot?.lyricCueIds?.some(id => !cues.some(c => c.id === id))) boardProblems.push(`Review lyric anchors for ${scene.label || 'each shot'}.`);
}
const storyboardApproved = !boardProblems.length && review.approvals?.storyboard?.basis === basis.storyboard;
- const camera = storyboardCameraReport(scenes, documentShots ? null : draft.storyboard);
+ const camera = storyboardCameraReport(scenes, documentShots ? null : boardStoryboard(project));
const proof = review.proof;
const excerpt = (project.excerpts || []).find(e => e.id === proof?.excerptId);
const proofProblems = unresolved('proof').map(f => `Resolve proof feedback for ${f.target}: ${f.text}`);
@@ -299,7 +325,9 @@ export function productionReadiness(project) {
return { basis, inputs, alignment: { basis: alignmentBasis, status: draft.lyricsMode === 'instrumental' ? 'instrumental'
: draft.timingStatus !== 'verified' ? 'provisional' : review.alignmentBasis === alignmentBasis ? 'verified' : 'stale' }, documentShotImport: { documentDirectory: project.composition?.document?.directory || null, audioBasis: alignmentBasis }, art: { approved: artApproved, problems: [...new Set(artProblems)], stale: artApproved ? null : staleApproval(project, 'art', basis.art, inputs) },
// The overlay text check is advice on the storyboard, like camera variety; it never blocks approval.
- storyboard: { approved: storyboardApproved, problems: [...new Set(boardProblems)], camera, text: overlayTextReport(project, overlayTextBasis), stale: storyboardApproved ? null : staleApproval(project, 'storyboard', basis.storyboard, inputs) },
+ storyboard: { approved: storyboardApproved, problems: [...new Set(boardProblems)], camera,
+ // Board shots as reviewed, derived rows included, so the editor and approval card show what the gate checked.
+ shots: documentShots ? null : boardStoryboard(project), text: overlayTextReport(project, overlayTextBasis), stale: storyboardApproved ? null : staleApproval(project, 'storyboard', basis.storyboard, inputs) },
proof: { approved: proofApproved, problems: proofProblems, excerptId: excerpt?.id || null, stale: proofApproved ? null : staleApproval(project, 'proof', basis.proof, inputs) },
castAndSets: castAndSetsApproval(project),
// The animated proof is optional review evidence: the approved storyboard is what the final render needs.
diff --git a/server/services/musicVideo/productionReview.storyboard.test.js b/server/services/musicVideo/productionReview.storyboard.test.js
new file mode 100644
index 0000000000..ffe4eba047
--- /dev/null
+++ b/server/services/musicVideo/productionReview.storyboard.test.js
@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { productionReadiness, productionAlignmentBasis } from './productionReview.js';
+
+const WORD_PROBLEM = /bounded, positive-duration word timings/;
+const SHOT_PROBLEM = /^Complete timing, action, staging, camera and transition/;
+const ANCHOR_PROBLEM = /^Review lyric anchors/;
+
+// A verified vocal song: line windows from the song's line timestamps, words from forced alignment.
+function project({ words = [{ w: 'walking', startSec: 0.5, endSec: 1 }, { w: 'home', startSec: 1, endSec: 2.24 }], draftShots = [] } = {}) {
+ const base = {
+ id: 'p1', audioAnalysis: { durationSec: 8 },
+ lyricCues: [{ id: 'c1', text: 'walking home', startSec: 0.6, endSec: 2, words }],
+ castAndSets: { status: 'approved', direction: { world: { camera: 'Handheld drift', transitions: 'Hard cut on the downbeat' } } },
+ scenes: [
+ { sceneId: 's1', label: 'Verse', startSec: 0, endSec: 4, visualIntent: 'She looks up from the monitor', framePrompt: 'Medium shot, desk lamp' },
+ { sceneId: 's2', label: 'Outro', startSec: 4, endSec: 8, visualIntent: 'Film spills onto the floor', framePrompt: 'Wide shot' },
+ ],
+ productionReview: { draft: { lyricsMode: 'vocal', timingStatus: 'verified', storyboard: draftShots } },
+ };
+ return { ...base, productionReview: { ...base.productionReview, alignmentBasis: productionAlignmentBasis(base) } };
+}
+
+describe('storyboard readiness after verified lyric timing', () => {
+ it('accepts aligned words that run a little past their line window, as the renderer shows them', () => {
+ const { storyboard, alignment } = productionReadiness(project());
+ expect(alignment.status).toBe('verified');
+ expect(storyboard.problems.some((p) => WORD_PROBLEM.test(p))).toBe(false);
+ });
+
+ it('still blocks a zero-length or missing word', () => {
+ const zero = productionReadiness(project({ words: [{ w: 'walking', startSec: 0.5, endSec: 0.5 }, { w: 'home', startSec: 1, endSec: 2 }] }));
+ expect(zero.storyboard.problems.some((p) => WORD_PROBLEM.test(p))).toBe(true);
+ const missing = productionReadiness(project({ words: [] }));
+ expect(missing.storyboard.problems.some((p) => WORD_PROBLEM.test(p))).toBe(true);
+ });
+
+ it('reads Board scenes planned without draft shots as complete, lyric-anchored shots', () => {
+ const { storyboard } = productionReadiness(project());
+ expect(storyboard.problems.filter((p) => SHOT_PROBLEM.test(p) || ANCHOR_PROBLEM.test(p))).toEqual([]);
+ expect(storyboard.shots).toEqual([
+ { sceneId: 's1', lyricCueIds: ['c1'], action: 'She looks up from the monitor', staging: 'Medium shot, desk lamp', camera: 'Handheld drift', transition: 'Hard cut on the downbeat' },
+ { sceneId: 's2', lyricCueIds: [], action: 'Film spills onto the floor', staging: 'Wide shot', camera: 'Handheld drift', transition: 'Hard cut on the downbeat' },
+ ]);
+ });
+
+ it('keeps a director-edited draft shot over the derived row', () => {
+ const edited = { sceneId: 's1', lyricCueIds: ['c1'], action: 'She laughs', staging: 'Close-up', camera: '', transition: 'Cut' };
+ const { storyboard } = productionReadiness(project({ draftShots: [edited] }));
+ expect(storyboard.shots[0]).toEqual(edited);
+ expect(storyboard.problems).toContain('Complete timing, action, staging, camera and transition for Verse.');
+ });
+});
diff --git a/server/services/musicVideo/productionReviewService.js b/server/services/musicVideo/productionReviewService.js
index 7d0df9b6a6..eed8574b36 100644
--- a/server/services/musicVideo/productionReviewService.js
+++ b/server/services/musicVideo/productionReviewService.js
@@ -3,7 +3,7 @@ import { ServerError } from '../../lib/errorHandler.js';
import { getProject, mutateProjectRecord } from './projects.js';
import { musicVideoEvents } from './events.js';
import { shotCameraLabel } from '../../lib/cameraMovements.js';
-import { productionReadiness, seedArtDraft, productionReviewBasis, productionAlignmentBasis, documentStoryboardBasis, approveProductionStage, assertProductionApproval, recordProductionFeedback, resolveProductionFeedback, revertApprovedInput } from './productionReview.js';
+import { productionReadiness, boardStoryboard, seedArtDraft, productionReviewBasis, productionAlignmentBasis, documentStoryboardBasis, approveProductionStage, assertProductionApproval, recordProductionFeedback, resolveProductionFeedback, revertApprovedInput } from './productionReview.js';
const reviewProcessId = randomUUID();
@@ -226,16 +226,7 @@ export async function prepareProductionReview(id, options = {}) {
const { project: planned } = await mutateProjectRecord(id, current => {
const latest = current.productionReview.draft;
if (latest.storyboardSource === 'document') return { project: current };
- // New shots borrow the Cast & Sets world's camera and transition language when the scene has
- // none, unless the sheet was skipped (the planner ignores a skipped direction too).
- const world = (current.castAndSets?.status !== 'skipped' && current.castAndSets?.direction?.world) || {};
- const storyboard = [...latest.storyboard, ...current.scenes.filter(scene => !latest.storyboard.some(shot => shot.sceneId === scene.sceneId)).map(scene => ({
- sceneId: scene.sceneId,
- lyricCueIds: (current.lyricCues || []).filter(c => c.startSec < scene.endSec && c.endSec > scene.startSec).map(c => c.id),
- action: scene.visualIntent || scene.prompt || '', staging: scene.framePrompt || '',
- camera: shotCameraLabel(scene.camera) || scene.direction?.camera || world.camera || '', transition: world.transitions || '',
- }))];
- return { project: { ...current, productionReview: { ...current.productionReview, draft: { ...latest, storyboard } } } };
+ return { project: { ...current, productionReview: { ...current.productionReview, draft: { ...latest, storyboard: boardStoryboard(current, latest.storyboard) } } } };
});
return changed(planned);
}
diff --git a/server/services/musicVideo/timedText.js b/server/services/musicVideo/timedText.js
index cc5cf7573a..34183981fb 100644
--- a/server/services/musicVideo/timedText.js
+++ b/server/services/musicVideo/timedText.js
@@ -100,6 +100,29 @@ export const normalizeLyricCues = (cues) => normalizeList(cues, 'lc', (cue) => {
return { text, ...(words ? { words, ...(cue.suspect === true ? { suspect: true } : {}) } : {}), ...matched };
});
+const finiteSec = (n) => typeof n === 'number' && Number.isFinite(n);
+const timedWords = (cue) => {
+ const words = Array.isArray(cue?.words) ? cue.words : [];
+ return words.length && words.every((w) => finiteSec(w?.startSec) && finiteSec(w?.endSec) && w.endSec > w.startSec) ? words : null;
+};
+
+/**
+ * The time a lyric line really spans: its own window widened to cover its
+ * word timings, or null when it has neither a window nor timed words. A line's
+ * window often comes from the song's line timestamps while its words come from
+ * forced alignment on the vocal, so a word can start or end a little outside
+ * it. The lyric renderer times each line from its words, so this is the span
+ * the viewer sees.
+ */
+export function lyricCueSpan(cue) {
+ const words = timedWords(cue);
+ const own = finiteSec(cue?.startSec) && finiteSec(cue?.endSec) && cue.endSec > cue.startSec ? cue : null;
+ if (!words) return own ? { startSec: own.startSec, endSec: own.endSec } : null;
+ const first = words[0].startSec;
+ const last = Math.max(...words.map((w) => w.endSec));
+ return { startSec: Math.min(own?.startSec ?? first, first), endSec: Math.max(own?.endSec ?? last, last) };
+}
+
/** Normalize an edited phrase list: keep ids, trim label/intent. */
export const normalizePhrases = (phrases) => normalizeList(phrases, 'mp', (phrase) => ({
label: trimTo(phrase.label, 120),