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

Apply the film look to footage renders and the storyboard animatic

Claude0a29a5bcc40f
diff --git a/client/src/components/media/FilmLookFrame.jsx b/client/src/components/media/FilmLookFrame.jsx
new file mode 100644
index 0000000000..f9a466452b
--- /dev/null
+++ b/client/src/components/media/FilmLookFrame.jsx
@@ -0,0 +1,38 @@
+import { useEffect, useId, useRef, useState } from 'react';
+import { filmLookFilterMarkup, isFilmLookNeutral, normalizeFilmLook } from '../../lib/filmLook.js';
+
+// Before the box is measured (and in a test DOM that never lays out), radii
+// scale to a nominal preview width rather than to nothing.
+const NOMINAL = { width: 1280, height: 720 };
+
+/**
+ * Children seen through a film look, live: the same SVG filter the render and
+ * the gallery bake use, sized to this box so every radius reads as it will at
+ * full size. `frame` is the song frame; it re-seeds the grain and drift so the
+ * texture moves the way the finished render's does. A neutral look renders the
+ * children untouched.
+ */
+export default function FilmLookFrame({ look, frame = 0, className = '', children }) {
+ const ref = useRef(null);
+ const [size, setSize] = useState(NOMINAL);
+ const filterId = `portos-film-look-${useId().replace(/[^A-Za-z0-9_-]/g, '')}`;
+ const settings = normalizeFilmLook(look);
+ const active = !!settings && !isFilmLookNeutral(settings);
+ useEffect(() => {
+ const box = ref.current;
+ if (!box || !active) return undefined;
+ const measure = () => { if (box.clientWidth > 0) setSize({ width: Math.round(box.clientWidth), height: Math.round(box.clientHeight) }); };
+ measure();
+ if (typeof ResizeObserver === 'undefined') return undefined;
+ const observer = new ResizeObserver(measure);
+ observer.observe(box);
+ return () => observer.disconnect();
+ }, [active]);
+ const built = active ? filmLookFilterMarkup(settings, { frame, width: size.width, height: size.height, id: filterId }) : null;
+ return (
+ <div ref={ref} className={`relative ${className}`} style={built?.active ? { filter: built.css } : undefined} data-film-look={built?.active ? 'on' : undefined}>
+ {built?.active && <div aria-hidden="true" dangerouslySetInnerHTML={{ __html: built.svg }} />}
+ {children}
+ </div>
+ );
+}
diff --git a/client/src/components/musicVideo/FilmLookPanel.jsx b/client/src/components/musicVideo/FilmLookPanel.jsx
index d1247e3800..81e3a2bb1f 100644
--- a/client/src/components/musicVideo/FilmLookPanel.jsx
+++ b/client/src/components/musicVideo/FilmLookPanel.jsx
@@ -3,11 +3,13 @@ import FilmLookControls from '../media/FilmLookControls.jsx';
import { isFilmLookNeutral } from '../../lib/filmLook.js';
/**
- * The project's finishing film look: the filter the composition live preview
- * and the final render are viewed through (lib/filmLook.js). Every slider move
- * reaches the docked preview at once (`onEditLocal`); releasing a control saves
- * (`onSave`). Source footage and generated images stay unchanged; to bake the
- * look into a still, open the image and use Film look there.
+ * The project's finishing film look: the filter the docked preview (the
+ * composition document or the storyboard animatic) and the final render are
+ * viewed through (lib/filmLook.js). Every slider move reaches the preview at
+ * once (`onEditLocal`); releasing a control saves (`onSave`). Source footage
+ * and generated images stay unchanged: a document render draws through the
+ * filter, a footage render gets it as a finishing pass over the finished cut,
+ * and a still is baked only from Film look in the image viewer.
*/
export default function FilmLookPanel({ project, onEditLocal, onSave }) {
const documentMode = project.composition?.mode === 'document';
@@ -19,7 +21,7 @@ export default function FilmLookPanel({ project, onEditLocal, onSave }) {
<span className="text-xs text-port-text-muted">{on ? 'Live in the preview · applied to the final render' : 'Off'}</span>
</div>
{!documentMode && (
- <p className="text-xs text-port-text-muted" role="status">The film look is applied by the composition-document render style; this project's render style ignores it. It still works on any image through Film look in the image viewer.</p>
+ <p className="text-xs text-port-text-muted">Applied as a finishing pass after the cut is encoded, so the clips themselves never change; the animatic shows it live.</p>
)}
<FilmLookControls look={project.filmLook} compact
onChange={(look) => onEditLocal({ filmLook: look })}
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.jsx b/client/src/components/musicVideo/StoryboardAnimatic.jsx
index bb7a0f39c3..7760ee5db6 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.jsx
@@ -1,4 +1,6 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import FilmLookFrame from '../media/FilmLookFrame.jsx';
+import { isFilmLookNeutral } from '../../lib/filmLook.js';
import { Captions } from 'lucide-react';
import { formatDurationSec } from '../../utils/formatters.js';
import { getMusicVideoLyricOverlayPreview } from '../../services/apiMusicVideo.js';
@@ -161,6 +163,8 @@ export function clipTimeAt(scene, t, clipSec = null) {
// How many shots past the one on screen get their clip loaded ahead, so a short shot is
// ready to show the moment the song reaches it.
const CLIP_PRELOAD_SHOTS = 2;
+// The song frame the film look's grain and drift follow; footage renders run at 24 fps.
+const ANIMATIC_FPS = 24;
/**
* A shot's selected video clip, muted under the master song and kept in step
@@ -260,6 +264,8 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
return (
<div className={`space-y-2 ${collapsed ? 'max-xl:hidden' : ''}`}>
<figure aria-label="Storyboard animatic" className="relative aspect-video w-full overflow-hidden rounded border border-port-border bg-black">
+ {/* The project's film look, as the final render applies it over the whole picture, lyrics included. */}
+ <FilmLookFrame look={project.filmLook} frame={Math.round(time * ANIMATIC_FPS)} className="h-full w-full">
{shot?.referenceImageId ? (
<img src={`/data/images/${shot.referenceImageId}`} alt="" className="h-full w-full object-contain" />
) : cardInFrame && !shot?.videoHistoryId ? (
@@ -272,6 +278,7 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
<ShotClip key={`${scene.sceneId}:${scene.videoHistoryId}`} scene={scene} audioRef={audioRef} time={time} current={scene === shot} />
))}
{overlay}
+ </FilmLookFrame>
</figure>
<div className="flex min-w-0 items-start gap-2">
<div className="min-w-0 flex-1 text-[11px] text-port-text-muted">
@@ -279,6 +286,7 @@ export default function StoryboardAnimatic({ project, audioUrl, seekRequest, col
<div className="flex flex-wrap items-center gap-x-2 gap-y-1">
<ShotStepper scenes={timed} time={time} onSeek={seekTo} keys />
<span className="tabular-nums">{formatDurationSec(shot.startSec)}</span>
+ {!isFilmLookNeutral(project.filmLook) && <span className="text-port-accent">Film look</span>}
</div>
)}
{!cardInFrame && shot && !shot.referenceImageId && !shot.videoHistoryId && (
diff --git a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
index 632fc5541f..cf6ada8a64 100644
--- a/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
+++ b/client/src/components/musicVideo/StoryboardAnimatic.test.jsx
@@ -143,3 +143,27 @@ describe('StoryboardAnimatic clips', () => {
expect(clipTimeAt({ startSec: 10, loop: false }, 16, 4)).toBeCloseTo(3.95);
});
});
+
+describe('StoryboardAnimatic film look', () => {
+ // Uniquely catches the animatic showing footage without the look the final render will apply.
+ it('shows the project film look over the whole picture on the song frame, and nothing without one', () => {
+ const look = { preset: 'super8', grain: 0.5, halation: 0.4 };
+ const { container, rerender } = render(<StoryboardAnimatic project={{ id: 'p', scenes, filmLook: look }} audioUrl="/song.mp3" />);
+ const frame = container.querySelector('figure [data-film-look="on"]');
+ expect(frame).toBeTruthy();
+ expect(frame.style.filter).toMatch(/^url\(#portos-film-look-/);
+ expect(frame.querySelector('svg filter')).toBeTruthy();
+ expect(screen.getByText('Film look')).toBeTruthy();
+ const before = frame.querySelector('svg').innerHTML;
+ const audio = screen.getByLabelText('Song for the storyboard animatic');
+ Object.defineProperty(audio, 'currentTime', { value: 12, configurable: true });
+ fireEvent.timeUpdate(audio);
+ // The picture sits inside the filtered box, and the grain re-seeds on the new song frame.
+ const after = container.querySelector('figure [data-film-look="on"]');
+ expect(after.querySelector('img').getAttribute('src')).toBe('/data/images/frame-b.png');
+ expect(after.querySelector('svg').innerHTML).not.toBe(before);
+ rerender(<StoryboardAnimatic project={{ id: 'p', scenes, filmLook: null }} audioUrl="/song.mp3" />);
+ expect(container.querySelector('[data-film-look]')).toBeNull();
+ expect(screen.queryByText('Film look')).toBeNull();
+ });
+});
diff --git a/docs/HTML_COMPOSITIONS.md b/docs/HTML_COMPOSITIONS.md
index fb5f0172d9..269b4b2902 100644
--- a/docs/HTML_COMPOSITIONS.md
+++ b/docs/HTML_COMPOSITIONS.md
@@ -302,7 +302,17 @@ what the preview shows and what the render bakes:
the editor also offers **Use on project**.
- **The final render** installs the same runtime in every worker browser
(`documentRenderInitScripts` → `openComposition({ initScripts })`), so the
- split render (#10365) and the overlay text probe see the filtered page.
+ split render (#10365) and the overlay text probe see the filtered page. The
+ code-rendered style takes the same scripts. A **footage render** (the
+ composed or plain-cut ffmpeg encode, final or excerpt) gets the look as a
+ **finishing pass** (`services/musicVideo/filmLookFinish.js`): the finished
+ MP4 plays full-frame in a one-video page in the composition browser, the
+ shared encoder captures it frame by frame on song time, and the render's own
+ audio is copied back untouched. Paid clips are never regenerated to change
+ the feel. The pass takes the second half of the render's progress bar and a
+ cancel aborts it.
+- **The storyboard animatic** (the docked preview for footage projects) shows
+ the look live over the whole picture, lyrics included, on the song frame.
The filter is an SVG `<filter>` applied to the document root (or to the
`<img>` for a still). Radii and offsets scale with the filtered element's
@@ -317,8 +327,8 @@ the frame before the page paints. A neutral look emits no filter at all.
Each control names its effect in photography terms, and the **In a prompt**
box rewrites the current settings as the words that ask a model for the same
qualities (`describeFilmLook`), so tuning a look also teaches the vocabulary
-for the next generation prompt. The look works on composition-document
-projects; the composed render style keeps its own render grade above.
+for the next generation prompt. A composed project's render grade (above)
+still applies inside the ffmpeg encode; the film look follows it.
## Music-video opening title card
diff --git a/server/services/musicVideo/codeRender.js b/server/services/musicVideo/codeRender.js
index 4541f8bdc3..bea2f91cb4 100644
--- a/server/services/musicVideo/codeRender.js
+++ b/server/services/musicVideo/codeRender.js
@@ -72,7 +72,7 @@ export function prepareCodeRender(project, { windowStart = null, windowEnd = nul
}
export async function encodeCodeComposition({
- html, song, width, height, fps, durationSec, audioPath, outputPath, directory, signal, onProgress, audioStartSec = 0, fade = false,
+ html, song, width, height, fps, durationSec, audioPath, outputPath, directory, signal, onProgress, audioStartSec = 0, fade = false, initScripts = [],
}) {
const { findFfmpeg, runFfmpegProcess, edgeFadeFilter } = await import('../../lib/ffmpeg.js');
const { openComposition } = await import('../htmlComposition/browser.js');
@@ -86,7 +86,8 @@ export async function encodeCodeComposition({
const silent = `${outputPath}.silent.mp4`;
let page;
try {
- page = await openComposition(directory, { signal });
+ // `initScripts` (the project's film look runtime) run before the page's own code.
+ page = await openComposition(directory, { signal, initScripts });
await encodeComposition(page, { durationSec, fps, width, height }, silent, {
signal, onProgress: (fraction) => onProgress?.(fraction * 0.9),
});
diff --git a/server/services/musicVideo/excerptRender.js b/server/services/musicVideo/excerptRender.js
index f6d414ca65..5c34198217 100644
--- a/server/services/musicVideo/excerptRender.js
+++ b/server/services/musicVideo/excerptRender.js
@@ -38,6 +38,7 @@ import { encodeCodeComposition, prepareCodeRender, writeCodeProofSheet } from '.
import { encodeDocumentComposition, prepareDocumentRender } from './documentRender.js';
import { projectTypographyPlan } from './composition.js';
import { renderTypographyOverlays, removeCompositionScratch } from './compositionRender.js';
+import { applyFilmLookFinish, filmLookFinishNeeded } from './filmLookFinish.js';
import { startExcerptOnProject, applyExcerptPatch } from './excerpt.js';
import { markRevisionRendering, settleRevisionRender } from './revision.js';
import { ensureInstanceId } from '../instanceIdentity.js';
@@ -369,8 +370,25 @@ export async function startExcerptRender(projectId, { startSec, endSec, aspect =
}
};
+ // The encode's failure and cancel path, shared with the film look pass.
+ const settleFailure = async (canceled, reason) => {
+ job.status = canceled ? 'canceled' : 'error';
+ job.lastError = reason;
+ const log = canceled ? console.log : console.error;
+ log(`${canceled ? '🛑' : '❌'} Music-video excerpt render ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(4, 12)}]: ${reason}`);
+ // #8986 acceptance: cancelling an excerpt removes its partial output.
+ await unlink(outputPath).catch(() => {});
+ await finalize({ status: canceled ? 'canceled' : 'error', error: canceled ? null : reason, filename: null, jobId: null });
+ broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
+ };
+
+ // A footage excerpt with a film look re-encodes its finished window through
+ // the look after ffmpeg (filmLookFinish.js), on song time so the grain
+ // matches the final render's frames.
+ const finishing = filmLookFinishNeeded(project);
const startEncode = (encodeArgs, progressBase = 0) => {
- const encodeProgress = (fraction) => progressBase + (1 - progressBase) * fraction;
+ const encodeTop = finishing ? progressBase + (1 - progressBase) / 2 : 1;
+ const encodeProgress = (fraction) => progressBase + (encodeTop - progressBase) * fraction;
const proc = spawn(ffmpeg, encodeArgs, safeChildProcessOptions({ stdio: ['ignore', 'ignore', 'pipe'] }));
job.process = proc;
@@ -391,7 +409,7 @@ export async function startExcerptRender(projectId, { startSec, endSec, aspect =
broadcastSse(job, { type: 'progress', progress: encodeProgress(Math.min(1, (us / 1_000_000) / totalDuration)) });
}
} else if (key === 'progress' && val === 'end') {
- broadcastSse(job, { type: 'progress', progress: 1 });
+ broadcastSse(job, { type: 'progress', progress: encodeTop });
}
}
});
@@ -418,17 +436,21 @@ export async function startExcerptRender(projectId, { startSec, endSec, aspect =
job.process = null;
if (code !== 0) {
const canceled = isMusicVideoRenderCanceled(job, signal);
- job.status = canceled ? 'canceled' : 'error';
- const reason = canceled ? 'Render cancelled' : signal ? `Killed by signal ${signal}` : `ffmpeg exit ${code}`;
- job.lastError = reason;
- const logClose = canceled ? console.log : console.error;
- logClose(`${canceled ? '🛑' : '❌'} Music-video excerpt render ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(4, 12)}]: ${reason}`);
- // #8986 acceptance: cancelling an excerpt removes its partial output.
- await unlink(outputPath).catch(() => {});
- await finalize({ status: canceled ? 'canceled' : 'error', error: canceled ? null : reason, filename: null, jobId: null });
- broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
+ await settleFailure(canceled, canceled ? 'Render cancelled' : signal ? `Killed by signal ${signal}` : `ffmpeg exit ${code}`);
return;
}
+ if (finishing) {
+ job.overlayAbort = new AbortController();
+ const { signal: finishSignal } = job.overlayAbort;
+ try {
+ await applyFilmLookFinish({ project, path: outputPath, jobId, offsetSec: startSec, signal: finishSignal, label: 'Music-video excerpt film look',
+ onProgress: (fraction) => broadcastSse(job, { type: 'progress', progress: encodeTop + (1 - encodeTop) * fraction }) });
+ } catch (err) {
+ await settleFailure(finishSignal.aborted, finishSignal.aborted ? 'Render cancelled' : `Film look pass failed: ${err.message}`);
+ return;
+ }
+ job.overlayAbort = null;
+ }
try {
job.status = 'complete';
const contactSheetFilename = await buildContactSheet();
diff --git a/server/services/musicVideo/filmLookFinish.js b/server/services/musicVideo/filmLookFinish.js
new file mode 100644
index 0000000000..ba09874037
--- /dev/null
+++ b/server/services/musicVideo/filmLookFinish.js
@@ -0,0 +1,165 @@
+/**
+ * Film-look finishing pass for footage renders.
+ *
+ * A composed or plain-cut music video is an ffmpeg encode, so the project's
+ * film look (lib/filmLook.js) cannot be installed in a page the way a
+ * composition-document render installs it (documentRenderInitScripts). This
+ * pass gives those encoders the identical filter after the fact: the finished
+ * MP4 plays full-frame in a one-video page in the composition browser, the
+ * shared encoder seeks and captures it frame by frame (split across browsers
+ * like a document render), and the render's own audio is copied back
+ * untouched. Paid clips are never regenerated to change the feel, and the
+ * grain, weave and flicker land on the same song frames the preview shows.
+ */
+
+import { copyFile, link, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PATHS } from '../../lib/paths.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { filmLookRuntimeSource, isFilmLookNeutral, normalizeFilmLook } from '../../lib/filmLook.js';
+
+export const FILM_LOOK_FINISH_SCRATCH_DIR = 'music-video-film-look';
+
+/** Whether a footage render of `project` gets the finishing pass. */
+export const filmLookFinishNeeded = (project) => !isFilmLookNeutral(project?.filmLook);
+
+/**
+ * The page the pass captures: the finished render full-frame, `seek(t)` on
+ * song time (frame n of a window starting at `offsetSec` is drawn at song time
+ * `offsetSec + n / fps`, which is render time `n / fps`). Pure.
+ */
+function filmLookFinishPage({ width, height, fps, durationSec, offsetSec = 0, src = 'media/source.mp4' }) {
+ const html = `<!doctype html><html><head><meta charset="utf-8"><title>Film look</title>
+<style>html,body{margin:0;width:${width}px;height:${height}px;overflow:hidden;background:#000}video{display:block;width:${width}px;height:${height}px;object-fit:fill}</style>
+</head><body><video id="source" src="${src}" muted playsinline preload="auto"></video><script src="app.js"></script></body></html>\n`;
+ // Seeks target the middle of a source frame so a frame boundary can never
+ // round to the previous frame, and resolve on 'seeked' AND a presented frame
+ // (a grace period stands in where the browser never presents), the way the
+ // shipped document engine seeks its takes.
+ const js = `(() => {
+ const FPS = ${fps}, DURATION = ${durationSec}, OFFSET = ${offsetSec}, WIDTH = ${width}, HEIGHT = ${height};
+ const FRAME_GRACE_MS = 1000;
+ const video = document.getElementById('source');
+ const loaded = new Promise((resolve, reject) => {
+ if (video.readyState >= 2) { resolve(); return; }
+ video.addEventListener('loadeddata', resolve, { once: true });
+ video.addEventListener('error', () => reject(new Error('the render failed to load (' + (video.error && video.error.code || '?') + ')')), { once: true });
+ });
+ function seekVideo(target) {
+ if (Math.abs(video.currentTime - target) < 1e-6 && video.readyState >= 2 && !video.seeking) return Promise.resolve();
+ return new Promise((resolve, reject) => {
+ let seeked = false;
+ let presented = typeof video.requestVideoFrameCallback !== 'function';
+ let grace = null;
+ let settled = false;
+ const timer = setTimeout(() => { cleanup(); reject(new Error('render seek timed out @ ' + target.toFixed(3) + 's')); }, 15000);
+ const finish = () => { if (seeked && presented) { cleanup(); resolve(); } };
+ const onSeeked = () => {
+ seeked = true;
+ if (!presented) grace = setTimeout(() => { presented = true; finish(); }, FRAME_GRACE_MS);
+ finish();
+ };
+ const fail = () => { cleanup(); reject(new Error('render seek failed (' + (video.error && video.error.code || '?') + ')')); };
+ function cleanup() { settled = true; clearTimeout(timer); clearTimeout(grace); video.removeEventListener('seeked', onSeeked); video.removeEventListener('error', fail); }
+ video.addEventListener('seeked', onSeeked);
+ video.addEventListener('error', fail);
+ const armPresented = () => video.requestVideoFrameCallback((_now, meta) => {
+ if (Number.isFinite(meta && meta.mediaTime) && Math.abs(meta.mediaTime - target) > 1 / FPS) { if (!settled) armPresented(); return; }
+ presented = true; finish();
+ });
+ if (!presented) armPresented();
+ video.currentTime = target;
+ });
+ }
+ globalThis.portosComposition = {
+ durationSec: DURATION, fps: FPS, width: WIDTH, height: HEIGHT,
+ async seek(t) {
+ await loaded;
+ const local = Math.max(0, t - OFFSET);
+ const target = Math.min((Math.floor(local * FPS + 1e-6) + 0.5) / FPS, Math.max(0, video.duration - 1e-3));
+ await seekVideo(target);
+ },
+ };
+})();
+`;
+ return { 'index.html': html, 'app.js': js };
+}
+
+/**
+ * Re-encode the finished render at `path` through the project's film look, in
+ * place. Resolves `true` when the pass ran, `false` when the look is neutral
+ * (the file is untouched). `offsetSec` is the song time of the render's first
+ * frame (an excerpt's window start) so the grain lands on song frames.
+ * Rejects on failure or when `signal` aborts, leaving `path` as it was.
+ */
+export async function applyFilmLookFinish({ project, path, jobId, signal, onProgress, offsetSec = 0, label = 'Music-video film look' }) {
+ const look = normalizeFilmLook(project?.filmLook);
+ if (!look || isFilmLookNeutral(look)) return false;
+ if (typeof jobId !== 'string' || !/^[A-Za-z0-9_-]+$/.test(jobId)) throw new Error('Invalid film look job id');
+ const { findFfmpeg, runFfmpegProcess, probeVideoGeometry } = await import('../../lib/ffmpeg.js');
+ const { openComposition } = await import('../htmlComposition/browser.js');
+ const { encodeComposition, encodeCompositionSegments } = await import('../htmlComposition/encode.js');
+ const ffmpeg = await findFfmpeg();
+ if (!ffmpeg) throw new ServerError('ffmpeg not found on PATH', { status: 500, code: 'FFMPEG_MISSING' });
+ const geometry = await probeVideoGeometry(path);
+ if (!geometry) throw new ServerError('The rendered video could not be measured for its film look pass', { status: 500, code: 'FILM_LOOK_FINISH_PROBE' });
+ const { width, height, fps } = geometry;
+ const frames = Math.max(1, geometry.numFrames || Math.round(geometry.durationSec * fps));
+ const durationSec = frames / fps;
+ const directory = `${FILM_LOOK_FINISH_SCRATCH_DIR}/${jobId}`;
+ const scratch = join(PATHS.data, directory);
+ const silent = `${path}.look.silent.mp4`;
+ const finished = `${path}.look.mp4`;
+ let page;
+ try {
+ await rm(scratch, { recursive: true, force: true });
+ await mkdir(join(scratch, 'media'), { recursive: true });
+ // The finished render is large: a hard link stages it without a copy on
+ // the same volume (the browser refuses symlinks); a copy stands in elsewhere.
+ const source = join(scratch, 'media', 'source.mp4');
+ await link(path, source).catch(() => copyFile(path, source));
+ for (const [name, body] of Object.entries(filmLookFinishPage({ width, height, fps, durationSec, offsetSec }))) {
+ await writeFile(join(scratch, name), body);
+ }
+ signal?.throwIfAborted();
+ const openPage = (pageSignal) => openComposition(directory, { signal: pageSignal, streamMedia: true, ownedBrowser: true, initScripts: [filmLookRuntimeSource(look)] });
+ page = await openPage(signal);
+ const h264 = await page.evaluate(`document.createElement('video').canPlayType('video/mp4; codecs="avc1.640028"')`);
+ if (!h264) {
+ throw new ServerError('The managed browser cannot decode H.264 video (a Chromium build without proprietary codecs) — point Settings › Browser at Google Chrome', {
+ status: 422, code: 'COMPOSITION_BROWSER_CODEC',
+ });
+ }
+ const encoded = await encodeCompositionSegments(page, { width, height, fps, durationSec }, silent, {
+ openPage, encode: encodeComposition, signal, offsetSec,
+ onProgress: (fraction) => onProgress?.(fraction * 0.95),
+ onRetry: ({ frame, attempt, segment, error }) => console.warn(`⚠️ ${label} [${jobId.slice(0, 8)}] ${segment == null ? '' : `worker ${segment + 1} `}restarting its browser at song frame ${frame} (retry ${attempt}): ${error.message}`),
+ });
+ // A replaced first page was already closed after its failure.
+ if (!encoded?.pageReplaced) {
+ page.check();
+ await page.close({ verify: true });
+ }
+ page = null;
+ signal?.throwIfAborted();
+ // The pass changes pixels only: the render's audio (master, sound bed, an
+ // excerpt's trim) is copied back untouched.
+ const mux = await runFfmpegProcess({
+ bin: ffmpeg, signal,
+ args: ['-hide_banner', '-loglevel', 'error', '-i', silent, '-i', path, '-map', '0:v:0', '-map', '1:a?', '-c', 'copy', '-movflags', '+faststart', '-y', finished],
+ });
+ if (!mux.ok) {
+ signal?.throwIfAborted();
+ throw new ServerError(`Film look mux failed: ${mux.reason}`, { status: 500, code: 'FILM_LOOK_FINISH_MUX' });
+ }
+ await rename(finished, path);
+ onProgress?.(1);
+ console.log(`🎞️ ${label} [${jobId.slice(0, 8)}]: ${look.preset} over ${frames} frames at ${width}×${height}`);
+ return true;
+ } finally {
+ if (page) await page.close().catch(() => {});
+ await rm(scratch, { recursive: true, force: true }).catch(() => {});
+ await rm(silent, { force: true }).catch(() => {});
+ await rm(finished, { force: true }).catch(() => {});
+ }
+}
diff --git a/server/services/musicVideo/filmLookFinish.test.js b/server/services/musicVideo/filmLookFinish.test.js
new file mode 100644
index 0000000000..5a10ce8600
--- /dev/null
+++ b/server/services/musicVideo/filmLookFinish.test.js
@@ -0,0 +1,123 @@
+/**
+ * The film look finishing pass over a footage render, with the composition
+ * browser, the shared encoder and ffmpeg stubbed at their boundaries: what the
+ * pass stages and asks of them, that the render is replaced in place only
+ * once the pass succeeds, and that nothing is left behind either way.
+ */
+
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';
+
+vi.mock('../../lib/paths.js', async (importOriginal) => makePathsProxy(await importOriginal(), {
+ dataRoot: () => lazyTempDataRoot('portos-mv-film-look-finish-'),
+}));
+const { seen } = vi.hoisted(() => ({ seen: { opened: [], contract: null, options: null, progress: [], ffmpeg: [], encodeFail: null } }));
+vi.mock('../../lib/ffmpeg.js', () => ({
+ findFfmpeg: async () => 'ffmpeg',
+ // 48 frames at 24 fps: the container reports a hair more than the frames hold.
+ probeVideoGeometry: async () => ({ width: 1280, height: 720, fps: 24, numFrames: 48, durationSec: 2.04 }),
+ runFfmpegProcess: async ({ args }) => {
+ const { writeFile: write } = await import('node:fs/promises');
+ seen.ffmpeg.push(args);
+ await write(args.at(-1), 'finished-video');
+ return { ok: true };
+ },
+}));
+// The browser mock records the staged page the pass opens and how it opens it.
+vi.mock('../htmlComposition/browser.js', () => ({
+ openComposition: async (directory, options) => {
+ const { readFile: read } = await import('node:fs/promises');
+ const { join: joinPath } = await import('node:path');
+ const { PATHS: paths } = await import('../../lib/paths.js');
+ const dir = joinPath(paths.data, directory);
+ seen.opened.push({
+ directory, options,
+ index: await read(joinPath(dir, 'index.html'), 'utf8'),
+ app: await read(joinPath(dir, 'app.js'), 'utf8'),
+ source: await read(joinPath(dir, 'media', 'source.mp4'), 'utf8'),
+ });
+ return { evaluate: async () => 'probably', check() {}, async close() {}, async send() { return {}; } };
+ },
+}));
+vi.mock('../htmlComposition/encode.js', () => ({
+ encodeComposition: vi.fn(),
+ encodeCompositionSegments: async (_page, contract, outputPath, options) => {
+ const { writeFile: write } = await import('node:fs/promises');
+ seen.contract = contract;
+ seen.options = options;
+ if (seen.encodeFail) throw seen.encodeFail;
+ options.onProgress?.(0.5);
+ await write(outputPath, 'silent-video');
+ return {};
+ },
+}));
+
+const { PATHS } = await import('../../lib/paths.js');
+const { FILM_LOOK_FINISH_SCRATCH_DIR, applyFilmLookFinish, filmLookFinishNeeded } = await import('./filmLookFinish.js');
+
+const look = { preset: 'super8', grain: 0.5, halation: 0.4 };
+let path;
+beforeEach(async () => {
+ seen.opened.length = 0;
+ seen.ffmpeg.length = 0;
+ seen.progress.length = 0;
+ seen.contract = null;
+ seen.options = null;
+ seen.encodeFail = null;
+ await mkdir(PATHS.videos, { recursive: true });
+ path = join(PATHS.videos, 'music-video-example.mp4');
+ await writeFile(path, 'composed-render');
+});
+afterAll(() => cleanupTempDataRoots());
+
+describe('film look finishing pass', () => {
+ it('leaves a render without a look alone, without a browser', async () => {
+ expect(filmLookFinishNeeded({ filmLook: null })).toBe(false);
+ expect(filmLookFinishNeeded({ filmLook: { preset: 'none' } })).toBe(false);
+ expect(filmLookFinishNeeded({ filmLook: look })).toBe(true);
+ expect(await applyFilmLookFinish({ project: { filmLook: null }, path, jobId: 'job-plain' })).toBe(false);
+ expect(seen.opened).toEqual([]);
+ expect(await readFile(path, 'utf8')).toBe('composed-render');
+ });
+
+ it('plays the finished cut through the look on song time, copies its audio back and replaces it in place', async () => {
+ const result = await applyFilmLookFinish({ project: { filmLook: look }, path, jobId: 'job-look', offsetSec: 3, onProgress: (f) => seen.progress.push(f) });
+ expect(result).toBe(true);
+ // The staged page: the render itself (linked, not re-encoded), full frame, seeking on song time.
+ expect(seen.opened).toHaveLength(1);
+ const [opened] = seen.opened;
+ expect(opened.directory).toBe(`${FILM_LOOK_FINISH_SCRATCH_DIR}/job-look`);
+ expect(opened.options).toMatchObject({ streamMedia: true, ownedBrowser: true });
+ expect(opened.options.initScripts).toHaveLength(1);
+ expect(opened.options.initScripts[0]).toContain('__portosFilmLook');
+ expect(opened.options.initScripts[0]).toContain('"grain":0.5');
+ expect(opened.source).toBe('composed-render');
+ expect(opened.index).toContain('<video id="source" src="media/source.mp4"');
+ expect(opened.app).toContain('OFFSET = 3');
+ expect(opened.app).toContain('FPS = 24');
+ expect(opened.app).toContain('globalThis.portosComposition =');
+ // The contract is the render's own geometry on whole frames; the window starts at the excerpt's song time.
+ expect(seen.contract).toEqual({ width: 1280, height: 720, fps: 24, durationSec: 2 });
+ expect(seen.options).toMatchObject({ offsetSec: 3 });
+ expect(seen.progress).toEqual([0.475, 1]);
+ // Pixels from the pass, audio copied from the render, then swapped in.
+ expect(seen.ffmpeg).toHaveLength(1);
+ const mux = seen.ffmpeg[0];
+ expect(mux.slice(mux.indexOf('-i'))).toEqual(['-i', `${path}.look.silent.mp4`, '-i', path, '-map', '0:v:0', '-map', '1:a?', '-c', 'copy', '-movflags', '+faststart', '-y', `${path}.look.mp4`]);
+ expect(await readFile(path, 'utf8')).toBe('finished-video');
+ expect(existsSync(join(PATHS.data, FILM_LOOK_FINISH_SCRATCH_DIR, 'job-look'))).toBe(false);
+ expect(existsSync(`${path}.look.silent.mp4`)).toBe(false);
+ expect(existsSync(`${path}.look.mp4`)).toBe(false);
+ });
+
+ it('keeps the render as it was when the capture fails, and cleans up', async () => {
+ seen.encodeFail = new Error('browser died');
+ await expect(applyFilmLookFinish({ project: { filmLook: look }, path, jobId: 'job-fail' })).rejects.toThrow('browser died');
+ expect(await readFile(path, 'utf8')).toBe('composed-render');
+ expect(seen.ffmpeg).toEqual([]);
+ expect(existsSync(join(PATHS.data, FILM_LOOK_FINISH_SCRATCH_DIR, 'job-fail'))).toBe(false);
+ });
+});
diff --git a/server/services/musicVideo/render.js b/server/services/musicVideo/render.js
index 270af35877..25b3ca2cd2 100644
--- a/server/services/musicVideo/render.js
+++ b/server/services/musicVideo/render.js
@@ -44,8 +44,9 @@ import { applyProjectPatch } from './projectsLogic.js';
import { isSelfDrawnLayer, sceneHasAuthoredSpan, sceneVisualLayer } from '../../lib/musicVideoLayers.js';
import { projectTypographyPlan } from './composition.js';
import { encodeCodeComposition, prepareCodeRender, writeCodeProofSheet } from './codeRender.js';
-import { encodeDocumentComposition, prepareDocumentRender, sweepDocumentScratch } from './documentRender.js';
+import { documentRenderInitScripts, encodeDocumentComposition, prepareDocumentRender, sweepDocumentScratch } from './documentRender.js';
import { renderTypographyOverlays, removeCompositionScratch, sweepCompositionScratch } from './compositionRender.js';
+import { applyFilmLookFinish, filmLookFinishNeeded } from './filmLookFinish.js';
import { selectedPerformanceInstruction } from '../../lib/musicVideoShotTiming.js';
import { captureMusicVideoEvidence, musicVideoTakeChanges } from '../../lib/musicVideoDependencies.js';
import { assertCurrentPerformanceTakes, withDraftPerformanceFallbacks } from './performanceShot.js';
@@ -667,9 +668,10 @@ const SEEKED_RENDERERS = Object.freeze({
label: 'code',
modelId: 'music-video-code',
prepare: async (project) => prepareCodeRender(project),
- encode: async ({ plan, projectId, jobId, audioPath, outputPath, signal, onProgress }) => {
+ encode: async ({ plan, project, projectId, jobId, audioPath, outputPath, signal, onProgress }) => {
await encodeCodeComposition({
...plan, audioPath, outputPath, directory: `compositions/music-video/${projectId}/${jobId}`, signal, onProgress,
+ initScripts: documentRenderInitScripts(project),
});
return { width: plan.width, height: plan.height, fps: plan.fps, durationSec: plan.durationSec, boundaryTimes: plan.sectionTimes };
},
@@ -878,10 +880,39 @@ async function renderAdmittedMusicVideo(projectId, options, permit) {
console.warn(`⚠️ Music-video render [${jobId.slice(0, 8)}] could not remove its overlay scratch: ${err.message}`);
}) : null);
+ // Terminal failure or cancel, one path for the overlay capture, the encode
+ // and the film look pass. A cancel is a user action (stdout); a failure is
+ // an error (#7945).
+ const settleFailure = async (canceled, reason) => {
+ job.status = canceled ? 'canceled' : 'error';
+ job.lastError = reason;
+ const log = canceled ? console.log : console.error;
+ log(`${canceled ? '🛑' : '❌'} Music-video render ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(0, 8)}]: ${reason}`);
+ await unlink(outputPath).catch(() => {});
+ broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
+ projectRenders.delete(projectId);
+ // A cancel restores the pre-render status (so a cancelled re-render of a
+ // 'complete' project stays 'complete'); a real failure marks it 'failed'.
+ const targetStatus = canceled ? priorStatus : 'failed';
+ await updateProject(projectId, settledRender(targetStatus)).catch((updateErr) => {
+ maintenance.markCurrentUnsettled();
+ console.error(`❌ Music-video render [${jobId.slice(0, 8)}] project ${projectId.slice(0, 8)} status→${targetStatus} write failed: ${updateErr.message}`);
+ });
+ emitRenderSettled(projectId, job);
+ await releaseScratch();
+ closeJobAfterDelay(jobs, jobId);
+ permit.finish();
+ };
+
+ // A footage render with a film look re-encodes its finished cut through the
+ // look after ffmpeg (filmLookFinish.js); the pass takes the second half of
+ // whatever the encode's share of the bar is.
+ const finishing = filmLookFinishNeeded(project);
// A composed render first captures its overlay (progress 0–50%), then
// encodes (50–100%); a plain render encodes across the whole bar.
const startEncode = (encodeArgs, progressBase = 0) => {
- const encodeProgress = (fraction) => progressBase + (1 - progressBase) * fraction;
+ const encodeTop = finishing ? progressBase + (1 - progressBase) / 2 : 1;
+ const encodeProgress = (fraction) => progressBase + (encodeTop - progressBase) * fraction;
const proc = spawn(ffmpeg, encodeArgs, safeChildProcessOptions({ stdio: ['ignore', 'ignore', 'pipe'] }));
job.process = proc;
@@ -902,7 +933,7 @@ async function renderAdmittedMusicVideo(projectId, options, permit) {
broadcastSse(job, { type: 'progress', progress: encodeProgress(Math.min(1, (us / 1_000_000) / totalDuration)) });
}
} else if (key === 'progress' && val === 'end') {
- broadcastSse(job, { type: 'progress', progress: 1 });
+ broadcastSse(job, { type: 'progress', progress: encodeTop });
}
}
});
@@ -942,28 +973,23 @@ async function renderAdmittedMusicVideo(projectId, options, permit) {
job.process = null;
if (code !== 0) {
const canceled = isMusicVideoRenderCanceled(job, signal);
- job.status = canceled ? 'canceled' : 'error';
- const reason = canceled ? 'Render cancelled' : signal ? `Killed by signal ${signal}` : `ffmpeg exit ${code}`;
- job.lastError = reason;
- // A cancel is a user action (stdout); a non-zero exit is a failure (#7945).
- const logClose = canceled ? console.log : console.error;
- logClose(`${canceled ? '🛑' : '❌'} Music-video render ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(0, 8)}]: ${reason}`);
- await unlink(outputPath).catch(() => {});
- broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
- projectRenders.delete(projectId);
- // A cancel restores the pre-render status (so a cancelled re-render of a
- // 'complete' project stays 'complete'); a real failure marks it 'failed'.
- const targetStatus = canceled ? priorStatus : 'failed';
- await updateProject(projectId, settledRender(targetStatus)).catch((updateErr) => {
- maintenance.markCurrentUnsettled();
- console.error(`❌ Music-video render [${jobId.slice(0, 8)}] project ${projectId.slice(0, 8)} status→${targetStatus} write failed: ${updateErr.message}`);
- });
- emitRenderSettled(projectId, job);
- await releaseScratch();
- closeJobAfterDelay(jobs, jobId);
- permit.finish();
+ await settleFailure(canceled, canceled ? 'Render cancelled' : signal ? `Killed by signal ${signal}` : `ffmpeg exit ${code}`);
return;
}
+ // The cut is encoded; a film look re-encodes it in place through the
+ // look before it is published. A cancel here aborts the pass.
+ if (finishing) {
+ job.overlayAbort = new AbortController();
+ const { signal: finishSignal } = job.overlayAbort;
+ try {
+ await applyFilmLookFinish({ project, path: outputPath, jobId, signal: finishSignal,
+ onProgress: (fraction) => broadcastSse(job, { type: 'progress', progress: encodeTop + (1 - encodeTop) * fraction }) });
+ } catch (err) {
+ await settleFailure(finishSignal.aborted, finishSignal.aborted ? 'Render cancelled' : `Film look pass failed: ${err.message}`);
+ return;
+ }
+ job.overlayAbort = null;
+ }
// Success finalization runs in an event callback (no request to bubble
// to) — a throw in thumbnailing/history I/O would otherwise leave the
// project stuck 'rendering' and projectRenders un-cleared (every later
@@ -1049,22 +1075,7 @@ async function renderAdmittedMusicVideo(projectId, options, permit) {
startEncode(layered.args, 0.5);
}).catch(async (err) => {
const canceled = signal.aborted;
- job.status = canceled ? 'canceled' : 'error';
- const reason = canceled ? 'Render cancelled' : `Typography overlay failed: ${err.message}`;
- job.lastError = reason;
- const log = canceled ? console.log : console.error;
- log(`${canceled ? '🛑' : '❌'} Music-video render ${canceled ? 'cancelled' : 'failed'} [${jobId.slice(0, 8)}]: ${reason}`);
- broadcastSse(job, { type: canceled ? 'canceled' : 'error', error: reason });
- projectRenders.delete(projectId);
- const targetStatus = canceled ? priorStatus : 'failed';
- await updateProject(projectId, settledRender(targetStatus)).catch((updateErr) => {
- maintenance.markCurrentUnsettled();
- console.error(`❌ Music-video render [${jobId.slice(0, 8)}] project ${projectId.slice(0, 8)} status→${targetStatus} write failed: ${updateErr.message}`);
- });
- emitRenderSettled(projectId, job);
- await releaseScratch();
- closeJobAfterDelay(jobs, jobId);
- permit.finish();
+ await settleFailure(canceled, canceled ? 'Render cancelled' : `Typography overlay failed: ${err.message}`);
});
return { jobId };
diff --git a/server/services/musicVideo/render.terminal.test.js b/server/services/musicVideo/render.terminal.test.js
index c97207f402..a43fe5868d 100644
--- a/server/services/musicVideo/render.terminal.test.js
+++ b/server/services/musicVideo/render.terminal.test.js
@@ -600,3 +600,86 @@ describe('layered sections (#8985)', () => {
expect(h.procs).toHaveLength(0);
});
});
+
+// The film look finishing pass (filmLookFinish.js) runs between a zero-exit
+// encode and publication: the job stays cancellable through it and its failure
+// settles the render like an encode failure.
+const look = vi.hoisted(() => ({ calls: [], resolve: null, reject: null }));
+vi.mock('./filmLookFinish.js', () => ({
+ filmLookFinishNeeded: (project) => !!project?.filmLook,
+ applyFilmLookFinish: (options) => new Promise((resolve, reject) => {
+ look.calls.push(options);
+ look.resolve = resolve;
+ look.reject = reject;
+ options.signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+ }),
+}));
+
+describe('film look finishing pass on a footage render', () => {
+ const primeLook = (pid, status = 'ready') => {
+ prime(pid);
+ getProject.mockResolvedValue({
+ id: pid, name: 'P', trackId: 't1', status, filmLook: { preset: 'super8', grain: 0.5 },
+ scenes: [{ sceneId: 's1', order: 0, videoHistoryId: 'h1' }],
+ });
+ };
+ const encodeDone = async (proc) => {
+ proc.emit('spawn');
+ proc.stderr.emit('data', 'progress=end\n');
+ proc.emit('close', 0, null);
+ await tick();
+ };
+ beforeEach(() => { look.calls.length = 0; });
+
+ it('runs the pass over the encoded file after a zero exit, holding publication and the progress bar for it', async () => {
+ const pid = 'look-1';
+ primeLook(pid);
+ const { jobId } = await renderMusicVideo(pid);
+ await encodeDone(lastProc());
+ // The encode's end is the middle of the bar; the pass fills the rest.
+ expect(broadcastSse).toHaveBeenCalledWith(expect.anything(), { type: 'progress', progress: 0.5 });
+ expect(look.calls).toHaveLength(1);
+ expect(look.calls[0]).toMatchObject({ jobId, path: expect.stringMatching(/^\/data\/videos\/music-video-/), project: expect.objectContaining({ id: pid }) });
+ expect(getRenderJobStatus(jobId).status).toBe('running');
+ expect(updateProject).not.toHaveBeenCalledWith(pid, expect.objectContaining({ status: 'complete' }));
+ look.calls[0].onProgress(0.5);
+ expect(broadcastSse).toHaveBeenCalledWith(expect.anything(), { type: 'progress', progress: 0.75 });
+ look.resolve(true);
+ await tick();
+ await tick();
+ expect(getRenderJobStatus(jobId).status).toBe('complete');
+ expect(updateProject).toHaveBeenCalledWith(pid, expect.objectContaining({ status: 'complete', renderHistoryId: jobId }));
+ expect(broadcastSse).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ type: 'complete' }));
+ });
+
+ it('a cancel during the pass aborts it, removes the file and restores the prior status', async () => {
+ const pid = 'look-2';
+ primeLook(pid, 'complete');
+ const { jobId } = await renderMusicVideo(pid);
+ await encodeDone(lastProc());
+ expect(look.calls).toHaveLength(1);
+ expect(cancelRender(jobId)).toBe(true);
+ await tick();
+ await tick();
+ expect(look.calls[0].signal.aborted).toBe(true);
+ expect(getRenderJobStatus(jobId).status).toBe('canceled');
+ expect(unlink).toHaveBeenCalledWith(look.calls[0].path);
+ expect(updateProject).toHaveBeenCalledWith(pid, settled('complete'));
+ expect(broadcastSse).toHaveBeenCalledWith(expect.anything(), { type: 'canceled', error: 'Render cancelled' });
+ // Slot released: a new render starts.
+ expect((await renderMusicVideo(pid)).jobId).not.toBe(jobId);
+ });
+
+ it('a failed pass settles the render as failed, naming the pass', async () => {
+ const pid = 'look-3';
+ primeLook(pid);
+ const { jobId } = await renderMusicVideo(pid);
+ await encodeDone(lastProc());
+ look.reject(new Error('no browser'));
+ await tick();
+ await tick();
+ expect(getRenderJobStatus(jobId)).toEqual({ status: 'error', error: 'Film look pass failed: no browser' });
+ expect(unlink).toHaveBeenCalledWith(look.calls[0].path);
+ expect(updateProject).toHaveBeenCalledWith(pid, settled('failed'));
+ });
+});