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: fixable lyric anchors, an obvious take in use, Reject unused, and Reverse (#11404)

[._.]/0267a4fd7f22
diff --git a/client/src/components/musicVideo/SceneCard.jsx b/client/src/components/musicVideo/SceneCard.jsx
index d5844441fe..2d1a833094 100644
--- a/client/src/components/musicVideo/SceneCard.jsx
+++ b/client/src/components/musicVideo/SceneCard.jsx
@@ -3,6 +3,7 @@ import ShotActionInspector from './ShotActionInspector.jsx';
import SceneCameraControls from './SceneCameraControls.jsx';
import SceneStartFrame from './SceneStartFrame.jsx';
import SceneClipTiming from './SceneClipTiming.jsx';
+import SceneRejectUnused from './SceneRejectUnused.jsx';
import { MUSIC_VIDEO_MEDIUM_LABELS } from '../../../../server/lib/musicVideoMediumPlan.js';
import { useEffect, useRef, useState } from 'react';
import { Trash2, Activity, ArrowUp, ArrowDown, ChevronRight, Video, Maximize2, AlertTriangle, Clapperboard, Shuffle } from 'lucide-react';
@@ -16,7 +17,7 @@ import { isPerformanceScene, planPerformanceRepair } from '../../lib/musicVideoS
import SceneTakeStrip from './SceneTakeStrip.jsx';
import { sceneEndFramePlanFor } from './SceneEndFrame.jsx';
import SceneFrames from './SceneFrames.jsx';
-import { MUSIC_VIDEO_LYRIC_ROLES, MUSIC_VIDEO_TEXT_ZONES, MUSIC_VIDEO_VISUAL_LAYERS, clipOffsetSec, clipSpeedRate, sceneHasAuthoredSpan } from '../../lib/musicVideoLayers.js';
+import { MUSIC_VIDEO_LYRIC_ROLES, MUSIC_VIDEO_TEXT_ZONES, MUSIC_VIDEO_VISUAL_LAYERS, clipOffsetSec, clipReversed, clipSpeedRate, sceneHasAuthoredSpan } from '../../lib/musicVideoLayers.js';
// #8985: what a composed render shows for this scene's span.
const LAYER_LABELS = { footage: 'Footage', still: 'Still image', card: 'Title card', code: 'Code-drawn' };
@@ -114,7 +115,7 @@ export default function SceneCard({
settingsSaving, videoBlockedReason, videoBlockedReasonFor = null, canContinueShot,
onMove, onDelete, onEditLocal, onSave,
project = null, onGenerateFrame, onGenerateVideo, onContinueVideo, onGenerateEndFrame, generatingEndFrame = false, onContinueFromPrevious, previousHasClip = false,
- onOpenPreview, onSelectTake, onReviewTake, onImportTake, onImportClipTake, onPlacePoolItem, onTrimClip, projectId = null, aspect = '16:9', videoModels = [], defaultVideoModel = '', shotNumbers = undefined, takeBusy = false, layered = false, documentComposition = false,
+ onOpenPreview, onSelectTake, onReviewTake, onRejectUnusedTakes = null, onImportTake, onImportClipTake, onPlacePoolItem, onTrimClip, projectId = null, aspect = '16:9', videoModels = [], defaultVideoModel = '', shotNumbers = undefined, takeBusy = false, layered = false, documentComposition = false,
lipSyncBackend = '', songDurationSec = null, onSplit, onMergeNext, onMoveStart = null, nextEndSec = null, falVideoSettings = null, onSeek, performanceReview = null, onRepairPerformance, repairBusy = false,
expanded, onToggleExpand, footageOptional = false, failedScenes = null, songReview = null,
}) {
@@ -149,7 +150,8 @@ export default function SceneCard({
const clipSec = clipMeta && clipMeta.id === scene.videoHistoryId ? clipMeta.sec : null;
const clipSize = clipMeta && clipMeta.id === scene.videoHistoryId && clipMeta.width > 0 ? { width: clipMeta.width, height: clipMeta.height } : null;
// Pre-#8964 scenes have no `loop` key and keep the legacy loop-to-fill render.
- const loops = scene.loop !== false;
+ // A reversed clip is read once, backwards, so it holds rather than loops.
+ const loops = scene.loop !== false && !clipReversed(scene);
const spanSec = scene.beatAligned && typeof scene.startSec === 'number' && typeof scene.endSec === 'number'
? scene.endSec - scene.startSec
: null;
@@ -287,7 +289,7 @@ export default function SceneCard({
Beat-aligned
</label>
<label className="flex items-center gap-1 min-h-[44px] sm:min-h-0" title="Repeat the generated clip to fill a span longer than the clip. Off: the shot must be covered by its clip (trim, continue, or replace it).">
- <input type="checkbox" checked={loops} disabled={performance} onChange={(e) => applyPatch({ loop: e.target.checked })} />
+ <input type="checkbox" checked={loops} disabled={performance || clipReversed(scene)} onChange={(e) => applyPatch({ loop: e.target.checked })} />
Loop clip
</label>
</div>
@@ -462,8 +464,10 @@ export default function SceneCard({
</span>
<button type="button" onClick={() => applyPatch({ endSec: Math.round((scene.startSec + playedSec) * 1000) / 1000 })}
className="rounded bg-port-bg border border-port-border px-2 py-1 min-h-[44px] sm:min-h-0 text-port-text">Trim to clip</button>
- <button type="button" onClick={() => applyPatch({ loop: true })}
- className="rounded bg-port-bg border border-port-border px-2 py-1 min-h-[44px] sm:min-h-0 text-port-text">Loop clip</button>
+ {!clipReversed(scene) && (
+ <button type="button" onClick={() => applyPatch({ loop: true })}
+ className="rounded bg-port-bg border border-port-border px-2 py-1 min-h-[44px] sm:min-h-0 text-port-text">Loop clip</button>
+ )}
</div>
)}
{layer !== 'footage' && layered && !sceneHasAuthoredSpan(scene) && (
@@ -477,6 +481,9 @@ export default function SceneCard({
{!documentComposition && ' A composed render shows it as a black frame under the typography; render from a composition document to draw it.'}
</p>
) : (
+ <>
+ {/* Finalize the shot: only the frames and clip in use stay candidates. */}
+ <SceneRejectUnused scene={scene} busy={takeBusy} onReject={onRejectUnusedTakes} />
<div className="grid gap-3 @3xl:grid-cols-2">
{/* Frames: the still this shot starts from and, optionally, the one it ends on (#11173),
each with its prompt and Render under it, then the tapped frame's takes. */}
@@ -521,6 +528,10 @@ export default function SceneCard({
if (Number.isFinite(sec) && sec > 0) setClipMeta({ id: scene.videoHistoryId, sec, width, height });
}}
/>
+ {/* This thumbnail plays the file as is; the player and the render play it backwards. */}
+ {clipReversed(scene) && (
+ <span className="port-media-overlay pointer-events-none absolute left-1 top-1 rounded px-1.5 py-0.5 text-[10px]">Reversed in the player</span>
+ )}
{/* Corner expand — do not put the open handler on <video> itself;
that would fight native play/pause controls. Pause first so the
lightbox's unmuted autoplay doesn't double-play the audio. */}
@@ -627,6 +638,7 @@ export default function SceneCard({
{shotSettings}
</section>
</div>
+ </>
)}
{codeShot && shotSettings}
{(scene.visualIntent || scene.direction || scene.direction?.actionContract) && (
diff --git a/client/src/components/musicVideo/SceneCard.test.jsx b/client/src/components/musicVideo/SceneCard.test.jsx
index 0c0758e199..62bc449864 100644
--- a/client/src/components/musicVideo/SceneCard.test.jsx
+++ b/client/src/components/musicVideo/SceneCard.test.jsx
@@ -647,3 +647,49 @@ describe('Beat toggle into the next shot', () => {
expect(screen.getByLabelText('Beat toggle speed').value).toBe('half');
});
});
+
+describe('finalizing a shot\'s takes', () => {
+ const take = (takeId, kind, assetId, status = 'candidate') => ({ takeId, kind, assetId, status, source: 'generated', note: null });
+ const scene = { sceneId: 's1', referenceImageId: 'a.png', videoHistoryId: 'v1', startSec: 0, endSec: 4,
+ takes: [take('t1', 'image', 'a.png'), take('t2', 'image', 'b.png'), take('t3', 'video', 'v1'), take('t4', 'video', 'v2'), take('t5', 'video', 'v3', 'rejected')] };
+
+ // Uniquely catches the take in use reading like any other, and Reject unused firing without its confirm.
+ it('badges the take in use, and rejects the unused ones after one confirm', () => {
+ const onRejectUnusedTakes = vi.fn();
+ render(<SceneCard scene={scene} index={0} expanded onEditLocal={() => {}} onSave={() => {}} onRejectUnusedTakes={onRejectUnusedTakes} />);
+ expect(screen.getAllByText('In use').length).toBeGreaterThanOrEqual(2);
+ fireEvent.click(screen.getByRole('button', { name: 'Reject unused (2)' }));
+ expect(onRejectUnusedTakes).not.toHaveBeenCalled();
+ expect(screen.getByText('Reject 2 unused takes? The files stay.')).toBeTruthy();
+ fireEvent.click(screen.getByRole('button', { name: 'Reject 2' }));
+ expect(onRejectUnusedTakes).toHaveBeenCalledWith(scene);
+ expect(screen.queryByRole('button', { name: 'Reject 2' })).toBeNull();
+ });
+
+ it('offers nothing when every take is in use or rejected', () => {
+ render(<SceneCard scene={{ ...scene, takes: scene.takes.filter((t) => ['t1', 't3', 't5'].includes(t.takeId)) }} index={0} expanded
+ onEditLocal={() => {}} onSave={() => {}} onRejectUnusedTakes={vi.fn()} />);
+ expect(screen.queryByRole('button', { name: /Reject unused/ })).toBeNull();
+ });
+});
+
+describe('reverse a shot\'s clip', () => {
+ // Uniquely catches Reverse saving the wrong shape, staying on a lip-sync shot, or leaving Loop clip on.
+ it('saves Reverse as a shot setting, turns off looping, and is not offered on a lip-sync shot', () => {
+ const onSave = vi.fn();
+ function Harness({ initial }) {
+ const [scene, setScene] = useState(initial);
+ return <SceneCard scene={scene} index={0} expanded onEditLocal={(_id, patch) => setScene((current) => ({ ...current, ...patch }))} onSave={onSave} />;
+ }
+ const { unmount } = render(<Harness initial={{ sceneId: 's1', videoHistoryId: 'clip-1', startSec: 0, endSec: 4, takes: [] }} />);
+ fireEvent.click(screen.getByLabelText(/^Reverse/));
+ expect(onSave).toHaveBeenLastCalledWith('s1', { reverse: true });
+ expect(screen.getByText('Reversed in the player')).toBeTruthy();
+ expect(screen.getByLabelText('Loop clip').disabled).toBe(true);
+ fireEvent.click(screen.getByLabelText(/^Reverse/));
+ expect(onSave).toHaveBeenLastCalledWith('s1', { reverse: null });
+ unmount();
+ render(<Harness initial={{ sceneId: 's2', videoHistoryId: 'clip-1', shotMode: 'performance', startSec: 0, endSec: 4, takes: [] }} />);
+ expect(screen.queryByLabelText(/^Reverse/)).toBeNull();
+ });
+});
diff --git a/client/src/components/musicVideo/SceneClipTiming.jsx b/client/src/components/musicVideo/SceneClipTiming.jsx
index 79da21c79b..75b8813a38 100644
--- a/client/src/components/musicVideo/SceneClipTiming.jsx
+++ b/client/src/components/musicVideo/SceneClipTiming.jsx
@@ -1,6 +1,6 @@
import { useState } from 'react';
import { Minus, Plus } from 'lucide-react';
-import { CLIP_OFFSET_FRAMES_RANGE, CLIP_SPEED_FPS_RANGE, CLIP_TIMING_FPS, clipSpeedRate } from '../../lib/musicVideoLayers.js';
+import { CLIP_OFFSET_FRAMES_RANGE, CLIP_SPEED_FPS_RANGE, CLIP_TIMING_FPS, clipReversed, clipSpeedRate } from '../../lib/musicVideoLayers.js';
const STEP = 'flex items-center justify-center rounded bg-port-bg border border-port-border hover:bg-port-border/40 disabled:opacity-50 min-h-[44px] min-w-[44px] sm:min-h-[28px] sm:min-w-[28px]';
const plural = (n) => `${n} frame${n === 1 ? '' : 's'}`;
@@ -36,8 +36,8 @@ 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, and Offset in frames against the song.
- * `onChange(patch)` saves `{ speedFps }` or `{ offsetFrames }` (0 clears it).
+ * second over the 24 fps grid, Offset in frames against the song, and Reverse.
+ * `onChange(patch)` saves `{ speedFps }`, `{ offsetFrames }` (0 clears it) or `{ reverse }`.
*/
export default function SceneClipTiming({ fieldId, scene, disabled = false, disabledReason = null, onChange }) {
const speed = Number.isInteger(scene.speedFps) ? scene.speedFps : 0;
@@ -55,6 +55,14 @@ export default function SceneClipTiming({ fieldId, scene, disabled = false, disa
less="Start the clip one frame later" more="Start the clip one frame further in"
onSet={(next) => onChange({ offsetFrames: next || null })}
readout={offsetText} />
+ {/* A lip-sync performance never reverses: its mouth follows the song. */}
+ {scene.shotMode !== 'performance' && (
+ <label htmlFor={fieldId('reverse')} className="flex min-h-[44px] items-center gap-2 text-xs sm:min-h-0">
+ <input id={fieldId('reverse')} type="checkbox" checked={clipReversed(scene)} disabled={disabled}
+ onChange={(e) => onChange({ reverse: e.target.checked || null })} />
+ Reverse <span className="text-port-text-muted">plays backwards, no loop</span>
+ </label>
+ )}
</div>
);
}
diff --git a/client/src/components/musicVideo/SceneRejectUnused.jsx b/client/src/components/musicVideo/SceneRejectUnused.jsx
new file mode 100644
index 0000000000..17db462518
--- /dev/null
+++ b/client/src/components/musicVideo/SceneRejectUnused.jsx
@@ -0,0 +1,39 @@
+import { useState } from 'react';
+import { X } from 'lucide-react';
+import { TAKE_SLOT } from '../../lib/musicVideoTakes.js';
+
+const BTN = 'inline-flex min-h-[44px] items-center gap-1 rounded px-2 py-1 text-xs disabled:opacity-50 sm:min-h-0';
+
+/** How many of a shot's takes are neither its selected frame, end frame nor clip, nor already rejected. */
+export const unusedTakeCount = (scene) => (Array.isArray(scene?.takes) ? scene.takes : [])
+ .filter((take) => take?.takeId && TAKE_SLOT[take.kind] && take.status !== 'rejected' && scene[TAKE_SLOT[take.kind]] !== take.assetId).length;
+
+/**
+ * Finalize a shot's takes: one tap, then a confirm, rejects every take that is
+ * not in use. The files stay and Use or Restore brings any back.
+ */
+export default function SceneRejectUnused({ scene, busy = false, onReject }) {
+ const [confirming, setConfirming] = useState(false);
+ const count = unusedTakeCount(scene);
+ if (!count || !onReject) return null;
+ const takes = `${count} unused take${count === 1 ? '' : 's'}`;
+ return (
+ <div className="flex flex-wrap items-center gap-2 text-xs">
+ {confirming ? (
+ <>
+ <span className="text-port-text-muted">Reject {takes}? The files stay.</span>
+ <button type="button" disabled={busy} onClick={() => { setConfirming(false); onReject(scene); }}
+ className={`${BTN} bg-port-error/20 text-port-error`}>
+ <X size={12} aria-hidden="true" /> Reject {count}
+ </button>
+ <button type="button" onClick={() => setConfirming(false)} className={`${BTN} border border-port-border`}>Cancel</button>
+ </>
+ ) : (
+ <button type="button" disabled={busy} onClick={() => setConfirming(true)}
+ className={`${BTN} border border-port-border`} title="Keep only the frames and clip in use">
+ <X size={12} aria-hidden="true" /> Reject unused ({count})
+ </button>
+ )}
+ </div>
+ );
+}
diff --git a/client/src/components/musicVideo/SceneTakeStrip.jsx b/client/src/components/musicVideo/SceneTakeStrip.jsx
index aef929b63b..71e2534b56 100644
--- a/client/src/components/musicVideo/SceneTakeStrip.jsx
+++ b/client/src/components/musicVideo/SceneTakeStrip.jsx
@@ -58,14 +58,20 @@ export default function SceneTakeStrip({
onFocus={() => setPlayingId(playKey)}
onBlur={() => setPlayingId(null)}
aria-label={`View ${kind === 'video' ? 'clip' : 'frame'} take full size`}
- className={`relative block w-full rounded overflow-hidden border focus:outline-none focus:ring-2 focus:ring-port-accent ${isSelected ? 'border-port-accent ring-2 ring-port-accent' : 'border-port-border'} ${rejected ? 'opacity-40' : ''}`}
+ className={`relative block w-full rounded overflow-hidden focus:outline-none focus:ring-2 focus:ring-port-accent ${isSelected ? 'border-2 border-port-accent ring-4 ring-port-accent/50' : 'border border-port-border'} ${rejected ? 'opacity-40' : ''}`}
>
<img src={takeThumbUrl(take)} alt="" loading="lazy" className="w-full aspect-video object-cover block bg-black" />
{playing && <video src={takeClipUrl(take)} autoPlay muted loop playsInline className="absolute inset-0 w-full h-full object-cover bg-black" />}
+ {/* The take the render uses wears a badge, so it reads at a glance among the others. */}
+ {isSelected && (
+ <span className="absolute left-1 top-1 inline-flex items-center gap-0.5 rounded bg-port-accent px-1.5 py-0.5 text-[10px] font-semibold text-white shadow">
+ <Check size={11} aria-hidden="true" /> In use
+ </span>
+ )}
</button>
<div className="text-[10px] text-port-text-muted truncate" title={take.originalName || take.prompt || takeProvenance(take)}>
{verdict && <span className={`mr-1 rounded px-1 ${VERDICT_TONE[verdict.tone]}`} title="Plate preflight verdict">{verdict.label}</span>}
- {isSelected ? <span className="text-port-accent">Selected · </span> : null}
+ {isSelected ? <span className="font-semibold text-port-accent">In use · </span> : null}
{rejected ? 'rejected · ' : ''}{takeProvenance(take)}
</div>
{take.note && noteFor !== take.takeId && (
diff --git a/client/src/components/musicVideo/StageChecklist.jsx b/client/src/components/musicVideo/StageChecklist.jsx
index 6f79476f39..925e720faa 100644
--- a/client/src/components/musicVideo/StageChecklist.jsx
+++ b/client/src/components/musicVideo/StageChecklist.jsx
@@ -12,7 +12,8 @@ import StaleApprovalActions from './StaleApprovalActions.jsx';
* (folded behind "See N changes" when there are several).
* An `optional` item is listed but never counted toward the step being done.
* An item's `notes` (open change requests) each get a Mark resolved button,
- * which calls `onAction({ run: 'resolve-feedback', feedbackId })`.
+ * which calls `onAction({ run: 'resolve-feedback', feedbackId })`. An item's `shots`
+ * each get a button that calls `onAction({ editShot: sceneId })`.
*/
export default function StageChecklist({ items, onAction, onRevert, headerAnchor = null, busy = false }) {
if (!items?.length) return null;
@@ -53,6 +54,22 @@ export default function StageChecklist({ items, onAction, onRevert, headerAnchor
{item.details.map((text) => <li key={text} className="break-words">{text}</li>)}
</ul>
)}
+ {/* Shots the row is about: each opens its card, beside what the row says about it. */}
+ {!item.done && item.shots?.length > 0 && (
+ <ul aria-label={`${item.label} shots`} className="mt-1 space-y-1">
+ {item.shots.map((shot) => (
+ <li key={shot.sceneId} className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-xs">
+ {onAction ? (
+ <button type="button" onClick={() => onAction({ label: shot.label, editShot: shot.sceneId })}
+ className="min-h-[44px] shrink-0 rounded border border-port-border px-2 py-1 text-port-accent sm:min-h-0">
+ {shot.label}
+ </button>
+ ) : <strong className="shrink-0">{shot.label}</strong>}
+ <span className="min-w-0 flex-1 basis-40 break-words text-port-text-muted">{shot.text}</span>
+ </li>
+ ))}
+ </ul>
+ )}
{/* Open change requests: each note names its target and settles with its own button. */}
{!item.done && item.notes?.length > 0 && (
<ul aria-label="Open change requests" className="mt-1 space-y-1">
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.jsx b/client/src/components/musicVideo/StoryboardAnimatic.jsx
index 1df615942c..6c0b6fe838 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.jsx
@@ -16,7 +16,7 @@ import FrameStepper, { captureMediaFrame } from './FrameStepper.jsx';
import { sceneFrameFit } from './SceneFrameFit.jsx';
import TransitionGlitch from './TransitionGlitch.jsx';
import ImageEffectStill from './ImageEffectStill.jsx';
-import { clipOffsetSec, clipSpeedRate, isLayeredComposition } from '../../lib/musicVideoLayers.js';
+import { clipOffsetSec, clipReversed, clipSpeedRate, isLayeredComposition } from '../../lib/musicVideoLayers.js';
import { sceneImageEffect } from '../../lib/musicVideoImageEffects.js';
import { sceneBeatToggles } from '../../lib/musicVideoCutEffects.js';
@@ -173,6 +173,12 @@ export function clipTimeAt(scene, t, clipSec = null) {
const local = Math.max(0, t - (scene.startSec || 0));
const rate = clipSpeedRate(scene);
const start = inSec + clipOffsetSec(scene);
+ if (clipReversed(scene)) {
+ // Backwards from the file's end, as the render reads it once: past its start it holds the first frame shown last.
+ if (!(clipSec > 0)) return 0;
+ const at = Math.max(0, start) + Math.max(0, local + Math.min(0, start)) * rate;
+ return Math.min(clipSec - 0.05, Math.max(0, clipSec - at));
+ }
if (rate !== 1 || start !== inSec) {
const sourceIn = Math.max(0, start);
const at = sourceIn + Math.max(0, local + Math.min(0, start)) * rate;
@@ -213,12 +219,14 @@ function ShotClip({ scene, audioRef, time, current, leadSec = 0 }) {
if (!video || !audio || video.readyState < 1) return;
const duration = Number.isFinite(video.duration) ? video.duration : null;
const target = clipTimeAt(timing, current ? audio.currentTime || 0 : scene.startSec || 0, duration);
- const tolerance = current && audio.paused ? CLIP_PAUSED_DRIFT_SEC : CLIP_DRIFT_SEC;
- if (Math.abs((video.currentTime || 0) - target) > tolerance) video.currentTime = target;
+ // A browser cannot play a clip backwards, so a reversed clip stays paused and is stepped to each frame.
+ const reversed = clipReversed(scene);
+ const tolerance = current && (audio.paused || reversed) ? CLIP_PAUSED_DRIFT_SEC : CLIP_DRIFT_SEC;
+ if (Math.abs((video.currentTime || 0) - target) > tolerance && !(reversed && video.seeking)) video.currentTime = target;
// The shot's hand-set speed; a negative offset's lead holds the first frame.
video.playbackRate = clipSpeedRate(scene);
- const leading = (scene.startSec || 0) - clipOffsetSec(scene) - (selectedPerformanceInstruction(scene)?.edit?.inSec ?? 0) > (audio.currentTime || 0);
- if (!current || audio.paused || leading) video.pause?.();
+ const leading = (timing.startSec || 0) - clipOffsetSec(scene) - (selectedPerformanceInstruction(scene)?.edit?.inSec ?? 0) > (audio.currentTime || 0);
+ if (!current || audio.paused || leading || reversed) video.pause?.();
else if (video.paused) video.play?.()?.catch?.(() => {});
}, [scene, timing, audioRef, current]);
// Shown once a frame is decoded where the clip should be; kept from then on, since a
@@ -228,6 +236,15 @@ function ShotClip({ scene, audioRef, time, current, leadSec = 0 }) {
if (video && video.readyState >= 2 && !video.seeking) setReady(true);
}, []);
useEffect(() => { sync(); }, [time, sync]);
+ // The song's time updates are too coarse to step a reversed clip, so it follows every animation frame.
+ const reversed = clipReversed(scene);
+ useEffect(() => {
+ if (!current || !reversed) return undefined;
+ let handle = 0;
+ const tick = () => { sync(); handle = requestAnimationFrame(tick); };
+ handle = requestAnimationFrame(tick);
+ return () => cancelAnimationFrame(handle);
+ }, [current, reversed, sync]);
useEffect(() => {
const audio = audioRef.current;
if (!audio) return undefined;
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
index aac7d9af9e..4bc0e1b20d 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
@@ -242,6 +242,17 @@ describe('StoryboardAnimatic clips', () => {
expect(clipTimeAt(early, 10.2, 6)).toBe(0);
expect(clipTimeAt(early, 11.25, 6)).toBeCloseTo(1);
});
+
+ // Uniquely catches a reversed shot previewing forwards, or looping where the render holds.
+ it('plays a reversed clip from its end, with its speed and offset, and holds once it runs out', () => {
+ const back = { startSec: 10, reverse: true };
+ expect(clipTimeAt(back, 10, 6)).toBeCloseTo(5.95);
+ expect(clipTimeAt(back, 12, 6)).toBeCloseTo(4);
+ expect(clipTimeAt(back, 20, 6)).toBe(0);
+ expect(clipTimeAt({ ...back, speedFps: 24, offsetFrames: 12 }, 11, 6)).toBeCloseTo(3.5);
+ // A lip-sync performance never reverses.
+ expect(clipTimeAt({ ...back, shotMode: 'performance' }, 12, 6)).toBe(2);
+ });
});
describe('StoryboardAnimatic film look', () => {
diff --git a/client/src/components/musicVideo/stages/BoardStage.jsx b/client/src/components/musicVideo/stages/BoardStage.jsx
index e6c9b05ec1..48310adc0d 100644
--- a/client/src/components/musicVideo/stages/BoardStage.jsx
+++ b/client/src/components/musicVideo/stages/BoardStage.jsx
@@ -229,6 +229,7 @@ export default function BoardStage({ board }) {
takeBusy={takes.busy}
onSelectTake={takes.selectTake}
onReviewTake={takes.reviewTake}
+ onRejectUnusedTakes={takes.rejectUnusedTakes}
onContinueFromPrevious={takes.continueFromPrevious}
// The server's own neighbor rule: the shot before this one by start time.
previousHasClip={Boolean(previousShot(project, scene.sceneId)?.videoHistoryId)}
diff --git a/client/src/hooks/useMusicVideoProductionReview.js b/client/src/hooks/useMusicVideoProductionReview.js
index 6082b20556..c10733adc8 100644
--- a/client/src/hooks/useMusicVideoProductionReview.js
+++ b/client/src/hooks/useMusicVideoProductionReview.js
@@ -1,7 +1,7 @@
import { useEffect, useRef, useState } from 'react';
import { checkMusicVideoOverlayText, reverifyMusicVideoAlignment, importMusicVideoDocumentShots, getMusicVideoProductionReview, saveMusicVideoProductionDraft, prepareMusicVideoProductionReview,
approveMusicVideoProductionReview, lockMusicVideoShots, renderMusicVideoProductionProof, musicVideoExcerptRenderEventsUrl,
- cancelMusicVideoExcerptRender, importMusicVideoProductionPlanning, bindMusicVideoProductionShot, addMusicVideoProductionFeedback, resolveMusicVideoProductionFeedback, reviseMusicVideoProductionFromFeedback, revertMusicVideoProductionInput } from '../services/apiMusicVideo.js';
+ cancelMusicVideoExcerptRender, importMusicVideoProductionPlanning, bindMusicVideoProductionShot, addMusicVideoProductionFeedback, resolveMusicVideoProductionFeedback, syncMusicVideoLyricAnchors, reviseMusicVideoProductionFromFeedback, revertMusicVideoProductionInput } from '../services/apiMusicVideo.js';
import useSseJobSlot from './useSseJobSlot.js';
/**
@@ -63,6 +63,8 @@ export default function useMusicVideoProductionReview({ project, replaceProject
return { readiness, current, readinessError: readiness ? null : readinessError, busy, error, proof: { ...proof, occupied: proof.active, active: proof.active && proof.context === project?.id },
feedback: body => call(() => addMusicVideoProductionFeedback(project.id, { ...body, basis: readiness?.basis[body.stage] }, { silent: true })),
resolveFeedback: (feedbackId, resolution) => call(() => resolveMusicVideoProductionFeedback(project.id, { feedbackId, resolution }, { silent: true })),
+ // Anchor the flagged shots (or `sceneIds`) to the lyric lines sung over them.
+ syncLyricAnchors: sceneIds => call(() => syncMusicVideoLyricAnchors(project.id, sceneIds ? { sceneIds } : {}, { silent: true })),
revise: stage => call(() => reviseMusicVideoProductionFromFeedback(project.id, { stage }, { silent: true })),
revert: (stage, field) => call(() => revertMusicVideoProductionInput(project.id, { stage, field }, { silent: true })),
importDocumentShots: body => call(() => importMusicVideoDocumentShots(project.id, body, { silent: true })),
diff --git a/client/src/hooks/useMusicVideoTakes.js b/client/src/hooks/useMusicVideoTakes.js
index 2491bb9802..9f32fe1a5b 100644
--- a/client/src/hooks/useMusicVideoTakes.js
+++ b/client/src/hooks/useMusicVideoTakes.js
@@ -6,6 +6,7 @@ import {
placeMusicVideoPoolItem,
continueMusicVideoSceneFromPrevious,
reviewMusicVideoSceneTake,
+ rejectUnusedMusicVideoSceneTakes,
getMusicVideoHandoff,
getMusicVideoHandoffBundle,
importMusicVideoHandoff,
@@ -112,6 +113,12 @@ export default function useMusicVideoTakes({ project, applyScenePatch }) {
'Failed to update take',
);
+ // Finalize a shot: every take other than its selected frame, end frame and clip is rejected (files kept).
+ const rejectUnusedTakes = (scene) => runTakeOp(
+ (projectId) => rejectUnusedMusicVideoSceneTakes(projectId, scene.sceneId, { silent: true }).then((res) => res.scene),
+ 'Failed to reject the unused takes',
+ );
+
// A frame picked from (or uploaded into) the gallery for one scene.
const importTake = (scene, item) => runTakeOp(
(projectId) => addMusicVideoSceneTake(projectId, scene.sceneId, {
@@ -185,5 +192,5 @@ export default function useMusicVideoTakes({ project, applyScenePatch }) {
if (failures.length) toast.error(failures.slice(0, 3).join(' · '));
};
- return { busy, selectTake, placePoolItem, trimClipTake, reviewTake, continueFromPrevious, importTake, importClipTake, exportHandoff, exportHandoffBundle, importHandoffFiles };
+ return { busy, selectTake, placePoolItem, trimClipTake, reviewTake, rejectUnusedTakes, continueFromPrevious, importTake, importClipTake, exportHandoff, exportHandoffBundle, importHandoffFiles };
}
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index 13525e984a..9772984877 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -63,7 +63,7 @@ grep -i "what you want to do" client/src/lib/README.md
| `musicVideoFiling.js` | Which music video an Image Gen / Video Gen render is for: `MUSIC_VIDEO_FILING_PARAM` (the `musicVideo` URL param), `musicVideoFilingFields(searchParams)` (the `musicVideoProjectId` request field), `musicVideoOf(item)` (a record's video). Used by `components/media/MusicVideoFilingSelect.jsx`, `hooks/useMediaPreviewActions.js` and the two generate pages. |
| `musicVideoMotion.js` | Re-export of `server/lib/musicVideoMotion.js` (`MOTION_CONTINUITY_CLAUSE`, `AUDIO_REACTIVE_PERFORMANCE_GUARD`, `silentMotionPrompt`) for board motion prompts. |
| `musicVideoBatchPlan.js` | Pure helpers for the Music Video missing-frame / missing-clip batches (#10153): `videoBatchPreview` (count + fal estimate summed from `falSceneTake`, unpriced count), `scenesWaitingForFrame`, `videosButtonLabel`, `batchSummary`, `batchActive`, `batchSceneName`. Used by `components/musicVideo/ProjectActionGroups.jsx`. |
-| `musicVideoLayers.js` | Music-video per-scene visual layers (#8985), re-exported from `server/lib/musicVideoLayers.js`: `MUSIC_VIDEO_VISUAL_LAYERS`, `MUSIC_VIDEO_STILL_MOVES`, `MUSIC_VIDEO_TEXT_ZONES` / `MUSIC_VIDEO_LYRIC_ROLES` (#10583 lyric type per shot), `sceneVisualLayer(scene, { layered })`, `sceneHasAuthoredSpan`, `sceneRenderReady(scene, { layered })`, and a footage shot's hand-set clip speed and offset (`clipSpeedRate`, `clipOffsetSec`). Used by `components/musicVideo/SceneCard.jsx`, `ProjectActionGroups.jsx` and `hooks/useMusicVideoSceneMedia.js`. |
+| `musicVideoLayers.js` | Music-video per-scene visual layers (#8985), re-exported from `server/lib/musicVideoLayers.js`: `MUSIC_VIDEO_VISUAL_LAYERS`, `MUSIC_VIDEO_STILL_MOVES`, `MUSIC_VIDEO_TEXT_ZONES` / `MUSIC_VIDEO_LYRIC_ROLES` (#10583 lyric type per shot), `sceneVisualLayer(scene, { layered })`, `sceneHasAuthoredSpan`, `sceneRenderReady(scene, { layered })`, and a footage shot's hand-set clip speed, offset and reverse (`clipSpeedRate`, `clipOffsetSec`, `clipReversed`). Used by `components/musicVideo/SceneCard.jsx`, `ProjectActionGroups.jsx` and `hooks/useMusicVideoSceneMedia.js`. |
| `musicVideoTakes.js` | Music-video scene takes view helpers (#8965): `sceneTakeList(scene, kind)` lists a scene's image/video takes with an un-materialized pre-takes selection appended as a read-only `legacy` take; `takePreviewKey`, `takeThumbUrl`, `takeClipUrl` (hover-preview clip), `sceneHasPendingDecision` (contact-sheet filter), `takeProvenance`; `TAKE_SLOT` maps a take kind to its selection field. Used by `components/musicVideo/SceneTakeStrip.jsx` and `pages/MusicVideo.jsx`. |
| `musicVideoSceneAttention.js` | Music Video per-scene attention model (#10152): `sceneAttention(scene, ctx)` returns the codes (`missing-frame`, `missing-clip`, `under-covered`, `contract-problem`, `perf-blocked`, `candidates-pending`, `plate-unverified`, `no-span`, `last-failure`) behind the collapsed scene-row chips, the Board `?scenes=attention\|missing\|all` filter (`parseSceneFilter`, `sceneMatchesFilter`) and the Produce per-shot strip; `SCENE_ATTENTION_LABELS`; `sceneMediaKind` (`clip` / `image` / `code` / `card`) and `SCENE_MEDIA_LABELS` for the Board thumbnail badges. Used by `components/musicVideo/SceneCard.jsx`, `stages/BoardStage.jsx` and `stages/ProduceStage.jsx`. |
| `musicVideoCoverOverlay.js` | Cover-art lettering preview (#10345): re-export of `server/lib/musicVideoCoverOverlay.js` (the design vocabulary, `normalizeCoverDesign`, `coverOverlaySvg`) plus `canvasCoverWidths(design, texts, fonts)`, which measures text with a canvas so the live preview wraps and sizes the title the way the server's measured render does. |
diff --git a/client/src/lib/musicVideoLayers.js b/client/src/lib/musicVideoLayers.js
index 34ed86f5ea..96abb21804 100644
--- a/client/src/lib/musicVideoLayers.js
+++ b/client/src/lib/musicVideoLayers.js
@@ -20,4 +20,5 @@ export {
CLIP_OFFSET_FRAMES_RANGE,
clipSpeedRate,
clipOffsetSec,
+ clipReversed,
} from '../../../server/lib/musicVideoLayers.js';
diff --git a/client/src/lib/musicVideoSceneAttention.js b/client/src/lib/musicVideoSceneAttention.js
index 99e35cc9c5..a0626a5898 100644
--- a/client/src/lib/musicVideoSceneAttention.js
+++ b/client/src/lib/musicVideoSceneAttention.js
@@ -9,7 +9,7 @@
import { shotActionContractProblem } from '../../../server/lib/musicVideoActionContract.js';
import { currentPlateEvidence } from '../../../server/lib/musicVideoPlateEvidence.js';
import { isEndFrameImageEffect } from './musicVideoImageEffects.js';
-import { isSelfDrawnLayer, sceneVisualLayer, sceneHasAuthoredSpan } from './musicVideoLayers.js';
+import { clipReversed, isSelfDrawnLayer, sceneVisualLayer, sceneHasAuthoredSpan } from './musicVideoLayers.js';
import { performanceBlockedReason, performanceCapability, planPerformanceWindow, isPerformanceScene } from './musicVideoShotTiming.js';
import { sceneHasPendingDecision, sceneTakeList } from './musicVideoTakes.js';
@@ -82,7 +82,7 @@ export function sceneAttention(scene, ctx = {}) {
if (!isSelfDrawnLayer(layer) && !scene.referenceImageId && !codeRendered) codes.push('missing-frame');
if (layer === 'footage' && !footageOptional && !scene.videoHistoryId) codes.push('missing-clip');
if (layer !== 'footage' && !sceneHasAuthoredSpan(scene)) codes.push('no-span');
- if (layer === 'footage' && scene.loop === false && scene.beatAligned && clipSec != null
+ if (layer === 'footage' && (scene.loop === false || clipReversed(scene)) && scene.beatAligned && clipSec != null
&& typeof scene.startSec === 'number' && typeof scene.endSec === 'number'
&& scene.endSec - scene.startSec - clipSec > COVERAGE_TOLERANCE_SEC) codes.push('under-covered');
const contract = scene.direction?.actionContract;
diff --git a/client/src/lib/musicVideoStages.js b/client/src/lib/musicVideoStages.js
index e9d00b89f9..dc159df14a 100644
--- a/client/src/lib/musicVideoStages.js
+++ b/client/src/lib/musicVideoStages.js
@@ -773,14 +773,40 @@ const STORYBOARD_PROBLEM_GROUPS = [
];
/** One open checklist item per group of storyboard readiness problems, per-shot problems counted rather than listed. */
-function storyboardProblemItems(readiness) {
- const problems = summarizeStoryboardProblems(readiness?.storyboard?.problems?.filter(notFeedback));
- if (readiness?.storyboard?.approved || !problems.length) return [];
- return STORYBOARD_PROBLEM_GROUPS.flatMap((group, index) => {
+function storyboardProblemItems(readiness, scenes = []) {
+ // Shots whose lyric anchors differ from the singing get a row of their own that names each shot.
+ const anchors = lyricAnchorItem(readiness, scenes);
+ const problems = summarizeStoryboardProblems(readiness?.storyboard?.problems?.filter(notFeedback)
+ .filter((text) => !anchors || !ANCHOR_PROBLEM.test(text)));
+ if (readiness?.storyboard?.approved || (!problems.length && !anchors)) return [];
+ return [...STORYBOARD_PROBLEM_GROUPS.flatMap((group, index) => {
const earlier = STORYBOARD_PROBLEM_GROUPS.slice(0, index);
const mine = problems.filter((text) => group.test.test(text) && !earlier.some((g) => g.test.test(text)));
return mine.length ? [{ id: `board-${group.id}`, label: group.label, done: false, details: mine, action: group.action }] : [];
- });
+ }), ...(anchors ? [anchors] : [])];
+}
+
+const ANCHOR_PROBLEM = /^Review lyric anchors for /;
+const quoted = (lines) => (lines.length ? lines.map((line) => `“${line}”`).join(' / ') : 'nothing');
+
+/**
+ * The Lyric anchors row: each flagged shot by number (a button to its card),
+ * what is sung over it and what it is anchored to, and one button that anchors
+ * them all to the singing.
+ */
+function lyricAnchorItem(readiness, scenes) {
+ const flagged = readiness?.storyboard?.lyricAnchors;
+ if (!flagged?.length || readiness?.storyboard?.approved) return null;
+ const number = (sceneId) => scenes.findIndex((scene) => scene.sceneId === sceneId) + 1;
+ return {
+ id: 'board-anchors', label: 'Lyric anchors', done: false,
+ detail: 'These shots are anchored to lyrics other than the ones sung over them.',
+ shots: flagged.map(({ sceneId, sung, anchored }) => ({
+ sceneId, label: number(sceneId) > 0 ? `Shot ${number(sceneId)}` : 'Shot',
+ text: `Sung: ${quoted(sung)} · anchored: ${quoted(anchored)}`,
+ })),
+ action: { label: 'Anchor to the sung lyrics', run: 'sync-lyric-anchors' },
+ };
}
// The art-direction row's detail and action for each Cast & Sets phase, while fields are still unwritten.
@@ -893,7 +919,7 @@ export function stageChecklist(stageId, project, readiness = project?.production
case 'board': {
const planned = scenes.length > 0 || (draft.storyboard || []).length > 0;
const feedback = feedbackItem(project, 'storyboard', readiness);
- const problems = [...storyboardProblemItems(readiness), ...(feedback ? [feedback] : [])];
+ const problems = [...storyboardProblemItems(readiness, scenes), ...(feedback ? [feedback] : [])];
return [
{ id: 'shots', label: 'Shots planned', done: planned, detail: planned ? null : 'Plan the shots from the header, or add scenes by hand.',
action: planned ? null : { label: 'Open the treatment', anchor: 'mv-board-treatment' } },
diff --git a/client/src/pages/MusicVideo.jsx b/client/src/pages/MusicVideo.jsx
index 5d5510cec9..ff2b09d7d8 100644
--- a/client/src/pages/MusicVideo.jsx
+++ b/client/src/pages/MusicVideo.jsx
@@ -1189,6 +1189,8 @@ export default function MusicVideo() {
if (action.run === 'resolve-feedback') { productionReview.resolveFeedback(action.feedbackId, ''); return; }
if (action.run === 'revise-feedback') { reviseFromFeedback(action.stage); return; }
if (action.run === 'keep-approval') { keepApproval(action.stage); return; }
+ if (action.run === 'sync-lyric-anchors') { productionReview.syncLyricAnchors(); return; }
+ if (action.editShot) { editShot(action.editShot); return; }
goToStage(action.stage || activeStage, action.anchor, action.params);
};
const runNextAction = () => {
diff --git a/client/src/pages/MusicVideo.test.jsx b/client/src/pages/MusicVideo.test.jsx
index 76ccfaec8c..0aabbdbd72 100644
--- a/client/src/pages/MusicVideo.test.jsx
+++ b/client/src/pages/MusicVideo.test.jsx
@@ -38,7 +38,7 @@ const { sseState, ytSseStates, getYtSseState } = vi.hoisted(() => {
// This page suite exercises existing controls with production approvals already granted.
// ProductionReviewPanel and route integration suites exercise the real approval refusals.
-const feedbackCalls = vi.hoisted(() => ({ resolveFeedback: vi.fn(async () => null), revise: vi.fn(async () => ({ revision: { sceneIds: ['s-a'] } })) }));
+const feedbackCalls = vi.hoisted(() => ({ resolveFeedback: vi.fn(async () => null), syncLyricAnchors: vi.fn(async () => null), revise: vi.fn(async () => ({ revision: { sceneIds: ['s-a'] } })) }));
vi.mock('../hooks/useMusicVideoProductionReview.js', () => ({ default: ({ project }) => ({
...feedbackCalls,
readiness: project?.productionReadiness || { readyForProduction: true, basis: {}, art: { approved: true, problems: [] }, storyboard: { approved: true, problems: [] }, proof: { approved: true, problems: [] } },
@@ -2577,7 +2577,7 @@ describe('MusicVideo visual spec, takes and handoff (#8965)', () => {
fireEvent.click(within(strip).getByRole('button', { name: /Use/ }));
await waitFor(() => expect(selectMusicVideoSceneTake).toHaveBeenCalledWith('mv-takes', 's1', 't-b', { silent: true }));
// The server's answer moves the selection; the other take now offers "Use".
- await waitFor(() => expect(within(strip).getAllByText(/Selected/)).toHaveLength(1));
+ await waitFor(() => expect(within(strip).getAllByText(/In use ·/)).toHaveLength(1));
const items = within(strip).getAllByRole('listitem');
expect(within(items[1]).queryByRole('button', { name: /Use/ })).toBeNull();
@@ -3395,6 +3395,24 @@ describe('stage checklist and project options', () => {
expect(screen.getByRole('region', { name: 'Approve: Lyric-timed storyboard' })).toHaveTextContent('Resolve the change request on Chorus first.');
});
+ // Uniquely catches a lyric anchor problem the director cannot find or settle from the checklist.
+ it('names each shot whose lyric anchors differ from the singing, opens it, and anchors them all in one tap', async () => {
+ const project = { ...PROJECT_ANALYZED, scenes: [{ sceneId: 's-a', label: 'Drummer', startSec: 0, endSec: 4 }, { sceneId: 's-b', label: 'Singer', startSec: 4, endSec: 8 }],
+ productionReview: { draft: { storyboard: [] } },
+ productionReadiness: { readyForProduction: false, basis: {}, art: { approved: true, problems: [] },
+ storyboard: { approved: false, problems: ['Review lyric anchors for Singer.'],
+ lyricAnchors: [{ sceneId: 's-b', sung: ['If you think this is slop'], anchored: [] }] }, proof: { approved: false, problems: [] } } };
+ await openProject(project, 'board');
+ const checklist = screen.getByRole('region', { name: 'What this step needs' });
+ expect(checklist).not.toHaveTextContent('need lyric anchors reviewed');
+ const shots = within(checklist).getByRole('list', { name: 'Lyric anchors shots' });
+ expect(shots).toHaveTextContent('Shot 2Sung: “If you think this is slop” · anchored: nothing');
+ fireEvent.click(within(checklist).getByRole('button', { name: /Anchor to the sung lyrics/ }));
+ expect(feedbackCalls.syncLyricAnchors).toHaveBeenCalledWith();
+ fireEvent.click(within(shots).getByRole('button', { name: 'Shot 2' }));
+ await waitFor(() => expect(document.getElementById('scene-s-b')).toBeTruthy());
+ });
+
it('builds the cast & sets from the Look checklist when nothing is written yet', async () => {
const project = { ...PROJECT_ANALYZED, scenes: [], castAndSets: undefined, devArtifacts: [],
productionReadiness: { readyForProduction: false, basis: {}, art: { approved: false, problems: ['Cast guide needs editable direction.'] },
diff --git a/client/src/services/apiMusicVideo.js b/client/src/services/apiMusicVideo.js
index 666f6c1877..34289d695b 100644
--- a/client/src/services/apiMusicVideo.js
+++ b/client/src/services/apiMusicVideo.js
@@ -197,6 +197,8 @@ export const continueMusicVideoSceneFromPrevious = (id, sceneId, body = {}, opti
request(`/music-video/${encodeURIComponent(id)}/scenes/${encodeURIComponent(sceneId)}/continue-from-previous`, {
method: 'POST', body: JSON.stringify(body), ...options,
});
+export const rejectUnusedMusicVideoSceneTakes = (id, sceneId, options = {}) =>
+ request(`/music-video/${encodeURIComponent(id)}/scenes/${encodeURIComponent(sceneId)}/takes/reject-unused`, { method: 'POST', ...options });
export const reviewMusicVideoSceneTake = (id, sceneId, takeId, review, options = {}) =>
request(`${takesPath(id, sceneId)}/${encodeURIComponent(takeId)}`, {
method: 'PATCH', body: JSON.stringify(review), ...options,
@@ -587,6 +589,7 @@ export const addMusicVideoProductionFeedback = (id, body, options = {}) => reque
// Write one changed input of a stale approval back to its approved value (#10241). `stage` is art | storyboard | proof | castAndSets.
export const revertMusicVideoProductionInput = (id, body, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review/revert`, { method: 'POST', body: JSON.stringify(body), ...options });
export const reviseMusicVideoProductionFromFeedback = (id, body, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review/revise`, { method: 'POST', body: JSON.stringify(body), ...options });
+export const syncMusicVideoLyricAnchors = (id, body = {}, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review/lyric-anchors`, { method: 'POST', body: JSON.stringify(body), ...options });
export const resolveMusicVideoProductionFeedback = (id, body, options = {}) => request(`/music-video/${encodeURIComponent(id)}/production-review/feedback/resolve`, { method: 'POST', body: JSON.stringify(body), ...options });
// Drafting is free; generation and candidate selection are separate explicit actions.
export const saveMusicVideoSongRevision = (id, fields, options = {}) => request(`/music-video/${encodeURIComponent(id)}/song-revision`, { method: 'POST', body: JSON.stringify(fields), ...options });
diff --git a/server/lib/README.md b/server/lib/README.md
index 737e5c46dc..b03c38ad16 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -562,7 +562,8 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `claimFlowTaskTypes.js` | `hasClaimFlowContract(task)` shares trusted claim identity across registration, completion and resume. `CLAIM_FLOW_TASK_TYPES` — the ONE list of task kinds whose prompts own their own `claim/<item>` worktree and push/PR/MR/review lifecycle (#6613). `services/cosTaskGenerator.js` stamps `metadata.claimFlow` from it (WRITE side); `services/agentPromptBuilder.js` reads it back through `isClaimFlowTask()` to pick a run's claim posture (READ side). It lived as two byte-identical copies, so a new claim type added to one silently split the writer from the reader — no error, just a claim run treated as a plain commit-only handoff; `claimFlowTaskTypes.test.js` fails if a local copy reappears. Imports nothing. |
| `chiptuneRender.js` | Deterministic chiptune score → mono PCM → 16-bit WAV buffer (pure Node, no audio deps); `renderScoreToPcm` / `pcmToWavBuffer` / `renderScoreToWav`. |
| `chiptuneScore.js` | Chiptune score contract (#2911): `chiptuneScoreSchema` (Zod) + `sanitizeChiptuneScore`, `buildScoreEvents` — the pattern/order → absolute-time flatten mirrored by `client/src/lib/chiptunePlayback.js`. |
-| `musicVideoLayers.js` | Music Video per-scene visual layers (#8985): `MUSIC_VIDEO_VISUAL_LAYERS` (`footage`/`still`/`card`/`code`), `MUSIC_VIDEO_STILL_MOVES` (`hold`/`push`/`pan`), `MUSIC_VIDEO_FRAME_FITS` (`fill`/`still`/`vhs`/`black`: how an off-shape clip fills the frame), `sceneVisualLayer(scene, { layered })` (only a composed render honors a still/card), `sceneHasAuthoredSpan`, and `sceneRenderReady(scene, { layered })`. `clipSpeedRate(scene)` / `clipOffsetSec(scene)` read a footage shot's hand-set `speedFps` and `offsetFrames` on the 24 fps grid (`CLIP_TIMING_FPS`, `CLIP_SPEED_FPS_RANGE`, `CLIP_OFFSET_FRAMES_RANGE`). Pure leaf shared by `services/musicVideo/render.js` and the client board (`client/src/lib/musicVideoLayers.js`). |
+| `musicVideoLayers.js` | Music Video per-scene visual layers (#8985): `MUSIC_VIDEO_VISUAL_LAYERS` (`footage`/`still`/`card`/`code`), `MUSIC_VIDEO_STILL_MOVES` (`hold`/`push`/`pan`), `MUSIC_VIDEO_FRAME_FITS` (`fill`/`still`/`vhs`/`black`: how an off-shape clip fills the frame), `sceneVisualLayer(scene, { layered })` (only a composed render honors a still/card), `sceneHasAuthoredSpan`, and `sceneRenderReady(scene, { layered })`. `clipSpeedRate(scene)` / `clipOffsetSec(scene)` / `clipReversed(scene)` read a footage shot's hand-set `speedFps`, `offsetFrames` and `reverse` on the 24 fps grid (`CLIP_TIMING_FPS`, `CLIP_SPEED_FPS_RANGE`, `CLIP_OFFSET_FRAMES_RANGE`). Pure leaf shared by `services/musicVideo/render.js` and the client board (`client/src/lib/musicVideoLayers.js`). |
+| `musicVideoLyricAnchors.js` | Music Video lyric anchors: `cuesSungWithin(cues, startSec, endSec)`, the lines a shot's span anchors, each counted from its first sung word to its last when it has word timing, else its line window. Shared by the storyboard anchor check and the retime anchor sync. |
| `musicVideoImageEffects.js` | Music Video image effects: a code-drawn effect a still shot plays instead of a generated clip (`imageEffect`: `flash-develop`, a camera flash then the picture develops like an instant photo over `imageEffectSec`; or a fade, flash or glitch from the start frame to the end frame). `sceneImageEffect(scene, { layered })`, `imageEffectState` (the effect at a time into the shot, painted by the storyboard animatic) and `musicVideoImageEffectFilter` (the same curves as ffmpeg filters for the final render). Browser-safe and import-free: document videos ship it as is. |
| `musicVideoTransitions.js` | Music Video cut transitions: VHS glitch styles a shot sets on the cut into (`transitionIn`) or out of (`transitionOut`) it, `transitionGlitchFrames` (the glitched frames of a cut timeline, never moving a cut), `transitionFrameAt`, `sceneTransitionSections`, `imageEffectGlitchFrames`/`mergeGlitchFrames` (end-frame glitch effects in the same shape), `shotGlitchFrames`/`sceneShotGlitchFrames` (glitches a shot sets at moments inside it, `scene.glitches`), `blockBox` and `musicVideoTransitionFilter` (per-frame ffmpeg filters for the final render). Browser-safe; the storyboard animatic paints the same frames. |
| `pitchMath.js` | Dependency-free scientific-pitch math shared by the LLM-authored music formats on both runtimes: `pitchToMidi("C4")` → 60 (null when unparseable) and `midiToFreq(69)` → 440. |
diff --git a/server/lib/index.js b/server/lib/index.js
index 6ea152a6a7..bb042172c2 100644
--- a/server/lib/index.js
+++ b/server/lib/index.js
@@ -509,6 +509,7 @@ export * from './chiptuneRender.js';
export * from './chiptuneScore.js';
export * from './pitchMath.js';
export * from './musicVideoLayers.js';
+export * from './musicVideoLyricAnchors.js';
export * from './wavAudioFile.js';
export * from './superColliderRuntime.js';
export * from './waveSketch.js';
diff --git a/server/lib/musicVideoDependencies.js b/server/lib/musicVideoDependencies.js
index be5d045444..1486798289 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'].filter((key) => scene[key]).map((key) => [key, scene[key]]))
+ .concat(['speedFps', 'offsetFrames', 'reverse'].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/musicVideoLayers.js b/server/lib/musicVideoLayers.js
index 9850769345..3833095ae0 100644
--- a/server/lib/musicVideoLayers.js
+++ b/server/lib/musicVideoLayers.js
@@ -97,3 +97,5 @@ const whole = (value, { min, max }) => (Number.isInteger(value) ? Math.min(max,
export const clipSpeedRate = (scene) => (CLIP_TIMING_FPS + whole(scene?.speedFps, CLIP_SPEED_FPS_RANGE)) / CLIP_TIMING_FPS;
/** How far a shot's clip slides against the song, in seconds: positive skips in, negative holds the first frame. */
export const clipOffsetSec = (scene) => whole(scene?.offsetFrames, CLIP_OFFSET_FRAMES_RANGE) / CLIP_TIMING_FPS;
+// A footage shot's clip set to play backwards. A lip-sync performance never reverses: its mouth follows the song.
+export const clipReversed = (scene) => scene?.reverse === true && scene?.shotMode !== 'performance';
diff --git a/server/lib/musicVideoLyricAnchors.js b/server/lib/musicVideoLyricAnchors.js
new file mode 100644
index 0000000000..9907e9a3b4
--- /dev/null
+++ b/server/lib/musicVideoLyricAnchors.js
@@ -0,0 +1,23 @@
+/**
+ * Which timed lyric lines a shot's span anchors. A line counts from its first
+ * sung word to its last when it has word timing (#9074), not from its line
+ * window: lyric alignment opens each line where the line before it ended, so
+ * an instrumental gap before a line would otherwise tie the shots in that gap
+ * to a lyric nobody sings over them. A line without words keeps its window.
+ */
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+
+/** `{ startSec, endSec }` of the singing in a cue, or null when it is untimed. */
+function sungCueSpan(cue) {
+ const words = Array.isArray(cue?.words) ? cue.words.filter((w) => finite(w?.startSec) && finite(w?.endSec)) : [];
+ if (words.length) return { startSec: Math.min(...words.map((w) => w.startSec)), endSec: Math.max(...words.map((w) => w.endSec)) };
+ return finite(cue?.startSec) && finite(cue?.endSec) ? { startSec: cue.startSec, endSec: cue.endSec } : null;
+}
+
+/** The cues whose singing overlaps `[startSec, endSec)`, in song order. */
+export function cuesSungWithin(cues, startSec, endSec) {
+ return (Array.isArray(cues) ? cues : []).filter((cue) => {
+ const span = sungCueSpan(cue);
+ return span && span.startSec < endSec && span.endSec > startSec;
+ });
+}
diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.js
index eb700fa3d0..dd1198da4d 100644
--- a/server/lib/musicVideoValidation.js
+++ b/server/lib/musicVideoValidation.js
@@ -610,6 +610,8 @@ const sceneLayerFields = {
// A footage clip played faster or slower by whole frames a second, and slid against the song by whole frames; null clears it.
speedFps: z.number().int().min(CLIP_SPEED_FPS_RANGE.min).max(CLIP_SPEED_FPS_RANGE.max).nullable().optional(),
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 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(),
@@ -1708,6 +1710,10 @@ export const musicVideoProductionReviseSchema = musicVideoCastAndSetsStartSchema
export const musicVideoProductionRevertSchema = z.object({
stage: z.enum(['art', 'storyboard', 'proof', 'castAndSets']), field: z.string().trim().min(1).max(100),
}).strict();
+// Anchor these storyboard shots (every flagged shot when absent) to the lyric lines sung over them.
+export const musicVideoLyricAnchorSyncSchema = z.object({
+ sceneIds: z.array(z.string().min(1).max(64)).min(1).max(2000).optional(),
+}).strict();
export const musicVideoProductionFeedbackResolutionSchema = z.object({
feedbackId: z.string().min(1).max(128), resolution: z.string().trim().max(8000).default(''), password: z.string().max(1024).optional(),
}).strict();
diff --git a/server/routes/musicVideo.js b/server/routes/musicVideo.js
index 764638e587..38a7c7371e 100644
--- a/server/routes/musicVideo.js
+++ b/server/routes/musicVideo.js
@@ -12,10 +12,10 @@ import { existsSync } from 'fs';
import { unlink } from 'fs/promises';
import { pipeline } from 'stream/promises';
import { Router } from 'express';
-import { musicVideoSongStyleSunoSchema, musicVideoProjectListQuerySchema, musicVideoFinishedOutsideSchema, musicVideoProductionDraftSchema, musicVideoProductionApprovalSchema, musicVideoShotLockSchema, musicVideoProductionProofSchema, musicVideoProductionImportSchema, musicVideoContinueShotSchema, musicVideoPoolUseSchema, musicVideoPoolMarkSchema, musicVideoPoolDeleteSchema, musicVideoProductionFeedbackSchema, musicVideoProductionFeedbackResolutionSchema, musicVideoProductionReviseSchema, musicVideoProductionRevertSchema } from '../lib/musicVideoValidation.js';
+import { musicVideoSongStyleSunoSchema, musicVideoProjectListQuerySchema, musicVideoFinishedOutsideSchema, musicVideoProductionDraftSchema, musicVideoProductionApprovalSchema, musicVideoShotLockSchema, musicVideoProductionProofSchema, musicVideoProductionImportSchema, musicVideoContinueShotSchema, musicVideoPoolUseSchema, musicVideoPoolMarkSchema, musicVideoPoolDeleteSchema, musicVideoProductionFeedbackSchema, musicVideoProductionFeedbackResolutionSchema, musicVideoLyricAnchorSyncSchema, musicVideoProductionReviseSchema, musicVideoProductionRevertSchema } from '../lib/musicVideoValidation.js';
import { productionReadiness } from '../services/musicVideo/productionReview.js';
import { finishedOutsideBlocker } from '../lib/musicVideoFinishedOutside.js';
-import { getProductionReview, saveProductionDraft, prepareProductionReview, approveProductionReview, lockProductionShots, renderProductionProof, requireProductionReviewer, importProductionPlanning, bindProductionShot, addProductionFeedback, closeProductionFeedback, reviseProductionFromFeedback, revertProductionInput } from '../services/musicVideo/productionReviewService.js';
+import { getProductionReview, saveProductionDraft, prepareProductionReview, approveProductionReview, lockProductionShots, renderProductionProof, requireProductionReviewer, importProductionPlanning, bindProductionShot, addProductionFeedback, closeProductionFeedback, syncLyricAnchors, reviseProductionFromFeedback, revertProductionInput } from '../services/musicVideo/productionReviewService.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import {
validateRequest,
@@ -120,6 +120,7 @@ import {
placeMediaPoolItem,
markMediaPoolAssets,
reviewSceneTake,
+ rejectUnusedSceneTakes,
refreshSongStyleFromSuno,
} from '../services/musicVideo/projects.js';
import { buildHandoffManifest, buildHandoffBundle, matchSceneByFileTag } from '../services/musicVideo/handoff.js';
@@ -730,6 +731,9 @@ router.post('/:id/production-review/feedback/resolve', asyncHandler(async (req,
const reviewer = await requireProductionReviewer(req);
res.json(await closeProductionFeedback(req.params.id, { feedbackId: input.feedbackId, resolution: input.resolution, reviewer }));
}));
+router.post('/:id/production-review/lyric-anchors', asyncHandler(async (req, res) => {
+ res.json(await syncLyricAnchors(req.params.id, validateRequest(musicVideoLyricAnchorSyncSchema, req.body ?? {})));
+}));
// An explicit click: the only provider call is the stage's own revision.
router.post('/:id/production-review/revise', asyncHandler(async (req, res) => {
res.json(await reviseProductionFromFeedback(req.params.id, validateRequest(musicVideoProductionReviseSchema, req.body ?? {})));
@@ -1590,6 +1594,11 @@ router.post('/:id/scenes/:sceneId/takes/:takeId/select', asyncHandler(async (req
res.json(await selectSceneTake(req.params.id, req.params.sceneId, req.params.takeId));
}));
+// No body: marks the shot's unselected takes rejected, keeping their files.
+router.post('/:id/scenes/:sceneId/takes/reject-unused', asyncHandler(async (req, res) => {
+ res.json(await rejectUnusedSceneTakes(req.params.id, req.params.sceneId));
+}));
+
router.patch('/:id/scenes/:sceneId/takes/:takeId', asyncHandler(async (req, res) => {
const review = validateRequest(musicVideoTakeReviewSchema, req.body);
res.json(await reviewSceneTake(req.params.id, req.params.sceneId, req.params.takeId, review));
diff --git a/server/services/musicVideo/productionReview.js b/server/services/musicVideo/productionReview.js
index e269c9ef9d..bda02178ef 100644
--- a/server/services/musicVideo/productionReview.js
+++ b/server/services/musicVideo/productionReview.js
@@ -10,6 +10,7 @@ import { cameraVarietyReport } from './shotCamera.js';
import { overlayTextReport } from './overlayText.js';
import { musicVideoAspect } from '../../lib/musicVideoAspect.js';
import { lyricCueSpan } from './timedText.js';
+import { cuesSungWithin } from '../../lib/musicVideoLyricAnchors.js';
import { isLayeredComposition, sceneVisualLayer } from '../../lib/musicVideoLayers.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;
@@ -190,12 +191,12 @@ export function clipLocks(project, locks = shotLocks(project)) {
}));
}
-const clipLocked = (project, sceneId) => project.productionReview?.clipApprovals?.[sceneId]
+export const clipLocked = (project, sceneId) => project.productionReview?.clipApprovals?.[sceneId]
&& clipLocks(project)?.[sceneId] === 'locked';
/** 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'];
+ 'referenceImageId', 'endImageId', 'shotMode', 'performanceSpeaker', 'performanceStyle', 'visualLayer', 'loop', 'videoHistoryId', 'codeClip', 'speedFps', 'offsetFrames', 'reverse'];
/**
* Refuse a change to a shot whose video is locked: `patch` is a scene patch
@@ -549,7 +550,7 @@ 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),
+ lyricCueIds: cuesSungWithin(project.lyricCues, scene.startSec, scene.endSec).map(c => c.id),
action: scene.visualIntent || scene.prompt || '', staging: scene.framePrompt || '',
camera: shotCameraLabel(scene.camera) || scene.direction?.camera || world.camera || '', transition: sceneTransition(scene.direction) || world.transitions || 'Cut',
};
@@ -561,6 +562,32 @@ export function boardStoryboard(project, storyboard = project.productionReview?.
.map(scene => boardShotFromScene(project, scene))];
}
+/**
+ * Re-anchor the storyboard rows of `sceneIds` (every shot when null) to the
+ * lyric lines sung over their scenes now, keeping each row's span in step with
+ * its scene. A shot with no draft row already reads its anchors from its scene.
+ * Returns the project unchanged when nothing moved.
+ */
+export function anchorShotsToSungLyrics(project, sceneIds = null) {
+ const draft = project.productionReview?.draft;
+ if (!Array.isArray(draft?.storyboard) || draft.storyboardSource === 'document') return project;
+ const scenes = new Map((project.scenes || []).map(scene => [scene.sceneId, scene]));
+ const cues = (project.lyricCues || []).filter(c => text(c.text));
+ let moved = false;
+ const storyboard = draft.storyboard.map(shot => {
+ const scene = shot?.sceneId && scenes.get(shot.sceneId);
+ if (!scene || (sceneIds && !sceneIds.includes(shot.sceneId))) return shot;
+ const lyricCueIds = cuesSungWithin(cues, scene.startSec, scene.endSec).map(c => c.id);
+ const span = 'startSec' in shot || 'endSec' in shot ? { startSec: scene.startSec, endSec: scene.endSec } : {};
+ const same = lyricCueIds.length === (shot.lyricCueIds || []).length && lyricCueIds.every((id, i) => shot.lyricCueIds[i] === id)
+ && Object.entries(span).every(([key, value]) => shot[key] === value);
+ if (same) return shot;
+ moved = true;
+ return { ...shot, ...span, lyricCueIds };
+ });
+ return moved ? { ...project, productionReview: { ...project.productionReview, draft: { ...draft, storyboard } } } : project;
+}
+
export function productionReadiness(project) {
const review = project.productionReview || {};
const draft = review.draft || {};
@@ -576,6 +603,8 @@ export function productionReadiness(project) {
if (!['text/html', 'image/png', 'image/jpeg'].includes(artifact(project, draft.guideArtifactId)?.mimeType)) artProblems.push('Attach a visual cast/environment sheet from Development artifacts.');
if (artifact(project, draft.guideArtifactId)?.mimeType?.startsWith('image/') && !musicVideoAllowsMedia(project, 'image')) artProblems.push('Code only requires a code-authored visual guide; select a compatible Development artifact.');
const artApproved = !artProblems.length && review.approvals?.art?.basis === basis.art;
+ // Shots whose lyric anchors differ from the lines sung over them, with both, so the checklist can show and fix them.
+ const lyricAnchors = [];
const boardProblems = unresolved('storyboard').map(f => `Resolve storyboard feedback for ${f.target}: ${f.text}`);
if (!artApproved) boardProblems.push('Review and approve the current art direction first.');
const duration = project.audioAnalysis?.durationSec;
@@ -618,9 +647,14 @@ export function productionReadiness(project) {
|| !shot || ['action', 'staging', 'camera', 'transition'].some(key => !text(shot[key]))) {
boardProblems.push(`Complete timing, action, staging, camera and transition for ${scene.label || 'each shot'}.`);
}
- const overlapping = cues.filter(c => c.startSec < scene.endSec && c.endSec > scene.startSec);
- if (overlapping.some(c => !shot?.lyricCueIds?.includes(c.id))
- || shot?.lyricCueIds?.some(id => !cues.some(c => c.id === id))) boardProblems.push(`Review lyric anchors for ${scene.label || 'each shot'}.`);
+ // A shot anchors every line sung over it, counted from the line's first sung word (lib/musicVideoLyricAnchors.js).
+ const sung = cuesSungWithin(cues, scene.startSec, scene.endSec);
+ if (sung.some(c => !shot?.lyricCueIds?.includes(c.id))
+ || shot?.lyricCueIds?.some(id => !cues.some(c => c.id === id))) {
+ boardProblems.push(`Review lyric anchors for ${scene.label || 'each shot'}.`);
+ if (!documentShots) lyricAnchors.push({ sceneId: scene.sceneId, sung: sung.map(c => c.text),
+ anchored: (shot?.lyricCueIds || []).map(id => cues.find(c => c.id === id)?.text).filter(Boolean) });
+ }
}
// Once any shot has been locked, the board is approved exactly when every shot is.
const locks = shotLocks(project);
@@ -643,7 +677,7 @@ export function productionReadiness(project) {
// The overlay text check is advice on the storyboard, like camera variety; it never blocks approval.
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),
+ shots: documentShots ? null : boardStoryboard(project), lyricAnchors, text: overlayTextReport(project, overlayTextBasis), stale: storyboardApproved ? null : staleApproval(project, 'storyboard', basis.storyboard, inputs),
shotLocks: locks, unlocked: byShot ? unlocked : [], clipLocks: clips,
// Video shots whose clip is not locked yet: the board is finished when every shot is fully locked.
clipsUnlocked: clips ? Object.keys(clips).filter(id => clips[id] && clips[id] !== 'locked') : [] },
diff --git a/server/services/musicVideo/productionReview.storyboard.test.js b/server/services/musicVideo/productionReview.storyboard.test.js
index 742ce3ccd6..6f457a6288 100644
--- a/server/services/musicVideo/productionReview.storyboard.test.js
+++ b/server/services/musicVideo/productionReview.storyboard.test.js
@@ -1,5 +1,5 @@
import { describe, it, expect } from 'vitest';
-import { productionReadiness, productionAlignmentBasis, approveProductionStage, carryProductionApprovals, carryShotLocks, assertShotApproval, assertClipUnlocked, setShotLocks } from './productionReview.js';
+import { anchorShotsToSungLyrics, productionReadiness, productionAlignmentBasis, approveProductionStage, carryProductionApprovals, carryShotLocks, assertShotApproval, assertClipUnlocked, setShotLocks } from './productionReview.js';
import { addScenes, applySceneUpdate, mergeNextScene, removeScene } from './projectsLogic.js';
const WORD_PROBLEM = /bounded, positive-duration word timings/;
@@ -235,3 +235,36 @@ describe('derived shot transitions', () => {
expect(storyboard.problems.filter(p => SHOT_PROBLEM.test(p))).toEqual([]);
});
});
+
+describe('lyric anchors follow the singing', () => {
+ // The line window opens at 3.5 (where the line before ended); its first word is sung at 5.
+ const cue = { id: 'c2', text: 'if you think this is slop', startSec: 3.5, endSec: 7, words: [{ w: 'if', startSec: 5, endSec: 5.4 }, { w: 'slop', startSec: 6, endSec: 6.8 }] };
+ function board(shots) {
+ const base = project({ draftShots: shots });
+ return { ...base, lyricCues: [...base.lyricCues, cue], scenes: [base.scenes[0], { ...base.scenes[1], startSec: 4, endSec: 4.9, sceneId: 's2', label: 'Drummer' },
+ { ...base.scenes[1], sceneId: 's3', label: 'Singer', startSec: 4.9, endSec: 8 }] };
+ }
+ const row = (sceneId, lyricCueIds) => ({ sceneId, lyricCueIds, action: 'a', staging: 'b', camera: 'c', transition: 'Cut' });
+
+ // Uniquely catches a shot in the instrumental gap before a line being held to that line's anchor.
+ it('anchors a line to the shots its words are sung over, not the gap before them, and names what to fix', () => {
+ const stale = board([row('s1', ['c1']), row('s2', ['c2']), row('s3', [])]);
+ const { storyboard } = productionReadiness(stale);
+ expect(storyboard.problems.filter((p) => ANCHOR_PROBLEM.test(p))).toEqual(['Review lyric anchors for Singer.']);
+ expect(storyboard.lyricAnchors).toEqual([{ sceneId: 's3', sung: ['if you think this is slop'], anchored: [] }]);
+ const fixed = anchorShotsToSungLyrics(stale, ['s3']);
+ expect(fixed.productionReview.draft.storyboard.find((shot) => shot.sceneId === 's3').lyricCueIds).toEqual(['c2']);
+ expect(productionReadiness(fixed).storyboard.lyricAnchors).toEqual([]);
+ });
+
+ // Uniquely catches a retimed shot keeping the lyric and anchor of the span it left.
+ it('moves the lyric and its anchor with a retimed shot', () => {
+ const swapped = board([row('s1', ['c1']), row('s2', []), row('s3', ['c2'])]);
+ const { project: next } = applySceneUpdate(swapped, 's2', { endSec: 6 });
+ expect(next.scenes.find((scene) => scene.sceneId === 's2').lyricText).toBe('if you think this is slop');
+ expect(next.productionReview.draft.storyboard.find((shot) => shot.sceneId === 's2').lyricCueIds).toEqual(['c2']);
+ const { project: back } = applySceneUpdate(next, 's2', { endSec: 4.9 });
+ expect(back.scenes.find((scene) => scene.sceneId === 's2').lyricText).toBeNull();
+ expect(back.productionReview.draft.storyboard.find((shot) => shot.sceneId === 's2').lyricCueIds).toEqual([]);
+ });
+});
diff --git a/server/services/musicVideo/productionReviewService.js b/server/services/musicVideo/productionReviewService.js
index ca1b9f47ed..2c0a086f67 100644
--- a/server/services/musicVideo/productionReviewService.js
+++ b/server/services/musicVideo/productionReviewService.js
@@ -3,7 +3,8 @@ 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, boardStoryboard, seedArtDraft, productionReviewBasis, productionAlignmentBasis, documentStoryboardBasis, approveProductionStage, assertProductionApproval, assertShotApproval, assertClipUnlocked, setShotLocks, recordProductionFeedback, resolveProductionFeedback, revertApprovedInput } from './productionReview.js';
+import { productionReadiness, boardStoryboard, seedArtDraft, productionReviewBasis, productionAlignmentBasis, documentStoryboardBasis, approveProductionStage, assertProductionApproval, assertShotApproval, assertClipUnlocked, setShotLocks, recordProductionFeedback, resolveProductionFeedback, revertApprovedInput, anchorShotsToSungLyrics, clipLocked } from './productionReview.js';
+import { cuesSungWithin } from '../../lib/musicVideoLyricAnchors.js';
const reviewProcessId = randomUUID();
@@ -304,6 +305,26 @@ export async function addProductionFeedback(id, input) {
const { project } = await mutateProjectRecord(id, current => ({ project: recordProductionFeedback(current, input) }));
return changed(project);
}
+/**
+ * Anchor shots to the lyric lines sung over them: the shots named, else every
+ * shot the storyboard check flags. Each also shows those lines as its lyric,
+ * except a shot whose video is locked: its lyric is a locked render input.
+ */
+export async function syncLyricAnchors(id, { sceneIds = null } = {}) {
+ const { project } = await mutateProjectRecord(id, current => {
+ const ids = sceneIds || productionReadiness(current).storyboard.lyricAnchors.map(entry => entry.sceneId);
+ if (!ids.length) return { project: current };
+ const anchored = anchorShotsToSungLyrics(current, ids);
+ const scenes = (anchored.scenes || []).map(scene => {
+ if (!ids.includes(scene.sceneId) || clipLocked(current, scene.sceneId)) return scene;
+ const sung = cuesSungWithin(anchored.lyricCues, scene.startSec, scene.endSec).map(cue => cue.text?.trim()).filter(Boolean);
+ return { ...scene, lyricText: sung.length ? sung.join(' / ').slice(0, 2000) : null };
+ });
+ return { project: { ...anchored, scenes, updatedAt: new Date().toISOString() } };
+ });
+ return changed(project);
+}
+
export async function closeProductionFeedback(id, input) {
const { project } = await mutateProjectRecord(id, current => ({ project: resolveProductionFeedback(current, input) }));
return changed(project);
diff --git a/server/services/musicVideo/projects.js b/server/services/musicVideo/projects.js
index abcfcd0550..6c7c769603 100644
--- a/server/services/musicVideo/projects.js
+++ b/server/services/musicVideo/projects.js
@@ -445,6 +445,13 @@ export async function placeMediaPoolItem(id, sceneId, { kind, assetId, withAsset
return scene;
}
+/** Reject every take of a shot that is not its selected frame, end frame or clip. Returns `{ scene, rejected }`. */
+export async function rejectUnusedSceneTakes(id, sceneId) {
+ const { rejectUnusedTakes } = await import('./takes.js');
+ const { scene, rejected } = await mutateProjectRecord(id, (current) => rejectUnusedTakes(current, sceneId));
+ return { scene, rejected };
+}
+
/** Reject/restore a take and/or set its note. Returns the updated scene. */
export async function reviewSceneTake(id, sceneId, takeId, review) {
const [{ reviewSceneTake: reviewTake }, { assertClipUnlocked }] = await Promise.all([import('./takes.js'), import('./productionReview.js')]);
diff --git a/server/services/musicVideo/projects.test.js b/server/services/musicVideo/projects.test.js
index 26cda2a779..6e93900369 100644
--- a/server/services/musicVideo/projects.test.js
+++ b/server/services/musicVideo/projects.test.js
@@ -484,3 +484,24 @@ describe('moving the cut before a shot', () => {
expect((await projects.getProject(p.id)).scenes.map((scene) => [scene.startSec, scene.endSec])).toEqual([[0, 1.25], [1.25, 4]]);
});
});
+
+describe('anchoring shots to the sung lyrics', () => {
+ // Uniquely catches the anchor fix rewriting the lyric of a shot whose video is locked.
+ it('re-anchors the named shots and refreshes their lyric, leaving a locked video\'s lyric alone', async () => {
+ const [{ setShotLocks }, { syncLyricAnchors }] = await Promise.all([import('./productionReview.js'), import('./productionReviewService.js')]);
+ const p = await projects.createProject({ name: 'Anchor lyrics' });
+ const { scenes: [a, b] } = await projects.addProjectScenes(p.id, [
+ { startSec: 0, endSec: 2, prompt: 'First', lyricText: 'old line' },
+ { startSec: 2, endSec: 4, prompt: 'Second', lyricText: 'old line' },
+ ]);
+ await projects.mutateProjectRecord(p.id, (current) => ({ project: { ...current,
+ lyricCues: [{ id: 'c1', text: 'sung over both', startSec: 0, endSec: 4 }],
+ productionReview: { draft: { storyboard: [a, b].map((s) => ({ sceneId: s.sceneId, lyricCueIds: [] })) } } } }));
+ await projects.updateScene(p.id, b.sceneId, { videoHistoryId: 'clip-b' });
+ await projects.mutateProjectRecord(p.id, (current) => ({ project: setShotLocks(setShotLocks(current, { sceneIds: [b.sceneId], locked: true, stage: 'still' }),
+ { sceneIds: [b.sceneId], locked: true, stage: 'video' }) }));
+ const { project } = await syncLyricAnchors(p.id, { sceneIds: [a.sceneId, b.sceneId] });
+ expect(project.productionReview.draft.storyboard.map((row) => row.lyricCueIds)).toEqual([['c1'], ['c1']]);
+ expect(project.scenes.map((scene) => scene.lyricText)).toEqual(['sung over both', 'old line']);
+ });
+});
diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.js
index 2e95b4918b..ecc0e536aa 100644
--- a/server/services/musicVideo/projectsLogic.js
+++ b/server/services/musicVideo/projectsLogic.js
@@ -41,7 +41,8 @@ import { normalizeFilmLook } from '../../lib/filmLook.js';
import { normalizeTitleCard } from '../../lib/musicVideoTitleCard.js';
import { normalizeStatsOutro } from '../../lib/musicVideoStatsOutro.js';
import { remapTreatmentForClone, scenesFingerprint } from './treatment.js';
-import { carryStoryboardApproval } from './productionReview.js';
+import { anchorShotsToSungLyrics, carryStoryboardApproval } from './productionReview.js';
+import { cuesSungWithin } from '../../lib/musicVideoLyricAnchors.js';
import { normalizeMusicVideoAutomation } from '../../lib/musicVideoAutomation.js';
export { sanitizeProjectForSync } from '../../lib/projectStoreKit.js';
@@ -522,6 +523,7 @@ function buildScene(input, { order }) {
...(input.frameFit ? { frameFit: input.frameFit } : {}),
...(input.speedFps ? { speedFps: input.speedFps } : {}),
...(input.offsetFrames ? { offsetFrames: input.offsetFrames } : {}),
+ ...(input.reverse ? { reverse: true } : {}),
...(input.transitionIn ? { transitionIn: input.transitionIn } : {}),
...(input.transitionOut ? { transitionOut: input.transitionOut } : {}),
...(input.glitches?.length ? { glitches: input.glitches } : {}),
@@ -611,6 +613,7 @@ export function replaceScenes(project, sceneInputs) {
...(prior.frameFit ? { frameFit: prior.frameFit } : {}),
...(prior.speedFps ? { speedFps: prior.speedFps } : {}),
...(prior.offsetFrames ? { offsetFrames: prior.offsetFrames } : {}),
+ ...(prior.reverse ? { reverse: true } : {}),
...(prior.transitionIn ? { transitionIn: prior.transitionIn } : {}),
...(prior.transitionOut ? { transitionOut: prior.transitionOut } : {}),
...(prior.glitches?.length ? { glitches: prior.glitches } : {}),
@@ -629,7 +632,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', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect',
+ 'referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit', 'speedFps', 'offsetFrames', 'reverse', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect',
'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec'];
/**
@@ -651,10 +654,17 @@ export function applySceneUpdate(project, sceneId, patch) {
if (updated.startSec != null && updated.endSec != null && updated.endSec < updated.startSec) {
throw new ServerError('endSec must be >= startSec', { status: 400, code: 'VALIDATION_ERROR' });
}
+ // A retimed shot shows, and anchors, the lyric lines now sung over it.
+ const retimed = (('startSec' in data && data.startSec !== scenes[idx].startSec) || ('endSec' in data && data.endSec !== scenes[idx].endSec))
+ && (project.lyricCues || []).some((cue) => typeof cue?.startSec === 'number');
+ if (retimed && !('lyricText' in data)) {
+ const sung = cuesSungWithin(project.lyricCues, updated.startSec, updated.endSec).map((cue) => cue.text?.trim()).filter(Boolean);
+ updated.lyricText = sung.length ? sung.join(' / ').slice(0, 2000) : null;
+ }
assertMusicVideoMediaSelections({ ...project, scenes: [updated], visualSpec: null });
const nextScenes = scenes.slice();
nextScenes[idx] = updated;
- const next = touch(project, { scenes: nextScenes });
+ const next = retimed ? anchorShotsToSungLyrics(touch(project, { scenes: nextScenes }), [sceneId]) : touch(project, { scenes: nextScenes });
// Retiming or rewording a shot, or picking another take, keeps the storyboard approval it was judged on.
const shotEdit = Object.keys(data).every((key) => SCENE_SHOT_EDIT_FIELDS.includes(key));
return { project: shotEdit ? carryStoryboardApproval(project, next, 'Edited a shot') : next, updated };
diff --git a/server/services/musicVideo/render.js b/server/services/musicVideo/render.js
index cbb70d8730..98ced9d018 100644
--- a/server/services/musicVideo/render.js
+++ b/server/services/musicVideo/render.js
@@ -41,7 +41,7 @@ import { loadHistory, mutateVideoHistory } from '../videoGen/local.js';
import { getTrack } from '../tracks/index.js';
import { getProject, listProjects, updateProject, mutateProjectRecord } from './projects.js';
import { applyProjectPatch } from './projectsLogic.js';
-import { MUSIC_VIDEO_FRAME_FITS, clipOffsetSec, clipSpeedRate, isSelfDrawnLayer, sceneHasAuthoredSpan, sceneVisualLayer } from '../../lib/musicVideoLayers.js';
+import { MUSIC_VIDEO_FRAME_FITS, clipOffsetSec, clipReversed, clipSpeedRate, isSelfDrawnLayer, sceneHasAuthoredSpan, sceneVisualLayer } from '../../lib/musicVideoLayers.js';
import { musicVideoAspect, musicVideoRenderCanvas } from '../../lib/musicVideoAspect.js';
import { projectTypographyPlan } from './composition.js';
import { encodeCodeComposition, prepareCodeRender, writeCodeProofSheet } from './codeRender.js';
@@ -311,7 +311,9 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss
// below (which rewrites `duration` to the rendered span) so coverage can
// be judged against it.
sourceSec,
- loop: edit ? false : sceneLoops(scene),
+ // 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 } : {}),
...(rate !== 1 ? { rate } : {}),
...(leadSec > 0 ? { leadSec } : {}),
inSec,
@@ -478,7 +480,9 @@ function sectionChain(c, input, { canonW, canonH, fps, frames, frameGrid }) {
// A hand-set speed retimes the clip and a negative offset holds its first frame, both before the trim.
const speed = c.rate && c.rate !== 1 ? `setpts=(PTS-STARTPTS)/${Number(c.rate.toFixed(6))},` : '';
const lead = c.leadSec > 0 ? `tpad=start_mode=clone:start_duration=${round3(c.leadSec)},` : '';
- const timed = `${speed}${lead}fps=${fps},${hold}${trim},setpts=PTS-STARTPTS`;
+ // A reversed clip plays from its last frame, before any speed, offset or trim.
+ const reverse = c.reverse ? 'reverse,setpts=PTS-STARTPTS,' : '';
+ const timed = `${reverse}${speed}${lead}fps=${fps},${hold}${trim},setpts=PTS-STARTPTS`;
const cover = `scale=${canonW}:${canonH}:force_original_aspect_ratio=increase,crop=${canonW}:${canonH},setsar=1`;
const fit = `scale=${canonW}:${canonH}:force_original_aspect_ratio=decrease,setsar=1`;
const centered = `overlay=(W-w)/2:(H-h)/2:shortest=1`;
diff --git a/server/services/musicVideo/render.test.js b/server/services/musicVideo/render.test.js
index e726226243..324c0a6ec8 100644
--- a/server/services/musicVideo/render.test.js
+++ b/server/services/musicVideo/render.test.js
@@ -331,6 +331,20 @@ describe('resolveSceneClips', () => {
expect(fc([{ ...faster, rate: undefined }])).not.toContain('PTS-STARTPTS)/');
});
+ // Uniquely catches a reversed shot looping its input forever (reverse would never end) or playing forwards.
+ it('plays a reversed clip backwards from the same file, read once, before its speed', async () => {
+ loadHistory.mockResolvedValue([{ id: 'h1', filename: 'a.mp4', width: 768, height: 512, fps: 24, numFrames: 96 }]);
+ const [reversed, sung] = await resolveSceneClips({ scenes: [
+ { sceneId: 's1', order: 0, videoHistoryId: 'h1', reverse: true, speedFps: 24 },
+ { sceneId: 's2', order: 1, videoHistoryId: 'h1', reverse: true, shotMode: 'performance' },
+ ] });
+ expect(reversed).toMatchObject({ reverse: true, loop: false, rate: 2 });
+ expect(sung.reverse).toBeUndefined();
+ const { args } = buildMusicVideoFfmpegArgs([reversed], '/music/track.wav', '/out.mp4', { audioDurationSec: 30 });
+ expect(args).not.toContain('-stream_loop');
+ expect(args[args.indexOf('-filter_complex') + 1]).toContain('reverse,setpts=PTS-STARTPTS,setpts=(PTS-STARTPTS)/2,fps=24');
+ });
+
it('cuts a code shot as a black ground in a composed render (#10297)', async () => {
loadHistory.mockResolvedValue([]);
const clips = await resolveSceneClips({ scenes: [{ sceneId: 's1', order: 0, visualLayer: 'code', startSec: 2, endSec: 5 }] }, { layered: true });
diff --git a/server/services/musicVideo/takes.js b/server/services/musicVideo/takes.js
index d6202fef17..338b70c6fa 100644
--- a/server/services/musicVideo/takes.js
+++ b/server/services/musicVideo/takes.js
@@ -240,6 +240,24 @@ export function selectSceneTake(project, sceneId, takeId) {
* Reject/restore a take and/or set its review note. Rejecting the SELECTED take
* clears the slot so the scene reads as "needs a take" again.
*/
+/**
+ * Finalize a shot's takes: every take that is not the selected frame, end
+ * frame or clip becomes rejected. Files and notes stay, the selection does not
+ * change, and Use or Restore brings any of them back.
+ */
+export function rejectUnusedTakes(project, sceneId) {
+ const scenes = project.scenes || [];
+ const idx = scenes.findIndex((s) => s.sceneId === sceneId);
+ if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
+ const scene = scenes[idx];
+ const unused = (take) => take?.takeId && TAKE_SLOT[take.kind] && take.status !== 'rejected' && scene[TAKE_SLOT[take.kind]] !== take.assetId;
+ const takes = Array.isArray(scene.takes) ? scene.takes : [];
+ const rejected = takes.filter(unused).length;
+ if (!rejected) return { project, scene, rejected };
+ const next = { ...scene, takes: takes.map((take) => (unused(take) ? { ...take, status: 'rejected' } : take)) };
+ return { project: replaceScene(project, idx, next), scene: next, rejected };
+}
+
export function reviewSceneTake(project, sceneId, takeId, { status, note }) {
const { idx, scene, takes, take } = locateTake(project, sceneId, takeId);
const updated = {
diff --git a/server/services/musicVideo/takes.test.js b/server/services/musicVideo/takes.test.js
index 44f4b9161b..1d479524d2 100644
--- a/server/services/musicVideo/takes.test.js
+++ b/server/services/musicVideo/takes.test.js
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { appendSceneTakes } from './takes.js';
+import { appendSceneTakes, rejectUnusedTakes } from './takes.js';
import { captureMusicVideoEvidence, captureTakeDependencies } from '../../lib/musicVideoDependencies.js';
const project = () => ({ id: 'mv-1', scenes: [{ sceneId: 's1' }] });
@@ -72,3 +72,21 @@ describe('a clip made toward an end frame (#11173)', () => {
expect(scene.takes.at(-1).status).toBe('candidate');
});
});
+
+describe('reject unused takes', () => {
+ // Uniquely catches finalizing a shot touching its selection or a take that is in use.
+ it('rejects every take not in use, keeping the selection, notes and the takes already rejected', () => {
+ const take = (takeId, kind, assetId, extra = {}) => ({ takeId, kind, assetId, status: 'candidate', note: null, ...extra });
+ const scene = { sceneId: 's1', referenceImageId: 'a.png', endImageId: null, videoHistoryId: 'v2',
+ takes: [take('t1', 'image', 'a.png'), take('t2', 'image', 'b.png', { note: 'too dark' }), take('t3', 'endImage', 'e.png'),
+ take('t4', 'video', 'v1', { status: 'rejected' }), take('t5', 'video', 'v2'), take('t6', 'video', 'v3')] };
+ const { project, scene: next, rejected } = rejectUnusedTakes({ scenes: [scene] }, 's1');
+ expect(rejected).toBe(3);
+ expect(next.takes.map((t) => [t.takeId, t.status])).toEqual([['t1', 'candidate'], ['t2', 'rejected'], ['t3', 'rejected'],
+ ['t4', 'rejected'], ['t5', 'candidate'], ['t6', 'rejected']]);
+ expect(next.takes[1].note).toBe('too dark');
+ expect([next.referenceImageId, next.endImageId, next.videoHistoryId]).toEqual(['a.png', null, 'v2']);
+ expect(project.scenes[0].takes).toEqual(next.takes);
+ expect(rejectUnusedTakes(project, 's1').rejected).toBe(0);
+ });
+});