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

Add dissolve and fade through black between music video shots (#11496)

[._.]/15bfaac957ce
diff --git a/client/src/components/musicVideo/SceneCard.jsx b/client/src/components/musicVideo/SceneCard.jsx
index 002586eaf3..384eb90908 100644
--- a/client/src/components/musicVideo/SceneCard.jsx
+++ b/client/src/components/musicVideo/SceneCard.jsx
@@ -38,6 +38,7 @@ import SceneRenderTarget, { lastRenderTarget, renderTargetOverrides } from './Sc
import SceneRenderInputs, { shotCardRenderRequest, shotCardRequestProblem } from './SceneRenderInputs.jsx';
import SceneFrameFit, { sceneFrameFit } from './SceneFrameFit.jsx';
import SceneCutEffect from './SceneCutEffect.jsx';
+import { plannedTransitions } from '../../lib/musicVideoCutEffects.js';
import SceneGlitches from './SceneGlitches.jsx';
import SceneTransitions from './SceneTransitions.jsx';
import SceneImageEffect from './SceneImageEffect.jsx';
@@ -260,8 +261,9 @@ export default function SceneCard({
span={sceneHasAuthoredSpan(scene) ? { startSec: scene.startSec, endSec: scene.endSec } : null} />
{/* A VHS glitch riding on the cut into or out of this shot; never moves the cut. */}
<SceneTransitions fieldId={fieldId} scene={scene} onChange={applyPatch} />
- {/* Both clips flipping on the beats over the end of this shot, switched on or off. */}
- <SceneCutEffect fieldId={fieldId} scene={scene} onChange={applyPatch} />
+ {/* How this shot hands over to the next: a cut, beat toggle, dissolve or fade, as its storyboard row plans until one is picked. */}
+ <SceneCutEffect fieldId={fieldId} scene={scene} isLast={!!isLast} onChange={applyPatch}
+ planned={plannedTransitions(project?.productionReview?.draft?.storyboard).get(scene.sceneId)} />
{/* Glitches at moments inside the shot, set and moved on a slider; they add no time. */}
<SceneGlitches fieldId={fieldId} scene={scene} onChange={applyPatch} />
{/* Everything set once and rarely revisited: timing, shot mode, layer, and a non-footage shot's camera. */}
diff --git a/client/src/components/musicVideo/SceneCard.test.jsx b/client/src/components/musicVideo/SceneCard.test.jsx
index 885436ab3f..9b6e50f966 100644
--- a/client/src/components/musicVideo/SceneCard.test.jsx
+++ b/client/src/components/musicVideo/SceneCard.test.jsx
@@ -628,23 +628,42 @@ describe('clip speed and offset by hand', () => {
});
});
-// Uniquely catches the beat toggle control saving the wrong shape or losing its settings when switched off.
-describe('Beat toggle into the next shot', () => {
- it('switches on with defaults, changes its settings and keeps them when switched off', () => {
+// Uniquely catches the cut effect picker saving the wrong shape, losing its
+// settings on Cut, or ignoring the transition the storyboard plans.
+describe('How a shot hands over to the next', () => {
+ function Harness({ initial = {}, project = null, isLast = false, onSave }) {
+ const [scene, setScene] = useState({ sceneId: 's1', startSec: 0, endSec: 4, takes: [], ...initial });
+ return <SceneCard scene={scene} index={0} isLast={isLast} project={project} onEditLocal={(_id, patch) => setScene((current) => ({ ...current, ...patch }))} onSave={onSave} />;
+ }
+
+ it('picks an effect with defaults, changes its settings and keeps them on Cut', () => {
const onSave = vi.fn();
- function Harness() {
- const [scene, setScene] = useState({ sceneId: 's1', startSec: 0, endSec: 4, takes: [] });
- return <SceneCard scene={scene} index={0} onEditLocal={(_id, patch) => setScene((current) => ({ ...current, ...patch }))} onSave={onSave} />;
- }
- render(<Harness />);
- const toggle = screen.getByLabelText('Beat toggle into next shot');
- fireEvent.click(toggle);
+ render(<Harness onSave={onSave} />);
+ const picker = screen.getByLabelText('Into next shot');
+ fireEvent.change(picker, { target: { value: 'beat-toggle' } });
expect(onSave).toHaveBeenLastCalledWith('s1', { cutEffect: { style: 'beat-toggle', enabled: true, overlapSec: 1, rate: 'beat' } });
fireEvent.change(screen.getByLabelText('Beat toggle speed'), { target: { value: 'half' } });
- expect(onSave).toHaveBeenLastCalledWith('s1', { cutEffect: { style: 'beat-toggle', enabled: true, overlapSec: 1, rate: 'half' } });
- fireEvent.click(toggle);
- expect(onSave).toHaveBeenLastCalledWith('s1', { cutEffect: { style: 'beat-toggle', enabled: false, overlapSec: 1, rate: 'half' } });
- expect(screen.getByLabelText('Beat toggle speed').value).toBe('half');
+ fireEvent.change(screen.getByLabelText('Into next shot length'), { target: { value: '2' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { cutEffect: { style: 'beat-toggle', enabled: true, overlapSec: 2, rate: 'half' } });
+ fireEvent.change(picker, { target: { value: 'dissolve' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { cutEffect: { style: 'dissolve', enabled: true, overlapSec: 2, rate: 'half' } });
+ expect(screen.queryByLabelText('Beat toggle speed')).toBeNull();
+ fireEvent.change(picker, { target: { value: '' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { cutEffect: { style: 'dissolve', enabled: false, overlapSec: 2, rate: 'half' } });
+ expect(picker.value).toBe('');
+ });
+
+ it('shows the storyboard\'s planned Dissolve until a pick, and offers only a fade to black on the last shot', () => {
+ const onSave = vi.fn();
+ const project = { productionReview: { draft: { storyboard: [{ sceneId: 's1', transition: 'Slow dissolve into the dream' }] } } };
+ const { unmount } = render(<Harness project={project} onSave={onSave} />);
+ expect(screen.getByLabelText('Into next shot').value).toBe('dissolve');
+ fireEvent.change(screen.getByLabelText('Into next shot'), { target: { value: '' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { cutEffect: { style: 'dissolve', enabled: false, overlapSec: 1, rate: 'beat' } });
+ unmount();
+ render(<Harness isLast onSave={onSave} />);
+ const end = screen.getByLabelText('At the end');
+ expect([...end.options].map((o) => o.text)).toEqual(['Cut', 'Fade to black']);
});
});
diff --git a/client/src/components/musicVideo/SceneCutEffect.jsx b/client/src/components/musicVideo/SceneCutEffect.jsx
index de614593c0..94a182b41c 100644
--- a/client/src/components/musicVideo/SceneCutEffect.jsx
+++ b/client/src/components/musicVideo/SceneCutEffect.jsx
@@ -1,42 +1,61 @@
-import { BEAT_TOGGLE_OVERLAP, BEAT_TOGGLE_RATE_LABELS, BEAT_TOGGLE_RATES, sceneCutEffect } from '../../lib/musicVideoCutEffects.js';
+import { BEAT_TOGGLE_OVERLAP, BEAT_TOGGLE_RATE_LABELS, BEAT_TOGGLE_RATES, MUSIC_VIDEO_CUT_EFFECT_LABELS, MUSIC_VIDEO_CUT_EFFECTS, sceneCutEffect } from '../../lib/musicVideoCutEffects.js';
-const OVERLAPS = Object.freeze([0.5, 1, 1.5, 2]);
-const OVERLAP_LABELS = { 0.5: '½ s', 1: '1 s', 1.5: '1½ s', 2: '2 s' };
+const OVERLAPS = Object.freeze([0.5, 1, 1.5, 2, 3, 4]);
+const OVERLAP_LABELS = { 0.5: '½ s', 1: '1 s', 1.5: '1½ s', 2: '2 s', 3: '3 s', 4: '4 s' };
+const TITLES = {
+ 'beat-toggle': 'Both clips play over the end of this shot and the picture flips between them on the beats, then the next shot carries on',
+ dissolve: 'The next shot fades in over the end of this one, fully in on the cut',
+ 'fade-black': 'This shot fades to black and the next fades in from it, half the length each side of the cut',
+};
/**
- * The beat toggle across the cut out of a shot: a switch, then how long before
- * the cut it plays and how fast it flips. Switching it off keeps the settings,
- * so turning it back on brings them back. It never moves a cut or changes a lock.
+ * How a shot hands over to the next one: a plain cut, a beat toggle, a dissolve
+ * or a fade through black (on the last shot, a cut or a fade to black), with how
+ * long it plays. Picking Cut switches the effect off but keeps its settings, so
+ * picking it again brings them back. A storyboard row that plans a Dissolve or
+ * Fade (`planned`) is the choice until one is picked. It never moves a cut or changes a lock.
*/
-export default function SceneCutEffect({ fieldId, scene, onChange, disabled = false }) {
- const effect = sceneCutEffect(scene);
- const on = !!effect?.enabled;
+export default function SceneCutEffect({ fieldId, scene, planned = null, isLast = false, onChange, disabled = false }) {
+ const effect = sceneCutEffect(scene, planned);
+ const styles = isLast ? ['fade-black'] : MUSIC_VIDEO_CUT_EFFECTS;
+ const style = effect?.enabled && styles.includes(effect.style) ? effect.style : '';
const save = (patch) => onChange({
- cutEffect: { style: 'beat-toggle', enabled: on, overlapSec: effect?.overlapSec ?? BEAT_TOGGLE_OVERLAP.default, rate: effect?.rate ?? 'beat', ...patch },
+ cutEffect: { style: effect?.style ?? 'beat-toggle', enabled: !!style, overlapSec: effect?.overlapSec ?? BEAT_TOGGLE_OVERLAP.default, rate: effect?.rate ?? 'beat', ...patch },
});
+ const pick = (next) => {
+ if (next) save({ style: next, enabled: true });
+ else if (effect) save({ enabled: false });
+ };
const selectClass = 'bg-port-bg border border-port-border rounded px-1 py-1 text-xs min-h-[44px] sm:min-h-0 disabled:opacity-50';
const overlap = OVERLAPS.includes(effect?.overlapSec) ? effect.overlapSec : null;
+ const label = isLast ? 'At the end' : 'Into next shot';
return (
<div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs" data-testid="scene-cut-effect">
- <label htmlFor={fieldId('beat-toggle')} className="flex min-h-[44px] items-center gap-1.5 sm:min-h-0"
- title="Both clips play over the end of this shot and the picture flips between them on the beats, then the next shot carries on">
- <input id={fieldId('beat-toggle')} type="checkbox" checked={on} disabled={disabled}
- onChange={(e) => save({ enabled: e.target.checked })} className="accent-port-accent" />
- <span className={on ? 'text-port-accent' : 'text-port-text-muted'}>Beat toggle into next shot</span>
- </label>
- {effect && (
+ <span className="flex min-w-0 items-center gap-1">
+ <label htmlFor={fieldId('cut-effect')} className={style ? 'text-port-accent' : 'text-port-text-muted'}>{label}</label>
+ <select id={fieldId('cut-effect')} value={style} disabled={disabled} title={TITLES[style] || 'A plain cut'}
+ onChange={(e) => pick(e.target.value)} className={`min-w-0 ${selectClass}`}>
+ <option value="">Cut</option>
+ {styles.map((s) => <option key={s} value={s}>{isLast && s === 'fade-black' ? 'Fade to black' : MUSIC_VIDEO_CUT_EFFECT_LABELS[s]}</option>)}
+ </select>
+ </span>
+ {style && (
<>
- <label htmlFor={fieldId('beat-toggle-overlap')} className="sr-only">Beat toggle length</label>
- <select id={fieldId('beat-toggle-overlap')} value={overlap ?? ''} disabled={disabled} title="How long before the cut it plays"
+ <label htmlFor={fieldId('cut-effect-length')} className="sr-only">{`${label} length`}</label>
+ <select id={fieldId('cut-effect-length')} value={overlap ?? ''} disabled={disabled} title="How long it plays"
onChange={(e) => save({ overlapSec: Number(e.target.value) })} className={selectClass}>
{overlap == null && <option value="">{`${effect.overlapSec} s`}</option>}
{OVERLAPS.map((sec) => <option key={sec} value={sec}>{OVERLAP_LABELS[sec]}</option>)}
</select>
- <label htmlFor={fieldId('beat-toggle-rate')} className="sr-only">Beat toggle speed</label>
- <select id={fieldId('beat-toggle-rate')} value={effect.rate} disabled={disabled}
- onChange={(e) => save({ rate: e.target.value })} className={selectClass}>
- {BEAT_TOGGLE_RATES.map((rate) => <option key={rate} value={rate}>{BEAT_TOGGLE_RATE_LABELS[rate]}</option>)}
- </select>
+ {style === 'beat-toggle' && (
+ <>
+ <label htmlFor={fieldId('beat-toggle-rate')} className="sr-only">Beat toggle speed</label>
+ <select id={fieldId('beat-toggle-rate')} value={effect.rate} disabled={disabled}
+ onChange={(e) => save({ rate: e.target.value })} className={selectClass}>
+ {BEAT_TOGGLE_RATES.map((rate) => <option key={rate} value={rate}>{BEAT_TOGGLE_RATE_LABELS[rate]}</option>)}
+ </select>
+ </>
+ )}
</>
)}
</div>
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.jsx b/client/src/components/musicVideo/StoryboardAnimatic.jsx
index 18f31a6662..89cbe1b1ff 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.jsx
@@ -18,7 +18,7 @@ import TransitionGlitch from './TransitionGlitch.jsx';
import ImageEffectStill from './ImageEffectStill.jsx';
import { clipOffsetSec, clipReversed, clipSpeedRate, isLayeredComposition } from '../../lib/musicVideoLayers.js';
import { sceneImageEffect } from '../../lib/musicVideoImageEffects.js';
-import { sceneBeatToggles } from '../../lib/musicVideoCutEffects.js';
+import { plannedTransitions, sceneCutEffects } from '../../lib/musicVideoCutEffects.js';
const timedShots = (scenes) => scenes.filter((scene) => Number.isFinite(scene?.startSec)).sort((a, b) => a.startSec - b.startSec);
@@ -336,12 +336,43 @@ function ShotClip({ scene, audioRef, time, current, preload = 'auto' }) {
);
}
+// Runs `apply(songTime)` on every animation frame while the song plays, and once more when it pauses:
+// the song's timeupdate is far too coarse for a beat flip or a smooth fade.
+function useSongFrames(audioRef, apply) {
+ useEffect(() => {
+ const audio = audioRef.current;
+ if (!audio) return undefined;
+ let handle = 0;
+ const tick = () => {
+ apply(audio.currentTime || 0);
+ handle = requestAnimationFrame(tick);
+ };
+ const start = () => { cancelAnimationFrame(handle); handle = requestAnimationFrame(tick); };
+ const stop = () => { cancelAnimationFrame(handle); apply(audio.currentTime || 0); };
+ audio.addEventListener('play', start);
+ audio.addEventListener('pause', stop);
+ if (!audio.paused) start();
+ return () => {
+ cancelAnimationFrame(handle);
+ audio.removeEventListener('play', start);
+ audio.removeEventListener('pause', stop);
+ };
+ }, [audioRef, apply]);
+}
+
+// How much of the incoming clip shows at song time `t`: on a toggle's flips, or a
+// dissolve's ramp, which reaches full on the cut as the render's alpha fade does.
+const incomingOpacity = (effect, t) => {
+ if (effect.style !== 'dissolve') return effect.incoming.some(([a, b]) => t >= a && t < b) ? 1 : 0;
+ if (t < effect.windowStartSec || t >= effect.cutSec) return 0;
+ return Math.min(1, (t - effect.windowStartSec) / (effect.cutSec - effect.windowStartSec + 1 / ANIMATIC_FPS));
+};
+
/**
- * The incoming shot of a beat toggle (lib/musicVideoCutEffects.js) over the
- * outgoing one: its clip runs on the song's clock, reading the footage before
- * its in-point, and shows only on the toggle's frames, as the final render overlays it. Playback flips it on
- * animation frames, since the song's timeupdate is far too coarse for a beat.
- * A shot without a clip shows its still.
+ * The incoming shot of a beat toggle or dissolve (lib/musicVideoCutEffects.js)
+ * over the outgoing one: its clip runs on the song's clock, reading the footage
+ * before its in-point, and shows on the toggle's frames or fades in over the
+ * dissolve's, as the final render overlays it. A shot without a clip shows its still.
*/
function ToggleClip({ scene, toggle, audioRef, time }) {
const mediaRef = useRef(null);
@@ -351,7 +382,7 @@ function ToggleClip({ scene, toggle, audioRef, time }) {
const el = mediaRef.current;
const audio = audioRef.current;
if (!el) return;
- el.style.opacity = toggle.incoming.some(([a, b]) => t >= a && t < b) ? '1' : '0';
+ el.style.opacity = String(incomingOpacity(toggle, t));
if (el.tagName !== 'VIDEO' || el.readyState < 1) return;
const duration = Number.isFinite(el.duration) ? el.duration : null;
const target = clipTimeAt(scene, Math.min(Math.max(t, toggle.windowStartSec), toggle.cutSec), duration, { early: true });
@@ -366,25 +397,7 @@ function ToggleClip({ scene, toggle, audioRef, time }) {
const el = mediaRef.current;
return () => { if (el?.tagName === 'VIDEO') releaseVideo(el); };
}, [src]);
- useEffect(() => {
- const audio = audioRef.current;
- if (!audio) return undefined;
- let handle = 0;
- const tick = () => {
- apply(audio.currentTime || 0);
- handle = requestAnimationFrame(tick);
- };
- const start = () => { cancelAnimationFrame(handle); handle = requestAnimationFrame(tick); };
- const stop = () => { cancelAnimationFrame(handle); apply(audio.currentTime || 0); };
- audio.addEventListener('play', start);
- audio.addEventListener('pause', stop);
- if (!audio.paused) start();
- return () => {
- cancelAnimationFrame(handle);
- audio.removeEventListener('play', start);
- audio.removeEventListener('pause', stop);
- };
- }, [audioRef, apply]);
+ useSongFrames(audioRef, apply);
const fit = sceneFrameFit(scene);
const className = `pointer-events-none absolute inset-0 h-full w-full ${src && fit !== 'fill' ? 'object-contain' : 'object-cover'} ${fit === 'black' ? 'bg-black' : ''}`;
if (src) {
@@ -395,6 +408,24 @@ function ToggleClip({ scene, toggle, audioRef, time }) {
return <img ref={mediaRef} src={`/data/images/${scene.referenceImageId}`} alt="" data-testid="beat-toggle-clip" style={{ opacity: 0 }} className={className} />;
}
+/**
+ * A fade through black (lib/musicVideoCutEffects.js): black over the picture
+ * that darkens into the cut and lifts after it, as the render fades the two shots.
+ */
+function FadeBlack({ fade, audioRef, time }) {
+ const ref = useRef(null);
+ const apply = useCallback((t) => {
+ const el = ref.current;
+ if (!el) return;
+ const down = t >= fade.outStartSec && t < fade.cutSec ? (t - fade.outStartSec) / (fade.cutSec - fade.outStartSec) : 0;
+ const up = t >= fade.cutSec && t < fade.inEndSec ? 1 - (t - fade.cutSec) / (fade.inEndSec - fade.cutSec) : 0;
+ el.style.opacity = String(Math.min(1, Math.max(down, up)));
+ }, [fade]);
+ useEffect(() => { apply(time); }, [time, apply]);
+ useSongFrames(audioRef, apply);
+ return <div ref={ref} data-testid="fade-black" style={{ opacity: 0 }} className="pointer-events-none absolute inset-0 bg-black" />;
+}
+
/**
* The cutting room floor outro after the song (lib/musicVideoStatsOutro.js):
* when the song ends it plays for its own length on a clock of its own, and
@@ -494,11 +525,15 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
const media = figure?.querySelector('video[data-ready="true"]:not([aria-hidden="true"])') || figure?.querySelector('img');
return captureMediaFrame(media);
};
- // Beat toggles across cuts, on the frames the final render flips (lib/musicVideoCutEffects.js).
+ // Cut effects (beat toggles, dissolves, fades through black), on the frames the final
+ // render paints them (lib/musicVideoCutEffects.js), storyboard-planned ones included.
const beats = project.audioAnalysis?.beats;
- const toggles = useMemo(() => sceneBeatToggles(scenes, { fps: ANIMATIC_FPS, beats, endSec: songEndSec || null }), [scenes, beats, songEndSec]);
- // A toggle mounts its incoming clip a little ahead, so it has loaded when the flips start.
- const nearToggles = toggles.filter((t) => time >= t.windowStartSec - 3 && time < t.cutSec);
+ const storyboardRows = project.productionReview?.draft?.storyboard;
+ const planned = useMemo(() => plannedTransitions(storyboardRows), [storyboardRows]);
+ const cutEffects = useMemo(() => sceneCutEffects(scenes, { fps: ANIMATIC_FPS, beats, endSec: songEndSec || null, planned }), [scenes, beats, songEndSec, planned]);
+ // A toggle or dissolve mounts its incoming clip a little ahead, so it has loaded when it starts showing.
+ const nearToggles = cutEffects.filter((t) => t.incoming && time >= t.windowStartSec - 3 && time < t.cutSec);
+ const nearFades = cutEffects.filter((t) => t.style === 'fade-black' && time >= t.outStartSec - 1 && time < t.inEndSec + 1);
const shot = shotAt(scenes, time);
const timed = timedShots(scenes);
const index = shot ? timed.indexOf(shot) : -1;
@@ -544,6 +579,7 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
const incoming = scenes.find((scene) => scene.sceneId === toggle.toSceneId);
return incoming ? <ToggleClip key={`toggle:${toggle.toSceneId}:${incoming.videoHistoryId || ''}`} scene={incoming} toggle={toggle} audioRef={audioRef} time={time} /> : null;
})}
+ {nearFades.map((fade) => <FadeBlack key={`fade:${fade.fromSceneId}`} fade={fade} audioRef={audioRef} time={time} />)}
{/* The shots' VHS glitches on their cuts, on the frames the final render repaints. */}
<TransitionGlitch scenes={scenes} figureRef={figureRef} audioRef={audioRef} time={time} layered={layered}
endSec={Number(project.audioAnalysis?.durationSec) || null} fps={ANIMATIC_FPS} />
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
index 0c3a3387c3..01733eda55 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
@@ -154,6 +154,38 @@ describe('StoryboardAnimatic clips', () => {
expect(clipB.currentTime).toBeCloseTo(1.875, 2);
});
+ // Uniquely catches the animatic's dissolve or fade through black (including one the
+ // storyboard plans) showing on frames the final render does not, or not ramping.
+ it('fades the next shot in over a dissolve and darkens through black around a fade', async () => {
+ const scenes = [
+ { sceneId: 'a', label: 'One', startSec: 0, endSec: 4, videoHistoryId: 'clip-a' },
+ { sceneId: 'b', label: 'Two', startSec: 4, endSec: 8, videoHistoryId: 'clip-b', cutEffect: { style: 'fade-black', enabled: true, overlapSec: 1 } },
+ { sceneId: 'c', label: 'Three', startSec: 8, endSec: 12, videoHistoryId: 'clip-c' },
+ ];
+ const project = { id: 'p', scenes, productionReview: { draft: { storyboard: [{ sceneId: 'a', transition: 'Dissolve' }] } } };
+ render(<StoryboardAnimatic project={project} audioUrl="/song.mp3" />);
+ const audio = screen.getByLabelText('Song for the storyboard animatic');
+ const at = (t) => { Object.defineProperty(audio, 'currentTime', { value: t, configurable: true }); fireEvent.timeUpdate(audio); };
+ at(2.9);
+ const incoming = await screen.findByTestId('beat-toggle-clip');
+ expect(incoming.style.opacity).toBe('0');
+ at(3.5);
+ const half = Number(incoming.style.opacity);
+ expect(half).toBeGreaterThan(0.4);
+ expect(half).toBeLessThan(0.6);
+ at(3.95);
+ expect(Number(incoming.style.opacity)).toBeGreaterThan(half);
+ at(7.4);
+ const black = await screen.findByTestId('fade-black');
+ expect(black.style.opacity).toBe('0');
+ at(7.75);
+ expect(Number(black.style.opacity)).toBeCloseTo(0.5, 2);
+ at(8.25);
+ expect(Number(black.style.opacity)).toBeCloseTo(0.5, 2);
+ at(8.6);
+ expect(black.style.opacity).toBe('0');
+ });
+
it('loads the next shots\' clips ahead and cuts to the same loaded clip', async () => {
const scenes = [
{ sceneId: 'a', label: 'One', startSec: 0, endSec: 1, referenceImageId: 'frame-a.png' },
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index e58bbf6974..ebd4462767 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -318,5 +318,5 @@ grep -i "what you want to do" client/src/lib/README.md
| `filmLook.js` | Shared film look controls, presets, normalizer, prompt vocabulary, the SVG filter markup the editor previews with and the playback-time motion layers (server `lib/filmLook.js`). |
| `musicVideoNarrativeEvents.js` | Named narrative event kinds, absolute onset/word/frame resolution and deterministic silence/reactive state for composition documents. |
| `musicVideoImageEffects.js` | Music-video image effects (a camera flash that develops over a still shot), re-exported from `server/lib/musicVideoImageEffects.js`: the effects, labels and develop lengths, `sceneImageEffect`, `imageEffectState`. Used by `components/musicVideo/SceneImageEffect.jsx` and the storyboard animatic. |
-| `musicVideoCutEffects.js` | Music-video cut effects (the beat toggle across a cut), re-exported from `server/lib/musicVideoCutEffects.js`: settings, labels, `sceneCutEffect`, `sceneBeatToggles`. Used by `components/musicVideo/SceneCutEffect.jsx` and the storyboard animatic. |
+| `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. |
diff --git a/client/src/lib/musicVideoCutEffects.js b/client/src/lib/musicVideoCutEffects.js
index 738c3436b2..aa6fd09859 100644
--- a/client/src/lib/musicVideoCutEffects.js
+++ b/client/src/lib/musicVideoCutEffects.js
@@ -1,7 +1,7 @@
/**
* Music Video cut effects — re-export of `server/lib/musicVideoCutEffects.js`,
- * so the shot card's beat toggle control and the animatic's toggling follow the
- * same settings and frames as the final render.
+ * so the shot card's cut effect control and the animatic's toggles, dissolves and
+ * fades follow the same settings and frames as the final render.
*/
export {
BEAT_TOGGLE_OVERLAP,
@@ -9,8 +9,10 @@ export {
BEAT_TOGGLE_RATES,
MUSIC_VIDEO_CUT_EFFECT_LABELS,
MUSIC_VIDEO_CUT_EFFECTS,
- beatToggleCuts,
beatToggleSwitches,
- sceneBeatToggles,
+ cutEffectCuts,
+ plannedCutEffect,
+ plannedTransitions,
sceneCutEffect,
+ sceneCutEffects,
} from '../../../server/lib/musicVideoCutEffects.js';
diff --git a/server/lib/README.md b/server/lib/README.md
index 7f76ede35f..67369877f1 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -876,7 +876,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `musicVideoLocalModels.js` | Which local video models render which Music Video shot: `localModelRendersCutaway` (image-to-video), `localModelRendersPerformance` (LTX-2 family a2v or MiniMax H3 Ref2VA, from the still + song slice), `localMusicVideoModels(models, performance)` and `localModelTakesSongAudio` (LTX-2 family a2v: a cutaway can take its song slice). Shared by the shot card and project model pickers and `submitJob.js` / `prepareParams.js`. |
| `musicVideoHandoffFrame.js` | Continuing shots: `sceneClipOutFrameSec(scene, clipDurationSec, fps)` is the time in a shot's clip of the last frame the cut shows (performance edit in/out, loop wrap, hold past the clip's end); `previousShot(project, sceneId)` is the shot before it by start time. |
| `musicVideoCrossLinks.js` | Cross-links between a release's posts: each post's public link, the `Label: url` lines a new draft adds, which links a posted record carries (`links`, or what its draft always linked), and `crossLinkBackfill(kit)` listing the links each editable post (YouTube, Suno, X, Stacker News) still lacks. Shared by the publish payloads and the Publish stage. |
-| `musicVideoCutEffects.js` | Music Video cut effects a shot sets on its cut out (`scene.cutEffect`, kept while switched off): the beat toggle, which flips the picture between the two shots' clips on the beats before the cut. `sceneCutEffect`, `beatToggleSwitches`, `beatToggleCuts` (the render's frames) and `sceneBeatToggles` (the animatic's song times). Browser-safe. |
+| `musicVideoCutEffects.js` | Music Video cut effects a shot sets on its cut out (`scene.cutEffect`, kept while switched off): the beat toggle (flips between the two shots' clips on the beats before the cut), a dissolve and a fade through black. `sceneCutEffect`, `beatToggleSwitches`, `cutEffectCuts` (the render's frames), `sceneCutEffects` (the animatic's song times), and `plannedCutEffect` / `plannedTransitions` (a storyboard row's Dissolve or Fade as the default effect). Browser-safe. |
| `musicVideoExcerptRange.js` | `excerptRangeFits(startSec, endSec, totalSec, fps)`: whether a code/document excerpt window fits a frame-quantized render, allowing the end up to one frame past it (scene ends follow the analysed song length; the caller clamps). The start must fall inside the render; an unknown fps allows no slack. |
| `musicVideoPlateEvidence.js` | Asset-bound authored-shot plate requirements, current evidence and selected-image admission. |
diff --git a/server/lib/musicVideoCutEffects.js b/server/lib/musicVideoCutEffects.js
index dcaac0c7d0..c3419a1ea8 100644
--- a/server/lib/musicVideoCutEffects.js
+++ b/server/lib/musicVideoCutEffects.js
@@ -12,20 +12,26 @@
* and a lip-sync stay on the song, and the shot itself starts exactly where it
* would without the toggle.
*
- * One definition serves both players: the final render overlays the incoming
- * clip on exactly the frames `beatToggleCuts` names, and the storyboard
- * animatic shows it on the same frames.
+ * `dissolve`: over the last moments of the outgoing shot the incoming clip fades
+ * in over it, on the song's clock like the toggle's, and is fully in on the cut.
+ *
+ * `fade-black`: the outgoing shot fades to black and the incoming one fades in
+ * from it, half the length on each side of the cut. On the last shot it fades
+ * the video out to black.
+ *
+ * One definition serves both players: the final render paints exactly the
+ * frames `cutEffectCuts` names, and the storyboard animatic shows the same.
*/
-export const MUSIC_VIDEO_CUT_EFFECTS = Object.freeze(['beat-toggle']);
+export const MUSIC_VIDEO_CUT_EFFECTS = Object.freeze(['beat-toggle', 'dissolve', 'fade-black']);
-export const MUSIC_VIDEO_CUT_EFFECT_LABELS = Object.freeze({ 'beat-toggle': 'Beat toggle' });
+export const MUSIC_VIDEO_CUT_EFFECT_LABELS = Object.freeze({ 'beat-toggle': 'Beat toggle', dissolve: 'Dissolve', 'fade-black': 'Fade through black' });
// How often the picture flips: on every beat, or on every half beat (twice as fast).
export const BEAT_TOGGLE_RATES = Object.freeze(['beat', 'half']);
export const BEAT_TOGGLE_RATE_LABELS = Object.freeze({ beat: 'Every beat', half: 'Every half beat' });
-// The overlap before the cut the toggle plays over, in seconds.
+// How long a cut effect plays, in seconds: before the cut for a toggle or dissolve, across it for a fade.
export const BEAT_TOGGLE_OVERLAP = Object.freeze({ min: 0.25, max: 4, default: 1 });
// With no beat grid the overlap is split into this many even steps.
@@ -36,10 +42,12 @@ const CUT_GUARD_SEC = 0.02;
/**
* A scene's cut effect with its settings filled in (`{ style, enabled,
* overlapSec, rate }`), or null when it has none. A switched-off effect keeps
- * its settings, so turning it back on restores them.
+ * its settings, so turning it back on restores them. `planned` (a storyboard
+ * row's transition, see `plannedCutEffect`) stands in while the shot has never
+ * set one.
*/
-export function sceneCutEffect(scene) {
- const effect = scene?.cutEffect;
+export function sceneCutEffect(scene, planned = null) {
+ const effect = scene?.cutEffect === undefined ? plannedCutEffect(planned) : scene?.cutEffect;
if (!effect || !MUSIC_VIDEO_CUT_EFFECTS.includes(effect.style)) return null;
const overlap = Number(effect.overlapSec);
return {
@@ -76,16 +84,20 @@ export function beatToggleSwitches({ cutSec, overlapSec, rate = 'beat', beats =
}
/**
- * The beat toggles on a cut timeline. `pieces` are its sections in order,
- * `{ sceneId, startFrame, endFrame, partner?, cutEffect? }` on one
- * frame grid (`cutEffect` as `sceneCutEffect` returns it). A toggle plays on the
- * cut out of a shot's last piece into the next shot's first; an intercut
- * partner piece on either side carries none. Returns, per toggle:
- * `{ index, cutFrame, windowFrames, incoming: [[from, to)] }` with `index` the
- * outgoing piece, `incoming` the frames (on the timeline) that show the incoming
- * clip, and `windowFrames` how many frames before the cut its clip is read.
+ * The cut effects on a cut timeline. `pieces` are its sections in order,
+ * `{ sceneId, startFrame, endFrame, partner?, cutEffect? }` on one frame grid
+ * (`cutEffect` as `sceneCutEffect` returns it). An effect plays on the cut out
+ * of a shot's last piece into the next shot's first (a fade to black also at
+ * the end of the last shot); an intercut partner piece on either side carries
+ * none. Returns, per effect, `{ style, index, cutFrame }` with `index` the
+ * outgoing piece, plus:
+ * - beat toggle and dissolve: `windowFrames`, how many frames before the cut the
+ * incoming clip is read, and `incoming`, the frames (on the timeline) it shows
+ * on: the toggle's flips, or the whole window for a dissolve, which fades it in;
+ * - fade through black: `outFrames` fading out before the cut and `inFrames`
+ * fading in after it.
*/
-export function beatToggleCuts(pieces, { fps, beats = [] }) {
+export function cutEffectCuts(pieces, { fps, beats = [] }) {
const list = Array.isArray(pieces) ? pieces : [];
const lastOf = new Map();
const firstOf = new Map();
@@ -95,13 +107,30 @@ export function beatToggleCuts(pieces, { fps, beats = [] }) {
lastOf.set(p.sceneId, i);
});
const out = [];
- for (let i = 0; i < list.length - 1; i++) {
+ for (let i = 0; i < list.length; i++) {
const from = list[i];
const to = list[i + 1];
const effect = from?.cutEffect;
- if (!effect?.enabled || effect.style !== 'beat-toggle' || from.partner || to?.partner || from.sceneId === to.sceneId) continue;
- if (lastOf.get(from.sceneId) !== i || firstOf.get(to.sceneId) !== i + 1) continue;
- const cutFrame = to.startFrame;
+ if (!effect?.enabled || from.partner || lastOf.get(from.sceneId) !== i) continue;
+ const intoNext = !!to && !to.partner && to.sceneId !== from.sceneId && firstOf.get(to.sceneId) === i + 1;
+ const cutFrame = to ? to.startFrame : from.endFrame;
+ const lengthFrames = Math.max(1, Math.round(effect.overlapSec * fps));
+ if (effect.style === 'fade-black') {
+ if (to && !intoNext) continue;
+ const before = to ? Math.ceil(lengthFrames / 2) : lengthFrames;
+ const outFrames = Math.min(before, cutFrame - from.startFrame);
+ const inFrames = to ? Math.min(lengthFrames - before, to.endFrame - to.startFrame) : 0;
+ if (outFrames + inFrames > 0) out.push({ style: effect.style, index: i, cutFrame, outFrames, inFrames });
+ continue;
+ }
+ if (!intoNext) continue;
+ if (effect.style === 'dissolve') {
+ // It starts after the outgoing shot's first frame, so that shot always shows.
+ const windowFrames = Math.min(lengthFrames, cutFrame - from.startFrame - 1);
+ if (windowFrames > 0) out.push({ style: effect.style, index: i, cutFrame, windowFrames, incoming: [[cutFrame - windowFrames, cutFrame]] });
+ continue;
+ }
+ if (effect.style !== 'beat-toggle') continue;
const switches = beatToggleSwitches({ cutSec: cutFrame / fps, overlapSec: effect.overlapSec, rate: effect.rate, beats })
.map((sec) => Math.round(sec * fps))
// A flip keeps to the outgoing shot, after its first frame.
@@ -109,32 +138,53 @@ export function beatToggleCuts(pieces, { fps, beats = [] }) {
if (!switches.length) continue;
const incoming = [];
for (let k = 0; k < switches.length; k += 2) incoming.push([switches[k], k + 1 < switches.length ? switches[k + 1] : cutFrame]);
- const windowFrames = cutFrame - switches[0];
- out.push({ index: i, cutFrame, windowFrames, incoming });
+ out.push({ style: effect.style, index: i, cutFrame, windowFrames: cutFrame - switches[0], incoming });
}
return out;
}
/**
- * The storyboard's beat toggles in song seconds (the animatic's counterpart of
- * the render's): `[{ fromSceneId, toSceneId, windowStartSec, cutSec, incoming:
- * [[fromSec, toSec)] }]`.
+ * The storyboard's cut effects in song seconds (the animatic's counterpart of
+ * the render's): `[{ style, fromSceneId, toSceneId, cutSec, ... }]`, with
+ * `windowStartSec` and `incoming: [[fromSec, toSec)]` for a toggle or dissolve,
+ * and `outStartSec` / `inEndSec` for a fade through black (`toSceneId` null on
+ * the last shot). `planned` maps a scene id to its storyboard row's transition.
*/
-export function sceneBeatToggles(scenes, { fps, beats = [], endSec = null }) {
+export function sceneCutEffects(scenes, { fps, beats = [], endSec = null, planned = null }) {
const timed = (Array.isArray(scenes) ? scenes : []).filter((s) => Number.isFinite(s?.startSec)).sort((a, b) => a.startSec - b.startSec);
const pieces = timed.map((scene, i) => {
const next = timed[i + 1];
const stop = next ? next.startSec : (Number.isFinite(endSec) ? endSec : scene.endSec);
return {
sceneId: scene.sceneId, startFrame: Math.round(scene.startSec * fps), endFrame: Math.round((stop ?? scene.startSec) * fps),
- cutEffect: sceneCutEffect(scene),
+ cutEffect: sceneCutEffect(scene, planned?.get?.(scene.sceneId)),
};
});
- return beatToggleCuts(pieces, { fps, beats }).map((t) => ({
+ return cutEffectCuts(pieces, { fps, beats }).map((t) => ({
+ style: t.style,
fromSceneId: pieces[t.index].sceneId,
- toSceneId: pieces[t.index + 1].sceneId,
- windowStartSec: (t.cutFrame - t.windowFrames) / fps,
+ toSceneId: pieces[t.index + 1]?.sceneId ?? null,
cutSec: t.cutFrame / fps,
- incoming: t.incoming.map(([a, b]) => [a / fps, b / fps]),
+ ...(t.incoming ? { windowStartSec: (t.cutFrame - t.windowFrames) / fps, incoming: t.incoming.map(([a, b]) => [a / fps, b / fps]) }
+ : { outStartSec: (t.cutFrame - t.outFrames) / fps, inEndSec: (t.cutFrame + t.inFrames) / fps }),
}));
}
+
+// A storyboard row's transition, in its own words, as a cut effect out of its shot:
+// a fade to black, or a dissolve or plain fade into the next shot. An "Entry:" part
+// describes the cut into the shot, as does a fade in, so only the rest is read.
+const FADE_BLACK = /\b(fades?|dips?)\b[^.;]*\bblack\b|\bfade[sd]? out\b/i;
+const DISSOLVE = /\b(dissolves?|cross-?fades?|fades?)\b/i;
+
+/** The cut effect a storyboard row's `transition` text plans out of its shot, or null (a plain cut). */
+export function plannedCutEffect(transition) {
+ if (typeof transition !== 'string') return null;
+ const exit = transition.replace(/\bentry:[^.;]*[.;]?/i, '').replace(/\bfades? in\b[^.;]*/gi, '');
+ const style = FADE_BLACK.test(exit) ? 'fade-black' : DISSOLVE.test(exit) ? 'dissolve' : null;
+ return style ? { style, enabled: true, overlapSec: BEAT_TOGGLE_OVERLAP.default } : null;
+}
+
+/** Each storyboard row's transition by scene id (`rows`: `project.productionReview.draft.storyboard`), for `sceneCutEffect` and `sceneCutEffects`. */
+export function plannedTransitions(rows) {
+ return new Map((Array.isArray(rows) ? rows : []).filter((row) => row?.sceneId && typeof row.transition === 'string').map((row) => [row.sceneId, row.transition]));
+}
diff --git a/server/services/musicVideo/cutEffects.test.js b/server/services/musicVideo/cutEffects.test.js
index ebd0b9a318..5fbc073928 100644
--- a/server/services/musicVideo/cutEffects.test.js
+++ b/server/services/musicVideo/cutEffects.test.js
@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { findFfmpeg } from '../../lib/ffmpeg.js';
-import { beatToggleCuts, sceneCutEffect } from '../../lib/musicVideoCutEffects.js';
+import { cutEffectCuts, plannedCutEffect, plannedTransitions, sceneCutEffect } from '../../lib/musicVideoCutEffects.js';
import { buildMusicVideoFfmpegArgs } from './render.js';
import { applySceneUpdate } from './projectsLogic.js';
@@ -19,22 +19,64 @@ const toggle = (extra = {}) => sceneCutEffect({ cutEffect: { style: 'beat-toggle
// Uniquely catches where a beat toggle flips: which beats (or half beats) in the
// overlap, the even fallback with no beat grid, and which cuts carry one.
-describe('beatToggleCuts', () => {
+describe('cutEffectCuts', () => {
const piece = (sceneId, startFrame, endFrame, extra = {}) => ({ sceneId, startFrame, endFrame, ...extra });
it('flips to the incoming shot on each beat in the overlap before the cut, incoming first', () => {
- const [cut] = beatToggleCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 48)], { fps: 24, beats: [0.25, 0.5, 0.75, 1] });
- expect(cut).toEqual({ index: 0, cutFrame: 24, windowFrames: 12, incoming: [[12, 18]] });
- const [half] = beatToggleCuts([piece('a', 0, 24, { cutEffect: toggle({ rate: 'half' }) }), piece('b', 24, 48)], { fps: 24, beats: [0.25, 0.5, 0.75, 1] });
+ const [cut] = cutEffectCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 48)], { fps: 24, beats: [0.25, 0.5, 0.75, 1] });
+ expect(cut).toEqual({ style: 'beat-toggle', index: 0, cutFrame: 24, windowFrames: 12, incoming: [[12, 18]] });
+ const [half] = cutEffectCuts([piece('a', 0, 24, { cutEffect: toggle({ rate: 'half' }) }), piece('b', 24, 48)], { fps: 24, beats: [0.25, 0.5, 0.75, 1] });
expect(half).toMatchObject({ incoming: [[12, 15], [18, 21]] });
- const [even] = beatToggleCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 48)], { fps: 24 });
+ const [even] = cutEffectCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 48)], { fps: 24 });
expect(even.incoming).toEqual([[12, 15], [18, 21]]);
});
it('plays only when switched on, and never on an intercut partner or inside a split shot', () => {
- expect(beatToggleCuts([piece('a', 0, 24, { cutEffect: toggle({ enabled: false }) }), piece('b', 24, 48)], { fps: 24 })).toEqual([]);
- expect(beatToggleCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 48, { partner: true })], { fps: 24 })).toEqual([]);
- expect(beatToggleCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 36), piece('a', 36, 48, { cutEffect: toggle() })], { fps: 24 })).toEqual([]);
+ expect(cutEffectCuts([piece('a', 0, 24, { cutEffect: toggle({ enabled: false }) }), piece('b', 24, 48)], { fps: 24 })).toEqual([]);
+ expect(cutEffectCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 48, { partner: true })], { fps: 24 })).toEqual([]);
+ expect(cutEffectCuts([piece('a', 0, 24, { cutEffect: toggle() }), piece('b', 24, 36), piece('a', 36, 48, { cutEffect: toggle() })], { fps: 24 })).toEqual([]);
+ });
+
+ // Uniquely catches a dissolve or fade landing off the cut, overrunning a short shot, or a fade missing the video's end.
+ it('fades a dissolve in before the cut, and a fade through black half each side of it or out at the end', () => {
+ const effect = (style, overlapSec) => sceneCutEffect({ cutEffect: { style, overlapSec } });
+ expect(cutEffectCuts([piece('a', 0, 24, { cutEffect: effect('dissolve', 0.5) }), piece('b', 24, 48)], { fps: 24 }))
+ .toEqual([{ style: 'dissolve', index: 0, cutFrame: 24, windowFrames: 12, incoming: [[12, 24]] }]);
+ // A dissolve longer than its shot starts after the shot's first frame.
+ expect(cutEffectCuts([piece('a', 0, 6, { cutEffect: effect('dissolve', 2) }), piece('b', 6, 48)], { fps: 24 })[0]).toMatchObject({ windowFrames: 5 });
+ expect(cutEffectCuts([piece('a', 0, 24, { cutEffect: effect('fade-black', 1) }), piece('b', 24, 48)], { fps: 24 }))
+ .toEqual([{ style: 'fade-black', index: 0, cutFrame: 24, outFrames: 12, inFrames: 12 }]);
+ expect(cutEffectCuts([piece('a', 0, 24), piece('b', 24, 48, { cutEffect: effect('fade-black', 1) })], { fps: 24 }))
+ .toEqual([{ style: 'fade-black', index: 1, cutFrame: 48, outFrames: 24, inFrames: 0 }]);
+ // Only a fade has anything to do on the last shot.
+ expect(cutEffectCuts([piece('a', 0, 24, { cutEffect: effect('dissolve', 1) })], { fps: 24 })).toEqual([]);
+ });
+});
+
+// Uniquely catches a storyboard row's planned transition being misread, or
+// overriding a shot that already picked its own (a plain cut included).
+describe('a transition the storyboard plans', () => {
+ it.each([
+ ['Dissolve', 'dissolve'],
+ ['Slow dissolve into the bedroom', 'dissolve'],
+ ['Crossfade to the band', 'dissolve'],
+ ['Fade to her dreaming', 'dissolve'],
+ ['Fade to black', 'fade-black'],
+ ['Slow fade out', 'fade-black'],
+ ['Entry: dissolve from the car. Exit: hard cut', null],
+ ['Entry: match cut. Exit: dissolve to the bed', 'dissolve'],
+ ['Fade in from black', null],
+ ['Cut', null],
+ ['Whip pan to the drummer', null],
+ ])('reads "%s" as %s', (text, style) => {
+ expect(plannedCutEffect(text)?.style ?? null).toBe(style);
+ });
+
+ it('stands in only until the shot picks an effect of its own', () => {
+ const planned = plannedTransitions([{ sceneId: 's1', transition: 'Dissolve' }]).get('s1');
+ expect(sceneCutEffect({ sceneId: 's1' }, planned)).toMatchObject({ style: 'dissolve', enabled: true, overlapSec: 1 });
+ expect(sceneCutEffect({ sceneId: 's1', cutEffect: { style: 'dissolve', enabled: false } }, planned)).toMatchObject({ enabled: false });
+ expect(sceneCutEffect({ sceneId: 's1', cutEffect: null }, planned)).toBeNull();
});
});
@@ -96,6 +138,49 @@ describe.skipIf(!ffmpeg)('a beat toggle across a cut in the final render', () =>
});
});
+// Uniquely catches a dissolve or a fade through black failing in ffmpeg, landing
+// off its frames, adding time, or a dissolve's incoming clip leaving the song's clock.
+describe.skipIf(!ffmpeg)('a dissolve and a fade through black across a cut in the final render', () => {
+ const song = join(dir, 'song.wav');
+ const outgoing = join(dir, 'fx-outgoing.mp4');
+ const incoming = join(dir, 'fx-incoming.mp4');
+ const render = (style) => {
+ run(['-f', 'lavfi', '-i', 'sine=frequency=440:duration=2', '-y', song]);
+ run(['-f', 'lavfi', '-i', `color=white:s=${W}x${H}:r=${FPS}:d=1`, '-pix_fmt', 'yuv420p', '-y', outgoing]);
+ run(['-f', 'lavfi', '-i', `color=gray:s=${W}x${H}:r=${FPS}:d=1`, '-pix_fmt', 'yuv420p', '-y', incoming]);
+ const clip = (videoPath, i, extra = {}) => ({ sceneId: `s${i}`, videoPath, width: W, height: H, fps: FPS, duration: 1, sourceSec: 1, loop: false, inSec: 0, outSec: 1, frameFit: 'fill', ...extra });
+ const output = join(dir, `${style}.mp4`);
+ const cutEffect = sceneCutEffect({ cutEffect: { style, overlapSec: 0.5 } });
+ const plan = buildMusicVideoFfmpegArgs([clip(outgoing, 0, { cutEffect }), clip(incoming, 1)], song, output, { audioDurationSec: 2, frameGrid: true });
+ run(plan.args.filter((arg, i) => !(arg === '-progress' || plan.args[i - 1] === '-progress')));
+ expect(plan.totalDuration).toBe(2);
+ const means = frameMeans(output);
+ expect(means).toHaveLength(2 * FPS);
+ return means;
+ };
+
+ it('fades the incoming shot in over the last half second, fully in on the cut', () => {
+ const means = render('dissolve');
+ const gray = means[23];
+ // White until the window (frame 6), then stepping down toward the incoming gray, which holds from the cut.
+ expect(means.slice(0, 6).every((m) => m > 250)).toBe(true);
+ const window = means.slice(6, 12);
+ window.forEach((m, k) => expect(m).toBeLessThan(k === 0 ? 256 : window[k - 1]));
+ expect(window.every((m) => m > gray + 2)).toBe(true);
+ expect(means.slice(12).every((m) => Math.abs(m - gray) < 2)).toBe(true);
+ });
+
+ it('darkens into the cut and lifts after it', () => {
+ const means = render('fade-black');
+ expect(means.slice(0, 9).every((m) => m > 250)).toBe(true);
+ expect(means[11]).toBeLessThan(means[10]);
+ expect(means[11]).toBeLessThan(100);
+ expect(means[12]).toBeLessThan(20);
+ expect(means[14]).toBeGreaterThan(means[13]);
+ expect(Math.abs(means[15] - means[23])).toBeLessThan(2);
+ });
+});
+
// Uniquely catches the scene PATCH refusing the effect, losing its settings when switched off, or taking an unknown style.
describe('a shot\'s cut effect on the board', () => {
const project = { id: 'mv-1', scenes: [{ sceneId: 's1', order: 0, startSec: 0, endSec: 4, takes: [] }] };
@@ -106,6 +191,6 @@ describe('a shot\'s cut effect on the board', () => {
const { project: off } = applySceneUpdate(set, 's1', { cutEffect: { ...cutEffect, enabled: false } });
expect(sceneCutEffect(off.scenes[0])).toEqual({ ...cutEffect, enabled: false });
expect(applySceneUpdate(off, 's1', { cutEffect: null }).project.scenes[0].cutEffect).toBeNull();
- expect(() => applySceneUpdate(project, 's1', { cutEffect: { style: 'crossfade' } })).toThrow();
+ expect(() => applySceneUpdate(project, 's1', { cutEffect: { style: 'wipe' } })).toThrow();
});
});
diff --git a/server/services/musicVideo/render.js b/server/services/musicVideo/render.js
index a3f132788a..c39b26e5c2 100644
--- a/server/services/musicVideo/render.js
+++ b/server/services/musicVideo/render.js
@@ -60,7 +60,7 @@ import { AUDIO_NORM, buildAudioBedMix } from '../videoTimeline/audioBedMix.js';
import { musicVideoEvents } from './events.js';
import { projectSoundBed } from './soundBed.js';
import { intercutClips } from './intercut.js';
-import { beatToggleCuts, sceneCutEffect } from '../../lib/musicVideoCutEffects.js';
+import { cutEffectCuts, plannedTransitions, sceneCutEffect } from '../../lib/musicVideoCutEffects.js';
import { imageEffectGlitchFrames, mergeGlitchFrames, musicVideoTransitionFilter, sceneTransitions, shotGlitchFrames, transitionGlitchFrames } from '../../lib/musicVideoTransitions.js';
import { stillMoveForCamera } from '../../lib/cameraMovements.js';
import { isEndFrameImageEffect, musicVideoImageEffectFilter, sceneImageEffect } from '../../lib/musicVideoImageEffects.js';
@@ -122,9 +122,9 @@ const round3 = (n) => Math.round(n * 1000) / 1000;
// window was padded to the provider minimum) and ends at `edit.outSec`. It
// never loops: repeating a sung take would desync the mouth from the song.
const performanceEdit = (scene) => selectedPerformanceInstruction(scene)?.edit ?? null;
-// A shot's switched-on cut effect for its clip, or nothing.
-const cutEffectOf = (scene) => {
- const effect = sceneCutEffect(scene);
+// A shot's switched-on cut effect for its clip (else the one its storyboard row plans), or nothing.
+const cutEffectOf = (scene, planned) => {
+ const effect = sceneCutEffect(scene, planned.get(scene.sceneId));
return effect?.enabled ? { cutEffect: effect } : {};
};
@@ -235,6 +235,7 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss
status: 400, code: 'NO_SCENE_CLIPS',
});
}
+ const planned = plannedTransitions(project.productionReview?.draft?.storyboard);
const history = scenes.some((s) => sceneVisualLayer(s, { layered }) === 'footage') ? await loadHistory() : [];
const historyMap = new Map((Array.isArray(history) ? history : []).map((h) => [h.id, h]));
const missing = [];
@@ -246,7 +247,7 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss
if (layer !== 'footage') {
const spanSec = authoredSpan(scene);
if (spanSec == null) { untimed.push(scene.sceneId); continue; }
- const section = { sceneId: scene.sceneId, layer, inSec: 0, outSec: spanSec, duration: spanSec, sourceSec: spanSec, ...sceneTransitions(scene), ...cutEffectOf(scene) };
+ const section = { sceneId: scene.sceneId, layer, inSec: 0, outSec: spanSec, duration: spanSec, sourceSec: spanSec, ...sceneTransitions(scene), ...cutEffectOf(scene, planned) };
// A composed render has no code to run: a code shot (#10297) is a black
// ground the typography layer draws over, cut exactly like a blank card.
if (layer === 'code') {
@@ -324,7 +325,7 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss
// VHS glitches on its cuts (musicVideoTransitions.js) ride over the edit without moving it.
...sceneTransitions(scene),
// So does a beat toggle on its cut out (musicVideoCutEffects.js).
- ...cutEffectOf(scene),
+ ...cutEffectOf(scene, planned),
});
}
if (missing.length > 0) {
@@ -582,15 +583,17 @@ export function buildMusicVideoFfmpegArgs(clips, audioPath, outputPath, { audioD
}
return clipInput;
};
- // A beat toggle (musicVideoCutEffects.js) flips the picture to the next shot's clip
- // on the beats before a cut. That clip runs on the song's clock, read from an input
- // of its own, so its own section starts exactly where it would without the toggle.
+ // A beat toggle or dissolve (musicVideoCutEffects.js) shows the next shot's clip over
+ // the end of a shot: flipping to it on the beats, or fading it in. That clip runs on the
+ // song's clock, read from an input of its own, so its own section starts exactly where
+ // it would without the effect. A fade through black darkens the sections either side.
const sectionFrame = (sec) => Math.round(sec * fps);
- const toggles = beatToggleCuts(plan.map(({ c, startSec, endSec }) => ({
+ const cutEffects = cutEffectCuts(plan.map(({ c, startSec, endSec }) => ({
sceneId: c.sceneId, startFrame: sectionFrame(startSec), endFrame: sectionFrame(endSec),
partner: !!c.intercutOf, cutEffect: c.cutEffect,
})), { fps, beats });
- const prerolls = toggles.map((t) => {
+ const fades = cutEffects.filter((t) => t.style === 'fade-black');
+ const prerolls = cutEffects.filter((t) => t.incoming).map((t) => {
const { c } = plan[t.index + 1];
// The footage just before the incoming shot's in-point, on the output timebase
// its speed and offset already set; any part before the clip starts holds its first frame.
@@ -611,14 +614,20 @@ export function buildMusicVideoFfmpegArgs(clips, audioPath, outputPath, { audioD
inputs.push('-i', audioPath);
for (const overlay of overlays) inputs.push('-itsoffset', String(overlay.startSec), '-i', overlay.path);
- const filters = plan.map(({ c, frames }, i) => `${sectionChain(c, inputOf[i], { canonW, canonH, fps, frames, frameGrid })}[${prerolls.some((p) => p.index === i) ? 'vraw' : 'v'}${i}]`);
+ const fadeChain = (i, frames) => [
+ ...fades.filter((f) => f.index === i - 1 && f.inFrames > 0).map((f) => `,fade=t=in:s=0:n=${f.inFrames}`),
+ ...fades.filter((f) => f.index === i).map((f) => `,fade=t=out:s=${Math.max(0, frames - f.outFrames)}:n=${f.outFrames}`),
+ ].join('');
+ const filters = plan.map(({ c, frames }, i) => `${sectionChain(c, inputOf[i], { canonW, canonH, fps, frames, frameGrid })}${fadeChain(i, frames)}[${prerolls.some((p) => p.index === i) ? 'vraw' : 'v'}${i}]`);
for (const p of prerolls) {
const { frames, startSec } = plan[p.index];
const start = sectionFrame(startSec);
const pad = Math.max(0, frames - p.windowFrames);
const shown = p.incoming.map(([a, b]) => `between(n,${a - start},${b - start - 1})`).join('+');
filters.push(`${sectionChain(p.clip, p.input, { canonW, canonH, fps, frames: p.windowFrames, frameGrid })}[pre${p.index}]`);
- filters.push(`[pre${p.index}]tpad=start=${pad}:color=black,setpts=N/(${fps}*TB)[prepad${p.index}]`);
+ // A dissolve fades the incoming clip in across its window, fully in on the cut.
+ const fadeIn = p.style === 'dissolve' ? `format=yuva420p,fade=t=in:s=0:n=${p.windowFrames + 1}:alpha=1,` : '';
+ filters.push(`[pre${p.index}]${fadeIn}tpad=start=${pad}:color=black,setpts=N/(${fps}*TB)[prepad${p.index}]`);
filters.push(`[vraw${p.index}][prepad${p.index}]overlay=eof_action=pass:enable='${shown}'[v${p.index}]`);
}
const gradeFilter = musicVideoGradeFilter(grade, plan.map(({ c, startSec, endSec }) => ({ sceneId: c.sceneId, startSec, endSec })), { fps });