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.

Exports: XML keeps each source's starting timecode (#193)

Mouse_Hong168fe66a486a
diff --git a/.changeset/nle-source-timecode.md b/.changeset/nle-source-timecode.md
new file mode 100644
index 0000000..5c22581
--- /dev/null
+++ b/.changeset/nle-source-timecode.md
@@ -0,0 +1,5 @@
+---
+"openfilm": patch
+---
+
+Preserve source timecode and its DF/NDF display format in Premiere Pro and DaVinci Resolve XML exports, including full video conversions. Sequence starts and source-relative trims stay unchanged; rendered clips, audio segments and stems keep their zero start.
diff --git a/packages/openfilm/studio/server/exports.mjs b/packages/openfilm/studio/server/exports.mjs
index 18603f1..520ff1a 100644
--- a/packages/openfilm/studio/server/exports.mjs
+++ b/packages/openfilm/studio/server/exports.mjs
@@ -1381,7 +1381,11 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpo
else if (make.kind === 'raster') {
browser ??= await launch();
await rasterize(browser, make.from, make.w, make.h, to);
- } else if (make.kind === 'transcode') await transcode(make, to, signal, file.video);
+ } else if (make.kind === 'transcode') {
+ await transcode(make, to, signal, file.video);
+ // Full video conversions can retain timecode; use the produced file's metadata, not the original's.
+ if (!app && !fcp && file.video && !make.segment) file.timecode = (await probeSource(to)).timecode;
+ }
update(job, { progress: Math.floor((0.9 + 0.08 * ((i + 1) / others.length)) * 100) / 100 });
}
} finally {
diff --git a/packages/openfilm/studio/server/exports.test.mjs b/packages/openfilm/studio/server/exports.test.mjs
index 82d42e5..f2c8c90 100644
--- a/packages/openfilm/studio/server/exports.test.mjs
+++ b/packages/openfilm/studio/server/exports.test.mjs
@@ -7,7 +7,7 @@ import { basename, dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { createExports, diskFull, exportCapabilities, exportsRoot, ExportError, frameBox, dimsForShortEdge, keepChanges, projectFiles, projectSizes, shareOf, writableFolder } from './exports.mjs';
import { encoders, hardwareEncoder } from '../../src/encoders.mjs';
-import { allocateLanes, containMotion, fadeKeyframes, frameSpan, nleRate, planNleTimeline, xmemlDocument } from './nle.mjs';
+import { allocateLanes, containMotion, fadeKeyframes, frameSpan, nleRate, planNleTimeline, probeSource, xmemlDocument } from './nle.mjs';
import { fcpxmlDocument } from './fcpxml.mjs';
import { pptxParts } from './slides.mjs';
import { filmSubtitleSrt, parseFilmSubtitleStyle } from './film-subtitle.mjs';
@@ -593,6 +593,31 @@ test('an editing project\'s copied files get names of their own when two differ
assert.deepEqual(timeline.files.map((f) => f.job.from), ['a', 'b', 'c'].map((d, i) => join(scratch, `assets/${d}/${[nfc, nfd, 'CAF\u00c9'][i]}.wav`)));
});
+test('Premiere XML timecode matches a full video conversion without moving source-relative cuts', ffmpeg, async () => {
+ const folder = join(scratch, 'Source timecode');
+ mkdirSync(folder);
+ const source = join(folder, 'Camera Original.mkv');
+ execFileSync('ffmpeg', ['-v', 'error', '-f', 'lavfi', '-i',
+ 'color=red:s=160x90:r=25:d=4[r];color=green:s=160x90:r=25:d=4[g];color=blue:s=160x90:r=25:d=4[b];[r][g][b]concat=n=3:v=1:a=0',
+ '-c:v', 'libx264', '-metadata', 'timecode=01:00:00:00', source]);
+ assert.equal((await probeSource(source)).timecode?.value, '01:00:00:00', 'Matroska uses uppercase TIMECODE metadata');
+ writeFileSync(join(folder, 'film.html'), filmHtml({ stage: { w: 160, h: 90 }, tracks: [
+ { clips: [{ id: 'plain-cut', src: 'Camera Original.mkv', at: 0, time: [4, 6] }] },
+ ] }));
+ const done = await exported({ kind: 'nle', format: 'xml', fps: 25, audio: 'clips', subtitles: false }, 'Source timecode', folder);
+ const converted = done.outputs.find((path) => path.endsWith('.mov'));
+ assert.ok(converted);
+ assert.equal((await probeSource(converted)).timecode?.value, '01:00:00:00');
+ const [{ error, found }] = await parseXml([readFileSync(done.out, 'utf8')], (doc) => {
+ const text = (selector) => doc.querySelector(selector)?.textContent;
+ return { source: text('file > timecode > string'), rate: text('file > timecode > rate > timebase'),
+ sequence: text('sequence > timecode > string'), start: text('clipitem > start'), end: text('clipitem > end'),
+ from: text('clipitem > in'), to: text('clipitem > out') };
+ });
+ assert.equal(error, null);
+ assert.deepEqual(found, { source: '01:00:00:00', rate: '25', sequence: '00:00:00:00', start: '0', end: '50', from: '100', to: '150' });
+});
+
test('Final Cut Pro keeps source audio rows when an effect overlaps adjacent narration clips', () => {
const facts = { duration: 120, hasAudio: true, channels: 2, sampleRate: 48000 };
const sound = (id, track, at, to) => ({ id, track, at, from: 0, to, speed: 1, volume: 1, enabled: true,
diff --git a/packages/openfilm/studio/server/nle-timecode.test.mjs b/packages/openfilm/studio/server/nle-timecode.test.mjs
new file mode 100644
index 0000000..0bf469e
--- /dev/null
+++ b/packages/openfilm/studio/server/nle-timecode.test.mjs
@@ -0,0 +1,112 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { nleRate, planNleTimeline, probeSource, sourceTimecode, xmemlDocument } from './nle.mjs';
+
+const facts = { w: 160, h: 90, duration: 12, fps: 25, hasVideo: true, hasAudio: true,
+ timecode: { value: '01:00:00:00', rate: nleRate(25) } };
+const picture = { id: 'cut', kind: 'video', src: 'Camera Original.mp4', path: '/p/Camera Original.mp4',
+ at: 0, end: 2, from: 4, speed: 1, track: 0, hidden: false, facts };
+const sound = { id: 'sound', src: picture.src, path: picture.path, at: 0, from: 4, to: 6,
+ speed: 1, volume: 1, enabled: true, role: 'footage', picture: picture.id, facts };
+const plan = (options = {}, pictures = [picture], sounds = [sound]) => planNleTimeline({
+ stage: { w: 160, h: 90 }, duration: 2, pictures, sounds,
+}, { title: 'Timecode', fps: 25, audio: 'clips', media: 'copy', mediaDir: '/out', ...options });
+const timecodes = (xml) => [...xml.matchAll(/<timecode>([\s\S]*?)<\/timecode>/g)].map((m) => m[1]);
+
+test('source timecode validates native rates, NDF labels and drop-frame minute boundaries', () => {
+ for (const [value, fps, expected = value] of [
+ ['01:00:00:00', 25], ['00:00:00:00', 25], ['23:59:59:24', 25],
+ ['01:00:00:00', 29.97], ['00:01:00:00', 29.97], ['01:00:00:00', 23.976],
+ ['01:00:00;00', 30000 / 1001], ['00:01:00;02', 29.97], ['00:10:00;00', 29.97],
+ ['00:01:00;04', 59.94], ['00:10:00;00', 60000 / 1001],
+ ['01:00:00.00', 29.97, '01:00:00;00'],
+ ]) assert.deepEqual(sourceTimecode(value, fps), { value: expected, rate: nleRate(fps) }, `${value} at ${fps}`);
+ for (const [value, fps] of [
+ [undefined, 25], ['', 25], ['not a timecode', 25], ['24:00:00:00', 25],
+ ['00:60:00:00', 25], ['00:00:60:00', 25], ['00:00:00:25', 25],
+ ['00:00:00:00', undefined], ['00:00:00:00', 0], ['00:00:00:00', NaN],
+ ['00:00:00:00', Infinity], ['00:00:00:00', 25.4],
+ ['01:00:00;00', 25], ['01:00:00;00', 30], ['01:00:00;00', 23.976],
+ ['00:01:00;00', 29.97], ['00:01:00;01', 29.97], ['00:01:00;03', 59.94],
+ ]) assert.equal(sourceTimecode(value, fps), undefined, `${value} at ${fps}`);
+});
+
+test('copied and linked originals retain source timecode while cuts and sequence timecode stay relative', () => {
+ for (const media of ['copy', 'link']) for (const fps of [25, 29.97]) {
+ const timeline = plan({ media, fps }), xml = xmemlDocument(timeline);
+ const [sequence, source] = timecodes(xml);
+ assert.equal(timecodes(xml).length, 2, 'picture and sound share one file definition');
+ assert.equal(timeline.files[0].job.kind, media);
+ assert.match(source, /<timebase>25<\/timebase>\s*<ntsc>FALSE<\/ntsc>/);
+ assert.match(source, /<string>01:00:00:00<\/string>/);
+ assert.doesNotMatch(source, /<frame>/, 'string plus its source rate defines the 90000-frame address');
+ assert.match(source, /<displayformat>NDF<\/displayformat>/);
+ assert.match(sequence, /<string>00:00:00:00<\/string>\s*<frame>0<\/frame>\s*<displayformat>NDF<\/displayformat>/);
+ for (const clip of [...timeline.video[0].clips, ...timeline.audio[0].clips]) {
+ assert.equal(clip.start, 0);
+ assert.equal(clip.in, Math.round(4 * timeline.rate.fps));
+ assert.equal(clip.out, Math.round(6 * timeline.rate.fps));
+ }
+ assert.equal(timeline.files[0].durationFrames, Math.round(12 * timeline.rate.fps));
+ }
+});
+
+test('source timecode display format follows its separator', () => {
+ for (const [value, fps, format] of [['01:00:00:00', 25, 'NDF'], ['01:00:00;00', 29.97, 'DF']]) {
+ const factsWithTimecode = { ...facts, timecode: { value, rate: nleRate(fps) } };
+ const source = timecodes(xmemlDocument(plan({}, [{ ...picture, facts: factsWithTimecode }], [])))[1];
+ assert.ok(source.includes('<string>' + value + '</string>'));
+ assert.ok(source.includes('<displayformat>' + format + '</displayformat>'));
+ assert.doesNotMatch(source, /<frame>/);
+ }
+});
+
+test('derived media and untagged sources do not inherit an original recording timecode', () => {
+ const timelines = [
+ plan({}, [{ ...picture, styled: true }], []),
+ plan({}, [{ ...picture, src: 'source.webm', path: '/p/source.webm' }], []),
+ plan({}, [{ ...picture, kind: 'still', src: 'still.png', path: '/p/still.png' }], []),
+ plan({}, [], [{ ...sound, fade: [0, 0.4] }]),
+ plan({}, [], [{ ...sound, speed: 2 }]),
+ plan({ audio: 'stems', stems: ['footage'] }, [], [sound]),
+ plan({}, [{ ...picture, facts: { ...facts, timecode: undefined } }], []),
+ ];
+ for (const timeline of timelines) {
+ assert.equal(timeline.files[0].timecode, undefined);
+ for (const tc of timecodes(xmemlDocument(timeline))) {
+ assert.match(tc, /<string>00:00:00:00<\/string>\s*<frame>0<\/frame>\s*<displayformat>NDF<\/displayformat>/);
+ }
+ }
+});
+
+const hasFfmpeg = ['ffmpeg', 'ffprobe'].every((bin) => {
+ try { execFileSync(bin, ['-version'], { stdio: 'ignore' }); return true; } catch { return false; }
+});
+test('ffprobe carries real recording timecodes into XML, including drop-frame and missing tags', { skip: !hasFfmpeg && 'no ffmpeg/ffprobe', timeout: 60_000 }, async () => {
+ const root = await mkdtemp(join(tmpdir(), 'of-nle-timecode-'));
+ try {
+ for (const [i, [rate, value, extension = 'mp4']] of [
+ ['25', '01:00:00:00'], ['25', '00:00:00:00'], ['30000/1001', '01:00:00;00'],
+ ['60000/1001', '01:00:00;00'], ['30000/1001', '01:00:00:00'], ['25', null],
+ ['25', '01:00:00:00', 'mkv'],
+ ].entries()) {
+ const path = join(root, `source-${i}.${extension}`);
+ execFileSync('ffmpeg', ['-v', 'error', '-f', 'lavfi', '-i', `color=red:size=32x32:rate=${rate}`,
+ '-t', '0.2', '-c:v', 'libx264', ...(value ? (extension === 'mkv' ? ['-metadata', `timecode=${value}`] : ['-timecode', value]) : []), path]);
+ const found = await probeSource(path);
+ if (value === null) assert.equal(found.timecode, undefined);
+ else {
+ assert.equal(found.timecode?.value, value);
+ assert.deepEqual(found.timecode.rate, nleRate(found.fps));
+ if (extension === 'mp4') {
+ const timeline = plan({}, [{ ...picture, path, from: 0, end: 0.08, facts: found }], []);
+ assert.ok(timecodes(xmemlDocument(timeline))[1].includes(`<string>${value}</string>`));
+ }
+ }
+ }
+ } finally { await rm(root, { recursive: true, force: true }); }
+});
diff --git a/packages/openfilm/studio/server/nle.mjs b/packages/openfilm/studio/server/nle.mjs
index 92cc2d1..ce3f588 100644
--- a/packages/openfilm/studio/server/nle.mjs
+++ b/packages/openfilm/studio/server/nle.mjs
@@ -31,7 +31,7 @@ import { exactRate } from '../../src/rate.mjs';
/**
* @typedef {import('../../src/film-doc.mjs').FilmBox} FilmBox
* @typedef {{ w?: number, h?: number, duration?: number, fps?: number, hasVideo?: boolean, hasAudio?: boolean,
- * channels?: number, sampleRate?: number, alpha?: boolean }} SourceFacts
+ * channels?: number, sampleRate?: number, alpha?: boolean, timecode?: NleTimecode }} SourceFacts
* @typedef {{ id: string, kind: 'page' | 'video' | 'still', src: string, path: string, at: number, end: number,
* from: number, speed: number, box?: FilmBox, track: number, hidden: boolean, styled?: boolean, faded?: boolean,
* facts: SourceFacts | null }} NlePicture
@@ -48,6 +48,7 @@ import { exactRate } from '../../src/rate.mjs';
* stems?: SoundRole[], audioTracks?: 'roles' | 'source', alpha?: NleAlpha }} NlePlanOptions
* @typedef {'png' | 'prores4444'} NleAlpha How a picture with alpha is written, in a MOV (default ProRes 4444)
* @typedef {{ timebase: number, ntsc: boolean, fps: number }} NleRate
+ * @typedef {{ value: string, rate: NleRate }} NleTimecode
* @typedef {{ kind: 'render', clip: string, frames: number }
* | { kind: 'copy', from: string }
* | { kind: 'link', from: string }
@@ -57,7 +58,7 @@ import { exactRate } from '../../src/rate.mjs';
* How a file is made: a clip rendered, a source cloned or pointed at, a still drawn to PNG, a source converted
* (`segment`: only those source seconds, at that speed, `seconds` long), a mixed stem
* @typedef {{ id: string, name: string, path: string, job: NleMediaJob, durationFrames: number,
- * video?: { w: number, h: number, alpha: boolean, still: boolean, fps?: number }, audio?: { channels: number, sampleRate: number } }} NleFile
+ * video?: { w: number, h: number, alpha: boolean, still: boolean, fps?: number }, audio?: { channels: number, sampleRate: number }, timecode?: NleTimecode }} NleFile
* @typedef {{ id: string, name: string, fileId: string, start: number, end: number, in: number, out: number, enabled: boolean,
* motion?: { scale: number, center: { h: number, v: number } }, gain?: number,
* levels?: { when: number, value: number }[], linkGroup?: string, sourceRow?: string }} NleClip
@@ -81,6 +82,20 @@ export function nleRate(fps) {
return ntsc ? { timebase: base, ntsc: true, fps: (base * 1000) / 1001 } : { timebase: base, ntsc: false, fps: base };
}
+/** A source's SMPTE address, only when its label and rate agree. @param {string | undefined} raw @param {number | undefined} fps @returns {NleTimecode | undefined} */
+export function sourceTimecode(raw, fps) {
+ const parts = /^(\d{2}):([0-5]\d):([0-5]\d)([:;.])(\d{2,3})$/.exec(raw ?? '');
+ if (!parts || !fps || fps <= 0 || fps >= 500) return;
+ const rate = nleRate(fps);
+ if (Math.abs(rate.fps - fps) > 0.001) return;
+ const hours = Number(parts[1]), minutes = Number(parts[2]), seconds = Number(parts[3]), frames = Number(parts[5]);
+ if (hours >= 24 || frames >= rate.timebase) return;
+ const drop = parts[4] !== ':';
+ if (drop && (!rate.ntsc || ![30, 60].includes(rate.timebase)
+ || (minutes % 10 !== 0 && seconds === 0 && frames < rate.timebase / 15))) return;
+ return { value: parts[0].replace('.', ';'), rate };
+}
+
/** Seconds → sequence frames. @param {number} sec @param {NleRate} rate */
export const toFrame = (sec, rate) => Math.round(sec * rate.fps);
@@ -233,6 +248,7 @@ export function planNleTimeline(film, opts) {
durationFrames: facts.duration ? Math.max(1, toFrame(facts.duration, rate)) : Math.max(1, minFrames),
...(video ? { video: { w: facts.w ?? stage.w, h: facts.h ?? stage.h, alpha: Boolean(facts.alpha), still: false, fps: facts.fps } } : {}),
...(audio ? { audio: converted ? { channels: audio.channels, sampleRate: 48_000 } : audio } : {}),
+ ...(!converted && facts.timecode ? { timecode: facts.timecode } : {}),
});
if (facts.duration) measured.add(file.id);
}
@@ -399,9 +415,12 @@ export const nlePathUrl = (path) => pathToFileURL(path).href.replace(/^file:\/\/
const bool = (/** @type {boolean} */ v) => (v ? 'TRUE' : 'FALSE');
const num = (/** @type {number} */ n) => String(round6(n));
const rateXml = (/** @type {NleRate} */ rate, /** @type {string} */ pad) => `${pad}<rate>\n${pad} <timebase>${rate.timebase}</timebase>\n${pad} <ntsc>${bool(rate.ntsc)}</ntsc>\n${pad}</rate>`;
-const timecodeXml = (/** @type {NleRate} */ rate, /** @type {string} */ pad) => [
- `${pad}<timecode>`, rateXml(rate, `${pad} `), `${pad} <string>00:00:00:00</string>`, `${pad} <frame>0</frame>`,
- `${pad} <displayformat>NDF</displayformat>`, `${pad}</timecode>`,
+const timecodeXml = (/** @type {NleRate} */ rate, /** @type {string} */ pad, /** @type {NleTimecode | undefined} */ source = undefined) => [
+ `${pad}<timecode>`, rateXml(source?.rate ?? rate, `${pad} `),
+ `${pad} <string>${xmlEscape(source?.value ?? '00:00:00:00')}</string>`,
+ // xmeml accepts the string and its own rate without a second, potentially conflicting frame count.
+ ...(source ? [] : [`${pad} <frame>0</frame>`]),
+ `${pad} <displayformat>${source?.value.includes(';') ? 'DF' : 'NDF'}</displayformat>`, `${pad}</timecode>`,
].join('\n');
/** @param {NleFile} file @param {NleRate} rate @param {string} pad */
@@ -412,7 +431,7 @@ function fileXml(file, rate, pad) {
`${pad} <pathurl>${xmlEscape(nlePathUrl(file.path))}</pathurl>`,
rateXml(rate, `${pad} `),
`${pad} <duration>${file.durationFrames}</duration>`,
- timecodeXml(rate, `${pad} `),
+ timecodeXml(rate, `${pad} `, file.timecode),
`${pad} <media>`,
];
if (file.video) {
@@ -535,14 +554,14 @@ export function xmemlDocument(timeline) {
export function probeSource(path) {
return new Promise((done) => {
const proc = spawn('ffprobe', ['-v', 'error', '-show_entries',
- 'format=duration,format_name:stream=codec_type,width,height,avg_frame_rate,r_frame_rate,channels,sample_rate,pix_fmt:stream_tags=alpha_mode',
+ 'format=duration,format_name:format_tags=timecode:stream=codec_type,width,height,avg_frame_rate,r_frame_rate,channels,sample_rate,pix_fmt:stream_tags=alpha_mode,timecode',
'-of', 'json', path], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
let out = '';
proc.stdout.on('data', (c) => { out += c; });
proc.on('error', () => done({}));
proc.on('close', () => {
try {
- /** @type {{ format?: { duration?: string, format_name?: string }, streams?: { codec_type?: string, width?: number, height?: number, avg_frame_rate?: string, r_frame_rate?: string, channels?: number, sample_rate?: string, pix_fmt?: string, tags?: { alpha_mode?: string } }[] }} */
+ /** @type {{ format?: { duration?: string, format_name?: string, tags?: Record<string, string> }, streams?: { codec_type?: string, width?: number, height?: number, avg_frame_rate?: string, r_frame_rate?: string, channels?: number, sample_rate?: string, pix_fmt?: string, tags?: Record<string, string> }[] }} */
const json = JSON.parse(out);
const streams = json.streams ?? [];
const v = streams.find((s) => s.codec_type === 'video');
@@ -551,11 +570,15 @@ export function probeSource(path) {
const still = /image|png|mjpeg|jpeg|bmp|tiff/.test(json.format?.format_name ?? '');
const fr = (/** @type {string | undefined} */ raw) => { const [n, d] = (raw ?? '').split('/').map(Number); return n && d ? n / d : undefined; };
const fps = fr(v?.avg_frame_rate) ?? fr(v?.r_frame_rate);
+ const tagged = (/** @type {Record<string, string> | undefined} */ tags) => Object.entries(tags ?? {}).find(([key]) => key.toLowerCase() === 'timecode')?.[1];
+ const timecode = sourceTimecode(tagged(v?.tags) ?? tagged(json.format?.tags)
+ ?? tagged(streams.find((s) => s.codec_type === 'data' && tagged(s.tags))?.tags), fps);
done({
...(v?.width ? { w: v.width } : {}),
...(v?.height ? { h: v.height } : {}),
...(Number.isFinite(sec) && sec > 0 && !still ? { duration: sec } : {}),
...(fps && fps < 500 && !still ? { fps } : {}),
+ ...(timecode && !still ? { timecode } : {}),
hasVideo: Boolean(v),
hasAudio: Boolean(a),
...(a?.channels ? { channels: a.channels } : {}),