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

Frame-by-frame stepping and Save frame in the music video preview (#11223)

[._.]/6c803f5c2162
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
index 5810418bc8..56134de1c6 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
@@ -2,7 +2,8 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { Pause, Play } from 'lucide-react';
import { normalizeTitleCard } from '../../../../server/lib/musicVideoTitleCard.js';
import useGeneratedPreview from '../../hooks/useGeneratedPreview.js';
-import ShotStepper from './ShotStepper.jsx';
+import ShotStepper, { shotSteps } from './ShotStepper.jsx';
+import FrameStepper from './FrameStepper.jsx';
const buttonCls = 'flex items-center gap-1 bg-port-bg border border-port-border rounded px-2 py-1.5 text-sm min-h-[44px] sm:min-h-0 disabled:opacity-50';
@@ -35,7 +36,7 @@ const startsDeferred = (collapsed) => collapsed && window.matchMedia?.(DESKTOP_Q
* the picture below `lg` until the dock is expanded or the viewport is desktop.
* `lyrics` previews timed lyrics instead of the document. `draft` previews the
* candidate document. `shotNav` adds Back and Next shot buttons (and the arrow
- * keys) for the docked player.
+ * keys) and frame-by-frame stepping for the docked player.
*/
export default function CompositionPreviewPlayer({ project, audioUrl, seekRequest = null, collapsed = false, draft = false, lyrics = false, shotNav = false, scrubId: givenScrubId = null }) {
const doc = lyrics ? { playthrough: true } : (draft ? project.composition?.documentDraft : project.composition?.document) || null;
@@ -108,6 +109,7 @@ export default function CompositionPreviewPlayer({ project, audioUrl, seekReques
const title = lyrics ? 'Lyric timing playthrough' : draft ? 'Composition candidate preview' : 'Composition document preview';
const aspect = preview.width && preview.height ? `${preview.width} / ${preview.height}` : '16 / 9';
const lyric = lyricAt(project.lyricCues, t);
+ const shotIndex = shotNav ? shotSteps(project.scenes, t).index : 0;
const failed = preview.status === 'error' || preview.status === 'unavailable';
const timeLabel = failed
? 'Preview unavailable'
@@ -136,6 +138,18 @@ export default function CompositionPreviewPlayer({ project, audioUrl, seekReques
<span className="text-xs text-port-text-muted tabular-nums">{timeLabel}</span>
</div>
{shotNav && <ShotStepper scenes={project.scenes} time={t} onSeek={seek} disabled={!preview.ready || failed} keys />}
+ {shotNav && (
+ <FrameStepper
+ time={t}
+ fps={fps}
+ maxSec={duration || null}
+ onSeek={(time) => { audioRef.current?.pause?.(); setPlaying(false); seek(time); }}
+ disabled={!preview.ready || failed}
+ capture={() => (preview.frameUrl ? fetch(preview.frameUrl).then((res) => res.blob()) : Promise.resolve(null))}
+ label={[project.name, shotIndex ? `Shot ${shotIndex}` : null].filter(Boolean).join(' · ')}
+ keys
+ />
+ )}
{lyric && !lyrics && <p className="text-xs italic break-words" aria-live="off" data-testid="preview-lyric">♪ {lyric}</p>}
{audioUrl && <audio ref={audioRef} src={audioUrl} preload="none" className="hidden" onEnded={() => setPlaying(false)} />}
</div>
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
index e9ce6bc226..55216cf50e 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
@@ -41,6 +41,8 @@ const socket = vi.hoisted(() => {
});
vi.mock('../../services/apiMusicVideo.js', () => api);
vi.mock('../../services/socket', () => ({ default: socket }));
+const uploadGalleryImage = vi.hoisted(() => vi.fn(async () => ({ filename: 'upload-1234abcd.png' })));
+vi.mock('../../services/apiSystem.js', () => ({ uploadGalleryImage }));
import CompositionPreviewPlayer from './CompositionPreviewPlayer.jsx';
@@ -199,4 +201,16 @@ describe('CompositionPreviewPlayer', () => {
expect(screen.getByLabelText('Scrub the composition candidate').id).toBe('mv-doc-draft-scrub');
expect(document.querySelector('iframe')).toBeNull();
});
+
+ it('saves the docked preview frame on screen to the gallery', async () => {
+ const blob = new Blob(['jpeg'], { type: 'image/jpeg' });
+ const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({ blob: async () => blob });
+ const { container } = render(<CompositionPreviewPlayer project={{ ...project, scenes: [{ sceneId: 'a', startSec: 0 }] }} audioUrl="/song.mp3" shotNav />);
+ await waitFor(() => expect(container.querySelector('img')?.getAttribute('src')).toBeTruthy());
+ const frameSrc = container.querySelector('img').getAttribute('src');
+ await act(async () => { screen.getByRole('button', { name: /Save frame/ }).click(); });
+ expect(fetchSpy).toHaveBeenCalledWith(frameSrc);
+ expect(uploadGalleryImage).toHaveBeenCalledWith(blob, { silent: true });
+ fetchSpy.mockRestore();
+ });
});
diff --git a/client/src/components/musicVideo/FrameStepper.jsx b/client/src/components/musicVideo/FrameStepper.jsx
new file mode 100644
index 0000000000..a022121825
--- /dev/null
+++ b/client/src/components/musicVideo/FrameStepper.jsx
@@ -0,0 +1,131 @@
+import { useEffect, useId, useRef, useState } from 'react';
+import { ChevronLeft, ChevronRight, ImageDown } from 'lucide-react';
+import toast from '../ui/Toast';
+import { shouldIgnoreGlobalKey } from '../../lib/a11yKeyboard.js';
+import { uploadGalleryImage } from '../../services/apiSystem.js';
+
+export const PREVIEW_FPS = 24;
+
+/** The song frame at `t` seconds: the frame whose span holds it. */
+export const frameAt = (t, fps = PREVIEW_FPS) => Math.max(0, Math.floor((Number(t) || 0) * fps + 1e-6));
+
+/** Where a seek to frame `frame` lands: the middle of that frame, so it shows and reads back as that frame. */
+export const frameTime = (frame, fps = PREVIEW_FPS) => (Math.max(0, Math.round(frame)) + 0.5) / fps;
+
+/** `m:ss:ff` for a song frame. */
+export function frameTimecode(frame, fps = PREVIEW_FPS) {
+ const whole = Math.floor(frame / fps);
+ return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, '0')}:${String(frame % fps).padStart(String(fps - 1).length, '0')}`;
+}
+
+/**
+ * The picture a video (at its current time) or an image element shows, as a PNG
+ * blob; null when it has nothing decoded yet.
+ */
+export function captureMediaFrame(el) {
+ const width = el?.videoWidth || el?.naturalWidth || 0;
+ const height = el?.videoHeight || el?.naturalHeight || 0;
+ if (!width || !height || (el.tagName === 'VIDEO' && el.readyState < 2)) return Promise.resolve(null);
+ const canvas = document.createElement('canvas');
+ canvas.width = width;
+ canvas.height = height;
+ canvas.getContext('2d')?.drawImage(el, 0, 0);
+ return new Promise((resolve) => canvas.toBlob((blob) => resolve(blob), 'image/png'));
+}
+
+const buttonCls = 'flex min-h-[44px] min-w-[44px] shrink-0 items-center justify-center gap-1 rounded border border-port-border bg-port-bg px-1 text-port-text disabled:opacity-40 sm:min-h-[28px] sm:min-w-[28px]';
+const inputCls = 'min-h-[44px] rounded border border-port-border bg-port-bg px-1 text-right tabular-nums text-port-text sm:min-h-[28px]';
+
+/**
+ * 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 "."
+ * 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 = '' }) {
+ const ids = useId();
+ const frame = frameAt(time, fps);
+ const lastFrame = Number.isFinite(maxSec) && maxSec > 0 ? Math.max(0, Math.ceil(maxSec * fps) - 1) : null;
+ const [step, setStep] = useState(1);
+ const [draft, setDraft] = useState(null);
+ const [saving, setSaving] = useState(false);
+ const stepBy = Math.max(1, Math.floor(Number(step) || 1));
+ const go = (target) => {
+ const clamped = Math.max(0, lastFrame == null ? target : Math.min(lastFrame, target));
+ onSeek(frameTime(clamped, fps));
+ };
+ const latest = useRef(null);
+ latest.current = { frame, stepBy, go, disabled };
+ useEffect(() => {
+ if (!keys) return undefined;
+ const onKey = (event) => {
+ if (event.key !== ',' && event.key !== '.') return;
+ if (shouldIgnoreGlobalKey(event, { ignoreRepeat: false }) || event.target?.closest?.('audio, video, input')) return;
+ const current = latest.current;
+ if (current.disabled) return;
+ event.preventDefault();
+ current.go(current.frame + (event.key === '.' ? current.stepBy : -current.stepBy));
+ };
+ window.addEventListener('keydown', onKey);
+ return () => window.removeEventListener('keydown', onKey);
+ }, [keys]);
+ const save = async () => {
+ setSaving(true);
+ const blob = await capture().catch(() => null);
+ const saved = blob ? await uploadGalleryImage(blob, { silent: true }).catch(() => null) : null;
+ setSaving(false);
+ const name = [label, `frame ${frame}`].filter(Boolean).join(' · ');
+ if (saved?.filename) toast.success(`Saved ${name} to the image gallery`);
+ else toast.error(`Couldn't save ${name}`);
+ };
+ return (
+ <div className={`flex min-w-0 flex-wrap items-center gap-1.5 text-[11px] text-port-text-muted ${className}`}>
+ <button type="button" onClick={() => go(frame - stepBy)} disabled={disabled || frame <= 0} aria-label={`Back ${stepBy} ${stepBy === 1 ? 'frame' : 'frames'}`} title="Back (,)" className={buttonCls}>
+ <ChevronLeft size={14} aria-hidden="true" />
+ </button>
+ <label htmlFor={`${ids}-step`} className="sr-only">Frames per step</label>
+ <input
+ id={`${ids}-step`}
+ type="number"
+ inputMode="numeric"
+ min={1}
+ value={step}
+ onChange={(e) => setStep(e.target.value)}
+ onBlur={() => setStep(stepBy)}
+ title="Frames per step"
+ className={`${inputCls} w-12`}
+ />
+ <button type="button" onClick={() => go(frame + stepBy)} disabled={disabled || (lastFrame != null && frame >= lastFrame)} aria-label={`Forward ${stepBy} ${stepBy === 1 ? 'frame' : 'frames'}`} title="Forward (.)" className={buttonCls}>
+ <ChevronRight size={14} aria-hidden="true" />
+ </button>
+ <label htmlFor={`${ids}-frame`} className="whitespace-nowrap">Frame</label>
+ <input
+ id={`${ids}-frame`}
+ type="number"
+ inputMode="numeric"
+ min={0}
+ value={draft ?? frame}
+ disabled={disabled}
+ onFocus={() => setDraft(String(frame))}
+ onChange={(e) => setDraft(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key !== 'Enter') return;
+ const typed = Math.floor(Number(draft));
+ if (Number.isFinite(typed)) go(typed);
+ setDraft(null);
+ e.currentTarget.blur();
+ }}
+ onBlur={() => setDraft(null)}
+ className={`${inputCls} w-20`}
+ />
+ <span className="whitespace-nowrap tabular-nums">{frameTimecode(frame, fps)}</span>
+ {capture && (
+ <button type="button" onClick={save} disabled={disabled || saving} title="Save this frame to the image gallery" className={`${buttonCls} px-2`}>
+ <ImageDown size={14} aria-hidden="true" /> {saving ? 'Saving…' : 'Save frame'}
+ </button>
+ )}
+ </div>
+ );
+}
diff --git a/client/src/components/musicVideo/FrameStepper.test.jsx b/client/src/components/musicVideo/FrameStepper.test.jsx
new file mode 100644
index 0000000000..c0be8147c6
--- /dev/null
+++ b/client/src/components/musicVideo/FrameStepper.test.jsx
@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import FrameStepper, { frameAt, frameTime, frameTimecode } from './FrameStepper.jsx';
+
+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() } }));
+
+afterEach(() => { uploadGalleryImage.mockClear(); toastSuccess.mockClear(); });
+
+describe('frame math', () => {
+ it('numbers song frames and seeks to the middle of one', () => {
+ expect(frameAt(1, 24)).toBe(24);
+ expect(frameAt(1.0399, 24)).toBe(24);
+ expect(frameAt(frameTime(100, 24), 24)).toBe(100);
+ expect(frameTimecode(24 * 61 + 5, 24)).toBe('1:01:05');
+ });
+});
+
+describe('FrameStepper', () => {
+ it('steps by the chosen count, jumps to a typed frame, and binds , and .', () => {
+ const onSeek = vi.fn();
+ render(<FrameStepper time={frameTime(100)} onSeek={onSeek} maxSec={10} keys />);
+ fireEvent.click(screen.getByRole('button', { name: 'Forward 1 frame' }));
+ expect(frameAt(onSeek.mock.lastCall[0])).toBe(101);
+ fireEvent.change(screen.getByLabelText('Frames per step'), { target: { value: '12' } });
+ fireEvent.click(screen.getByRole('button', { name: 'Back 12 frames' }));
+ expect(frameAt(onSeek.mock.lastCall[0])).toBe(88);
+ const frame = screen.getByLabelText('Frame');
+ fireEvent.focus(frame);
+ fireEvent.change(frame, { target: { value: '9999' } });
+ fireEvent.keyDown(frame, { key: 'Enter' });
+ expect(frameAt(onSeek.mock.lastCall[0])).toBe(239);
+ fireEvent.keyDown(window, { key: '.' });
+ expect(frameAt(onSeek.mock.lastCall[0])).toBe(112);
+ expect(screen.getByText('0:04:04')).toBeTruthy();
+ });
+
+ it('saves the frame on screen to the gallery', async () => {
+ const blob = new Blob(['png'], { type: 'image/png' });
+ render(<FrameStepper time={frameTime(48)} onSeek={vi.fn()} capture={async () => blob} label="Example Song · Shot 2" />);
+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: /Save frame/ })); });
+ expect(uploadGalleryImage).toHaveBeenCalledWith(blob, { silent: true });
+ expect(toastSuccess).toHaveBeenCalledWith('Saved Example Song · Shot 2 · frame 48 to the image gallery');
+ });
+});
diff --git a/client/src/components/musicVideo/PreviewDock.jsx b/client/src/components/musicVideo/PreviewDock.jsx
index a7d087b2c6..5e43eca0e2 100644
--- a/client/src/components/musicVideo/PreviewDock.jsx
+++ b/client/src/components/musicVideo/PreviewDock.jsx
@@ -3,14 +3,16 @@ import { useSearchParams } from 'react-router';
import { ChevronDown, ChevronUp, MonitorPlay } from 'lucide-react';
import CompositionPreviewPlayer from './CompositionPreviewPlayer.jsx';
import StoryboardAnimatic from './StoryboardAnimatic.jsx';
-import ShotStepper from './ShotStepper.jsx';
+import ShotStepper, { shotSteps } from './ShotStepper.jsx';
+import FrameStepper, { captureMediaFrame } from './FrameStepper.jsx';
// A rendered file (the final render or a draft excerpt). Its clock starts at
// the clip's own start, so a seek to song time `t` lands at `t - startSec` and
// is ignored outside it. Back and Next step through the shots inside it.
-function VideoPreview({ source, scenes, seekRequest, collapsed }) {
+function VideoPreview({ source, scenes, projectName, seekRequest, collapsed }) {
const videoRef = useRef(null);
const [time, setTime] = useState(0);
+ const [duration, setDuration] = useState(null);
const pending = useRef(null);
const applied = useRef(null);
const seekTo = (t, play = false) => {
@@ -27,6 +29,14 @@ function VideoPreview({ source, scenes, seekRequest, collapsed }) {
if (t >= 0 && (source.endSec == null || t <= source.endSec - source.startSec)) seekTo(t, !!seekRequest.play);
}, [seekRequest, source.startSec, source.endSec]);
const startSec = source.startSec || 0;
+ const range = { startSec, endSec: source.endSec ?? null };
+ const songTime = startSec + time;
+ const shot = shotSteps(scenes, songTime, range).index;
+ const stepFrame = (t) => {
+ videoRef.current?.pause?.();
+ seekTo(t - startSec);
+ setTime(t - startSec);
+ };
return (
<div className={`space-y-2 ${collapsed ? 'max-xl:hidden' : ''}`}>
<video
@@ -38,14 +48,23 @@ function VideoPreview({ source, scenes, seekRequest, collapsed }) {
onLoadedMetadata={() => { if (pending.current != null) { seekTo(pending.current); pending.current = null; } }}
onTimeUpdate={(e) => setTime(e.currentTarget.currentTime)}
onSeeked={(e) => setTime(e.currentTarget.currentTime)}
+ onLoadedData={(e) => setDuration(e.currentTarget.duration)}
aria-label={source.id === 'final' ? 'Final render preview' : 'Draft excerpt preview'}
className="aspect-video max-h-[50vh] w-full rounded border border-port-border bg-black object-contain"
/>
<ShotStepper
scenes={scenes}
- time={startSec + time}
+ time={songTime}
onSeek={(t) => { seekTo(t - startSec); setTime(t - startSec); }}
- range={{ startSec, endSec: source.endSec ?? null }}
+ range={range}
+ keys
+ />
+ <FrameStepper
+ time={songTime}
+ onSeek={stepFrame}
+ maxSec={source.endSec ?? (Number.isFinite(duration) ? startSec + duration : null)}
+ capture={() => captureMediaFrame(videoRef.current)}
+ label={[projectName, shot ? `Shot ${shot}` : null].filter(Boolean).join(' · ')}
keys
/>
</div>
@@ -117,7 +136,7 @@ export default function PreviewDock({ project, sources, audioUrl, seekRequest, c
{source?.kind === 'document' && <div className={collapsed ? 'max-xl:hidden' : ''}><CompositionPreviewPlayer project={project} audioUrl={audioUrl} seekRequest={seekRequest} collapsed={collapsed} shotNav /></div>}
{source?.kind === 'lyrics' && <div className={collapsed ? 'max-xl:hidden' : ''}><CompositionPreviewPlayer project={project} audioUrl={audioUrl} seekRequest={seekRequest} collapsed={collapsed} lyrics shotNav /></div>}
{source?.kind === 'animatic' && <StoryboardAnimatic project={project} audioUrl={audioUrl} seekRequest={seekRequest} collapsed={collapsed} />}
- {source?.kind === 'video' && <VideoPreview key={source.id} source={source} scenes={project.scenes} seekRequest={seekRequest} collapsed={collapsed} />}
+ {source?.kind === 'video' && <VideoPreview key={source.id} source={source} scenes={project.scenes} projectName={project.name} seekRequest={seekRequest} collapsed={collapsed} />}
</aside>
);
}
diff --git a/client/src/components/musicVideo/PreviewDock.test.jsx b/client/src/components/musicVideo/PreviewDock.test.jsx
index b4ee667ff1..8f2a2e4600 100644
--- a/client/src/components/musicVideo/PreviewDock.test.jsx
+++ b/client/src/components/musicVideo/PreviewDock.test.jsx
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
import { fireEvent, render, screen } from '@testing-library/react';
import { MemoryRouter } from 'react-router';
import PreviewDock from './PreviewDock.jsx';
@@ -18,4 +18,18 @@ describe('PreviewDock video shot steps', () => {
expect(screen.getByText('Shot 2 / 2')).toBeTruthy();
expect(screen.getByRole('button', { name: 'Next shot' }).disabled).toBe(true);
});
+
+ it('steps a draft excerpt frame by frame in song frames, pausing it', () => {
+ const project = { id: 'p', scenes: [{ startSec: 22 }] };
+ const sources = [{ id: 'draft-1', kind: 'video', label: 'Draft', src: '/data/videos/draft.mp4', startSec: 20, endSec: 30 }];
+ render(<MemoryRouter><PreviewDock project={project} sources={sources} audioUrl="/song.mp3" /></MemoryRouter>);
+ const video = screen.getByLabelText('Draft excerpt preview');
+ Object.defineProperty(video, 'readyState', { value: 4, configurable: true });
+ video.pause = vi.fn();
+ expect(screen.getByLabelText('Frame').value).toBe('480');
+ fireEvent.click(screen.getByRole('button', { name: 'Forward 1 frame' }));
+ expect(video.pause).toHaveBeenCalled();
+ expect(video.currentTime).toBeCloseTo(1.5 / 24);
+ expect(screen.getByLabelText('Frame').value).toBe('481');
+ });
});
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.jsx b/client/src/components/musicVideo/StoryboardAnimatic.jsx
index c081fb88be..a48de42fb7 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.jsx
@@ -10,6 +10,7 @@ import { useVideoFileSrc } from '../../hooks/useVideoFileSrc.js';
import { selectedPerformanceInstruction } from '../../lib/musicVideoShotTiming.js';
import { normalizeTitleCard } from '../../../../server/lib/musicVideoTitleCard.js';
import ShotStepper from './ShotStepper.jsx';
+import FrameStepper, { captureMediaFrame } from './FrameStepper.jsx';
const timedShots = (scenes) => scenes.filter((scene) => Number.isFinite(scene?.startSec)).sort((a, b) => a.startSec - b.startSec);
@@ -235,6 +236,7 @@ function ShotClip({ scene, audioRef, time, current }) {
*/
export default function StoryboardAnimatic({ project, audioUrl, seekRequest, collapsed }) {
const audioRef = useRef(null);
+ const figureRef = useRef(null);
const applied = useRef(null);
const [time, setTime] = useState(0);
const [lyricsOn, setLyricsOn] = useState(true);
@@ -260,6 +262,17 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
audioRef.current.currentTime = t;
setTime(t);
}, []);
+ // Frame steps pause the song first, so the frame stays on screen to check.
+ const stepFrame = useCallback((t) => {
+ audioRef.current?.pause?.();
+ seekTo(t);
+ }, [seekTo]);
+ // 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);
+ };
const shot = shotAt(scenes, time);
const timed = timedShots(scenes);
const index = shot ? timed.indexOf(shot) : -1;
@@ -272,7 +285,7 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
const cardInFrame = !overlay;
return (
<div className={`space-y-2 ${collapsed ? 'max-xl:hidden' : ''}`}>
- <figure aria-label="Storyboard animatic" className="relative aspect-video w-full overflow-hidden rounded border border-port-border bg-black">
+ <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(time * ANIMATIC_FPS)} playing={playing} className="h-full w-full">
{shot?.referenceImageId ? (
@@ -326,6 +339,17 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
</button>
)}
</div>
+ {shot && (
+ <FrameStepper
+ time={time}
+ fps={ANIMATIC_FPS}
+ maxSec={Number(project.audioAnalysis?.durationSec) || null}
+ onSeek={stepFrame}
+ capture={captureFrame}
+ label={[project.name, `Shot ${index + 1}`].filter(Boolean).join(' · ')}
+ keys
+ />
+ )}
<audio
ref={audioRef}
src={audioUrl}
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
index eaef09a93d..2f99c685b7 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
@@ -70,6 +70,11 @@ 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` })),
}));
@@ -133,6 +138,17 @@ describe('StoryboardAnimatic clips', () => {
expect(audio.currentTime).toBe(0);
});
+ 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('maps song time into the clip: trimmed in-point, then loop or hold past its end', () => {
const performance = {
sceneId: 'p', startSec: 10, endSec: 20, shotMode: 'performance', videoHistoryId: 'v1',