Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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.jsxindex 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, seekRequesconst 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.jsxindex 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.jsxnew file mode 100644index 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.jsxnew file mode 100644index 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.jsxindex 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"/><ShotStepperscenes={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.jsxindex 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.jsxindex 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, colaudioRef.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, colconst 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+ />+ )}<audioref={audioRef}src={audioUrl}diff --git a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx b/client/src/components/musicVideo/StoryboardAnimatic.test.jsxindex 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',