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

fix([issue-11629]): save the displayed storyboard frame (#11631)

[._.]/8bb141e7e2c7
diff --git a/client/src/components/musicVideo/FrameStepper.jsx b/client/src/components/musicVideo/FrameStepper.jsx
index a022121825..b0f09bd88e 100644
--- a/client/src/components/musicVideo/FrameStepper.jsx
+++ b/client/src/components/musicVideo/FrameStepper.jsx
@@ -40,8 +40,8 @@ const inputCls = 'min-h-[44px] rounded border border-port-border bg-port-bg px-1
* Frame-by-frame controls for a preview player: step back or forward by a
* chosen number of frames, type a song frame number to jump to it, and read its
* timecode. `onSeek(songSec)` must pause the player and move it. With
- * `capture` (an async function giving the frame on screen as an image blob),
- * Save frame puts that picture in the image gallery. `keys` binds "," and "."
+ * `capture` (an async function returning a blob or `{ blob, time, fps, label }`),
+ * Save frame puts that picture in the image gallery. Metadata identifies the frozen frame. `keys` binds "," and "."
* on the page to the step buttons.
*/
export default function FrameStepper({ time, onSeek, fps = PREVIEW_FPS, maxSec = null, disabled = false, keys = false, capture = null, label = '', className = '' }) {
@@ -73,12 +73,15 @@ export default function FrameStepper({ time, onSeek, fps = PREVIEW_FPS, maxSec =
}, [keys]);
const save = async () => {
setSaving(true);
- const blob = await capture().catch(() => null);
+ let captureError = null;
+ const captured = await capture().catch((error) => { captureError = error; return null; });
+ const blob = captured?.blob ?? captured;
const saved = blob ? await uploadGalleryImage(blob, { silent: true }).catch(() => null) : null;
setSaving(false);
- const name = [label, `frame ${frame}`].filter(Boolean).join(' · ');
+ const capturedFrame = Number.isFinite(captured?.time) ? frameAt(captured.time, captured.fps || fps) : frame;
+ const name = [captured?.label ?? label, `frame ${capturedFrame}`].filter(Boolean).join(' · ');
if (saved?.filename) toast.success(`Saved ${name} to the image gallery`);
- else toast.error(`Couldn't save ${name}`);
+ else toast.error(`Couldn't save ${name}${captureError?.message ? `: ${captureError.message}` : ''}`);
};
return (
<div className={`flex min-w-0 flex-wrap items-center gap-1.5 text-[11px] text-port-text-muted ${className}`}>
diff --git a/client/src/components/musicVideo/FrameStepper.test.jsx b/client/src/components/musicVideo/FrameStepper.test.jsx
index c0be8147c6..18f1384531 100644
--- a/client/src/components/musicVideo/FrameStepper.test.jsx
+++ b/client/src/components/musicVideo/FrameStepper.test.jsx
@@ -6,9 +6,10 @@ const uploadGalleryImage = vi.fn(async () => ({ filename: 'upload-1234abcd.png'
vi.mock('../../services/apiSystem.js', () => ({ uploadGalleryImage: (...args) => uploadGalleryImage(...args) }));
const toastSuccess = vi.fn();
-vi.mock('../ui/Toast', () => ({ default: { success: (...args) => toastSuccess(...args), error: vi.fn() } }));
+const toastError = vi.fn();
+vi.mock('../ui/Toast', () => ({ default: { success: (...args) => toastSuccess(...args), error: (...args) => toastError(...args) } }));
-afterEach(() => { uploadGalleryImage.mockClear(); toastSuccess.mockClear(); });
+afterEach(() => { uploadGalleryImage.mockClear(); toastSuccess.mockClear(); toastError.mockClear(); });
describe('frame math', () => {
it('numbers song frames and seeks to the middle of one', () => {
@@ -45,4 +46,21 @@ describe('FrameStepper', () => {
expect(uploadGalleryImage).toHaveBeenCalledWith(blob, { silent: true });
expect(toastSuccess).toHaveBeenCalledWith('Saved Example Song · Shot 2 · frame 48 to the image gallery');
});
+
+ it('names the frozen audio frame and reports capture or upload failures without success', async () => {
+ const blob = new Blob(['png'], { type: 'image/png' });
+ const capture = vi.fn(async () => ({ blob, time: 3, fps: 24, label: 'Shot 2' }));
+ render(<FrameStepper time={0} onSeek={vi.fn()} capture={capture} />);
+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: /Save frame/ })); });
+ expect(toastSuccess).toHaveBeenCalledWith('Saved Shot 2 · frame 72 to the image gallery');
+ toastSuccess.mockClear(); uploadGalleryImage.mockClear();
+ capture.mockRejectedValueOnce(new Error('Missing layer'));
+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: /Save frame/ })); });
+ expect(uploadGalleryImage).not.toHaveBeenCalled();
+ expect(toastError).toHaveBeenCalledWith("Couldn't save frame 0: Missing layer");
+ uploadGalleryImage.mockRejectedValueOnce(new Error('Upload failed'));
+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: /Save frame/ })); });
+ expect(toastError).toHaveBeenLastCalledWith("Couldn't save Shot 2 · frame 72");
+ expect(toastSuccess).not.toHaveBeenCalled();
+ });
});
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.jsx b/client/src/components/musicVideo/StoryboardAnimatic.jsx
index 736cb45967..03c3e2ce11 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.jsx
@@ -1,6 +1,7 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import FilmLookFrame from '../media/FilmLookFrame.jsx';
import { safeReadStorage, safeWriteStorage } from '../../lib/safeStorage.js';
+import { uuidv4 } from '../../lib/uuid.js';
import { isFilmLookNeutral } from '../../lib/filmLook.js';
import { Captions, Film, Scissors } from 'lucide-react';
import { formatDurationSec } from '../../utils/formatters.js';
@@ -13,7 +14,8 @@ import { normalizeTitleCard } from '../../../../server/lib/musicVideoTitleCard.j
import { normalizeStatsOutro, statsOutroSeconds } from '../../../../server/lib/musicVideoStatsOutro.js';
import StatsOutroCanvas from './StatsOutroCanvas.jsx';
import ShotStepper from './ShotStepper.jsx';
-import FrameStepper, { captureMediaFrame } from './FrameStepper.jsx';
+import FrameStepper from './FrameStepper.jsx';
+import { capturePreviewFrame, lyricFrameCaptureBridge } from '../../lib/musicVideoFrameCapture.js';
import { sceneFrameFit } from './SceneFrameFit.jsx';
import TransitionGlitch from './TransitionGlitch.jsx';
import ImageEffectStill from './ImageEffectStill.jsx';
@@ -54,6 +56,7 @@ function useLyricOverlay({ project, enabled, audioRef, time }) {
const [preview, setPreview] = useState(null);
const [failed, setFailed] = useState(false);
const iframeRef = useRef(null);
+ const captureRef = useRef(null);
const seekState = useRef({ inFlight: false, pending: null, ready: false, sentAt: 0 });
const version = enabled ? playthroughVersion(project) : null;
// The opening title card rides on the lyric layer, posted live so its panel's edits show at once.
@@ -66,6 +69,7 @@ function useLyricOverlay({ project, enabled, audioRef, time }) {
useEffect(() => {
let active = true;
+ captureRef.current?.reject(new Error('Lyric preview changed'));
setPreview(null);
setFailed(false);
seekState.current = { inFlight: false, pending: null, ready: false, sentAt: 0 };
@@ -73,7 +77,7 @@ function useLyricOverlay({ project, enabled, audioRef, time }) {
getMusicVideoLyricOverlayPreview(project.id, { silent: true })
.then((next) => { if (active) setPreview(next); })
.catch(() => { if (active) setFailed(true); });
- return () => { active = false; };
+ return () => { active = false; captureRef.current?.reject(new Error('Lyric preview changed')); };
}, [project.id, version]);
const postSeek = useCallback((t) => {
@@ -103,7 +107,17 @@ function useLyricOverlay({ project, enabled, audioRef, time }) {
} else if (message.type === 'portos-mv:seeked') {
state.inFlight = false;
if (state.pending != null) { const next = state.pending; state.pending = null; postSeek(next); }
+ else if (captureRef.current?.t === message.t) {
+ const capture = captureRef.current;
+ event.source.postMessage({ type: 'portos-mv:capture-lyrics', id: capture.id, t: capture.t }, '*');
+ }
+ } else if (message.type === 'portos-mv:captured-lyrics') {
+ const capture = captureRef.current;
+ if (!capture || message.id !== capture.id || message.t !== capture.t) return;
+ if (message.error || typeof message.png !== 'string' || message.png.length > 24000000 || !/^data:image\/png;base64,[A-Za-z0-9+/=]+$/.test(message.png)) capture.reject(new Error('Lyric frame unavailable'));
+ else capture.resolve(message.png);
} else if (message.type === 'portos-mv:error') {
+ captureRef.current?.reject(new Error('Lyric frame unavailable'));
setFailed(true);
}
};
@@ -136,15 +150,26 @@ function useLyricOverlay({ project, enabled, audioRef, time }) {
};
}, [preview, postSeek, audioRef]);
- if (!preview?.html || failed) return { overlay: null, failed };
+ const capture = (t) => new Promise((resolve, reject) => {
+ if (!seekState.current.ready || failed || !iframeRef.current) { reject(new Error('Lyric frame unavailable')); return; }
+ const id = uuidv4();
+ const finish = (done, result) => { clearTimeout(timer); captureRef.current = null; done(result); };
+ const timer = setTimeout(() => finish(reject, new Error('Lyric capture timed out')), 5000);
+ captureRef.current = { id, t, resolve: (png) => finish(resolve, png), reject: (error) => finish(reject, error) };
+ // The existing serialized seek bridge finishes the requested song time first.
+ seekState.current.pending = null;
+ postSeek(t);
+ });
+ if (!preview?.html || failed) return { overlay: null, failed, capture };
return {
failed,
+ capture,
overlay: (
<iframe
ref={iframeRef}
title="Lyrics over the storyboard animatic"
sandbox="allow-scripts"
- srcDoc={preview.html}
+ srcDoc={`${preview.html}<script>(${lyricFrameCaptureBridge.toString()})();</script>`}
// `color-scheme: normal` keeps the frame transparent under a dark parent page.
style={{ colorScheme: 'normal' }}
className="pointer-events-none absolute inset-0 h-full w-full border-0 bg-transparent"
@@ -477,6 +502,7 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
const [lookOn, setLookOn] = useState(() => safeReadStorage(ANIMATIC_LOOK_KEY) !== 'off');
// While the song plays the look is the light playback version; paused, the exact render filter.
const [playing, setPlaying] = useState(false);
+ const captureBasis = useRef(null);
const lookAvailable = !isFilmLookNeutral(project.filmLook);
const toggleLook = () => setLookOn((on) => { safeWriteStorage(ANIMATIC_LOOK_KEY, on ? 'off' : 'on'); return !on; });
const scenes = project.scenes || [];
@@ -487,7 +513,7 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
const leadFile = useVideoFileSrc(layered ? lead?.videoHistoryId : null, { geometry: true });
const stillFps = leadFile.fps || ANIMATIC_FPS;
const lyricsAvailable = hasTimedLyrics(project);
- const { overlay, failed } = useLyricOverlay({ project, enabled: lyricsAvailable && lyricsOn, audioRef, time });
+ const { overlay, failed, capture: captureLyrics } = useLyricOverlay({ project, enabled: lyricsAvailable && lyricsOn, audioRef, time });
// The cutting room floor outro: it plays when the song ends, and Ending plays it straight away; playing or seeking the song leaves it.
const outro = useMusicVideoStatsOutro({ projectId: project.id, seconds: statsOutroSeconds(project.statsOutro), audioRef });
const outroLook = useMemo(() => normalizeStatsOutro(project.statsOutro), [project.statsOutro]);
@@ -512,11 +538,45 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
}, [seekTo]);
// Edit shot pauses the song so the shot stays on screen while its card opens.
const editShot = onEditShot ? (sceneId) => { audioRef.current?.pause?.(); onEditShot(sceneId); } : null;
- // Save frame keeps the shot's picture: its clip's frame once that shows, else its still.
- const captureFrame = () => {
- const figure = figureRef.current;
- const media = figure?.querySelector('video[data-ready="true"]:not([aria-hidden="true"])') || figure?.querySelector('img');
- return captureMediaFrame(media);
+ captureBasis.current = { project, lyricsOn, lookOn, outro: outro.active, outroTime: outro.t, outroStats: outro.stats };
+ const captureFrame = async () => {
+ const basis = captureBasis.current;
+ const audio = audioRef.current;
+ audio?.pause();
+ outro.pause();
+ const at = audio?.currentTime || 0;
+ setTime(at);
+ setPlaying(false);
+ // Pause swaps the live film look for its exact filter and catches the shot up
+ // to the audio clock. Effects/clip seeks then get a paint before freezing.
+ await new Promise((resolve, reject) => {
+ let handle;
+ const timer = setTimeout(() => { cancelAnimationFrame(handle); reject(new Error('Preview did not settle')); }, 2000);
+ handle = requestAnimationFrame(() => { handle = requestAnimationFrame(() => { clearTimeout(timer); resolve(); }); });
+ });
+ const unchanged = () => {
+ const current = captureBasis.current;
+ return current.project === basis.project && current.lyricsOn === basis.lyricsOn && current.lookOn === basis.lookOn
+ && current.outro === basis.outro && current.outroTime === basis.outroTime && current.outroStats === basis.outroStats
+ && audio?.paused && audio.currentTime === at;
+ };
+ if (!unchanged()) throw new Error('Preview changed during capture');
+ const selected = shotAt(scenes, at);
+ if (!basis.outro && selected?.videoHistoryId && sceneVisualLayer(selected, { layered }) === 'footage') {
+ const figure = figureRef.current;
+ const clip = figure?.querySelector('video[data-ready="true"]:not([aria-hidden="true"])');
+ const fallback = [...(figure?.querySelectorAll('img') || [])].find((image) => image.getAttribute('src') === `/data/images/${selected.referenceImageId}` && image.complete && image.naturalWidth > 0);
+ if (!clip && !fallback) throw new Error('Video frame is still loading');
+ }
+ if (lyricsAvailable && lyricsOn && !overlay) throw new Error('Lyric frame unavailable');
+ const iframeImages = new Map();
+ const iframe = figureRef.current?.querySelector('iframe');
+ if (iframe) iframeImages.set(iframe, await captureLyrics(at));
+ if (!unchanged()) throw new Error('Preview changed during capture');
+ const blob = await capturePreviewFrame(figureRef.current?.firstElementChild, { iframeImages });
+ if (!unchanged()) throw new Error('Preview changed during capture');
+ const shotLabel = basis.outro ? 'Ending' : `Shot ${timedShots(scenes).indexOf(selected) + 1}`;
+ return { blob, time: at, fps: ANIMATIC_FPS, label: [project.name, shotLabel].filter(Boolean).join(' · ') };
};
// Cut effects (beat toggles, dissolves, fades through black), on the frames the final
// render paints them (lib/musicVideoCutEffects.js), storyboard-planned ones included.
@@ -549,7 +609,7 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
<figure ref={figureRef} aria-label="Storyboard animatic" className="relative aspect-video w-full overflow-hidden rounded border border-port-border bg-black">
{/* The project's film look, as the final render applies it over the whole picture, lyrics included. */}
<FilmLookFrame look={lookOn ? project.filmLook : null} frame={Math.round((outro.active ? songEndSec + outro.t : time) * ANIMATIC_FPS)}
- playing={playing || (outro.active && outro.t < outro.seconds)} className="h-full w-full">
+ playing={playing || (outro.active && !outro.paused && outro.t < outro.seconds)} className="h-full w-full">
{shot?.referenceImageId && stillShot ? (
<StillShot key={shot.sceneId} scene={shot} audioRef={audioRef} time={time} fps={stillFps} effect={shotEffect} />
) : shot?.referenceImageId ? (
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
index 0e717a489c..aaabf2c7b2 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
@@ -203,11 +203,6 @@ describe('StoryboardAnimatic lyrics', () => {
});
});
-const uploadGalleryImage = vi.hoisted(() => vi.fn(async () => ({ filename: 'upload-1234abcd.png' })));
-vi.mock('../../services/apiSystem.js', () => ({ uploadGalleryImage }));
-// Save frame hands over the element it would draw, so the test sees which picture it picked.
-vi.mock('./FrameStepper.jsx', async (importOriginal) => ({ ...(await importOriginal()), captureMediaFrame: async (el) => el }));
-
vi.mock('../../services/apiImageVideo.js', () => ({
getVideoHistoryItem: vi.fn(async (id) => ({ id, filename: `${id}.mov` })),
}));
@@ -401,17 +396,6 @@ describe('StoryboardAnimatic clips', () => {
expect(onEditShot).toHaveBeenCalledWith(stills[1].sceneId);
});
- it('saves the shot\'s still, then its clip once that shows', async () => {
- render(<StoryboardAnimatic project={{ id: 'p', name: 'Example Song', scenes: clipScenes }} audioUrl="/song.mp3" />);
- const clip = await screen.findByLabelText('Clip for Opening');
- await act(async () => { fireEvent.click(screen.getByRole('button', { name: /Save frame/ })); });
- expect(uploadGalleryImage.mock.lastCall[0].tagName).toBe('IMG');
- Object.defineProperty(clip, 'readyState', { value: 4, configurable: true });
- fireEvent.loadedData(clip);
- await act(async () => { fireEvent.click(screen.getByRole('button', { name: /Save frame/ })); });
- expect(uploadGalleryImage.mock.lastCall[0]).toBe(clip);
- });
-
it('moves a paused clip to the exact frame on each frame step', async () => {
render(<StoryboardAnimatic project={{ id: 'p', scenes: clipScenes }} audioUrl="/song.mp3" />);
const clip = await screen.findByLabelText('Clip for Opening');
diff --git a/client/src/hooks/README.md b/client/src/hooks/README.md
index d55657a5ed..431c3b324c 100644
--- a/client/src/hooks/README.md
+++ b/client/src/hooks/README.md
@@ -266,7 +266,7 @@ grep -i "what you want to do" client/src/hooks/README.md
| `useMusicVideoProduction` | Server-owned production run (#9066): start a browserless plan → frames → clips → reviewed-draft run with an allowed provider/model pool and explicit limits, and Stop / Resume / Cancel it; applies the project pushed on `music-video:production` and toasts terminal outcomes. Returns `{ busy, start(body), resume(runId, body?), stop(runId), cancel(runId) }`. | The Music Video production panel. |
| `useMusicVideoRenderJob` | The final-render job (#1760 Phase 2): kickoff (409 → attach to the existing job), SSE progress, terminal-frame handling and non-terminal stream-close recovery. Thin `useSseJobSlot` adapter with 0–1 progress conversion; returns `{ active, pending, context, job, progress, start(projectId), cancel, reattach(projectId), reattaching }`; a project the server marks `rendering` re-attaches on load through a READ of the live job (`GET /:id/render`), never a POST (#9940); `onSettled(reason, projectId)` fires on every terminal frame; `onRendered(projectId, result)` / `onFailed(projectId)` key on the projectId captured at kickoff. | The Music Video "Render final" control. |
| `useMusicVideoShotRenders` | The composed final render's per-shot segment cache: `GET /:id/shot-renders` re-read as render inputs change (debounced) and when a shot render settles, plus live `music-video:shot-render` progress per shot. Returns `{ status, live, markLive(sceneId, entry), refresh }`; `status` is null outside the composed render style. | The shot card's Final render section and the Render final control. |
-| `useMusicVideoStatsOutro` | The cutting room floor outro's clock: `start()` plays it for `seconds` on its own rAF clock and fetches the tally afresh; with `audioRef` it also starts when the song ends; a new project or length stops it. Returns `{ seconds, t, stats, active, start, stop }`. | The storyboard animatic's ending and the board's Ending card. |
+| `useMusicVideoStatsOutro` | The cutting room floor outro's clock: `start()` plays it for `seconds` on its own rAF clock and fetches the tally afresh; with `audioRef` it also starts when the song ends; a new project or length stops it. Returns `{ seconds, t, stats, active, paused, start, stop, pause }`; `pause` freezes the displayed outro for frame capture. | The storyboard animatic's ending and the board's Ending card. |
| `useMusicVideoRevisions` | Selective section revision (#8987): open a revision from a reviewed draft excerpt (its flagged sections' takes are rejected, the rest kept), resume it from the server checkpoint — generating ONLY the sections the server reports as `needsGeneration` through the board's scene lanes, or adopting the draft re-render via `attachRender` once every revised section has a take — and cancel it. A server refusal toasts as a failure; a throw in the hook's own follow-up AFTER the server succeeded reloads the saved record instead (#9940), so an opened repair whose resume failed stays recoverable from the "Needs attention" banner. Returns `{ busy, revise(excerptId, sceneIds?), repair(basis), repairPerformance(sceneId, input), resume(revisionId), cancel(revisionId) }`. | The Music Video excerpt panel. |
| `useMusicVideoAutoReview` | Opt-in automatic review/retries (#8988): start a run over a draft window with explicit review (`maxAttempts`) and paid-generation (`maxGenerations`) limits plus a vision reviewer; applies the project pushed on `music-video:auto-review` and reports outcomes; the server generates a run's revised sections itself (#10014), so the board never submits them and a run completes with no tab open. Returns `{ busy, action, start(startSec, endSec, limits, reviewer), resume(runId, limits?), stop(runId), cancel(runId) }`. | The Music Video excerpt panel. |
| `useMusicVideoExcerpts` | Draft excerpt render + timecoded review notes (#8986): a `useSseJobSlot` render job over a chosen `[startSec, endSec)` window (any terminal frame reloads the project, since the persisted excerpt shape lives server-side) plus add/edit/delete review-note calls that apply the fresh whole project from each response. Returns `{ rendering, progress, deletingId, noteBusyId, startExcerpt(startSec, endSec), cancelExcerpt(excerptId), attachRender(jobId, projectId), deleteExcerpt(excerptId), addNote(excerptId, {atSec, note, verdict?}), editNote(excerptId, noteId, patch), deleteNote(excerptId, noteId) }`. | The Music Video excerpt panel. |
diff --git a/client/src/hooks/useMusicVideoStatsOutro.js b/client/src/hooks/useMusicVideoStatsOutro.js
index faa0f18a04..374cfcc9c4 100644
--- a/client/src/hooks/useMusicVideoStatsOutro.js
+++ b/client/src/hooks/useMusicVideoStatsOutro.js
@@ -6,24 +6,28 @@ import { getMusicVideoOutroStats } from '../services/apiMusicVideo.js';
* plays it for `seconds` on a clock of its own and fetches the tally afresh, so
* it counts the latest choices; it holds on its last frame once it has run.
* With `audioRef`, it also starts when that song ends. A different project or
- * length stops it. Returns `{ seconds, t, stats, active, start, stop }`
+ * length stops it. Returns `{ seconds, t, stats, active, paused, start, stop, pause }`
* (`t` null while it is off screen).
*/
export default function useMusicVideoStatsOutro({ projectId, seconds, audioRef = null }) {
const [t, setT] = useState(null);
const [stats, setStats] = useState(null);
+ const [paused, setPaused] = useState(false);
const run = useRef({ handle: 0, startedAt: 0, generation: 0 });
const stop = useCallback(() => {
cancelAnimationFrame(run.current.handle);
run.current.generation += 1;
setT(null);
+ setPaused(false);
}, []);
+ const pause = useCallback(() => { cancelAnimationFrame(run.current.handle); setPaused(true); }, []);
const start = useCallback(() => {
if (!(seconds > 0)) return;
cancelAnimationFrame(run.current.handle);
const generation = ++run.current.generation;
run.current.startedAt = performance.now();
setT(0);
+ setPaused(false);
getMusicVideoOutroStats(projectId, { silent: true })
.then((next) => { if (run.current.generation === generation) setStats(next?.stats || null); })
.catch(() => {});
@@ -43,5 +47,5 @@ export default function useMusicVideoStatsOutro({ projectId, seconds, audioRef =
audio.addEventListener('ended', start);
return () => audio.removeEventListener('ended', start);
}, [audioRef, seconds, start]);
- return { seconds, t, stats, active: t != null, start, stop };
+ return { seconds, t, stats, active: t != null, paused, start, stop, pause };
}
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index 885422e880..d55c568cbc 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -321,3 +321,4 @@ grep -i "what you want to do" client/src/lib/README.md
| `musicVideoCutEffects.js` | Music-video cut effects (beat toggle, dissolve, fade through black across a cut), re-exported from `server/lib/musicVideoCutEffects.js`: settings, labels, `sceneCutEffect`, `sceneCutEffects`, `plannedTransitions`. Used by `components/musicVideo/SceneCutEffect.jsx` and the storyboard animatic. |
| `musicVideoTransitions.js` | Music-video cut transitions (VHS glitches over a cut), re-exported from `server/lib/musicVideoTransitions.js`: the styles and labels, `sceneTransitionSections`, `transitionGlitchFrames`, `transitionFrameAt`, in-shot glitches (`sceneShotGlitchFrames`), `blockBox` and `edgeGlows` for painting. Used by `components/musicVideo/SceneTransitions.jsx`, `SceneGlitches.jsx` and the storyboard animatic. |
| `musicVideoShotEffects.js` | Music-video shot effects at a glance: `shotEffects` (a shot's start / mid-shot / end effects, read through the render's own transition, image-effect and cut-effect helpers) and `shotEffectCounts` (every effect option's use per slot, zeros included). Used by the Shots board's card badges and its Effects card. |
+| `musicVideoFrameCapture.js` | `capturePreviewFrame` freezes the displayed animatic DOM, decoded media and canvas layers into an inert SVG and PNG with actual fitting, transforms and film look; `lyricFrameCaptureBridge` captures the known sandboxed lyric/title canvas layers after an acknowledged seek. Fails on missing, tainted or unsupported layers. |
diff --git a/client/src/lib/index.js b/client/src/lib/index.js
index 0751a06db0..2601fa5ce0 100644
--- a/client/src/lib/index.js
+++ b/client/src/lib/index.js
@@ -70,6 +70,7 @@ export * from './musicDuration.js';
export * from './muscriptorModels.js';
export * from './musicVideoBatchPlan.js';
export * from './musicVideoLayers.js';
+export * from './musicVideoFrameCapture.js';
export * from './musicVideoAspect.js';
export * from './musicVideoFiling.js';
export * from './musicVideoMotion.js';
diff --git a/client/src/lib/musicVideoFrameCapture.js b/client/src/lib/musicVideoFrameCapture.js
new file mode 100644
index 0000000000..4107ea3ddf
--- /dev/null
+++ b/client/src/lib/musicVideoFrameCapture.js
@@ -0,0 +1,128 @@
+/**
+ * Freeze the actual preview tree, including CSS fitting/transforms and SVG filters.
+ * Media becomes decoded pixels before async rasterization, so a later seek cannot
+ * replace the selected frame. The resulting SVG is used only as an inert image.
+ */
+export async function capturePreviewFrame(root, { iframeImages = new Map() } = {}) {
+ if (!root) throw new Error('Preview unavailable');
+ const box = root.getBoundingClientRect();
+ const width = Math.ceil(box.width);
+ const height = Math.ceil(box.height);
+ if (!width || !height || width * height > 16777216) throw new Error('Preview size unavailable');
+ const raster = (source, w, h) => {
+ if (!w || !h) throw new Error('Preview media has not decoded');
+ const canvas = document.createElement('canvas');
+ const scale = Math.min(1, Math.sqrt(16777216 / (w * h)));
+ canvas.width = Math.max(1, Math.round(w * scale)); canvas.height = Math.max(1, Math.round(h * scale));
+ const ctx = canvas.getContext('2d');
+ if (!ctx) throw new Error('Frame capture unavailable');
+ ctx.drawImage(source, 0, 0, canvas.width, canvas.height);
+ return canvas.toDataURL('image/png');
+ };
+ const freeze = (node) => {
+ if (node.nodeType === Node.TEXT_NODE) return node.cloneNode();
+ if (node.nodeType !== Node.ELEMENT_NODE || ['SCRIPT', 'STYLE', 'LINK', 'NOSCRIPT'].includes(node.tagName)) return null;
+ const style = getComputedStyle(node);
+ const hidden = style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0
+ || (node.tagName === 'VIDEO' && node.getAttribute('aria-hidden') === 'true');
+ const media = ['IMG', 'VIDEO', 'CANVAS', 'IFRAME'].includes(node.tagName);
+ const copy = media ? document.createElement(hidden ? 'div' : 'img') : node.cloneNode(false);
+ for (const attribute of [...copy.attributes]) {
+ if (/^on/i.test(attribute.name)) copy.removeAttribute(attribute.name);
+ }
+ for (const property of style) {
+ // Computed local SVG filter URLs include the live document's address.
+ const value = style.getPropertyValue(property).replace(/url\(["']?[^)"']*#([^)"']+)["']?\)/g, 'url(#$1)');
+ copy.style.setProperty(property, value);
+ }
+ copy.style.animation = 'none'; copy.style.transition = 'none';
+ if (hidden) return copy;
+ if (media) {
+ if (node.tagName === 'IFRAME') {
+ const png = iframeImages.get(node);
+ if (!png) throw new Error('Lyric frame unavailable');
+ copy.src = png;
+ } else if (node.tagName === 'VIDEO') {
+ if (node.readyState < 2 || node.seeking) throw new Error('Video frame is still loading');
+ copy.src = raster(node, node.videoWidth, node.videoHeight);
+ } else if (node.tagName === 'CANVAS') copy.src = raster(node, node.width, node.height);
+ else {
+ if (!node.complete) throw new Error('Image frame is still loading');
+ copy.src = raster(node, node.naturalWidth, node.naturalHeight);
+ }
+ return copy;
+ }
+ for (const child of node.childNodes) {
+ const frozen = freeze(child);
+ if (frozen) copy.appendChild(frozen);
+ }
+ return copy;
+ };
+ const frozen = freeze(root);
+ frozen.style.position = 'relative'; frozen.style.margin = '0';
+ frozen.style.left = '0'; frozen.style.top = '0';
+ frozen.style.width = `${box.width}px`; frozen.style.height = `${box.height}px`;
+ const markup = new XMLSerializer().serializeToString(frozen);
+ // The extra column proves foreignObject actually rendered; unsupported browsers
+ // must fail rather than upload a valid but blank PNG. It is cropped from output.
+ const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width + 1}" height="${height}"><foreignObject width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:${width + 1}px;height:${height}px">${markup}<div style="position:absolute;left:${width}px;bottom:0;width:1px;height:1px;background:rgb(13,231,97)"></div></div></foreignObject></svg>`;
+ const image = new Image();
+ image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+ let timer;
+ try {
+ await Promise.race([image.decode(), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Frame capture timed out')), 5000); })]);
+ } catch (error) { image.src = ''; throw error; }
+ finally { clearTimeout(timer); }
+ const canvas = document.createElement('canvas');
+ canvas.width = width + 1; canvas.height = height;
+ const ctx = canvas.getContext('2d');
+ if (!ctx) throw new Error('Frame capture unavailable');
+ ctx.drawImage(image, 0, 0);
+ const probe = ctx.getImageData(width, height - 1, 1, 1).data;
+ if (probe[0] !== 13 || probe[1] !== 231 || probe[2] !== 97 || probe[3] !== 255) throw new Error('This browser cannot capture the preview');
+ const output = document.createElement('canvas');
+ output.width = width; output.height = height;
+ const paint = output.getContext('2d');
+ if (!paint) throw new Error('Frame capture unavailable');
+ // The figure's black ground sits outside the film-look filter.
+ paint.fillStyle = '#000'; paint.fillRect(0, 0, width, height);
+ paint.drawImage(canvas, 0, 0);
+ const blob = await new Promise((resolve) => output.toBlob(resolve, 'image/png'));
+ if (!blob) throw new Error('Frame capture failed');
+ return blob;
+}
+
+/** Capture-only bridge for the known canvas-based lyric overlay, including its title card. */
+export function lyricFrameCaptureBridge() {
+ addEventListener('message', (event) => {
+ const request = event.data;
+ if (event.source !== parent || request?.type !== 'portos-mv:capture-lyrics'
+ || typeof request.id !== 'string' || request.id.length > 100 || !Number.isFinite(request.t)) return;
+ try {
+ const output = document.createElement('canvas');
+ output.width = innerWidth; output.height = innerHeight;
+ if (!output.width || !output.height || output.width * output.height > 16777216) throw new Error('Invalid lyric frame');
+ const ctx = output.getContext('2d');
+ const layers = [...document.querySelectorAll('canvas')];
+ if (!ctx || !layers.length) throw new Error('Lyric frame unavailable');
+ for (const canvas of layers) {
+ const style = getComputedStyle(canvas);
+ if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0) continue;
+ const box = canvas.getBoundingClientRect();
+ ctx.globalAlpha = Number(style.opacity);
+ const scale = style.objectFit === 'contain' ? Math.min(box.width / canvas.width, box.height / canvas.height)
+ : style.objectFit === 'cover' ? Math.max(box.width / canvas.width, box.height / canvas.height) : null;
+ const width = scale == null ? box.width : canvas.width * scale;
+ const height = scale == null ? box.height : canvas.height * scale;
+ ctx.save(); ctx.beginPath(); ctx.rect(box.left, box.top, box.width, box.height); ctx.clip();
+ ctx.drawImage(canvas, box.left + (box.width - width) / 2, box.top + (box.height - height) / 2, width, height);
+ ctx.restore();
+ }
+ const png = output.toDataURL('image/png');
+ if (png.length > 24000000) throw new Error('Lyric frame is too large');
+ parent.postMessage({ type: 'portos-mv:captured-lyrics', id: request.id, t: request.t, png }, '*');
+ } catch {
+ parent.postMessage({ type: 'portos-mv:captured-lyrics', id: request.id, t: request.t, error: true }, '*');
+ }
+ });
+}
diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.js
index 540eeadb1e..f93e3c2a50 100644
--- a/scripts/ci-test-plan.js
+++ b/scripts/ci-test-plan.js
@@ -45,6 +45,7 @@ export const BROWSER_SUITES = [
'server/routes/musicVideoRichAuthoring.browser.test.js',
'server/routes/musicVideoSongRevision.browser.test.js',
'server/services/federatedMedia/sourceAudio.browser.test.js',
+ 'server/services/musicVideo/animaticCapture.browser.test.js',
'server/services/musicVideo/documentRender.browser.test.js',
'server/services/musicVideo/documentTemplates/layered/engine.overlay.browser.test.js',
'server/services/musicVideo/documentTemplates/shared/lyricType.browser.test.js',
diff --git a/scripts/ci-test-plan.test.js b/scripts/ci-test-plan.test.js
index 78fda2f396..e33ff1c1f1 100644
--- a/scripts/ci-test-plan.test.js
+++ b/scripts/ci-test-plan.test.js
@@ -1536,6 +1536,18 @@ it('projects transitive browser consumers through the planner CLI without replac
describe('cross-workspace browser suites (#10312)', () => {
+ it('selects animatic pixel coverage when only the compositor or Save frame control changes', () => {
+ const cwd = fileURLToPath(new URL('../', import.meta.url));
+ const suite = 'server/services/musicVideo/animaticCapture.browser.test.js';
+ for (const source of ['client/src/lib/musicVideoFrameCapture.js', 'client/src/components/musicVideo/FrameStepper.jsx']) {
+ const inputs = collectPlanInputs({ baseSha: 'HEAD', changedFiles: [source], cwd });
+ const trackedFiles = inputs.trackedFiles.filter((path) => !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path) || BROWSER_SUITES.includes(path));
+ const plan = buildCiTestPlan(inputs.changedFiles, { ...inputs, trackedFiles });
+ expect(plan.full).toBe(false);
+ expect(plan.browserFiles).toContain(suite);
+ }
+ });
+
it('selects every music-video browser suite when a client component they mount changes', () => {
const cwd = fileURLToPath(new URL('../', import.meta.url));
const source = 'client/src/components/musicVideo/ProductionReviewPanel.jsx';
diff --git a/server/services/musicVideo/animaticCapture.browser.test.js b/server/services/musicVideo/animaticCapture.browser.test.js
new file mode 100644
index 0000000000..48b7f411d2
--- /dev/null
+++ b/server/services/musicVideo/animaticCapture.browser.test.js
@@ -0,0 +1,235 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { execFileSync } from 'node:child_process';
+import express from 'express';
+import sharp from 'sharp';
+import { chromium } from 'playwright-core';
+import { startOwnedBrowserFixture } from '../../test/browserFixture.js';
+import { browserSuiteCanRun } from '../../lib/browserSuiteGate.js';
+import { findFfmpeg } from '../../lib/ffmpeg.js';
+import { filmLookPreset } from '../../lib/filmLook.js';
+import { buildLyricPlaythroughPreview } from './lyricPlaythrough.js';
+
+const client = resolve(import.meta.dirname, '../../../client');
+// Bundled StoryboardAnimatic.jsx exercises musicVideoFrameCapture.js and FrameStepper.jsx.
+// These source references are the fixture's CI dependency contract: generated JSX has no static import edge.
+const requireClient = createRequire(join(client, 'package.json'));
+let bundlers;
+try { bundlers = ['vite', '@vitejs/plugin-react', '@tailwindcss/postcss'].map((name) => requireClient.resolve(name)); }
+catch (error) { if (error.code !== 'MODULE_NOT_FOUND') throw error; }
+const chrome = [process.env.CHROME_PATH, chromium.executablePath(), '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/usr/bin/google-chrome', '/usr/bin/chromium'].find((path) => path && existsSync(path));
+const ffmpeg = await findFfmpeg();
+const canRun = browserSuiteCanRun('animatic frame capture', { Chrome: chrome, ffmpeg, 'client dependencies': bundlers });
+
+const still = { sceneId: 'still', order: 0, label: 'Example still', startSec: 0, endSec: 4, visualLayer: 'still', referenceImageId: 'grid.png', stillMove: 'hold' };
+const project = (scenes = [still], extra = {}) => ({ id: 'capture-fixture', name: 'Example capture', scenes, composition: { mode: 'composed' }, ...extra });
+let dir, server, fixture, page, lyricProject;
+const errors = [];
+afterAll(async () => {
+ await fixture?.close();
+ if (server) await new Promise((done) => server.close(done));
+ if (dir) await rm(dir, { recursive: true, force: true });
+});
+
+describe.skipIf(!canRun)('saved storyboard pixels in a real browser', () => {
+ beforeAll(async () => {
+ dir = await mkdtemp(join(tmpdir(), 'portos-animatic-capture-'));
+ await symlink(join(client, 'node_modules'), join(dir, 'node_modules'), 'dir');
+ const entry = `import React,{useState} from 'react';import{createRoot}from'react-dom/client';import Animatic from ${JSON.stringify(join(client, 'src/components/musicVideo/StoryboardAnimatic.jsx'))};import toast,{Toaster}from ${JSON.stringify(join(client, 'src/components/ui/Toast.jsx'))};
+window.uploads=[];window.captureErrors=[];const report=toast.error;toast.error=(message,...args)=>{window.captureErrors.push(message);return report(message,...args)};const realFetch=window.fetch;window.fetch=async(url,options)=>{if(url==='/api/image-gen/upload'){window.uploads.push(Array.from(new Uint8Array(await options.body.get('file').arrayBuffer())));return Response.json({filename:'synthetic.png'});}return realFetch(url,options)};
+window.gateCaptureOnce=()=>{const decode=Image.prototype.decode;window.captureDecodePending=false;let release;const pending=new Promise(done=>{release=done});window.releaseCapture=release;Image.prototype.decode=function(){Image.prototype.decode=decode;window.captureDecodePending=true;return pending.then(()=>decode.call(this))}};
+function App(){const[state,setState]=useState(null);window.show=(project,t)=>{window.captureErrors=[];setState({project,seek:{t,n:(window.seq=(window.seq||0)+1)}})};return <><main style={{width:642}}>{state&&<Animatic project={state.project} audioUrl='/song.wav' seekRequest={state.seek}/>}</main><Toaster/></>};createRoot(document.getElementById('root')).render(<App/>);`;
+ await writeFile(join(dir, 'entry.jsx'), `import ${JSON.stringify(join(client, 'src/index.css'))};\n${entry}`);
+ await writeFile(join(dir, 'index.html'), '<html><head></head><body style="margin:0"><div id="root"></div><script type="module" src="/entry.jsx"></script></body></html>');
+ const { build } = await import(bundlers[0]);
+ const { default: react } = await import(bundlers[1]);
+ const { default: tailwind } = await import(bundlers[2]);
+ await build({ configFile: false, root: dir, publicDir: join(client, 'public'), plugins: [react()], css: { postcss: { plugins: [tailwind({ base: client })] } }, build: { outDir: join(dir, 'dist'), emptyOutDir: true }, logLevel: 'warn' });
+ const grid = '<svg width="1200" height="400" xmlns="http://www.w3.org/2000/svg"><rect width="1200" height="400" fill="#164080"/><rect width="200" height="400" fill="#ff3010"/><rect x="400" width="200" height="400" fill="#20dd50"/><rect x="1000" width="200" height="400" fill="#f5cf10"/><circle cx="650" cy="100" r="50" fill="white"/></svg>';
+ await sharp(Buffer.from(grid)).png().toFile(join(dir, 'grid.png'));
+ await sharp({ create: { width: 200, height: 400, channels: 3, background: '#ff00ff' } }).png().toFile(join(dir, 'end.png'));
+ execFileSync(ffmpeg, ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'color=c=cyan:s=120x240:r=24:d=4', '-c:v', 'libvpx', join(dir, 'clip.webm')]);
+ execFileSync(ffmpeg, ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'sine=frequency=220:duration=8', join(dir, 'song.wav')]);
+ const app = express();
+ app.get('/data/images/:id', (req, res) => res.sendFile(join(dir, req.params.id)));
+ app.get('/api/video-gen/history/:id', (req, res) => res.json({ id: req.params.id, filename: 'clip.webm', fps: 24, numFrames: 96, width: 120, height: 240 }));
+ app.get('/api/music-video/:id/stats-outro', (req, res) => res.json({ stats: { shots: 2, stills: { made: 3, kept: 1 }, clips: { made: 2, kept: 1 }, floorImages: [] } }));
+ app.get('/api/music-video/:id/lyrics/overlay/preview', async (req, res, next) => {
+ try { res.json(await buildLyricPlaythroughPreview(lyricProject, { overlay: true })); }
+ catch (error) { next(error); }
+ });
+ app.get('/data/videos/clip.webm', (req, res) => res.sendFile(join(dir, 'clip.webm')));
+ app.get('/song.wav', (req, res) => res.sendFile(join(dir, 'song.wav')));
+ app.use(express.static(join(dir, 'dist')));
+ server = await new Promise((done) => { const listener = app.listen(0, '127.0.0.1', () => done(listener)); });
+ fixture = await startOwnedBrowserFixture({ chromium, launchOptions: { executablePath: chrome, headless: true } });
+ page = await fixture.browser.newPage({ viewport: { width: 1000, height: 800 } });
+ page.on('pageerror', (error) => errors.push(error.message));
+ await page.goto(`http://127.0.0.1:${server.address().port}`);
+ await page.waitForFunction(() => typeof window.show === 'function');
+ }, 30000);
+
+ const show = async (value, t) => {
+ await page.evaluate(({ value, t }) => { window.uploads = []; window.show(value, t); }, { value, t });
+ await page.waitForFunction((t) => Math.abs(document.querySelector('audio')?.currentTime - t) < 0.00001, t);
+ await page.waitForFunction(() => [...document.querySelectorAll('figure img')].every((image) => image.complete && image.naturalWidth > 0));
+ };
+ const capture = async (label = '', { decodedVideoReference = false } = {}) => {
+ await page.getByRole('button', { name: 'Save frame', exact: true }).click();
+ await page.waitForFunction(() => window.uploads.length > 0 || window.captureErrors.length > 0);
+ expect(await page.evaluate(() => window.captureErrors), label).toEqual([]);
+ const saved = Buffer.from(await page.evaluate(() => window.uploads.at(-1)));
+ const picture = page.getByLabel('Storyboard animatic', { exact: true }).locator(':scope > div').first();
+ if (decodedVideoReference) await picture.evaluate((root) => {
+ // Chrome's native VIDEO display and Canvas2D currently convert source colors
+ // differently (tracked in #11630). Compare framing/effects to decoded pixels through the actual
+ // CSS layout, retaining the native-display discrepancy as separate evidence.
+ window.restoreVideoReference = [];
+ for (const video of root.querySelectorAll('video[data-ready="true"]:not([aria-hidden="true"])')) {
+ const canvas = document.createElement('canvas');
+ canvas.width = video.videoWidth; canvas.height = video.videoHeight;
+ canvas.getContext('2d').drawImage(video, 0, 0);
+ canvas.className = video.className; canvas.style.cssText = video.style.cssText;
+ video.replaceWith(canvas);
+ window.restoreVideoReference.push(() => canvas.replaceWith(video));
+ }
+ });
+ // Global notification chrome is outside the video frame being saved.
+ let displayed;
+ try { displayed = await picture.screenshot({ style: '[data-toast-id]{visibility:hidden}' }); }
+ finally {
+ if (decodedVideoReference) await page.evaluate(() => window.restoreVideoReference.forEach((restore) => restore()));
+ }
+ const a = await sharp(saved).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+ const b = await sharp(displayed).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+ expect([a.info.width, a.info.height]).toEqual([b.info.width, b.info.height]);
+ let difference = 0, opaque = 0;
+ for (let i = 0; i < a.data.length; i += 1) {
+ difference += Math.abs(a.data[i] - b.data[i]);
+ if (i % 4 === 3 && a.data[i] === 255) opaque += 1;
+ }
+ expect(difference / a.data.length, label).toBeLessThan(1);
+ expect(opaque).toBe(a.info.width * a.info.height);
+ return saved;
+ };
+
+ it('saves actual cover crops and camera endpoints for asymmetric push/pan stills', async () => {
+ for (const move of ['hold', 'push', 'pan']) {
+ await show(project([{ ...still, stillMove: move }]), 0);
+ const first = await capture();
+ await show(project([{ ...still, stillMove: move }]), 4 - 1 / 24);
+ const last = await capture();
+ expect(Buffer.compare(first, last) === 0).toBe(move === 'hold');
+ }
+ expect(errors).toEqual([]);
+ });
+
+ it('saves decoded footage with black, still, fill and VHS fitting while ignoring hidden preloads', async () => {
+ for (const frameFit of ['black', 'still', 'fill', 'vhs']) {
+ await show(project([{ ...still, visualLayer: 'footage', videoHistoryId: 'clip', frameFit },
+ { ...still, sceneId: 'next', order: 1, startSec: 4, endSec: 8, visualLayer: 'footage', videoHistoryId: 'preloaded' }]), 1);
+ await page.waitForFunction(() => document.querySelector('video[data-ready="true"]:not([aria-hidden="true"])')?.seeking === false);
+ await capture(frameFit, { decodedVideoReference: true });
+ }
+ });
+
+ it('saves end-frame effects, flash/develop, incoming dissolves and fade-black in their displayed order', async () => {
+ for (const [effect, t] of [['end-fade', 1.3], ['end-fade', 3], ['flash-develop', 0.1], ['flash-develop', 1]]) {
+ await show(project([{ ...still, imageEffect: effect, imageEffectSec: 1, endImageId: 'end.png', stillMove: 'pan' }]), t);
+ await capture();
+ }
+ await show(project([{ ...still, cutEffect: { style: 'dissolve', enabled: true, overlapSec: 1 } },
+ { ...still, sceneId: 'next', order: 1, startSec: 4, endSec: 8, referenceImageId: 'end.png', stillMove: 'push' }]), 3.5);
+ await capture();
+ await show(project([{ ...still, cutEffect: { style: 'fade-black', enabled: true, overlapSec: 1 } }]), 3.8);
+ await capture();
+ });
+
+ it('captures the exact paused film-look filter after freezing a newer audio clock across a shot boundary', async () => {
+ const look = filmLookPreset('vhs');
+ await show(project([still, { ...still, sceneId: 'next', startSec: 4, endSec: 8, order: 1, referenceImageId: 'end.png' }], { filmLook: look }), 3);
+ await page.evaluate(() => {
+ const audio = document.querySelector('audio');
+ audio.currentTime = 4.5;
+ audio.dispatchEvent(new Event('play'));
+ });
+ const styled = await capture();
+ expect(await page.locator('[data-film-look="exact"]').count()).toBe(1);
+ expect(await page.locator('figure img').first().getAttribute('src')).toBe('/data/images/end.png');
+ await page.getByRole('button', { name: 'Film look', exact: true }).click();
+ await page.evaluate(() => { window.uploads = []; });
+ const clean = await capture();
+ expect(Buffer.compare(styled, clean)).not.toBe(0);
+ });
+
+ it('captures the opaque lyric and title canvases only after the requested song seek completes', async () => {
+ const extra = { audioAnalysis: { durationSec: 8 }, lyricCues: [{ id: 'line', text: 'EXAMPLE WORDS', startSec: 1, endSec: 4 }],
+ titleCard: { enabled: true, title: 'Example title', artist: 'Example artist', startSec: 0, endSec: 5 } };
+ lyricProject = project([{ ...still, referenceImageId: null }], extra);
+ await show(project([still], extra), 2);
+ const frame = page.frameLocator('iframe');
+ await frame.locator('#stage').waitFor();
+ const withWords = await capture();
+ await page.getByRole('button', { name: 'Lyrics', exact: true }).click();
+ await page.evaluate(() => { window.uploads = []; });
+ const withoutWords = await capture();
+ expect(Buffer.compare(withWords, withoutWords)).not.toBe(0);
+ });
+
+ it('rejects a loading video-only shot without uploading a blank or a preloaded frame', async () => {
+ await page.route('**/data/videos/clip.webm', (route) => route.abort());
+ await show(project([{ ...still, referenceImageId: null, visualLayer: 'footage', videoHistoryId: 'loading' }]), 1);
+ await page.getByRole('button', { name: 'Save frame', exact: true }).click();
+ await page.waitForFunction(() => window.captureErrors.length > 0);
+ expect(await page.evaluate(() => window.uploads.length)).toBe(0);
+ expect(await page.evaluate(() => window.captureErrors.at(-1))).toContain('Video frame is still loading');
+ await page.unroute('**/data/videos/clip.webm');
+ });
+
+ it('freezes the displayed outro canvas and exact look before capture', async () => {
+ await show(project([still], { statsOutro: { enabled: true, durationSec: 8 }, filmLook: filmLookPreset('polaroid') }), 1);
+ const look = page.getByRole('button', { name: 'Film look', exact: true });
+ if (await look.getAttribute('aria-pressed') === 'false') await look.click();
+ await page.getByRole('button', { name: 'Ending', exact: true }).click();
+ await page.getByTestId('animatic-stats-outro').waitFor();
+ await page.evaluate(() => document.fonts.ready);
+ const saved = await capture();
+ expect(await page.locator('[data-film-look="exact"]').count()).toBe(1);
+ await page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+ await page.evaluate(() => { window.uploads = []; });
+ expect(Buffer.compare(saved, await capture())).toBe(0);
+ });
+
+ it('rejects a project change or late outro statistics while async frame rasterization is pending', async () => {
+ await show(project(), 1);
+ await page.evaluate(() => window.gateCaptureOnce());
+ await page.getByRole('button', { name: 'Save frame', exact: true }).click();
+ await page.waitForFunction(() => window.captureDecodePending);
+ await show(project([{ ...still, referenceImageId: 'end.png' }]), 1);
+ await page.evaluate(() => window.releaseCapture());
+ await page.waitForFunction(() => window.captureErrors.length > 0);
+ expect(await page.evaluate(() => window.uploads.length)).toBe(0);
+ expect(await page.evaluate(() => window.captureErrors.at(-1))).toContain('Preview changed during capture');
+
+ let pendingStats;
+ await page.route('**/api/music-video/*/stats-outro', (route) => { pendingStats = route; });
+ await show(project([still], { statsOutro: { enabled: true, durationSec: 8 } }), 1);
+ await page.getByRole('button', { name: 'Ending', exact: true }).click();
+ await page.getByTestId('animatic-stats-outro').waitFor();
+ await page.evaluate(() => window.gateCaptureOnce());
+ await page.getByRole('button', { name: 'Save frame', exact: true }).click();
+ await page.waitForFunction(() => window.captureDecodePending);
+ expect(pendingStats).toBeTruthy();
+ await pendingStats.fulfill({ json: { stats: { shots: 9, floorImages: [] } } });
+ await page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+ await page.evaluate(() => window.releaseCapture());
+ await page.waitForFunction(() => window.captureErrors.length > 0);
+ expect(await page.evaluate(() => window.uploads.length)).toBe(0);
+ expect(await page.evaluate(() => window.captureErrors.at(-1))).toContain('Preview changed during capture');
+ await page.unroute('**/api/music-video/*/stats-outro');
+ });
+});