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 VHS glitch and channel change transitions on music video cuts (#11278)

[._.]/f5eb09eb0d9b
diff --git a/client/src/components/musicVideo/SceneCard.jsx b/client/src/components/musicVideo/SceneCard.jsx
index 1779ceaff2..d78de19050 100644
--- a/client/src/components/musicVideo/SceneCard.jsx
+++ b/client/src/components/musicVideo/SceneCard.jsx
@@ -33,6 +33,7 @@ import { ShotLockButton, useShotLock } from './ShotLock.jsx';
import ScenePoster from './ScenePoster.jsx';
import SceneRenderTarget, { lastRenderTarget, renderTargetOverrides } from './SceneRenderTarget.jsx';
import SceneFrameFit, { sceneFrameFit } from './SceneFrameFit.jsx';
+import SceneTransitions from './SceneTransitions.jsx';
// The two timeline-bound scene fields rendered as identical number inputs.
const SCENE_TIME_FIELDS = [['Start', 'startSec'], ['End', 'endSec']];
@@ -221,6 +222,8 @@ export default function SceneCard({
<>
{/* What this shot's render covers and costs, and what blocks it, stays in view. */}
<SceneTimingPlan timing={timing} sceneId={scene.sceneId} lipSyncBackend={renderLane} onSplit={onSplit} onMergeNext={onMergeNext} />
+ {/* A VHS glitch riding on the cut into or out of this shot; never moves the cut. */}
+ <SceneTransitions fieldId={fieldId} scene={scene} onChange={applyPatch} />
{/* Everything set once and rarely revisited: timing, shot mode, layer, camera. */}
<details className="group/settings rounded border border-port-border">
<summary className="flex min-h-[44px] cursor-pointer items-center gap-2 px-2 text-xs marker:content-none sm:min-h-[32px] [&::-webkit-details-marker]:hidden">
diff --git a/client/src/components/musicVideo/SceneCard.test.jsx b/client/src/components/musicVideo/SceneCard.test.jsx
index f2179ff43a..877f23b723 100644
--- a/client/src/components/musicVideo/SceneCard.test.jsx
+++ b/client/src/components/musicVideo/SceneCard.test.jsx
@@ -430,3 +430,22 @@ describe('frame fit for an off-shape clip', () => {
expect(onEditLocal).toHaveBeenCalledWith('s1', { frameFit: 'vhs' });
});
});
+
+// Uniquely catches the glitch picker saving the wrong field or failing to clear it.
+describe('VHS glitch transitions', () => {
+ it('sets a glitch on the cut out of a shot and clears it with Off', () => {
+ 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 out = screen.getByLabelText('Glitch out');
+ fireEvent.change(out, { target: { value: 'vhs-glitch' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { transitionOut: 'vhs-glitch' });
+ expect(out.value).toBe('vhs-glitch');
+ fireEvent.change(out, { target: { value: '' } });
+ expect(onSave).toHaveBeenLastCalledWith('s1', { transitionOut: null });
+ expect(screen.getByLabelText('Glitch in').value).toBe('');
+ });
+});
diff --git a/client/src/components/musicVideo/SceneTransitions.jsx b/client/src/components/musicVideo/SceneTransitions.jsx
new file mode 100644
index 0000000000..1e5c25b37d
--- /dev/null
+++ b/client/src/components/musicVideo/SceneTransitions.jsx
@@ -0,0 +1,32 @@
+import { MUSIC_VIDEO_TRANSITIONS, MUSIC_VIDEO_TRANSITION_LABELS } from '../../lib/musicVideoTransitions.js';
+
+const SIDES = Object.freeze([
+ ['transitionIn', 'Glitch in', 'in', 'A VHS glitch over the cut into this shot. It adds no time: the cut stays where it is.'],
+ ['transitionOut', 'Glitch out', 'out', 'A VHS glitch over the cut to the next shot. It adds no time: the cut stays where it is.'],
+]);
+
+/**
+ * The VHS glitch over the cut into and out of a shot, Off by default. It rides
+ * on the cut in the animatic and the final render alike, and never moves a cut
+ * or changes a lock.
+ */
+export default function SceneTransitions({ fieldId, scene, onChange, disabled = false }) {
+ return (
+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs" data-testid="scene-transitions">
+ {SIDES.map(([key, label, idSuffix, title]) => {
+ const value = MUSIC_VIDEO_TRANSITIONS.includes(scene[key]) ? scene[key] : '';
+ return (
+ <span key={key} className="flex min-w-0 items-center gap-1">
+ <label htmlFor={fieldId(`glitch-${idSuffix}`)} className={value ? 'text-port-accent' : 'text-port-text-muted'}>{label}</label>
+ <select id={fieldId(`glitch-${idSuffix}`)} value={value} disabled={disabled} title={title}
+ onChange={(e) => onChange({ [key]: e.target.value || null })}
+ className="min-w-0 bg-port-bg border border-port-border rounded px-1 py-1 text-xs min-h-[44px] sm:min-h-0 disabled:opacity-50">
+ <option value="">Off</option>
+ {MUSIC_VIDEO_TRANSITIONS.map((style) => <option key={style} value={style}>{MUSIC_VIDEO_TRANSITION_LABELS[style]}</option>)}
+ </select>
+ </span>
+ );
+ })}
+ </div>
+ );
+}
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.jsx b/client/src/components/musicVideo/StoryboardAnimatic.jsx
index 5a2e3d4db2..d2045bfcf5 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.jsx
@@ -12,6 +12,7 @@ import { normalizeTitleCard } from '../../../../server/lib/musicVideoTitleCard.j
import ShotStepper from './ShotStepper.jsx';
import FrameStepper, { captureMediaFrame } from './FrameStepper.jsx';
import { sceneFrameFit } from './SceneFrameFit.jsx';
+import TransitionGlitch from './TransitionGlitch.jsx';
const timedShots = (scenes) => scenes.filter((scene) => Number.isFinite(scene?.startSec)).sort((a, b) => a.startSec - b.startSec);
@@ -311,6 +312,9 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
{clipShots.map((scene) => (
<ShotClip key={`${scene.sceneId}:${scene.videoHistoryId}`} scene={scene} audioRef={audioRef} time={time} current={scene === shot} />
))}
+ {/* The shots' VHS glitches on their cuts, on the frames the final render repaints. */}
+ <TransitionGlitch scenes={scenes} figureRef={figureRef} audioRef={audioRef} time={time}
+ endSec={Number(project.audioAnalysis?.durationSec) || null} fps={ANIMATIC_FPS} />
{overlay}
</FilmLookFrame>
</figure>
diff --git a/client/src/components/musicVideo/TransitionGlitch.jsx b/client/src/components/musicVideo/TransitionGlitch.jsx
new file mode 100644
index 0000000000..c366a296aa
--- /dev/null
+++ b/client/src/components/musicVideo/TransitionGlitch.jsx
@@ -0,0 +1,261 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { sceneTransitionSections, transitionFrameAt, transitionGlitchFrames } from '../../lib/musicVideoTransitions.js';
+
+// The canvas paints at most this wide; a glitch lasts a few frames, so detail past it is never seen.
+const MAX_CANVAS_PX = 960;
+// Animation frames a paused glitch frame keeps repainting while its picture finishes decoding.
+const SETTLE_FRAMES = 30;
+
+const scratchCanvas = (() => {
+ const pool = new Map();
+ return (key, width, height) => {
+ let canvas = pool.get(key);
+ if (!canvas) { canvas = document.createElement('canvas'); pool.set(key, canvas); }
+ if (canvas.width !== width) canvas.width = width;
+ if (canvas.height !== height) canvas.height = height;
+ return canvas;
+ };
+})();
+
+// Deterministic tape snow: the same frame always shows the same grain.
+let snowTile = null;
+function snow() {
+ if (snowTile) return snowTile;
+ snowTile = document.createElement('canvas');
+ snowTile.width = 256;
+ snowTile.height = 256;
+ const ctx = snowTile.getContext('2d');
+ if (!ctx) return snowTile;
+ const image = ctx.createImageData(256, 256);
+ let seed = 123457;
+ for (let i = 0; i < image.data.length; i += 4) {
+ // xorshift32: an LCG's low byte repeats every 256 pixels and draws stripes.
+ seed ^= seed << 13; seed ^= seed >>> 17; seed ^= seed << 5;
+ const v = (seed >>> 24) & 255;
+ image.data[i] = v; image.data[i + 1] = v; image.data[i + 2] = v; image.data[i + 3] = 255;
+ }
+ ctx.putImageData(image, 0, 0);
+ return snowTile;
+}
+
+/** Draw a picture element the way its CSS object-fit lays it out in the frame. */
+function drawFitted(ctx, el, width, height) {
+ const w = el.videoWidth || el.naturalWidth;
+ const h = el.videoHeight || el.naturalHeight;
+ if (!w || !h) return;
+ const fit = getComputedStyle(el).objectFit;
+ const scale = fit === 'cover' ? Math.max(width / w, height / h) : fit === 'contain' ? Math.min(width / w, height / h) : null;
+ if (scale == null) { ctx.drawImage(el, 0, 0, width, height); return; }
+ const dw = w * scale;
+ const dh = h * scale;
+ ctx.drawImage(el, (width - dw) / 2, (height - dh) / 2, dw, dh);
+}
+
+// The render's slip (one ffmpeg swaprect): band [y, y+h) moves `a` px over and the
+// edge it uncovers shows the strip beside it.
+function slip(ctx, src, a, y, h, width) {
+ const d = Math.min(Math.abs(Math.round(a)), width - 1);
+ if (d < 1 || h < 1) return;
+ if (a > 0) {
+ ctx.drawImage(src, 0, y, width - d, h, d, y, width - d, h);
+ ctx.drawImage(src, d, y, d, h, 0, y, d, h);
+ } else {
+ ctx.drawImage(src, d, y, width - d, h, 0, y, width - d, h);
+ ctx.drawImage(src, Math.max(0, width - 2 * d), y, d, h, width - d, y, d, h);
+ }
+}
+
+// The render's vertical roll (one ffmpeg swaprect): the frame moves `a` px down (or up)
+// and the edge it uncovers shows the strip beside it.
+function roll(ctx, src, a, width, height) {
+ const d = Math.min(Math.abs(Math.round(a)), height - 1);
+ if (d < 1) return;
+ if (a > 0) {
+ ctx.drawImage(src, 0, 0, width, height - d, 0, d, width, height - d);
+ ctx.drawImage(src, 0, d, width, d, 0, 0, width, d);
+ } else {
+ ctx.drawImage(src, 0, d, width, height - d, 0, 0, width, height - d);
+ ctx.drawImage(src, 0, Math.max(0, height - 2 * d), width, d, 0, height - d, width, d);
+ }
+}
+
+/** Paint one glitch frame (`params` from musicVideoTransitions.js) of what the figure shows. */
+function paintGlitch(canvas, figure, params, frame) {
+ const box = canvas.getBoundingClientRect();
+ if (!box.width || !box.height) return false;
+ const width = Math.min(MAX_CANVAS_PX, Math.round(box.width * (window.devicePixelRatio || 1)));
+ const height = Math.round(width * box.height / box.width);
+ if (canvas.width !== width) canvas.width = width;
+ if (canvas.height !== height) canvas.height = height;
+ const out = canvas.getContext('2d');
+ if (!out) return false;
+
+ // The picture as the frame shows it: the still, then the clip over it once it has a frame.
+ let cur = scratchCanvas('a', width, height);
+ const base = cur.getContext('2d');
+ base.fillStyle = '#000';
+ base.fillRect(0, 0, width, height);
+ const still = figure?.querySelector('img');
+ const clip = figure?.querySelector('video[data-ready="true"]:not([aria-hidden="true"])');
+ const stillReady = !!still?.complete && still.naturalWidth > 0;
+ const clipReady = !!clip && clip.readyState >= 2;
+ // Nothing decoded yet: leave the picture clean rather than glitch a black frame.
+ if (!stillReady && !clipReady) return false;
+ if (stillReady) drawFitted(base, still, width, height);
+ if (clipReady) drawFitted(base, clip, width, height);
+
+ // Slips in the render's order: the whole frame, then each torn band, ping-ponging two scratch canvases.
+ const slips = [
+ ...(params.roll ? [{ roll: params.roll * height }] : []),
+ ...(params.shift ? [{ a: params.shift * width, y: 0, h: height }] : []),
+ ...(params.tears || []).map((t) => ({ a: t.shift * width, y: Math.round(t.y * height), h: Math.round(t.h * height) })),
+ ];
+ slips.forEach((s, i) => {
+ const next = scratchCanvas(i % 2 ? 'a' : 'b', width, height);
+ const ctx = next.getContext('2d');
+ ctx.drawImage(cur, 0, 0);
+ if (s.roll) roll(ctx, cur, s.roll, width, height);
+ else slip(ctx, cur, s.a, s.y, Math.min(s.h, height - s.y), width);
+ cur = next;
+ });
+
+ // Colour fringe: red and blue pulled apart sideways, rebuilt additively.
+ out.globalCompositeOperation = 'source-over';
+ out.globalAlpha = 1;
+ const fringe = Math.round((params.chroma || 0) * width);
+ if (fringe > 0) {
+ out.fillStyle = '#000';
+ out.fillRect(0, 0, width, height);
+ [['#f00', -fringe], ['#0f0', 0], ['#00f', fringe]].forEach(([mask, dx], i) => {
+ const layer = scratchCanvas(`c${i}`, width, height);
+ const lctx = layer.getContext('2d');
+ lctx.globalCompositeOperation = 'source-over';
+ lctx.drawImage(cur, dx, 0);
+ lctx.globalCompositeOperation = 'multiply';
+ lctx.fillStyle = mask;
+ lctx.fillRect(0, 0, width, height);
+ lctx.globalCompositeOperation = 'source-over';
+ out.globalCompositeOperation = 'lighter';
+ out.drawImage(layer, 0, 0);
+ });
+ out.globalCompositeOperation = 'source-over';
+ } else {
+ out.drawImage(cur, 0, 0);
+ }
+
+ // Brightness and saturation, in the render's order (before the bar, lines and snow).
+ const bright = params.bright ?? 1;
+ const sat = params.sat ?? 1;
+ if (bright > 1) {
+ // Adding the picture to itself at (b - 1) scales it by b.
+ const lit = scratchCanvas('lit', width, height);
+ lit.getContext('2d').drawImage(canvas, 0, 0);
+ out.globalCompositeOperation = 'lighter';
+ out.globalAlpha = Math.min(1, bright - 1);
+ out.drawImage(lit, 0, 0);
+ } else if (bright < 1) {
+ out.globalAlpha = 1 - bright;
+ out.fillStyle = '#000';
+ out.fillRect(0, 0, width, height);
+ }
+ if (sat < 1) {
+ out.globalCompositeOperation = 'saturation';
+ out.globalAlpha = 1 - sat;
+ out.fillStyle = '#808080';
+ out.fillRect(0, 0, width, height);
+ }
+ out.globalCompositeOperation = 'source-over';
+ out.globalAlpha = 1;
+ if (params.bar) {
+ out.fillStyle = `rgba(255,255,255,${params.bar.alpha})`;
+ out.fillRect(0, Math.round(params.bar.y * height), width, Math.max(2, Math.round(params.bar.h * height)));
+ }
+ if (params.lines) {
+ const gap = Math.max(2, Math.round(height / 270));
+ out.fillStyle = `rgba(0,0,0,${params.lines})`;
+ for (let y = 0; y < height; y += gap) out.fillRect(0, y, width, Math.max(1, Math.floor(gap / 2)));
+ }
+ if (params.noise) {
+ const pattern = out.createPattern(snow(), 'repeat');
+ if (pattern) {
+ out.save();
+ out.globalCompositeOperation = 'overlay';
+ out.globalAlpha = Math.min(1, params.noise);
+ // Each frame shifts the grain, as the render's temporal noise does.
+ out.translate((frame * 97) % 256, (frame * 61) % 256);
+ out.fillStyle = pattern;
+ out.fillRect(-256, -256, width + 256, height + 256);
+ // Past 1 the snow drowns the picture: a dead channel's static.
+ if (params.noise > 1) {
+ out.globalCompositeOperation = 'source-over';
+ out.globalAlpha = Math.min(1, params.noise - 1);
+ out.fillRect(-256, -256, width + 256, height + 256);
+ }
+ out.restore();
+ }
+ }
+ canvas.style.filter = sat > 1 ? `saturate(${sat})` : '';
+ return true;
+}
+
+/**
+ * The shots' cut transitions over the storyboard animatic: on each glitched
+ * frame (the same frames the final render repaints) a canvas over the picture
+ * paints the glitch of what is on screen; every other frame it stays hidden.
+ * Below the lyric layer, as the render keeps its typography clean.
+ */
+export default function TransitionGlitch({ scenes, figureRef, audioRef, time, endSec = null, fps }) {
+ const canvasRef = useRef(null);
+ const glitches = useMemo(() => transitionGlitchFrames(sceneTransitionSections(scenes, fps, { endSec })), [scenes, fps, endSec]);
+ const paint = useCallback((t) => {
+ const canvas = canvasRef.current;
+ if (!canvas) return;
+ const hit = transitionFrameAt(glitches, Math.floor(t * fps + 1e-6));
+ const shown = !!hit && paintGlitch(canvas, figureRef.current, hit.params, hit.frame);
+ canvas.style.visibility = shown ? 'visible' : 'hidden';
+ }, [glitches, fps, figureRef]);
+ // A pause, a scrub or a frame step lands through `time`; playback runs on animation frames.
+ // Paused, it repaints for a moment, since the clip's seek to the new frame decodes after the step.
+ useEffect(() => {
+ paint(time);
+ let handle = 0;
+ let left = SETTLE_FRAMES;
+ const settle = () => {
+ if (!audioRef.current?.paused || left-- <= 0) return;
+ paint(time);
+ handle = requestAnimationFrame(settle);
+ };
+ handle = requestAnimationFrame(settle);
+ return () => cancelAnimationFrame(handle);
+ }, [time, paint, audioRef]);
+ useEffect(() => {
+ const audio = audioRef.current;
+ if (!audio || !glitches.length) return undefined;
+ let handle = 0;
+ const tick = () => {
+ paint(audio.currentTime || 0);
+ handle = requestAnimationFrame(tick);
+ };
+ const start = () => { cancelAnimationFrame(handle); handle = requestAnimationFrame(tick); };
+ const stop = () => { cancelAnimationFrame(handle); paint(audio.currentTime || 0); };
+ audio.addEventListener('play', start);
+ audio.addEventListener('pause', stop);
+ audio.addEventListener('ended', stop);
+ if (!audio.paused) start();
+ return () => {
+ cancelAnimationFrame(handle);
+ audio.removeEventListener('play', start);
+ audio.removeEventListener('pause', stop);
+ audio.removeEventListener('ended', stop);
+ };
+ }, [audioRef, glitches, paint]);
+ if (!glitches.length) return null;
+ return (
+ <canvas
+ ref={canvasRef}
+ data-testid="animatic-glitch"
+ style={{ visibility: 'hidden' }}
+ className="pointer-events-none absolute inset-0 h-full w-full"
+ />
+ );
+}
diff --git a/client/src/components/musicVideo/TransitionGlitch.test.jsx b/client/src/components/musicVideo/TransitionGlitch.test.jsx
new file mode 100644
index 0000000000..0db0c9c91c
--- /dev/null
+++ b/client/src/components/musicVideo/TransitionGlitch.test.jsx
@@ -0,0 +1,16 @@
+import { createRef } from 'react';
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import TransitionGlitch from './TransitionGlitch.jsx';
+
+// Uniquely catches the animatic mounting a glitch layer over a storyboard with no
+// transitions, or failing to mount one when a shot sets one.
+describe('TransitionGlitch', () => {
+ const props = { figureRef: createRef(), audioRef: createRef(), time: 0, endSec: 8, fps: 24 };
+ it('mounts its canvas only when a shot sets a transition, hidden off the glitched frames', () => {
+ const { rerender } = render(<TransitionGlitch {...props} scenes={[{ sceneId: 'a', startSec: 0 }, { sceneId: 'b', startSec: 4 }]} />);
+ expect(screen.queryByTestId('animatic-glitch')).toBeNull();
+ rerender(<TransitionGlitch {...props} scenes={[{ sceneId: 'a', startSec: 0, transitionOut: 'channel-change' }, { sceneId: 'b', startSec: 4 }]} />);
+ expect(screen.getByTestId('animatic-glitch').style.visibility).toBe('hidden');
+ });
+});
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index 1ffd03d5a9..567e72fe12 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -317,3 +317,4 @@ grep -i "what you want to do" client/src/lib/README.md
| `musicVideoGrade.js` | Shared Music Video grade preset and grain bounds for the composition controls. |
| `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. |
+| `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`. Used by `components/musicVideo/SceneTransitions.jsx` and the storyboard animatic. |
diff --git a/client/src/lib/index.js b/client/src/lib/index.js
index 05344cd1b8..14ecfcdd98 100644
--- a/client/src/lib/index.js
+++ b/client/src/lib/index.js
@@ -277,3 +277,4 @@ export * from './trackProvenance.js';
export * from './musicVideoGrade.js';
export * from './filmLook.js';
export * from './musicVideoNarrativeEvents.js';
+export * from './musicVideoTransitions.js';
diff --git a/client/src/lib/musicVideoTransitions.js b/client/src/lib/musicVideoTransitions.js
new file mode 100644
index 0000000000..b5616b1d78
--- /dev/null
+++ b/client/src/lib/musicVideoTransitions.js
@@ -0,0 +1,14 @@
+/**
+ * Music Video cut transitions — re-export of `server/lib/musicVideoTransitions.js`,
+ * so the shot card's picker and the animatic's glitch frames follow the same
+ * styles and frame placement as the final render.
+ */
+export {
+ MUSIC_VIDEO_TRANSITIONS,
+ MUSIC_VIDEO_TRANSITION_LABELS,
+ MUSIC_VIDEO_TRANSITION_STYLES,
+ sceneTransitions,
+ sceneTransitionSections,
+ transitionFrameAt,
+ transitionGlitchFrames,
+} from '../../../server/lib/musicVideoTransitions.js';
diff --git a/server/lib/README.md b/server/lib/README.md
index b79fe5c42f..8c836f13a5 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -559,6 +559,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `chiptuneRender.js` | Deterministic chiptune score → mono PCM → 16-bit WAV buffer (pure Node, no audio deps); `renderScoreToPcm` / `pcmToWavBuffer` / `renderScoreToWav`. |
| `chiptuneScore.js` | Chiptune score contract (#2911): `chiptuneScoreSchema` (Zod) + `sanitizeChiptuneScore`, `buildScoreEvents` — the pattern/order → absolute-time flatten mirrored by `client/src/lib/chiptunePlayback.js`. |
| `musicVideoLayers.js` | Music Video per-scene visual layers (#8985): `MUSIC_VIDEO_VISUAL_LAYERS` (`footage`/`still`/`card`/`code`), `MUSIC_VIDEO_STILL_MOVES` (`hold`/`push`/`pan`), `MUSIC_VIDEO_FRAME_FITS` (`fill`/`still`/`vhs`/`black`: how an off-shape clip fills the frame), `sceneVisualLayer(scene, { layered })` (only a composed render honors a still/card), `sceneHasAuthoredSpan`, and `sceneRenderReady(scene, { layered })`. Pure leaf shared by `services/musicVideo/render.js` and the client board (`client/src/lib/musicVideoLayers.js`). |
+| `musicVideoTransitions.js` | Music Video cut transitions: VHS glitch styles a shot sets on the cut into (`transitionIn`) or out of (`transitionOut`) it, `transitionGlitchFrames` (the glitched frames of a cut timeline, never moving a cut), `transitionFrameAt`, `sceneTransitionSections` and `musicVideoTransitionFilter` (per-frame ffmpeg filters for the final render). Browser-safe; the storyboard animatic paints the same frames. |
| `pitchMath.js` | Dependency-free scientific-pitch math shared by the LLM-authored music formats on both runtimes: `pitchToMidi("C4")` → 60 (null when unparseable) and `midiToFreq(69)` → 440. |
| `wavAudioFile.js` | `writeWavAudioFile(wav, dir, basename)` — land a synthesized WAV Buffer as `<basename>.ogg` via the system ffmpeg, falling back to `<basename>.wav` (and dropping a stale `.ogg`) when ffmpeg is missing or the encode fails; resolves to the filename used. Shared by the chiptune and drawn-waveform renderers and the code-engine take upload. `wavDurationMs(buffer)` reads a PCM WAV's duration from its RIFF header (0 for anything that is not a parseable WAV). `measureWavAudio(buffer)` decodes PCM 16/24/32-bit or float 32/64 (EXTENSIBLE included) into `{ channels, sampleRate, frames, durationMs, peak, rms, nonFinite }` so native renders are judged by their samples (null when undecodable). |
| `superColliderRuntime.js` | Managed SuperCollider runtime contract (#9412), pure: image/runtime/policy version constants, `buildSuperColliderRunArgs` (the one contained `docker run` for untrusted `sclang` source: no network/caps, read-only root, limits, ro input, private output), `buildSuperColliderBuildArgs`, the shipped synthetic probe, `evaluateSuperColliderStatus` (docker-missing … ready, with stale image/evidence invalidation), and the render contract (#9413): `SUPERCOLLIDER_RENDER` bounds, the trusted NRT `SUPERCOLLIDER_RENDER_WRAPPER_SOURCE`, `classifySuperColliderRenderLog` (syntax/source/pattern/score/synthesis failures) and `parseDockerContainerList` for orphan sweeps. I/O lives in `services/superColliderRuntime.js`. |
diff --git a/server/lib/index.js b/server/lib/index.js
index 7dda412260..30e8573f9e 100644
--- a/server/lib/index.js
+++ b/server/lib/index.js
@@ -875,3 +875,5 @@ export * from './deepAudit.js';
export * from './deepAuditCoverage.js';
export * from './auditWorkflow.js';
+
+export * from './musicVideoTransitions.js';
diff --git a/server/lib/musicVideoDependencies.js b/server/lib/musicVideoDependencies.js
index 742679b2ab..072844a60a 100644
--- a/server/lib/musicVideoDependencies.js
+++ b/server/lib/musicVideoDependencies.js
@@ -19,6 +19,8 @@ const layerRef = (scene) => ({ role: 'layer', sceneId: scene.sceneId, assetId: s
.concat(scene.camera ? [['camera', scene.camera]] : [])
// A chosen frame fit changes the render; a shot left to fill keeps its evidence.
.concat(scene.frameFit && scene.frameFit !== 'fill' ? [['frameFit', scene.frameFit]] : [])
+ // A glitch over its cuts changes the render; a shot without one keeps its evidence.
+ .concat(['transitionIn', 'transitionOut'].filter((key) => scene[key]).map((key) => [key, scene[key]]))
// Only a music-driven performance joins it, so lip-sync evidence stays current.
.concat(scene.performanceStyle === 'music' ? [['performanceStyle', 'music']] : []))) });
const snapshot = (references) => ({ version: MUSIC_VIDEO_DEPENDENCY_VERSION, references });
diff --git a/server/lib/musicVideoTransitions.js b/server/lib/musicVideoTransitions.js
new file mode 100644
index 0000000000..2877fdfd67
--- /dev/null
+++ b/server/lib/musicVideoTransitions.js
@@ -0,0 +1,225 @@
+/**
+ * Music Video cut transitions: short VHS glitches that ride on top of a cut
+ * between two shots. A glitch never adds time or moves a cut: it repaints a
+ * few frames around the cut (the outgoing shot's last frames and the incoming
+ * shot's first) and every clip keeps its timing.
+ *
+ * A shot sets `transitionOut` (the cut to the next shot) and/or
+ * `transitionIn` (the cut from the previous one); both name the same cut, so
+ * the outgoing shot's choice wins when both are set. The first shot's "in"
+ * glitches the video's opening frames and the last shot's "out" its closing ones.
+ *
+ * One definition serves both players: the final render turns each glitch
+ * frame into ffmpeg filters enabled on exactly that frame
+ * (`musicVideoTransitionFilter`), and the storyboard animatic paints the same
+ * frame parameters on a canvas over the picture. Every distance is a fraction
+ * of the frame's width or height, so a glitch reads the same at any size.
+ */
+
+export const MUSIC_VIDEO_TRANSITIONS = Object.freeze(['vhs-glitch', 'channel-change', 'vhs-tracking', 'vhs-dropout']);
+
+export const MUSIC_VIDEO_TRANSITION_LABELS = Object.freeze({
+ 'vhs-glitch': 'VHS glitch',
+ 'channel-change': 'Channel change',
+ 'vhs-tracking': 'Tracking roll',
+ 'vhs-dropout': 'Dropout flash',
+});
+
+// Each style's frames, in order, and how many of them come before the cut
+// (`lead`, the outgoing shot's last frames). Per frame:
+// shift whole-frame horizontal slip (signed fraction of width)
+// roll whole-frame vertical roll (signed fraction of height), a TV losing vertical hold
+// tears bands slipped sideways: { y, h } fractions of height, shift of width
+// chroma colour fringe width (fraction of width)
+// bright brightness multiplier; sat a saturation multiplier
+// noise snow strength: 0..1 over the picture, up to 1.6 for a dead channel's static
+// lines scanline darkness, 0..1
+// bar a bright tracking band { y, h, alpha }
+export const MUSIC_VIDEO_TRANSITION_STYLES = Object.freeze({
+ 'vhs-glitch': {
+ lead: 1,
+ frames: [
+ { tears: [{ y: 0.58, h: 0.14, shift: 0.05 }], chroma: 0.008, bright: 1.05, sat: 1.2, noise: 0.25, lines: 0.25 },
+ { shift: 0.03, tears: [{ y: 0.12, h: 0.1, shift: -0.08 }, { y: 0.7, h: 0.18, shift: 0.1 }], chroma: 0.016, bright: 1.25, sat: 1.4,
+ noise: 0.45, lines: 0.4, bar: { y: 0.66, h: 0.035, alpha: 0.7 } },
+ { tears: [{ y: 0.4, h: 0.08, shift: 0.04 }], chroma: 0.006, sat: 1.1, noise: 0.2, lines: 0.2 },
+ ],
+ },
+ // A classic TV changing channels: the old picture rolls and breaks into
+ // static, a frame of dead air, and the new one rolls in and settles.
+ 'channel-change': {
+ lead: 3,
+ frames: [
+ { roll: 0.12, shift: 0.02, chroma: 0.006, bright: 1.1, noise: 0.4, lines: 0.3 },
+ { roll: 0.38, shift: -0.04, chroma: 0.012, bright: 0.8, sat: 0.6, noise: 0.9, lines: 0.4, bar: { y: 0.36, h: 0.06, alpha: 0.5 } },
+ // Dead air: the picture all but gone under a grey wash of static.
+ { bright: 0.35, sat: 0, bar: { y: 0, h: 1, alpha: 0.45 }, noise: 1.6, lines: 0.5 },
+ { bright: 0.3, sat: 0, bar: { y: 0, h: 1, alpha: 0.5 }, noise: 1.6, lines: 0.5 },
+ { roll: -0.3, shift: 0.03, chroma: 0.012, bright: 0.85, sat: 0.6, noise: 0.85, lines: 0.4, bar: { y: 0.68, h: 0.06, alpha: 0.5 } },
+ { roll: -0.08, chroma: 0.008, bright: 1.15, sat: 1.1, noise: 0.35, lines: 0.3 },
+ { chroma: 0.003, noise: 0.15, lines: 0.15 },
+ ],
+ },
+ 'vhs-tracking': {
+ lead: 2,
+ frames: [
+ { tears: [{ y: 0.86, h: 0.1, shift: 0.03 }], chroma: 0.004, noise: 0.2, lines: 0.25, bar: { y: 0.88, h: 0.05, alpha: 0.55 } },
+ { tears: [{ y: 0.64, h: 0.12, shift: -0.04 }], chroma: 0.008, bright: 1.1, noise: 0.35, lines: 0.3, bar: { y: 0.66, h: 0.06, alpha: 0.65 } },
+ { tears: [{ y: 0.42, h: 0.12, shift: 0.05 }], chroma: 0.01, bright: 1.15, sat: 1.2, noise: 0.4, lines: 0.35, bar: { y: 0.44, h: 0.06, alpha: 0.7 } },
+ { tears: [{ y: 0.2, h: 0.1, shift: -0.03 }], chroma: 0.006, noise: 0.3, lines: 0.3, bar: { y: 0.22, h: 0.05, alpha: 0.55 } },
+ { chroma: 0.003, noise: 0.15, lines: 0.2, bar: { y: 0.02, h: 0.04, alpha: 0.4 } },
+ ],
+ },
+ 'vhs-dropout': {
+ lead: 1,
+ frames: [
+ { bright: 1.6, sat: 0.3, noise: 0.7, lines: 0.5 },
+ { tears: [{ y: 0.3, h: 0.06, shift: 0.03 }], chroma: 0.01, bright: 1.2, sat: 0.6, noise: 0.5, lines: 0.35 },
+ ],
+ },
+});
+
+const isTransition = (value) => MUSIC_VIDEO_TRANSITIONS.includes(value);
+
+/** A scene's chosen transitions, only the ones that are set: `{ transitionIn?, transitionOut? }`. */
+export function sceneTransitions(scene) {
+ return {
+ ...(isTransition(scene?.transitionIn) ? { transitionIn: scene.transitionIn } : {}),
+ ...(isTransition(scene?.transitionOut) ? { transitionOut: scene.transitionOut } : {}),
+ };
+}
+
+/**
+ * Every glitched frame of a cut timeline. `sections` are the cut pieces in
+ * order, each `{ sceneId, startFrame, endFrame, transitionIn?, transitionOut? }`
+ * on one frame grid. A piece that only borrows another shot's footage (an
+ * intercut partner, `partner: true`) carries no transitions, and a shot cut
+ * into several pieces glitches in before its first piece and out after its
+ * last. Returns `[{ frame, style, index }]` sorted by frame, at most one per
+ * frame (an earlier cut keeps a frame two close cuts both reach).
+ */
+export function transitionGlitchFrames(sections, { totalFrames = null } = {}) {
+ const list = (Array.isArray(sections) ? sections : []).filter((s) => s && Number.isFinite(s.startFrame) && Number.isFinite(s.endFrame));
+ if (!list.length) return [];
+ const end = Number.isFinite(totalFrames) ? totalFrames : list[list.length - 1].endFrame;
+ const firstOf = new Map();
+ const lastOf = new Map();
+ list.forEach((s, i) => {
+ if (s.partner) return;
+ if (!firstOf.has(s.sceneId)) firstOf.set(s.sceneId, i);
+ lastOf.set(s.sceneId, i);
+ });
+ const outAt = (i) => (!list[i].partner && lastOf.get(list[i].sceneId) === i && isTransition(list[i].transitionOut) ? list[i].transitionOut : null);
+ const inAt = (i) => (!list[i].partner && firstOf.get(list[i].sceneId) === i && isTransition(list[i].transitionIn) ? list[i].transitionIn : null);
+ const taken = new Map();
+ const place = (style, firstFrame) => {
+ MUSIC_VIDEO_TRANSITION_STYLES[style].frames.forEach((_, index) => {
+ const frame = firstFrame + index;
+ if (frame >= 0 && frame < end && !taken.has(frame)) taken.set(frame, { frame, style, index });
+ });
+ };
+ // The opening shot's glitch in starts on the video's first frame.
+ if (inAt(0)) place(inAt(0), list[0].startFrame);
+ for (let i = 0; i < list.length - 1; i++) {
+ const style = outAt(i) || inAt(i + 1);
+ if (style) place(style, list[i + 1].startFrame - MUSIC_VIDEO_TRANSITION_STYLES[style].lead);
+ }
+ // The closing shot's glitch out ends on the video's last frame.
+ const last = list.length - 1;
+ if (outAt(last)) place(outAt(last), list[last].endFrame - MUSIC_VIDEO_TRANSITION_STYLES[outAt(last)].frames.length);
+ return [...taken.values()].sort((a, b) => a.frame - b.frame);
+}
+
+/** The glitch parameters to paint on `frame`, or null when that frame plays clean. */
+export function transitionFrameAt(glitches, frame) {
+ const hit = (glitches || []).find((g) => g.frame === frame);
+ return hit ? { ...hit, params: MUSIC_VIDEO_TRANSITION_STYLES[hit.style].frames[hit.index] } : null;
+}
+
+/**
+ * The storyboard's cut timeline on `fps`: each timed shot runs from its start
+ * to the next shot's start (the last to `endSec`, else its own end).
+ */
+export function sceneTransitionSections(scenes, fps, { endSec = null } = {}) {
+ const timed = (Array.isArray(scenes) ? scenes : []).filter((s) => Number.isFinite(s?.startSec)).sort((a, b) => a.startSec - b.startSec);
+ return 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), ...sceneTransitions(scene) };
+ });
+}
+
+const even = (n) => Math.round(n / 2) * 2;
+const num = (n) => String(Math.round(n * 10000) / 10000);
+
+// A horizontal slip of the band [y, y+h) by `px` (+ right, - left) as one
+// swaprect: the band moves over and the edge it uncovers shows the strip next to it.
+function slip(px, y, h, width) {
+ const a = Math.min(Math.abs(even(px)), width - 2);
+ if (a < 2 || h < 2) return null;
+ const [x1, x2] = px > 0 ? [0, a] : [a, 0];
+ return `swaprect=w=${width - a}:h=${h}:x1=${x1}:y1=${y}:x2=${x2}:y2=${y}`;
+}
+
+// A vertical roll by `px` (+ down, - up) as one swaprect over the full width.
+function roll(px, width, height) {
+ const a = Math.min(Math.abs(even(px)), height - 2);
+ if (a < 2) return null;
+ const [y1, y2] = px > 0 ? [0, a] : [a, 0];
+ return `swaprect=w=${width}:h=${height - a}:x1=0:y1=${y1}:x2=0:y2=${y2}`;
+}
+
+/** Inclusive frame runs as a timeline expression: `between(n,4,6)+between(n,90,90)`. */
+function framesExpr(frames) {
+ const sorted = [...new Set(frames)].sort((a, b) => a - b);
+ const runs = [];
+ for (const f of sorted) {
+ const run = runs[runs.length - 1];
+ if (run && f === run[1] + 1) run[1] = f;
+ else runs.push([f, f]);
+ }
+ return runs.map(([a, b]) => `between(n,${a},${b})`).join('+');
+}
+
+/**
+ * The ffmpeg filter chain (comma-joined, no labels) that paints `glitches` on
+ * a `width`x`height` yuv420p stream counting frames from 0, or null when there
+ * are none. Each filter is enabled only on its frames, so every other frame
+ * passes through untouched and the stream keeps its length.
+ */
+export function musicVideoTransitionFilter(glitches, { width, height }) {
+ if (!Array.isArray(glitches) || glitches.length === 0) return null;
+ const groups = new Map();
+ for (const g of glitches) {
+ const key = `${g.style}:${g.index}`;
+ if (!groups.has(key)) groups.set(key, { params: MUSIC_VIDEO_TRANSITION_STYLES[g.style].frames[g.index], frames: [] });
+ groups.get(key).frames.push(g.frame);
+ }
+ const chain = [];
+ const rows = (fraction) => Math.max(0, Math.min(height, even(fraction * height)));
+ for (const { params: p, frames } of groups.values()) {
+ const enable = `:enable='${framesExpr(frames)}'`;
+ const add = (filter) => { if (filter) chain.push(`${filter}${enable}`); };
+ if (p.roll) add(roll(p.roll * height, width, height));
+ if (p.shift) add(slip(p.shift * width, 0, height, width));
+ for (const tear of p.tears || []) {
+ const y = rows(tear.y);
+ add(slip(tear.shift * width, y, Math.min(rows(tear.h), height - y), width));
+ }
+ const fringe = Math.min(255, Math.round((p.chroma || 0) * width / 2));
+ if (fringe > 0) add(`chromashift=cbh=${fringe}:crh=${-fringe}`);
+ const bright = p.bright ?? 1;
+ const sat = p.sat ?? 1;
+ if (bright !== 1 || sat !== 1) {
+ const chroma = `'clip((val-128)*${num(bright * sat)}+128,0,255)'`;
+ add(`lutyuv=y='clip(val*${num(bright)},0,255)':u=${chroma}:v=${chroma}`);
+ }
+ if (p.bar) add(`drawbox=x=0:y=${rows(p.bar.y)}:w=iw:h=${Math.max(2, rows(p.bar.h))}:color=white@${num(p.bar.alpha)}:t=fill`);
+ if (p.lines) {
+ const gap = Math.max(2, Math.round(height / 270));
+ add(`drawgrid=w=iw:h=${gap}:t=${Math.max(1, Math.floor(gap / 2))}:c=black@${num(p.lines)}`);
+ }
+ if (p.noise) add(`noise=alls=${Math.min(100, Math.round(p.noise * 60))}:allf=t`);
+ }
+ return chain.length ? chain.join(',') : null;
+}
diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.js
index 1768ee9df2..905567d63e 100644
--- a/server/lib/musicVideoValidation.js
+++ b/server/lib/musicVideoValidation.js
@@ -52,6 +52,7 @@ import { shotActionContractProblem } from './musicVideoActionContract.js';
import { NARRATIVE_EVENT_KINDS } from './musicVideoNarrativeEvents.js';
import { MUSIC_VIDEO_MEDIA } from './musicVideoMediumPlan.js';
import { MUSIC_VIDEO_FRAME_FITS, MUSIC_VIDEO_LYRIC_ROLES, MUSIC_VIDEO_STILL_MOVES, MUSIC_VIDEO_TEXT_ZONES, MUSIC_VIDEO_VISUAL_LAYERS } from './musicVideoLayers.js';
+import { MUSIC_VIDEO_TRANSITIONS } from './musicVideoTransitions.js';
import { CAMERA_FRAMINGS, CAMERA_MOVEMENT_VALUES, CAMERA_SPEEDS } from './cameraMovements.js';
import { MUSIC_VIDEO_PERFORMANCE_STYLES, MUSIC_VIDEO_SHOT_MODES, SOURCE_AUDIO_LIPSYNC } from './musicVideoShotTiming.js';
import {
@@ -603,6 +604,9 @@ const sceneLayerFields = {
stillMove: z.enum(MUSIC_VIDEO_STILL_MOVES).optional(),
// How a clip of another shape fills the video's frame (musicVideoLayers.js).
frameFit: z.enum(MUSIC_VIDEO_FRAME_FITS).optional(),
+ // A VHS glitch over the cut into / out of this shot (musicVideoTransitions.js); null clears it.
+ transitionIn: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),
+ transitionOut: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),
cardText: z.string().max(500).nullable().optional(),
// #10302: footage that the composition also draws code over; still counts as footage.
codeOverlay: z.boolean().optional(),
diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.js
index a1bc709f7d..ed290c277c 100644
--- a/server/services/musicVideo/projectsLogic.js
+++ b/server/services/musicVideo/projectsLogic.js
@@ -515,6 +515,8 @@ function buildScene(input, { order }) {
...(input.codeOverlay ? { codeOverlay: true } : {}),
...(input.codeClip ? { codeClip: true } : {}),
...(input.frameFit ? { frameFit: input.frameFit } : {}),
+ ...(input.transitionIn ? { transitionIn: input.transitionIn } : {}),
+ ...(input.transitionOut ? { transitionOut: input.transitionOut } : {}),
cardColor: input.cardColor ?? null,
// #8977: cutaway (any image-to-video lane) unless the director asks for a
// lip-synced performance shot, which only a source-audio provider renders.
@@ -596,6 +598,8 @@ export function replaceScenes(project, sceneInputs) {
...(prior.endImageId ? { endImageId: prior.endImageId } : {}),
...(prior.endFramePrompt ? { endFramePrompt: prior.endFramePrompt } : {}),
...(prior.frameFit ? { frameFit: prior.frameFit } : {}),
+ ...(prior.transitionIn ? { transitionIn: prior.transitionIn } : {}),
+ ...(prior.transitionOut ? { transitionOut: prior.transitionOut } : {}),
takes: prior.takes || [],
...(prior.direction ? { direction: prior.direction } : {}),
};
@@ -606,7 +610,7 @@ export function replaceScenes(project, sceneInputs) {
// Scene fields a director edits within an approved shot (its span, wording and
// selected takes) without adding a shot or lyric the storyboard approval did not cover.
const SCENE_SHOT_EDIT_FIELDS = ['startSec', 'endSec', 'beatAligned', 'label', 'prompt', 'framePrompt', 'visualIntent',
- 'referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit'];
+ 'referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit', 'transitionIn', 'transitionOut'];
/**
* Apply a patch to a single scene. Returns `{ project, updated }`. Throws if the
diff --git a/server/services/musicVideo/render.js b/server/services/musicVideo/render.js
index 30522955bd..8a4a1b5f22 100644
--- a/server/services/musicVideo/render.js
+++ b/server/services/musicVideo/render.js
@@ -56,6 +56,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 { musicVideoTransitionFilter, sceneTransitions, transitionGlitchFrames } from '../../lib/musicVideoTransitions.js';
import { stillMoveForCamera } from '../../lib/cameraMovements.js';
// Per-project render mutex (keyed by projectId so two projects can render in
@@ -234,7 +235,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 };
+ const section = { sceneId: scene.sceneId, layer, inSec: 0, outSec: spanSec, duration: spanSec, sourceSec: spanSec, ...sceneTransitions(scene) };
// 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') {
@@ -285,6 +286,8 @@ export async function resolveSceneClips(project, { layered = false, stillForMiss
inSec,
outSec,
...footageFrameFit(scene),
+ // VHS glitches on its cuts (musicVideoTransitions.js) ride over the edit without moving it.
+ ...sceneTransitions(scene),
});
}
if (missing.length > 0) {
@@ -532,9 +535,16 @@ export function buildMusicVideoFfmpegArgs(clips, audioPath, outputPath, { audioD
const filters = plan.map(({ c, frames }, i) => `${sectionChain(c, inputOf[i], { canonW, canonH, fps, frames, frameGrid })}[v${i}]`);
const gradeFilter = musicVideoGradeFilter(grade, plan.map(({ c, startSec, endSec }) => ({ sceneId: c.sceneId, startSec, endSec })), { fps });
+ // Cut transitions repaint a few frames around their cuts, under the typography, and add no time.
+ const glitches = transitionGlitchFrames(plan.map(({ c, startSec, endSec }) => ({
+ sceneId: c.sceneId, startFrame: Math.round(startSec * fps), endFrame: Math.round(endSec * fps),
+ partner: !!c.intercutOf, transitionIn: c.transitionIn, transitionOut: c.transitionOut,
+ })));
+ const glitchFilter = musicVideoTransitionFilter(glitches, { width: canonW, height: canonH });
const cutLabel = overlays.length > 0 ? 'cut0' : 'outv';
- filters.push(`${plan.map((_, i) => `[v${i}]`).join('')}concat=n=${plan.length}:v=1:a=0[${gradeFilter ? 'ungraded' : cutLabel}]`);
- if (gradeFilter) filters.push(`[ungraded]${gradeFilter}[${cutLabel}]`);
+ const finishing = [gradeFilter, glitchFilter].filter(Boolean).join(',');
+ filters.push(`${plan.map((_, i) => `[v${i}]`).join('')}concat=n=${plan.length}:v=1:a=0[${finishing ? 'ungraded' : cutLabel}]`);
+ if (finishing) filters.push(`[ungraded]${finishing}[${cutLabel}]`);
overlays.forEach((_, k) => {
const out = k === overlays.length - 1 ? 'outv' : `cut${k + 1}`;
filters.push(`[cut${k}][${audioIdx + 1 + k}:v]overlay=eof_action=pass:format=auto[${out}]`);
diff --git a/server/services/musicVideo/transitions.test.js b/server/services/musicVideo/transitions.test.js
new file mode 100644
index 0000000000..541aa17d2c
--- /dev/null
+++ b/server/services/musicVideo/transitions.test.js
@@ -0,0 +1,90 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findFfmpeg } from '../../lib/ffmpeg.js';
+import { transitionGlitchFrames } from '../../lib/musicVideoTransitions.js';
+import { buildMusicVideoFfmpegArgs } from './render.js';
+import { applySceneUpdate } from './projectsLogic.js';
+
+const ffmpeg = await findFfmpeg();
+const dir = mkdtempSync(join(tmpdir(), 'portos-mv-transitions-'));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+const run = (args) => execFileSync(ffmpeg, ['-v', 'error', ...args], { maxBuffer: 64 * 1024 * 1024 });
+const FPS = 12;
+const W = 96;
+const H = 64;
+
+// Uniquely catches where a glitch lands: which cut a shot's in/out names, an
+// intercut partner or a split shot glitching mid-shot, and the video's ends.
+describe('transitionGlitchFrames', () => {
+ const piece = (sceneId, startFrame, endFrame, extra = {}) => ({ sceneId, startFrame, endFrame, ...extra });
+ const framesOf = (sections) => transitionGlitchFrames(sections).map((g) => `${g.frame}:${g.style}`);
+
+ it('puts a shot\'s glitch out on its cut to the next shot, and the outgoing choice wins over the next shot\'s in', () => {
+ expect(framesOf([piece('a', 0, 24, { transitionOut: 'vhs-glitch' }), piece('b', 24, 48, { transitionIn: 'vhs-dropout' })]))
+ .toEqual(['23:vhs-glitch', '24:vhs-glitch', '25:vhs-glitch']);
+ expect(framesOf([piece('a', 0, 24), piece('b', 24, 48, { transitionIn: 'vhs-dropout' })])).toEqual(['23:vhs-dropout', '24:vhs-dropout']);
+ });
+
+ it('glitches the opening and closing frames for the first shot\'s in and the last shot\'s out', () => {
+ expect(framesOf([piece('a', 0, 24, { transitionIn: 'vhs-dropout', transitionOut: 'vhs-dropout' })])).toEqual(['0:vhs-dropout', '1:vhs-dropout', '22:vhs-dropout', '23:vhs-dropout']);
+ });
+
+ it('skips intercut partners and glitches a split shot only around the whole shot', () => {
+ const sections = [
+ piece('a', 0, 10, { transitionIn: 'vhs-dropout', transitionOut: 'vhs-glitch' }),
+ piece('b', 10, 20, { partner: true, transitionOut: 'vhs-tracking' }),
+ piece('a', 20, 30, { transitionIn: 'vhs-dropout', transitionOut: 'vhs-glitch' }),
+ piece('c', 30, 40),
+ ];
+ expect(framesOf(sections)).toEqual(['0:vhs-dropout', '1:vhs-dropout', '29:vhs-glitch', '30:vhs-glitch', '31:vhs-glitch']);
+ });
+});
+
+// Per-frame pixel spread of a raw gray video: ~0 on a flat colour, high once glitched.
+function frameSpreads(path) {
+ const raw = run(['-i', path, '-f', 'rawvideo', '-pix_fmt', 'gray', '-']);
+ const size = W * H;
+ return Array.from({ length: raw.length / size }, (_, f) => {
+ const px = raw.subarray(f * size, (f + 1) * size);
+ const mean = px.reduce((sum, v) => sum + v, 0) / size;
+ return Math.sqrt(px.reduce((sum, v) => sum + (v - mean) ** 2, 0) / size);
+ });
+}
+
+// Uniquely catches the glitch filter chain failing in ffmpeg, landing on the
+// wrong frames, or adding time to the edit.
+describe.skipIf(!ffmpeg)('a VHS glitch on a cut in the final render', () => {
+ it.each([['vhs-glitch', [11, 12, 13]], ['channel-change', [9, 10, 11, 12, 13, 14, 15]]])('%s repaints only the frames around the cut and keeps every frame of the edit', (style, expected) => {
+ const song = join(dir, 'song.wav');
+ const clips = ['0x2050a0', '0xa05020'].map((color, i) => {
+ const videoPath = join(dir, `clip${i}.mp4`);
+ run(['-f', 'lavfi', '-i', `color=${color}:s=${W}x${H}:r=${FPS}:d=1`, '-pix_fmt', 'yuv420p', '-y', videoPath]);
+ return { sceneId: `s${i}`, videoPath, width: W, height: H, fps: FPS, duration: 1, sourceSec: 1, loop: false, inSec: 0, outSec: 1, frameFit: 'fill' };
+ });
+ run(['-f', 'lavfi', '-i', 'sine=frequency=440:duration=2', '-y', song]);
+ clips[0].transitionOut = style;
+ const output = join(dir, `${style}.mp4`);
+ const plan = buildMusicVideoFfmpegArgs(clips, song, output, { audioDurationSec: 2, frameGrid: true });
+ run(plan.args.filter((arg, i) => !(arg === '-progress' || plan.args[i - 1] === '-progress')));
+ expect(plan.totalDuration).toBe(2);
+ expect(plan.sections.map((s) => [s.startSec, s.endSec])).toEqual([[0, 1], [1, 2]]);
+ const spreads = frameSpreads(output);
+ expect(spreads).toHaveLength(2 * FPS);
+ expect(spreads.map((s, f) => (s > 4 ? f : null)).filter((f) => f != null)).toEqual(expected);
+ });
+});
+
+// Uniquely catches the scene PATCH refusing the new fields, keeping a cleared one, or taking an unknown style.
+describe('a shot\'s transitions on the board', () => {
+ const project = { id: 'mv-1', scenes: [{ sceneId: 's1', order: 0, startSec: 0, endSec: 4, takes: [] }] };
+ it('saves a glitch on either side, clears it with null and refuses an unknown style', () => {
+ const { project: set } = applySceneUpdate(project, 's1', { transitionIn: 'vhs-dropout', transitionOut: 'vhs-glitch' });
+ expect(set.scenes[0]).toMatchObject({ transitionIn: 'vhs-dropout', transitionOut: 'vhs-glitch' });
+ const { project: cleared } = applySceneUpdate(set, 's1', { transitionOut: null });
+ expect(cleared.scenes[0].transitionOut).toBeNull();
+ expect(() => applySceneUpdate(project, 's1', { transitionOut: 'crossfade' })).toThrow();
+ });
+});