The open source AI video agent: turns any coding agent into a video agent, with an editor to change anything it makes.
Render: decimal frame rates, with 23.976, 29.97 and 59.94 exact (#107)
taavie-z94ea4c8237f9
diff --git a/.changeset/render-fractional-fps.md b/.changeset/render-fractional-fps.mdnew file mode 100644index 0000000..f04c8f5--- /dev/null+++ b/.changeset/render-fractional-fps.md@@ -0,0 +1,5 @@+---+"openfilm": patch+---++Allow decimal frame rates such as 23.976, 29.97 and 59.94 in `openfilm render --fps`, keeping the existing range of 1 to 240. The NTSC rates render at their exact rates (24000/1001, 30000/1001, 60000/1001), as footage shot at them is.diff --git a/packages/openfilm/bin/openfilm.mjs b/packages/openfilm/bin/openfilm.mjsindex cc8b623..41b39c4 100755--- a/packages/openfilm/bin/openfilm.mjs+++ b/packages/openfilm/bin/openfilm.mjs@@ -78,7 +78,7 @@ openfilm skill remove <name>A project Studio has not shown yet is opened in Studio first.--out <file> another path; .webm or .mov with --alpha- --fps <n> frame rate (30)+ --fps <n> frame rate, including decimals such as 29.97 (30)--4k 3840 px wide --scale <n> any device pixel ratio--blur motion blur (8 samples) --samples <n> --shutter <0..1>--alpha transparent background --workers <n> parallel browsers`,@@ -144,7 +144,7 @@ if (o.help || !cmd) { console.log(HELP); process.exit(0); }const num = (v) => (v == null ? undefined : Number(v));const opts = { ...o, count: num(o.count), scale: num(o.scale), samples: num(o.samples), shutter: num(o.shutter), fps: num(o.fps), workers: num(o.workers) };/* a number option out of its range is a wrong command (2), said before anything starts */-const RANGES = { count: [1, 200, true], fps: [1, 240, true], scale: [0.1, 8, false], samples: [1, 64, true], shutter: [0, 1, false], workers: [1, 64, true] };+const RANGES = { count: [1, 200, true], fps: [1, 240, false], scale: [0.1, 8, false], samples: [1, 64, true], shutter: [0, 1, false], workers: [1, 64, true] };for (const [name, [lo, hi, whole]] of Object.entries(RANGES)) {const v = opts[name];if (v === undefined || (Number.isFinite(v) && v >= lo && v <= hi && (!whole || Number.isInteger(v)))) continue;diff --git a/packages/openfilm/src/rate.mjs b/packages/openfilm/src/rate.mjsnew file mode 100644index 0000000..a4bb028--- /dev/null+++ b/packages/openfilm/src/rate.mjs@@ -0,0 +1,16 @@+// @ts-check++/**+ * A frame rate as it really is. The NTSC rates 23.976, 29.97 and 59.94 (and 47.952, 119.88) are a whole rate slowed+ * by 1000/1001: exactly 24000/1001, 30000/1001 and 60000/1001, so a render's frames, its encoder's rate and the+ * file's rate tag match footage shot at them. Another rate is kept as it is, as num/1.+ * @param {number} fps @returns {{ fps: number, num: number, den: number }}+ */+export function exactRate(fps) {+ const whole = Math.round(fps);+ const ntsc = whole > 0 && Math.abs(fps - whole) > 0.001 && Math.abs(fps - (whole * 1000) / 1001) < 0.01;+ return ntsc ? { fps: (whole * 1000) / 1001, num: whole * 1000, den: 1001 } : { fps, num: fps, den: 1 };+}++/** The rate as ffmpeg takes it (`-r`, `-framerate`, a filter's expression), `times` over. @param {{ num: number, den: number }} rate @param {number} [times] */+export const ffmpegRate = ({ num, den }, times = 1) => (den === 1 ? String(num * times) : `${num * times}/${den}`);diff --git a/packages/openfilm/src/rate.test.mjs b/packages/openfilm/src/rate.test.mjsnew file mode 100644index 0000000..a9530a3--- /dev/null+++ b/packages/openfilm/src/rate.test.mjs@@ -0,0 +1,13 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { exactRate, ffmpegRate } from './rate.mjs';++test('the NTSC rates are their exact rates; another rate is kept as it is', () => {+ for (const [fps, num] of [[23.976, 24000], [23.98, 24000], [29.97, 30000], [30000 / 1001, 30000], [47.952, 48000], [59.94, 60000], [119.88, 120000]]) {+ assert.deepEqual(exactRate(fps), { fps: num / 1001, num, den: 1001 }, `${fps}`);+ assert.equal(ffmpegRate(exactRate(fps)), `${num}/1001`);+ }+ for (const fps of [1, 12.5, 24, 25, 30, 60, 240]) assert.deepEqual(exactRate(fps), { fps, num: fps, den: 1 }, `${fps}`);+ assert.equal(ffmpegRate(exactRate(29.97), 8), '240000/1001');+ assert.equal(ffmpegRate(exactRate(12.5), 2), '25');+});diff --git a/packages/openfilm/src/render.mjs b/packages/openfilm/src/render.mjsindex d93483e..5b03eb6 100644--- a/packages/openfilm/src/render.mjs+++ b/packages/openfilm/src/render.mjs@@ -7,6 +7,7 @@ import { basename, dirname, extname, join, resolve } from 'node:path';import { clipKind, FILM_FILE } from './film-doc.mjs';import { broken, encoders, hardwareEncoder, hardwareOptions, proresOptions } from './encoders.mjs';import { FilmPage, launch } from './host.mjs';+import { exactRate, ffmpegRate } from './rate.mjs';import { browserCopies, filmVideos } from './seekable.mjs';import { ffmpeg, filmSound, fmt, kill, mix, open, outDir, parseTarget, shown, UsageError, write } from './shared.mjs';@@ -80,7 +81,9 @@ export async function render(args, opts = {}) {const meta = probe.film.meta;await probe.film.close();- const fps = Number(opts.fps ?? 30);+ /* 29.97 is 30000/1001, as the footage shot at it is (rate.mjs) */+ const rate = exactRate(Number(opts.fps ?? 30));+ const fps = rate.fps;/* a page without a duration has no end: it is rendered by a range */const end = meta.duration ?? Infinity;if (!range && meta.duration == null) { await probe.close(); throw new UsageError('this page has no duration, so it has no end: give a range to render, e.g. openfilm render 0-6'); }@@ -162,7 +165,7 @@ export async function render(args, opts = {}) {const stop = new AbortController();const quit = () => stop.abort();opts.signal?.addEventListener('abort', quit, { once: true });- const runs = parts.map((p) => encode(p, { fps, samples, shutter, duration: end, format: f, onFrame: progress, still: alpha ? 'png' : 'jpeg', signal: stop.signal }));+ const runs = parts.map((p) => encode(p, { fps, rate, samples, shutter, duration: end, format: f, onFrame: progress, still: alpha ? 'png' : 'jpeg', signal: stop.signal }));try {await unlessCancelled(Promise.all(runs));} catch (e) {@@ -215,7 +218,7 @@ export async function render(args, opts = {}) {encoder,lines: [`→ ${shown(out)}`,- ` ${total} frames · ${fmt(to - from)} at ${fps} fps · ${Math.round(meta.width * scale)}×${Math.round(meta.height * scale)}${samples > 1 ? ` · ${samples} samples/frame` : ''}${alpha ? ' · alpha' : ''} · ${workers} worker${workers > 1 ? 's' : ''} · ${encoder} · ${seconds.toFixed(1)} s`,+ ` ${total} frames · ${fmt(to - from)} at ${Number(fps.toFixed(3))} fps · ${Math.round(meta.width * scale)}×${Math.round(meta.height * scale)}${samples > 1 ? ` · ${samples} samples/frame` : ''}${alpha ? ' · alpha' : ''} · ${workers} worker${workers > 1 ? 's' : ''} · ${encoder} · ${seconds.toFixed(1)} s`,...problems.map((p) => `✗ ${p.kind === 'request' ? 'request' : 'page'}: ${p.message}`),],};@@ -264,10 +267,10 @@ export function defaultWorkers({ cores, available } = machine(), frames = Infini}/** Frames [a, b) of one page into one file; sub-frames are averaged by ffmpeg (tmix) and every n-th kept. */-async function encode({ film, a, b, file }, { fps, samples, shutter, duration, format, onFrame, still, signal }) {- const blur = samples > 1 ? `tmix=frames=${samples},select='eq(mod(n\\,${samples})\\,${samples - 1})',setpts=N/(${fps}*TB),` : '';- const enc = ffmpeg(['-f', 'image2pipe', '-framerate', String(fps * samples), '-c:v', still === 'png' ? 'png' : 'mjpeg', '-i', '-',- '-vf', blur + format.pix, '-r', String(fps), ...format.video, file], { input: true });+async function encode({ film, a, b, file }, { fps, rate, samples, shutter, duration, format, onFrame, still, signal }) {+ const blur = samples > 1 ? `tmix=frames=${samples},select='eq(mod(n\\,${samples})\\,${samples - 1})',setpts=N/((${ffmpegRate(rate)})*TB),` : '';+ const enc = ffmpeg(['-f', 'image2pipe', '-framerate', ffmpegRate(rate, samples), '-c:v', still === 'png' ? 'png' : 'mjpeg', '-i', '-',+ '-vf', blur + format.pix, '-r', ffmpegRate(rate), ...format.video, file], { input: true });/* a cancelled render stops its encoder at once: the frames ffmpeg still holds are thrown away, not encoded (a 4Kencode takes seconds to drain); the parts folder goes with it (see render's finally) */const stop = () => kill(enc.proc);diff --git a/packages/openfilm/src/render.test.mjs b/packages/openfilm/src/render.test.mjsindex 600e0c7..da14ead 100644--- a/packages/openfilm/src/render.test.mjs+++ b/packages/openfilm/src/render.test.mjs@@ -1,6 +1,6 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { execFileSync, spawn } from 'node:child_process';+import { execFileSync, spawn, spawnSync } from 'node:child_process';import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';import { getPriority, tmpdir, totalmem } from 'node:os';import { join } from 'node:path';@@ -11,6 +11,46 @@ import { defaultWorkers, machine, outOfMemory, render } from './render.mjs';const hasFfmpeg = (() => { try { execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' }); return true; } catch { return false; } })();+test('the render command accepts decimal frame rates and still rejects invalid rates', () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-render-fps-options-'));+ try {+ const cli = fileURLToPath(new URL('../bin/openfilm.mjs', import.meta.url));+ for (const fps of ['1', '23.976', '29.97', '59.94', String(30000 / 1001), '240']) {+ const result = spawnSync(process.execPath, [cli, 'render', `--fps=${fps}`], { cwd: dir, encoding: 'utf8' });+ assert.equal(result.status, 2, result.stderr);+ assert.match(result.stderr, /is not in a project/, `--fps ${fps} passes option validation`);+ }+ for (const fps of ['0', '-1', '0.99', '240.1', 'NaN', 'Infinity']) {+ const result = spawnSync(process.execPath, [cli, 'render', `--fps=${fps}`], { cwd: dir, encoding: 'utf8' });+ assert.equal(result.status, 2, result.stderr);+ assert.match(result.stderr, /--fps is a number from 1 to 240/, `--fps ${fps} is rejected`);+ }+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test('the render command renders 29.97 as exactly 30000/1001, and keeps another decimal rate, through encoding, blur and parallel parts', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-render-fractional-'));+ try {+ writeFileSync(join(dir, 'p.html'), '<!doctype html><body style="margin:0"><script>window.film = { duration: 0.5, width: 320, height: 180, frame(t) { document.body.style.background = `hsl(${t * 360}, 80%, 50%)`; } };</script>');+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'p', src: 'p.html', at: 0, time: [0, 0.5] }] }] }));+ mkdirSync(join(dir, '.film'));+ writeFileSync(join(dir, '.film', 'opened'), '');+ const cli = fileURLToPath(new URL('../bin/openfilm.mjs', import.meta.url));+ for (const [fps, rate, workers, samples] of [[29.97, '30000/1001', 1, 1], [30000 / 1001, '30000/1001', 2, 2], [12.5, '25/2', 1, 1]]) {+ const out = join(dir, `${fps}.mp4`);+ execFileSync(process.execPath, [cli, 'render', '--fps', String(fps), '--workers', String(workers), '--samples', String(samples), '--out', out], { cwd: dir, timeout: 60_000, stdio: 'pipe' });+ const { streams: [video] } = JSON.parse(execFileSync('ffprobe', ['-v', 'error', '-count_frames', '-select_streams', 'v:0', '-show_entries', 'stream=r_frame_rate,avg_frame_rate,nb_read_frames', '-of', 'json', out], { encoding: 'utf8' }));+ assert.equal(video.r_frame_rate, rate);+ assert.equal(video.avg_frame_rate, rate);+ assert.equal(Number(video.nb_read_frames), Math.round(0.5 * fps));+ }+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});+test('a render with no format of its own encodes on the graphics chip when it can: H.264 for an MP4, ProRes for a MOV', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {const dir = mkdtempSync(join(tmpdir(), 'of-render-chip-'));try {diff --git a/packages/openfilm/studio/server/nle.mjs b/packages/openfilm/studio/server/nle.mjsindex 52ef6b0..91589e1 100644--- a/packages/openfilm/studio/server/nle.mjs+++ b/packages/openfilm/studio/server/nle.mjs@@ -24,6 +24,7 @@import { spawn } from 'node:child_process';import { pathToFileURL } from 'node:url';import { clipKind, pictureRect, soundRole } from '../../src/film-doc.mjs';+import { exactRate } from '../../src/rate.mjs';/*** @typedef {import('../../src/film-doc.mjs').FilmBox} FilmBox@@ -73,7 +74,7 @@ export const nleFps = (fps) => NLE_FPS.reduce((best, f) => (Math.abs(f - fps) </** 29.97 / 59.94 / 23.976 → ntsc (a whole timebase, the true rate ×1000/1001). @param {number} fps @returns {NleRate} */export function nleRate(fps) {const base = Math.max(1, Math.round(fps));- const ntsc = Math.abs(fps - base) > 0.001 && Math.abs(fps - (base * 1000) / 1001) < 0.01;+ const ntsc = exactRate(fps).den === 1001;return ntsc ? { timebase: base, ntsc: true, fps: (base * 1000) / 1001 } : { timebase: base, ntsc: false, fps: base };}