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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
Final render: locked clips render as they are, every refusal names its shots, one-tap fixes (#11579)
[._.]/227744019846
diff --git a/client/src/components/musicVideo/CompositionPanel.jsx b/client/src/components/musicVideo/CompositionPanel.jsxindex 9acf231f6f..401ab300f0 100644--- a/client/src/components/musicVideo/CompositionPanel.jsx+++ b/client/src/components/musicVideo/CompositionPanel.jsx@@ -19,7 +19,7 @@ export default function CompositionPanel({ board }) {const mode = project.composition?.mode;return (<fieldset disabled={locked} className="min-w-0">- <RenderFailure project={project} renderJob={board.renderJob} />+ <RenderFailure project={project} renderJob={board.renderJob} onPatchShots={board.onPatchShots} /><div className="space-y-2 rounded-lg border border-port-border bg-port-card p-3"><div className="flex flex-wrap items-center gap-2 text-xs text-port-text-muted"><span>Render style: <span className="text-port-text">{renderStyleLabel(mode)}</span></span>diff --git a/client/src/components/musicVideo/RenderStatusPanel.jsx b/client/src/components/musicVideo/RenderStatusPanel.jsxindex 9cdadf6297..e6d01d7a54 100644--- a/client/src/components/musicVideo/RenderStatusPanel.jsx+++ b/client/src/components/musicVideo/RenderStatusPanel.jsx@@ -1,5 +1,5 @@import Banner from '../ui/Banner.jsx';-import { useRef } from 'react';+import { useRef, useState } from 'react';import { Film, Download, Maximize2, AlertTriangle } from 'lucide-react';import { STALE_RENDER_MESSAGE } from '../../lib/musicVideoStages.js';import { assetDownloadUrl } from '../../lib/standaloneDownload.js';@@ -93,10 +93,50 @@ export default function RenderStatusPanel({);}-/** Persisted failures survive reload; kickoff/SSE failures stay bound to their project. */-export function RenderFailure({ project, renderJob }) {+const STALE_TAKE_CODES = new Set(['STALE_PERFORMANCE_TAKES', 'MUSIC_VIDEO_STALE_SOURCE_AUDIO_TAKES']);++// The one-tap fix a render refusal names, for the shots it applies to: shots+// with no lip-sync take become cutaways (a lip-sync take would lose its+// in-point), and shots longer than their clip hold its last frame.+function refusalFix(failure) {+ const plural = (ids, one, many) => (ids.length === 1 ? one : many);+ if (STALE_TAKE_CODES.has(failure?.code)) {+ const ids = (failure.context?.stale || []).filter((entry) => entry.cutaway).map((entry) => entry.sceneId);+ return ids.length ? { ids, patch: { shotMode: 'cutaway' }, label: `Switch ${plural(ids, 'it', `these ${ids.length}`)} to Cutaway`,+ done: `Switched ${ids.length} shot${plural(ids, '', 's')} to Cutaway` } : null;+ }+ if (failure?.code === 'INSUFFICIENT_CLIP_COVERAGE') {+ const ids = (failure.context?.shortfalls || []).map((entry) => entry.sceneId);+ return ids.length ? { ids, patch: { holdLastFrame: true }, label: `Hold the last frame on ${plural(ids, 'it', `these ${ids.length}`)}`,+ done: `Holding the last frame on ${ids.length} shot${plural(ids, '', 's')}` } : null;+ }+ return null;+}++/**+ * Persisted failures survive reload; kickoff/SSE failures stay bound to their project.+ * A refusal with a one-tap fix offers it: `onPatchShots(sceneIds, patch, doneMessage)`.+ */+export function RenderFailure({ project, renderJob, onPatchShots }) {+ const [fixing, setFixing] = useState(false);if (renderJob?.active && renderJob.context === project.id) return null;- const error = renderJob?.failure?.projectId === project.id ? renderJob.failure.message- : project.status === 'failed' ? project.renderError : null;- return error ? <Banner tone="error" title="Render failed" className="break-words">{error}</Banner> : null;+ const failure = renderJob?.failure?.projectId === project.id ? renderJob.failure : null;+ const error = failure ? failure.message : project.status === 'failed' ? project.renderError : null;+ if (!error) return null;+ const fix = onPatchShots ? refusalFix(failure) : null;+ const apply = () => {+ setFixing(true);+ Promise.resolve(onPatchShots(fix.ids, fix.patch, fix.done)).finally(() => setFixing(false));+ };+ return (+ <Banner tone="error" title="Render failed" className="break-words">+ {error}+ {fix && (+ <button type="button" onClick={apply} disabled={fixing}+ className="mt-2 block min-h-[44px] sm:min-h-0 rounded border border-port-border bg-port-bg px-2 py-1 text-xs text-port-text hover:bg-port-border/40 disabled:opacity-50">+ {fixing ? 'Saving…' : fix.label}+ </button>+ )}+ </Banner>+ );}diff --git a/client/src/components/musicVideo/RenderStatusPanel.test.jsx b/client/src/components/musicVideo/RenderStatusPanel.test.jsxindex ab26bc03b7..fc758725e5 100644--- a/client/src/components/musicVideo/RenderStatusPanel.test.jsx+++ b/client/src/components/musicVideo/RenderStatusPanel.test.jsx@@ -1,5 +1,5 @@-import { afterEach, expect, it } from 'vitest';-import { cleanup, render, screen } from '@testing-library/react';+import { afterEach, expect, it, vi } from 'vitest';+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';import RenderStatusPanel, { RenderFailure } from './RenderStatusPanel.jsx';afterEach(cleanup);@@ -20,3 +20,20 @@ it('shows an amber out-of-date notice only when the final render is stale (#1014rerender(<RenderStatusPanel renderHistoryId="rh-1" />);expect(screen.queryByRole('status')).not.toBeInTheDocument();});++// Uniquely catches a refusal's one-tap fix patching a shot it cannot fix, or a fix offered where none exists.+it('offers one tap that fixes the shots a render refusal names', async () => {+ const project = { id: 'mv-example', status: 'ready' };+ const onPatchShots = vi.fn(async () => {});+ const failure = { projectId: project.id, code: 'STALE_PERFORMANCE_TAKES', message: 'Shots 3 (no lip-sync record), 6 (re-timed): …',+ context: { stale: [{ sceneId: 'a', cutaway: true }, { sceneId: 'b', cutaway: false }, { sceneId: 'c', cutaway: true }] } };+ const { rerender } = render(<RenderFailure project={project} renderJob={{ failure }} onPatchShots={onPatchShots} />);+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: 'Switch these 2 to Cutaway' })); });+ expect(onPatchShots).toHaveBeenCalledWith(['a', 'c'], { shotMode: 'cutaway' }, 'Switched 2 shots to Cutaway');+ rerender(<RenderFailure project={project} renderJob={{ failure: { projectId: project.id, code: 'INSUFFICIENT_CLIP_COVERAGE', message: 'Shot 19 (0.58s short): …',+ context: { shortfalls: [{ sceneId: 'd', shortBySec: 0.58 }] } } }} onPatchShots={onPatchShots} />);+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: 'Hold the last frame on it' })); });+ expect(onPatchShots).toHaveBeenLastCalledWith(['d'], { holdLastFrame: true }, 'Holding the last frame on 1 shot');+ rerender(<RenderFailure project={project} renderJob={{ failure: { ...failure, code: 'MISSING_CLIPS' } }} onPatchShots={onPatchShots} />);+ expect(screen.queryByRole('button')).not.toBeInTheDocument();+});diff --git a/client/src/components/musicVideo/SceneClipTiming.jsx b/client/src/components/musicVideo/SceneClipTiming.jsxindex 75b8813a38..6055a2eeb4 100644--- a/client/src/components/musicVideo/SceneClipTiming.jsx+++ b/client/src/components/musicVideo/SceneClipTiming.jsx@@ -36,8 +36,9 @@ function Stepper({ id, label, value, range, disabled, onSet, readout, less, more/*** A footage shot's clip timing, set by hand and played the same way by the* player and the final render, from the one clip file: Speed in frames per- * second over the 24 fps grid, Offset in frames against the song, and Reverse.- * `onChange(patch)` saves `{ speedFps }`, `{ offsetFrames }` (0 clears it) or `{ reverse }`.+ * second over the 24 fps grid, Offset in frames against the song, Reverse, and+ * Hold last frame for a clip shorter than its shot.+ * `onChange(patch)` saves `{ speedFps }`, `{ offsetFrames }` (0 clears it), `{ reverse }` or `{ holdLastFrame }`.*/export default function SceneClipTiming({ fieldId, scene, disabled = false, disabledReason = null, onChange }) {const speed = Number.isInteger(scene.speedFps) ? scene.speedFps : 0;@@ -63,6 +64,12 @@ export default function SceneClipTiming({ fieldId, scene, disabled = false, disaReverse <span className="text-port-text-muted">plays backwards, no loop</span></label>)}+ {/* Holding fills the shot without changing the clip, so a locked video keeps it open. */}+ <label htmlFor={fieldId('hold')} className="flex min-h-[44px] items-center gap-2 text-xs sm:min-h-0">+ <input id={fieldId('hold')} type="checkbox" checked={scene.holdLastFrame === true}+ onChange={(e) => onChange({ holdLastFrame: e.target.checked || null })} />+ Hold last frame <span className="text-port-text-muted">when the clip ends before the shot</span>+ </label></div>);}diff --git a/client/src/components/musicVideo/stages/ReviewStage.jsx b/client/src/components/musicVideo/stages/ReviewStage.jsxindex a50a6e55d3..a149e0a7b1 100644--- a/client/src/components/musicVideo/stages/ReviewStage.jsx+++ b/client/src/components/musicVideo/stages/ReviewStage.jsx@@ -63,7 +63,7 @@ export default function ReviewStage({ board }) {return (<fieldset disabled={locked} className="min-w-0 space-y-3">{!project.renderHistoryId && <ReviewDraftPanel project={project} onOpen={board.openArtifact} draftState={board.reviewDraftState} />}- <RenderFailure project={project} renderJob={renderJob} />+ <RenderFailure project={project} renderJob={renderJob} onPatchShots={board.onPatchShots} />{project.renderHistoryId ? <>{finalRender}{drafts}</> : <>{drafts}{finalRender}</>}<StageSection title="Dependency changes and repair"><DependencyImpactPanel project={project} busy={revisions.busy} onRepair={revisions.repair} /></StageSection></fieldset>diff --git a/client/src/hooks/useMusicVideoRenderJob.js b/client/src/hooks/useMusicVideoRenderJob.jsindex 7e61afef8d..bd42c0e0cb 100644--- a/client/src/hooks/useMusicVideoRenderJob.js+++ b/client/src/hooks/useMusicVideoRenderJob.js@@ -44,7 +44,8 @@ export default function useMusicVideoRenderJob({ project, onRendered, onFailed,setFailure({ projectId, message: frame.error || 'Render failed' });onFailed?.(projectId, frame.error || 'Render failed');},- onKickoffError: (error, projectId) => { setFailure({ projectId, message: error?.message || 'Failed to start render' }); },+ // A refusal keeps its code and context, so the banner can offer the fix it names.+ onKickoffError: (error, projectId) => { setFailure({ projectId, message: error?.message || 'Failed to start render', code: error?.code, context: error?.context }); },successToast: () => 'Music video rendered',errorFallback: 'Render failed',canceledMessage: 'Render cancelled',@@ -116,6 +117,7 @@ export default function useMusicVideoRenderJob({ project, onRendered, onFailed,cancel,cancelling: !!slot.jobId && cancelRequestedFor === slot.jobId,failure,+ clearFailure: () => setFailure(null),reattaching,reattach,start: (id) => {diff --git a/client/src/pages/MusicVideo.jsx b/client/src/pages/MusicVideo.jsxindex 7b79c9ea00..94baf295d7 100644--- a/client/src/pages/MusicVideo.jsx+++ b/client/src/pages/MusicVideo.jsx@@ -769,6 +769,26 @@ export default function MusicVideo() {.catch((err) => toast.error(err?.message || 'Failed to add scene'));};+ // A render refusal's one-tap fix: the same patch on each shot it names.+ // Sequential, like auto-arrange, so each PATCH merges against the last.+ const patchShots = (sceneIds, patch, doneMessage) => {+ if (!selected || !sceneIds.length) return Promise.resolve();+ const snapshot = selected;+ const ids = new Set(sceneIds);+ replaceProject({ ...selected, scenes: selected.scenes.map((s) => (ids.has(s.sceneId) ? { ...s, ...patch } : s)) });+ return (async () => {+ for (const sceneId of sceneIds) await updateMusicVideoScene(selected.id, sceneId, patch, { silent: true });+ })()+ .then(() => {+ renderJob.clearFailure();+ toast.success(`${doneMessage} — render again`);+ })+ .catch((err) => {+ replaceProject(snapshot);+ toast.error(err?.message || 'Could not change the shots');+ });+ };+// Optimistic local edit; PATCH on blur (silent — this owns its error toast).const editSceneLocal = (sceneId, patch) => {replaceProject({ ...selected, scenes: selected.scenes.map((s) => (s.sceneId === sceneId ? { ...s, ...patch } : s)) });@@ -1259,6 +1279,7 @@ export default function MusicVideo() {videoSettings,sceneMedia,renderJob,+ onPatchShots: patchShots,production,castSets,devArtifacts,diff --git a/server/lib/musicVideoDependencies.js b/server/lib/musicVideoDependencies.jsindex 1486798289..22f6cdb3d9 100644--- a/server/lib/musicVideoDependencies.js+++ b/server/lib/musicVideoDependencies.js@@ -21,7 +21,7 @@ const layerRef = (scene) => ({ role: 'layer', sceneId: scene.sceneId, assetId: s// A chosen frame fit changes the render; a shot left to fill keeps its evidence..concat(scene.frameFit && scene.frameFit !== 'fill' ? [['frameFit', scene.frameFit]] : [])// A hand-set clip speed or offset changes the render; a shot left as rendered keeps its evidence.- .concat(['speedFps', 'offsetFrames', 'reverse'].filter((key) => scene[key]).map((key) => [key, scene[key]]))+ .concat(['speedFps', 'offsetFrames', 'reverse', 'holdLastFrame'].filter((key) => scene[key]).map((key) => [key, scene[key]]))// A glitch over its cuts changes the render; a shot without one keeps its evidence..concat(['transitionIn', 'transitionOut'].filter((key) => scene[key]).map((key) => [key, scene[key]])).concat(scene.glitches?.length ? [['glitches', scene.glitches]] : [])diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.jsindex 4745f4dc75..a9d48c6faa 100644--- a/server/lib/musicVideoValidation.js+++ b/server/lib/musicVideoValidation.js@@ -634,6 +634,8 @@ const sceneLayerFields = {offsetFrames: z.number().int().min(CLIP_OFFSET_FRAMES_RANGE.min).max(CLIP_OFFSET_FRAMES_RANGE.max).nullable().optional(),// The clip plays backwards (a footage shot; never a lip-sync performance).reverse: z.boolean().nullable().optional(),+ // A clip shorter than its shot holds its last frame for the rest of the shot; null clears it.+ holdLastFrame: z.boolean().nullable().optional(),// A VHS glitch over the cut into / out of this shot (musicVideoTransitions.js); null clears it.transitionIn: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),transitionOut: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),diff --git a/server/services/musicVideo/performanceShot.js b/server/services/musicVideo/performanceShot.jsindex 2b4ded276f..4d5678ae8e 100644--- a/server/services/musicVideo/performanceShot.js+++ b/server/services/musicVideo/performanceShot.js@@ -50,7 +50,9 @@ import {selectedPerformanceInstruction,SOURCE_AUDIO_MUSIC,} from '../../lib/musicVideoShotTiming.js';+import { clipOffsetSec, clipReversed, clipSpeedRate } from '../../lib/musicVideoLayers.js';import { getProject } from './projects.js';+import { clipLocks, nameShots } from './productionReview.js';import { assertVocalStemTimebase, resolveVocalStemPath } from './vocalStem.js';export const SHOT_INSTRUCTION_VERSION = 2;@@ -89,11 +91,29 @@ async function sliceAudioWindow(sourcePath, outPath, { startSec, endSec }) {const refuse = (message, code, status = 400) => new ServerError(message, { status, code });-// Recorded vs current scene times agree within a millisecond.-const SAME_TIME_SEC = 0.001;+// A shot's Offset moves its clip in whole 24 fps frames, so a slid shot whose+// Offset lines its take back up with the song lands within half a frame.+const IN_SYNC_SEC = 0.5 / 24;++/**+ * Whether a take still plays its sung audio under the words after the shot+ * was re-timed. The render starts the take at its in-point plus `Offset`, at+ * the shot's (new) start: the song moment it plays there is the one at its+ * in-point (`madeAtSec`) plus that Offset. A shot whose start did not+ * move (stretched or shortened at its end), or one slid with a matching+ * Offset, is in sync; the render's coverage check still refuses a shot the+ * take runs out under. A speed change always puts the mouth off the words.+ */+// The song moment a lip-sync take plays at its edit in-point, as the render+// places it: the take's audio window starts at clip time 0.+const madeAtSec = (instruction) => (Number.isFinite(instruction.audioWindow?.startSec)+ ? instruction.audioWindow.startSec + instruction.edit.inSec : instruction.songInterval?.startSec);++const playsInSync = (scene, madeAtSec) => Number.isFinite(madeAtSec) && clipSpeedRate(scene) === 1 && !clipReversed(scene)+ && Math.abs(madeAtSec + clipOffsetSec(scene) - scene.startSec) <= IN_SYNC_SEC;const STALE_REASON_LABELS = Object.freeze({- 'not-lip-synced': 'not lip-synced',+ 'not-lip-synced': 'no lip-sync record',retimed: 're-timed','audio-changed': 'sung window changed in the song',});@@ -143,7 +163,8 @@ function legacyMasterLookup(project, masterPath) {* or an import made before the scene became a performance;* - `audio-changed` (stale) — the master was replaced AND the take's own* audio window sounds different in it;- * - `retimed` (stale) — the scene's song interval moved since the take;+ * - `retimed` (stale) — the shot moved since the take, and its Offset (or a+ * speed change) no longer plays the take's audio under the song;* - `audio-rehashed` (NOT stale, informational) — the master's bytes* changed (a re-master or re-encode) but the take's window did not.*@@ -163,10 +184,10 @@ async function reviewPerformanceTakes(project, masterPath) {if (scene.videoHistoryId && !['still', 'card', 'code'].includes(scene.visualLayer) && supplied?.audioConditioning) {sha256 ??= await hashFile(masterPath);if (supplied.audioConditioning.sourceSha256 !== sha256) results.push({ sceneId: scene.sceneId, reason: 'source-audio-changed', stale: true });- else if (Math.round(scene.startSec * 48000) !== supplied.audioConditioning.startSample- || scene.endSec !== supplied.songInterval?.endSec) results.push({ sceneId: scene.sceneId, reason: 'retimed', stale: true });+ else if (!playsInSync(scene, supplied.audioConditioning.startSample / 48000)) results.push({ sceneId: scene.sceneId, reason: 'retimed', stale: true });}- if (!isPerformanceScene(scene) || !scene.videoHistoryId) continue;+ // A supplied-audio take (local LTX hearing the song) was judged above.+ if (!isPerformanceScene(scene) || !scene.videoHistoryId || supplied?.audioConditioning) continue;const instruction = selectedPerformanceInstruction(scene);if (instruction) selected.push({ scene, instruction });else results.push({ sceneId: scene.sceneId, reason: 'not-lip-synced', stale: true });@@ -186,7 +207,6 @@ async function reviewPerformanceTakes(project, masterPath) {return compareWindowFingerprint(fingerprint, currentEnvelope).same;};for (const { scene, instruction } of selected) {- const interval = instruction.songInterval || {};const rehashed = instruction.audio?.sha256 !== sha256;// A window that cannot be compared (decode failure) stays stale — the// pre-#9266 answer — rather than rendering a take out of sync.@@ -195,7 +215,7 @@ async function reviewPerformanceTakes(project, masterPath) {return false;});if (!unchanged) results.push({ sceneId: scene.sceneId, reason: 'audio-changed', stale: true });- else if (!(Math.abs(interval.startSec - scene.startSec) <= SAME_TIME_SEC && Math.abs(interval.endSec - scene.endSec) <= SAME_TIME_SEC)) {+ else if (!playsInSync(scene, madeAtSec(instruction))) {results.push({ sceneId: scene.sceneId, reason: 'retimed', stale: true });} else if (rehashed) results.push({ sceneId: scene.sceneId, reason: 'audio-rehashed', stale: false });}@@ -230,29 +250,37 @@ export async function withDraftPerformanceFallbacks(project, masterPath) {* The one staleness gate every renderer that draws performance takes runs* (concat, composed, document, and their excerpts): a performance take sings* one stretch of one recording, so a re-timed scene or a changed sung window- * would put mouth motion over the wrong audio. Throws 422- * STALE_PERFORMANCE_TAKES naming each scene's reason.+ * would put mouth motion over the wrong audio. A shot whose clip is locked+ * renders as locked: the director approved that clip as it plays. Any other+ * stale shot blocks, named by number with its reason. Throws 422+ * STALE_PERFORMANCE_TAKES (or MUSIC_VIDEO_STALE_SOURCE_AUDIO_TAKES when a+ * supplied-audio take is among them); `context.stale` lists+ * `{ sceneId, reason, cutaway }`, `cutaway` marking the shots a switch to+ * Cutaway fixes: those with no lip-sync take. A lip-sync take switched to+ * Cutaway loses its in-point and plays from its first frame, out of sync.*/export async function assertCurrentPerformanceTakes(project, masterPath) {const reviewed = await reviewPerformanceTakes(project, masterPath);const rehashed = reviewed.filter((r) => r.reason === 'audio-rehashed').length;if (rehashed > 0) console.log(`🎵 Music Video: ${rehashed} lip-sync take${rehashed === 1 ? '' : 's'} still match${rehashed === 1 ? 'es' : ''} the re-mastered song in ${rehashed === 1 ? 'its' : 'their'} sung window`);- const stale = reviewed.filter((r) => r.stale).map(({ sceneId, reason }) => ({ sceneId, reason }));+ const locks = clipLocks(project);+ const stale = reviewed.filter((r) => r.stale && locks?.[r.sceneId] !== 'locked')+ .map(({ sceneId, reason }) => ({ sceneId, reason, cutaway: reason === 'not-lip-synced' }));if (stale.length === 0) return;- if (stale.some(({ sceneId }) => {+ const shots = nameShots(project, stale.map(({ sceneId, reason }) => ({ sceneId, note: STALE_REASON_LABELS[reason] || reason })));+ const one = stale.length === 1;+ const them = one ? 'it' : 'them';+ const fixes = [`Regenerate ${them}`,+ ...(locks ? [`lock ${one ? 'its clip' : 'their clips'} to keep ${them} as ${one ? 'it plays' : 'they play'}`] : []),+ ...(stale.every((entry) => entry.cutaway) ? [`switch ${them} to Cutaway`] : [])];+ const fix = fixes.length > 1 ? `${fixes.slice(0, -1).join(', ')} or ${fixes.at(-1)}` : fixes[0];+ const suppliedAudio = ({ sceneId }) => {const scene = project.scenes.find((entry) => entry.sceneId === sceneId);- return scene?.takes?.some((take) => take.assetId === scene.videoHistoryId && take.shotInstruction?.audioConditioning);- })) {- throw new ServerError('A supplied-audio shot no longer matches the selected recording or scene interval; regenerate it before rendering',- { status: 422, code: 'MUSIC_VIDEO_STALE_SOURCE_AUDIO_TAKES', context: { stale } });- }- const counts = new Map();- for (const { reason } of stale) counts.set(reason, (counts.get(reason) || 0) + 1);- const why = [...counts].map(([reason, n]) => `${n} ${STALE_REASON_LABELS[reason] || reason}`).join(', ');- throw new ServerError(- `${stale.length} performance shot${stale.length === 1 ? ' has' : 's have'} no lip-synced take of the current song interval and recording (${why}) — regenerate ${stale.length === 1 ? 'it' : 'them'}, or switch to Cutaway, before rendering`,- { status: 422, code: 'STALE_PERFORMANCE_TAKES', context: { stale } },- );+ return !!scene?.takes?.some((take) => take.assetId === scene.videoHistoryId && take.shotInstruction?.audioConditioning);+ };+ const code = stale.some(suppliedAudio) ? 'MUSIC_VIDEO_STALE_SOURCE_AUDIO_TAKES' : 'STALE_PERFORMANCE_TAKES';+ throw new ServerError(`${shots}: the selected take may not sing in sync with the song. ${fix}`,+ { status: 422, code, context: { stale } });}/**diff --git a/server/services/musicVideo/performanceShot.test.js b/server/services/musicVideo/performanceShot.test.jsindex cefd506cc5..6852854a58 100644--- a/server/services/musicVideo/performanceShot.test.js+++ b/server/services/musicVideo/performanceShot.test.js@@ -31,7 +31,8 @@ vi.mock('../videoGen/local.js', async () => {const { PATHS } = await import('../../lib/fileUtils.js');const { findFfmpeg, probeVideoStreamInfo } = await import('../../lib/ffmpeg.js');-const { preparePerformanceShot, findStalePerformanceTakes, withDraftPerformanceFallbacks } = await import('./performanceShot.js');+const { preparePerformanceShot, findStalePerformanceTakes, withDraftPerformanceFallbacks, assertCurrentPerformanceTakes } = await import('./performanceShot.js');+const { setShotLocks } = await import('./productionReview.js');const fal = await import('../videoGen/fal.js');const { videoGenEvents } = await import('../videoGen/events.js');const { buildMusicVideoFfmpegArgs, beatSnapClips, resolveSceneClips } = await import('./render.js');@@ -120,6 +121,9 @@ it('blocks composition and exposes a repair when supplied audio used an older tagetProject.mockResolvedValue(supplied);getTrack.mockResolvedValue({ audioFilename: 'song.wav' });await expect(assertCurrentPerformanceTakes(supplied, await resolveMasterAudioPath(supplied))).resolves.toBeUndefined();+ // A local lip-sync take hears the song the same way: it is lip-synced, not a cutaway import.+ const lipSync = { ...supplied, scenes: [{ ...shot, shotMode: 'performance' }] };+ await expect(assertCurrentPerformanceTakes(lipSync, await resolveMasterAudioPath(lipSync))).resolves.toBeUndefined();await writeFile(join(PATHS.music, 'another-take.wav'), songWav({ markerAmp: 10000 }));getTrack.mockResolvedValue({ audioFilename: 'another-take.wav' });await expect(assertCurrentPerformanceTakes(supplied, await resolveMasterAudioPath(supplied))).rejects.toMatchObject({ code: 'MUSIC_VIDEO_STALE_SOURCE_AUDIO_TAKES' });@@ -219,11 +223,16 @@ describe.skipIf(!ffmpeg)('music-video performance shot through the fal lip-syncexpect(out.fps).toBe(24);expect(Math.abs(frames - 36)).toBeLessThanOrEqual(1);- // The take is only valid for the interval and recording it sang: a- // re-timed scene or a replaced song must be regenerated, not rendered.+ // The take is only valid while it plays its sung audio under the song: a+ // shot stretched at its end, or slid with an Offset that lines the take+ // back up, still sings; a slide without one, or a speed change, does not.const songPath = join(PATHS.music, 'song.wav');expect(await findStalePerformanceTakes({ scenes: [withTake] }, songPath)).toEqual([]);- expect(await findStalePerformanceTakes({ scenes: [{ ...withTake, endSec: 22 }] }, songPath))+ expect(await findStalePerformanceTakes({ scenes: [{ ...withTake, endSec: 22 }] }, songPath)).toEqual([]);+ expect(await findStalePerformanceTakes({ scenes: [{ ...withTake, startSec: 20.5, offsetFrames: 12 }] }, songPath)).toEqual([]);+ expect(await findStalePerformanceTakes({ scenes: [{ ...withTake, startSec: 20.5 }] }, songPath))+ .toEqual([{ sceneId: 'mvs-1', reason: 'retimed' }]);+ expect(await findStalePerformanceTakes({ scenes: [{ ...withTake, speedFps: 2 }] }, songPath)).toEqual([{ sceneId: 'mvs-1', reason: 'retimed' }]);// #9266: a re-master that changes the song OUTSIDE the take's window// (18.225–23.275) keeps the take; one that changes its sung window does not.@@ -637,3 +646,23 @@ describe('draft fallbacks for stale performance shots', () => {expect(project.scenes[0].videoHistoryId).toBe('sync-1');});});++describe('the final render lip-sync gate', () => {+ // Uniquely catches a refusal that does not name its shots, or a locked clip still blocking.+ it('names the shots in song order with each reason, and lets a locked clip render as it plays', async () => {+ const shot = (sceneId, startSec) => ({ sceneId, startSec, endSec: startSec + 2, shotMode: 'performance', prompt: 'a singer',+ referenceImageId: `${sceneId}.png`, videoHistoryId: `${sceneId}-clip`,+ takes: [{ takeId: `${sceneId}-t`, kind: 'video', assetId: `${sceneId}-clip`, sourceImageId: `${sceneId}.png`, status: 'selected' }] });+ const project = { id: 'mv-1', scenes: [shot('late', 6), shot('early', 0), { ...shot('cut', 3), shotMode: 'cutaway' }] };+ await expect(assertCurrentPerformanceTakes(project, 'unread.wav')).rejects.toMatchObject({+ status: 422, code: 'STALE_PERFORMANCE_TAKES',+ message: 'Shots 1 (no lip-sync record), 3 (no lip-sync record): the selected take may not sing in sync with the song. Regenerate them, lock their clips to keep them as they play or switch them to Cutaway',+ context: { stale: [{ sceneId: 'late', reason: 'not-lip-synced', cutaway: true }, { sceneId: 'early', reason: 'not-lip-synced', cutaway: true }] },+ });+ const stillLocked = setShotLocks(project, { sceneIds: ['late'], locked: true });+ const clipLocked = setShotLocks(stillLocked, { sceneIds: ['late'], locked: true, stage: 'video' });+ await expect(assertCurrentPerformanceTakes(clipLocked, 'unread.wav')).rejects.toThrow(/^Shot 1 \(no lip-sync record\): .* switch it to Cutaway$/);+ const allLocked = setShotLocks(setShotLocks(clipLocked, { sceneIds: ['early'], locked: true }), { sceneIds: ['early'], locked: true, stage: 'video' });+ await expect(assertCurrentPerformanceTakes(allLocked, 'unread.wav')).resolves.toBeUndefined();+ });+});diff --git a/server/services/musicVideo/productionReview.js b/server/services/musicVideo/productionReview.jsindex 8134ad5760..bbb5fde787 100644--- a/server/services/musicVideo/productionReview.js+++ b/server/services/musicVideo/productionReview.js@@ -194,6 +194,27 @@ export function clipLocks(project, locks = shotLocks(project)) {export const clipLocked = (project, sceneId) => project.productionReview?.clipApprovals?.[sceneId]&& clipLocks(project)?.[sceneId] === 'locked';+/** Each timed scene's shot number as the board shows it: song order, from 1. */+export function shotNumbers(project) {+ const order = (project.scenes || []).filter(scene => Number.isFinite(scene?.startSec)).sort((a, b) => a.startSec - b.startSec);+ return new Map(order.map((scene, i) => [scene.sceneId, i + 1]));+}++/**+ * Names shots for an error message in song order: "Shot 4", "Shots 2, 9", or+ * with notes "Shots 2 (re-timed), 9 (not lip-synced)". `entries` are sceneIds+ * or `{ sceneId, note }`. Untimed scenes have no number, so a list that holds+ * one falls back to a count ("3 shots").+ */+export function nameShots(project, entries) {+ const numbers = shotNumbers(project);+ const items = entries.map(entry => (typeof entry === 'string' ? { sceneId: entry } : entry))+ .map(({ sceneId, note }) => ({ n: numbers.get(sceneId), note }));+ if (items.some(({ n }) => !n)) return `${items.length} ${items.length === 1 ? 'shot' : 'shots'}`;+ const list = items.sort((a, b) => a.n - b.n).map(({ n, note }) => (note ? `${n} (${note})` : `${n}`)).join(', ');+ return `${items.length === 1 ? 'Shot' : 'Shots'} ${list}`;+}+/** What a locked clip freezes: the inputs it was rendered from, and the selected clip itself. */const CLIP_LOCKED_FIELDS = ['prompt', 'framePrompt', 'visualIntent', 'camera', 'direction', 'startSec', 'endSec', 'lyricText','referenceImageId', 'endImageId', 'shotMode', 'performanceSpeaker', 'performanceStyle', 'visualLayer', 'loop', 'videoHistoryId', 'codeClip', 'speedFps', 'offsetFrames', 'reverse'];diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.jsindex 200e2593da..c44c2f0020 100644--- a/server/services/musicVideo/projectsLogic.js+++ b/server/services/musicVideo/projectsLogic.js@@ -524,6 +524,7 @@ function buildScene(input, { order }) {...(input.speedFps ? { speedFps: input.speedFps } : {}),...(input.offsetFrames ? { offsetFrames: input.offsetFrames } : {}),...(input.reverse ? { reverse: true } : {}),+ ...(input.holdLastFrame ? { holdLastFrame: true } : {}),...(input.transitionIn ? { transitionIn: input.transitionIn } : {}),...(input.transitionOut ? { transitionOut: input.transitionOut } : {}),...(input.glitches?.length ? { glitches: input.glitches } : {}),@@ -614,6 +615,7 @@ export function replaceScenes(project, sceneInputs) {...(prior.speedFps ? { speedFps: prior.speedFps } : {}),...(prior.offsetFrames ? { offsetFrames: prior.offsetFrames } : {}),...(prior.reverse ? { reverse: true } : {}),+ ...(prior.holdLastFrame ? { holdLastFrame: true } : {}),...(prior.transitionIn ? { transitionIn: prior.transitionIn } : {}),...(prior.transitionOut ? { transitionOut: prior.transitionOut } : {}),...(prior.glitches?.length ? { glitches: prior.glitches } : {}),@@ -633,7 +635,7 @@ export function replaceScenes(project, sceneInputs) {// takes, and whether it plays as a clip or its still with an image effect) without// 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', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect',+ 'referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit', 'speedFps', 'offsetFrames', 'reverse', 'holdLastFrame', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect','visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds'];/**diff --git a/server/services/musicVideo/render.js b/server/services/musicVideo/render.jsindex 80dbf7e7c3..6aafd1f157 100644--- a/server/services/musicVideo/render.js+++ b/server/services/musicVideo/render.js@@ -1,7 +1,7 @@import { maintenance } from '../../lib/maintenanceAdmission.js';import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';import { assertMusicVideoMediaSelections } from '../../lib/musicVideoMediaPolicy.js';-import { assertProductionApproval, productionReviewBasis } from './productionReview.js';+import { assertProductionApproval, clipLocks, nameShots, productionReviewBasis } from './productionReview.js';import { musicVideoGradeFilter } from '../../lib/musicVideoGrade.js';/*** Music Video — render pipeline (#1760, Phase 2).@@ -132,17 +132,17 @@ const cutEffectOf = (scene, planned) => {// final frame (tpad) rather than repeating footage. Longer shortfalls block the// render until the director resolves them.const COVERAGE_TOLERANCE_SEC = 0.25;-const COVERAGE_RESOLUTIONS = Object.freeze(['trim', 'continue', 'replace', 'loop']);+const COVERAGE_RESOLUTIONS = Object.freeze(['hold', 'trim', 'continue', 'replace', 'loop']);/*** Pure: the snapped clips whose authored span needs more footage than their- * non-looping source clip provides. Returns+ * non-looping source clip provides (one set to hold its last frame is covered). Returns* `[{ sceneId, spanSec, clipSec, shortBySec }]` (empty when every shot is covered).*/function findCoverageShortfalls(clips, { toleranceSec = COVERAGE_TOLERANCE_SEC } = {}) {const out = [];for (const clip of Array.isArray(clips) ? clips : []) {- if (clip.layer || clip.loop !== false) continue;+ if (clip.layer || clip.loop !== false || clip.holdLastFrame) continue;const spanSec = clip.outSec - clip.inSec;const clipSec = clip.sourceSec ?? clip.duration;if (spanSec - clipSec > toleranceSec) {@@ -239,6 +239,7 @@ export async function resolveSceneClips(project, { layered = false, stillForMissconst history = scenes.some((s) => sceneVisualLayer(s, { layered }) === 'footage') ? await loadHistory() : [];const historyMap = new Map((Array.isArray(history) ? history : []).map((h) => [h.id, h]));const missing = [];+ const missingShots = [];const missingStills = [];const untimed = [];const clips = [];@@ -274,18 +275,18 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss}const entry = historyMap.get(scene.videoHistoryId);const videoPath = entry && entry.filename ? safeUnder(PATHS.videos, entry.filename) : null;- if (!entry || !videoPath || !existsSync(videoPath)) { missing.push(scene.videoHistoryId); continue; }+ if (!entry || !videoPath || !existsSync(videoPath)) { missing.push(scene.videoHistoryId); missingShots.push(scene.sceneId); continue; }// Hosted renders (Grok/fal/reactor) record no frame count or dimensions;// measure the file itself rather than reject a clip that exists (#8977).const measured = entry.numFrames && entry.fps && entry.width && entry.height? entry: { ...entry, ...(await probeVideoGeometry(videoPath)) };const duration = measured.numFrames && measured.fps ? measured.numFrames / measured.fps : null;- if (!duration || duration <= 0) { missing.push(scene.videoHistoryId); continue; }+ if (!duration || duration <= 0) { missing.push(scene.videoHistoryId); missingShots.push(scene.sceneId); continue; }// A dimensionless history entry would make buildMusicVideoFfmpegArgs emit// `scale=undefined:undefined` (opaque ffmpeg failure); treat it as a missing// clip so the caller gets the clean MISSING_CLIPS 4xx, matching the duration guard.- if (!measured.width || measured.width <= 0 || !measured.height || measured.height <= 0) { missing.push(scene.videoHistoryId); continue; }+ if (!measured.width || measured.width <= 0 || !measured.height || measured.height <= 0) { missing.push(scene.videoHistoryId); missingShots.push(scene.sceneId); continue; }const edit = performanceEdit(scene);const sourceInSec = edit ? Math.min(edit.inSec, duration) : 0;const sourceOutSec = edit ? Math.min(edit.outSec, duration) : duration;@@ -316,6 +317,8 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss// A reversed clip is read once, backwards, and holds its last frame rather than looping.loop: edit || clipReversed(scene) ? false : sceneLoops(scene),...(clipReversed(scene) ? { reverse: true } : {}),+ // The director chose to hold the last frame over a shot longer than its clip.+ ...(scene.holdLastFrame === true ? { holdLastFrame: true } : {}),...(rate !== 1 ? { rate } : {}),...(leadSec > 0 ? { leadSec } : {}),inSec: playbackInSec,@@ -328,17 +331,18 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss});}if (missing.length > 0) {- throw new ServerError(`Missing source clips for ${missing.length} scene(s)`, {+ const one = missing.length === 1;+ throw new ServerError(`${nameShots(project, missingShots)}: the selected clip file ${one ? 'is' : 'are'} missing or unreadable. Pick another take or render a new one`, {status: 404, code: 'MISSING_CLIPS', context: { missingClipIds: missing },});}if (missingStills.length > 0) {- throw new ServerError(`${missingStills.length} still section(s) have no reference frame — generate or pick one first`, {+ throw new ServerError(`${nameShots(project, missingStills)}: no still frame to show. Generate or pick one first`, {status: 404, code: 'MISSING_STILLS', context: { sceneIds: missingStills },});}if (untimed.length > 0) {- throw new ServerError(`${untimed.length} still or card section(s) need a start and end time`, {+ throw new ServerError(`${nameShots(project, untimed)}: give ${untimed.length === 1 ? 'this still or card' : 'these stills or cards'} a start and end time`, {status: 422, code: 'UNTIMED_SECTIONS', context: { sceneIds: untimed },});}@@ -742,10 +746,20 @@ export function excerptBoundaryTimes(sections, cues, startSec, endSec, { fps = 2// every scene's clip, and refuse a render whose shots don't cover their// authored span. Both callers build on the exact same resolved clip list, so// an excerpt frame matches what a full render would produce at that song time.+//+// A shot whose clip is locked renders as locked: the director approved that+// clip as it is, so frames changed after it was made no longer block.+// Any other stale clip blocks, naming its shots (numbered in song order) and the fix.export function assertCurrentClipDependencies(project) {+ const locks = clipLocks(project);const stale = (project.scenes || []).filter((scene) => scene.videoHistoryId && scene.visualLayer !== 'still' && !isSelfDrawnLayer(scene.visualLayer))+ .filter((scene) => locks?.[scene.sceneId] !== 'locked').filter((scene) => musicVideoTakeChanges(project, scene, (scene.takes || []).find((take) => take.kind === 'video' && take.assetId === scene.videoHistoryId)).length);- if (stale.length) throw new ServerError('Selected clips were derived from changed plates — preview and repair their dependencies before rendering',+ if (!stale.length) return;+ const shots = nameShots(project, stale.map((scene) => scene.sceneId));+ // A document storyboard has no clip locks, so a new render is its only fix.+ const fix = locks ? 'Lock the clip to keep it as it is, or render a new one' : 'Render a new one';+ throw new ServerError(`${shots}: the clip was made from frames that have since changed. ${fix}`,{ status: 422, code: 'STALE_CLIP_DEPENDENCIES', context: { sceneIds: stale.map((scene) => scene.sceneId) } });}@@ -769,11 +783,11 @@ export async function planMusicVideoRender(project, { draft = false } = {}) {const snapped = beatSnapClips(rawClips, beats, { scenes: project.scenes });// #8964: a new (non-looping) shot must never silently repeat footage to// fill its span. Refuse the render and name the shots that need a trim,- // a continuation, a replacement clip, or an explicit loop.+ // a continuation, a replacement clip, an explicit loop, or a held last frame.const shortfalls = findCoverageShortfalls(snapped);if (shortfalls.length > 0) {throw new ServerError(- `${shortfalls.length} shot${shortfalls.length === 1 ? ' is' : 's are'} longer than ${shortfalls.length === 1 ? 'its' : 'their'} source clip — trim, continue, replace, or loop ${shortfalls.length === 1 ? 'it' : 'them'} before rendering`,+ `${nameShots(project, shortfalls.map((entry) => ({ sceneId: entry.sceneId, note: `${entry.shortBySec}s short` })))}: longer than ${shortfalls.length === 1 ? 'its' : 'their'} clip. Hold the last frame, trim, continue, replace, or loop ${shortfalls.length === 1 ? 'it' : 'them'} before rendering`,{ status: 422, code: 'INSUFFICIENT_CLIP_COVERAGE', context: { shortfalls, resolutions: COVERAGE_RESOLUTIONS } },);}diff --git a/server/services/musicVideo/render.terminal.test.js b/server/services/musicVideo/render.terminal.test.jsindex 9d91fd6457..982fad4eba 100644--- a/server/services/musicVideo/render.terminal.test.js+++ b/server/services/musicVideo/render.terminal.test.js@@ -444,9 +444,10 @@ describe('renderMusicVideo clip coverage (#8964)', () => {const expected = {status: 422,code: 'INSUFFICIENT_CLIP_COVERAGE',+ message: 'Shot 1 (18s short): longer than its clip. Hold the last frame, trim, continue, replace, or loop it before rendering',context: {shortfalls: [{ sceneId: 's1', spanSec: 20, clipSec: 2, shortBySec: 18 }],- resolutions: ['trim', 'continue', 'replace', 'loop'],+ resolutions: ['hold', 'trim', 'continue', 'replace', 'loop'],},};await expect(renderMusicVideo('short-1')).rejects.toMatchObject(expected);@@ -464,6 +465,15 @@ describe('renderMusicVideo clip coverage (#8964)', () => {expect(filterGraph(args)).toContain('tpad=stop_mode=clone:stop_duration=0.2,trim=start=0:end=2.2');});+ // Uniquely catches the director's held last frame still blocking, or repeating footage.+ it('holds the last frame over a shot the director set to hold, however long the gap', async () => {+ primeScene('hold-1', { startSec: 0, endSec: 20, loop: false, holdLastFrame: true });+ await renderMusicVideo('hold-1');+ const { args } = lastProc();+ expect(args).not.toContain('-stream_loop');+ expect(filterGraph(args)).toContain('tpad=stop_mode=clone:stop_duration=18,trim=start=0:end=20');+ });+it('repeats a shot the director explicitly set to loop', async () => {primeScene('loop-1', { startSec: 0, endSec: 20, loop: true });await renderMusicVideo('loop-1');diff --git a/server/services/musicVideo/render.test.js b/server/services/musicVideo/render.test.jsindex 324c0a6ec8..5aec1ffe69 100644--- a/server/services/musicVideo/render.test.js+++ b/server/services/musicVideo/render.test.js@@ -26,7 +26,9 @@ import {resolveSceneClips,resolveMasterAudioPath,renderMusicVideo,+ assertCurrentClipDependencies,} from './render.js';+import { setShotLocks } from './productionReview.js';import { findFfmpeg, probeVideoGeometry } from '../../lib/ffmpeg.js';import { loadHistory } from '../videoGen/local.js';import { getTrack } from '../tracks/index.js';@@ -530,3 +532,18 @@ describe('partial-board production pilot rendering (#9351)', () => {expect(project.scenes[0].videoHistoryId).toBeUndefined();});});++describe('clips made from frames that changed since', () => {+ // Uniquely catches a locked clip still blocking the render, or the refusal not naming its shots.+ it('names the shots in song order, and lets a locked clip render as it is', () => {+ const shot = (sceneId, startSec) => ({ sceneId, startSec, endSec: startSec + 2, prompt: 'a lighthouse', referenceImageId: `${sceneId}-new.png`, videoHistoryId: `${sceneId}-clip`,+ takes: [{ takeId: `${sceneId}-t`, kind: 'video', assetId: `${sceneId}-clip`, sourceImageId: `${sceneId}-old.png`, status: 'selected' }] });+ const project = { id: 'mv-1', scenes: [shot('late', 6), shot('early', 0), shot('fine', 3)] };+ project.scenes[2].takes[0].sourceImageId = 'fine-new.png';+ expect(() => assertCurrentClipDependencies(project)).toThrow('Shots 1, 3: the clip was made from frames that have since changed. Lock the clip to keep it as it is, or render a new one');++ const stillLocked = setShotLocks(project, { sceneIds: ['late'], locked: true });+ const clipLocked = setShotLocks(stillLocked, { sceneIds: ['late'], locked: true, stage: 'video' });+ expect(() => assertCurrentClipDependencies(clipLocked)).toThrow(/^Shot 1: /);+ });+});