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.mdnew file mode 100644index 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.mjsindex 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 = subtitlesForExpoelse 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.mjsindex 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 differassert.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.mjsnew file mode 100644index 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.mjsindex 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 } : {}),