Skip to content

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.md
new file mode 100644
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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 4K
encode 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.mjs
index 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.mjs
index 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 };
}