Public: anyone can read this; the crew can change it.

A Final Cut `.fcpxml` project opens as a timeline table of clips, tracks and durations #13088

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13029-a-final-cut-fcpxml-project-opens-as-a-ti → main 4 commits fork 1 thread · 1 unresolved

  • Merged. scout/13029-a-final-cut-fcpxml-project-opens-as-a-ti was merged into main as ad90d85.

Review

Sign in to review this change.
9 files changed +227 −6
docs/features/README.md +1 −1
@@ -244,7 +244,7 @@ Read with the guide page [Your apps](../guide-your-apps.md).
244244 - [Config files as a form](config-form.md)
245245 - [Contacts files (.vcf) as a list of people](vcf-view.md)
246246 - [CSV and TSV as a table](csv-view.md)
247 - [Video-edit timelines (.otio, .edl) as a cut list](timeline-cut-list.md)
247 - [Video-edit timelines (.otio, .edl, .fcpxml) as a cut list](timeline-cut-list.md)
248248 - [Files in the browser: the media route and the kind registry](file-media.md)
249249 - [Font specimens](font.md)
250250 - [G-code layers](gcode.md)
docs/features/timeline-cut-list.md +2 −1
@@ -1,6 +1,6 @@
11 # Video-edit timelines as a cut list
22
3 Open a `.otio` (OpenTimelineIO) or `.edl` (CMX3600 edit decision list) file in a repository's file view and read it as a cut list instead of raw text.
3 Open a `.otio` (OpenTimelineIO), `.edl` (CMX3600 edit decision list) or `.fcpxml` (Final Cut Pro project) file in a repository's file view and read it as a cut list instead of raw text.
44
55 ## What you see
66
@@ -15,3 +15,4 @@ Open a `.otio` (OpenTimelineIO) or `.edl` (CMX3600 edit decision list) file in a
1515 - A file that is cut off, is not a Timeline, or has no events also keeps its source, with the reason above it.
1616 - **Frame rate.** An `.otio` carries its own rates. An `.edl` is read at the rate its header names (`FRAME RATE: 25`); with none, the page says it assumed one: 30 fps for a list marked `FCM: DROP FRAME`, 24 otherwise.
1717 - **Drop-frame.** Timecode is counted by nominal frames, so a drop-frame duration can be a frame or two off the editor's own figure. Treat totals as a guide, not a conform.
18 - **Final Cut `.fcpxml`.** One table per lane: the primary storyline (lane 0) first, then connected lanes in numeric order (…, -1, 1, 2 …). Only `asset-clip` and `clip` elements under a `spine` are read, with their `name`, `ref` (looked up in the `asset` list for the source), `lane`, `offset`, `start` and `duration`; titles, transitions, gaps, multicam and compound-clip internals are not shown, and the page says so. Times are read at the sequence format's `frameDuration`; when the sequence names no rate, 24 fps is assumed and the page says it. A file that is not well-formed XML, or has no spine or no clips, keeps its source.
src/web/render/fcpxml.ts added +130
@@ -0,0 +1,130 @@
1 /**

Both doors/docs: add .fcpxml to docs/features/timeline-cut-list.md and its index line in docs/features/README.md; the feature has no how-to as it stands.

2 * A Final Cut Pro project (`.fcpxml`) as a cut list: one table per lane
3 * (the primary storyline, then connected lanes 1, 2, -1 …) with clip name,
4 * asset, start, end and duration. Only `asset-clip` and `clip` elements under
5 * a `spine` are read; titles, transitions, gaps, multicam and compound
6 * internals are not, and the page says so. FCPXML versions differ, so this
7 * relies on nothing newer than `name`, `ref`, `lane`, `offset`, `start`,
8 * `duration` and the sequence format's `frameDuration`. Times are rationals
9 * (`1001/30000s`) shown as timecode at the sequence's frame rate; without one
10 * 24 fps is assumed and said.
11 *
12 * It reuses the tag scanner of `gpx.ts` (no XML engine, no entity expansion).
13 * Tags that do not nest, or a file with no clip, fall back to the source.
14 */
15
16 import { html } from "../html.ts";
17 import { TAG, attr, decode, local } from "./gpx.ts";
18 import { drawTimeline, timecode, type Cut, type Timeline } from "./timeline-table.ts";
19 import type { Rendered, RenderInput } from "./renderers.ts";
20
21 export type Parsed = { readonly timeline: Timeline } | { readonly error: string };
22
23 /** `1001/30000s`, `5s`, `2.5s` as seconds; undefined for anything else. */
24 export function seconds(v: string | undefined): number | undefined {
25 const m = /^\s*(-?\d+(?:\.\d+)?)(?:\/(\d+))?s\s*$/.exec(v ?? "");
26 if (m === null) return undefined;
27 const d = m[2] === undefined ? 1 : Number(m[2]);
28 const n = Number(m[1]) / d;
29 return d > 0 && Number.isFinite(n) ? n : undefined;
30 }
31
32 interface Clip { lane: string; name: string; ref: string; start: number; duration: number; offset: number; primary: boolean }
33
34 const laneOrder = (a: string, b: string): number => Number(a) - Number(b);
35
36 export function parseFcpxml(text: string): Parsed {
37 const stack: string[] = [];
38 const formats = new Map<string, number>();
39 const assets = new Map<string, string>();
40 const clips: Clip[] = [];
41 let title = "";
42 let seqFormat = "";
43 let sawRoot = false;
44 let spines = 0;
45 try {
46 for (const m of text.replace(/^/, "").matchAll(TAG)) {
47 const [, , closing, rawTag, attrs, selfClose, chars] = m;
48 if (chars !== undefined) {
49 if (stack.length === 0 && chars.trim() !== "") throw new Error("text outside root");
50 continue;
51 }
52 if (rawTag === undefined) continue;
53 const tag = local(rawTag);
54 if (closing === "/") {
55 if (stack.pop() !== tag) throw new Error("mismatch");
56 continue;
57 }
58 if (stack.length === 0) {
59 if (sawRoot || tag !== "fcpxml") throw new Error("root");
60 sawRoot = true;
61 }
62 const a = attrs ?? "";
63 const id = attr(a, "id");
64 if (tag === "format" && id !== undefined) {
65 const fd = seconds(attr(a, "frameDuration"));
66 if (fd !== undefined && fd > 0) formats.set(id, 1 / fd);
67 } else if (tag === "asset" && id !== undefined) {
68 assets.set(id, decode(attr(a, "name") ?? ""));
69 } else if (tag === "project" && title === "") {
70 title = decode(attr(a, "name") ?? "");
71 } else if (tag === "sequence" && seqFormat === "") {
72 seqFormat = attr(a, "format") ?? "";
73 } else if (tag === "spine") {
74 spines++;
75 } else if ((tag === "asset-clip" || tag === "clip") && stack.includes("spine")) {
76 const lane = (attr(a, "lane") ?? "0").trim();
77 clips.push({
78 lane: /^-?\d{1,3}$/.test(lane) ? String(Number(lane)) : "0",
79 name: decode(attr(a, "name") ?? ""),
80 ref: attr(a, "ref") ?? "",
81 start: seconds(attr(a, "start")) ?? 0,
82 duration: seconds(attr(a, "duration")) ?? 0,
83 offset: seconds(attr(a, "offset")) ?? 0,
84 primary: !stack.some((t) => t === "asset-clip" || t === "clip"),
85 });
86 }
87 if (selfClose !== "/") stack.push(tag);
88 }
89 } catch {
90 return { error: "it is not well-formed XML" };
91 }
92 if (!sawRoot || stack.length > 0) return { error: "it is not well-formed XML" };
93 if (clips.length === 0) return { error: spines === 0 ? "it holds no spine" : "its spines hold no clips" };
94
95 const fps = formats.get(seqFormat) ?? 0;
96 const rate = fps > 0 && fps <= 1000 ? fps : 24;
97 const byLane = new Map<string, Cut[]>();
98 let end = 0;
99 for (const c of clips) {
100 if (c.primary) end = Math.max(end, c.offset + c.duration);
101 const cuts = byLane.get(c.lane) ?? [];
102 cuts.push({
103 name: c.name || assets.get(c.ref) || c.ref || "(unnamed)",
104 source: assets.get(c.ref) || c.ref || "",
105 in: timecode(c.start * rate, rate),
106 out: timecode((c.start + c.duration) * rate, rate),
107 duration: timecode(c.duration * rate, rate),
108 });
109 byLane.set(c.lane, cuts);
110 }
111 const lanes = [...byLane].sort((x, y) => laneOrder(x[0], y[0]));
112 const frames = Math.round(end * rate);
113 const note =
114 "Only asset-clip and clip elements under a spine are read; titles, transitions, gaps and multicam are not shown." +
115 (fps > 0 ? "" : " The sequence names no frame rate; 24 fps is assumed.");
116 return {
117 timeline: {
118 title: title || "Untitled project",
119 tracks: lanes.map(([lane, cuts]) => ({ name: lane === "0" ? "Lane 0 (primary storyline)" : `Lane ${lane} (connected)`, cuts })),
120 total: `${timecode(frames, rate)} (${(Math.round(end * 100) / 100).toLocaleString()} s at ${Math.round(rate * 1000) / 1000} fps)`,
121 note,
122 },
123 };
124 }
125
126 export function fcpxml(input: RenderInput): Rendered {
127 const p = parseFcpxml(new TextDecoder().decode(input.body));
128 if ("error" in p) return { content: html``, lines: 0, fallback: `This file is not drawn as a cut list: ${p.error}.` };
129 return drawTimeline(input, p.timeline);
130 }
src/web/render/gpx.ts +4 −4
@@ -34,21 +34,21 @@ export interface Gpx {
3434
3535 const ENTITIES: Readonly<Record<string, string>> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
3636 /** Predefined and numeric references only; any other `&name;` stays text. */
37 const decode = (s: string): string =>
37 export const decode = (s: string): string =>
3838 s.replace(/&(?:#(\d{1,6})|#x([0-9a-fA-F]{1,5})|(amp|lt|gt|quot|apos));/g, (m, d, h, n) => {
3939 if (n !== undefined) return ENTITIES[n]!;
4040 const code = d !== undefined ? Number(d) : parseInt(h, 16);
4141 return code > 0x1f || code === 9 || code === 10 ? String.fromCodePoint(code) : m;
4242 });
4343
44 const TAG = /<!--[\s\S]*?-->|<!DOCTYPE[^[>]*(?:\[[\s\S]*?\])?\s*>|<!\[CDATA\[([\s\S]*?)\]\]>|<[?!][^>]*>|<(\/?)([A-Za-z_][\w:.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/?)>|([^<]+)/g;
44 export const TAG = /<!--[\s\S]*?-->|<!DOCTYPE[^[>]*(?:\[[\s\S]*?\])?\s*>|<!\[CDATA\[([\s\S]*?)\]\]>|<[?!][^>]*>|<(\/?)([A-Za-z_][\w:.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/?)>|([^<]+)/g;
4545 const ATTR = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
4646
47 const attr = (src: string, name: string): string | undefined => {
47 export const attr = (src: string, name: string): string | undefined => {
4848 for (const m of src.matchAll(ATTR)) if (m[1] === name) return m[2] ?? m[3];
4949 return undefined;
5050 };
51 const local = (tag: string): string => tag.slice(tag.indexOf(":") + 1).toLowerCase();
51 export const local = (tag: string): string => tag.slice(tag.indexOf(":") + 1).toLowerCase();
5252 const coord = (v: string | undefined, max: number): number | undefined => {
5353 if (v === undefined || !/^\s*[+-]?\d+(\.\d+)?\s*$/.test(v)) return undefined;
5454 const n = Number(v);
src/web/render/kinds.ts +3
@@ -42,6 +42,7 @@ export type FileKind =
4242 | "calendar"
4343 | "otio"
4444 | "edl"
45 | "fcpxml"
4546 | "contacts"
4647 | "mail"
4748 | "gcode"
@@ -102,6 +103,7 @@ export const RENDER_CAP: Readonly<Record<FileKind, number>> = {
102103 // not drawn.
103104 otio: 1 * MB,
104105 edl: 1 * MB,
106 fcpxml: 1 * MB,
105107 contacts: 5 * MB,
106108 mail: 5 * MB,
107109 gcode: 50 * MB,
@@ -240,6 +242,7 @@ const TEXTUAL: Readonly<Record<string, FileKind>> = {
240242 ics: "calendar",
241243 otio: "otio",
242244 edl: "edl",
245 fcpxml: "fcpxml",
243246 vcf: "contacts",
244247 vcard: "contacts",
245248 eml: "mail",
src/web/render/renderers.ts +2
@@ -25,6 +25,7 @@ import { font } from "./font.ts";
2525 import { ics } from "./ics.ts";
2626 import { otio } from "./otio.ts";
2727 import { edl } from "./edl.ts";
28 import { fcpxml } from "./fcpxml.ts";
2829 import { junit } from "./junit.ts";
2930 import { vcf } from "./vcf.ts";
3031 import { htmlPreview } from "./html_preview.ts";
@@ -119,6 +120,7 @@ export const RENDERERS: Partial<Readonly<Record<FileKind, Renderer>>> = {
119120 calendar: ics,
120121 otio,
121122 edl,
123 fcpxml,
122124 contacts: vcf,
123125 sarif,
124126 lcov,
test/fixtures/timelines/cut.fcpxml added +23
@@ -0,0 +1,23 @@
1 <?xml version="1.0" encoding="UTF-8"?>
2 <fcpxml version="1.10">
3 <resources>
4 <format id="r1" name="FFVideoFormat1080p25" frameDuration="100/2500s"/>
5 <asset id="r2" name="open.mov"/>
6 <asset id="r3" name="b-roll.mov"/>
7 </resources>
8 <library>
9 <event name="E">
10 <project name="Cut &lt;b&gt;One">
11 <sequence format="r1" duration="8s">
12 <spine>
13 <asset-clip ref="r2" name="Opening" offset="0s" start="1s" duration="5s">
14 <asset-clip ref="r3" lane="1" name="Cutaway &lt;b&gt;" offset="1s" start="0s" duration="2s"/>
15 </asset-clip>
16 <title name="Ignored" offset="5s" duration="1s"/>
17 <clip name="Closer" offset="5s" duration="3s"/>
18 </spine>
19 </sequence>
20 </project>
21 </event>
22 </library>
23 </fcpxml>
test/render-fcpxml.test.ts added +61
@@ -0,0 +1,61 @@
1 /** Final Cut `.fcpxml` as a cut list: good, malformed, over the ceiling, hostile text. */
2 import { describe, expect, test } from "bun:test";
3 import { readFileSync } from "node:fs";
4 import { fcpxml, parseFcpxml, seconds } from "../src/web/render/fcpxml.ts";
5 import { fileKind, RENDER_CAP } from "../src/web/render/kinds.ts";
6 import { RENDERERS } from "../src/web/render/renderers.ts";
7
8 const text = readFileSync(new URL("./fixtures/timelines/cut.fcpxml", import.meta.url), "utf8");
9 const enc = (s: string): Uint8Array => new TextEncoder().encode(s);
10 const input = (s: string) => ({ path: "a.fcpxml", size: s.length, body: enc(s), media: "/m", download: "/d" });
11
12 describe("fcpxml", () => {
13 test("is a kind with a renderer and a 1 MB ceiling", () => {
14 expect(fileKind("x/a.FCPXML", enc("<fcpxml/>"))).toBe("fcpxml");
15 expect(RENDERERS.fcpxml).toBe(fcpxml);
16 expect(RENDER_CAP.fcpxml).toBe(RENDER_CAP.edl);
17 });
18
19 test("a table per lane with name, start, duration; escaped; only clips read", () => {
20 const r = fcpxml(input(text));
21 const out = String(r.content);
22 expect(r.fallback).toBeUndefined();
23 expect(out.match(/<table/g)?.length).toBe(2);
24 expect(out).toContain("<caption>Lane 0 (primary storyline)</caption>");
25 expect(out).toContain("<caption>Lane 1 (connected)</caption>");
26 expect(out).toContain("<td>Opening</td><td>open.mov</td><td>00:00:01:00</td><td>00:00:06:00</td><td>00:00:05:00</td>");
27 expect(out).toContain("Cutaway &lt;b&gt;");
28 expect(out).toContain("Cut &lt;b&gt;One");
29 expect(out).not.toContain("<b>");
30 expect(out).not.toContain("Ignored");
31 expect(out).toContain("total length 00:00:08:00");
32 expect(out).toContain("Only asset-clip and clip elements under a spine");
33 expect(r.summary).toContain("3 clips");
34 });
35
36 test("rationals and a missing frame rate", () => {
37 expect(seconds("1001/30000s")).toBeCloseTo(0.03337, 4);
38 expect(seconds("3s")).toBe(3);
39 expect(seconds("x")).toBeUndefined();
40 const p = parseFcpxml('<fcpxml><spine><clip name="a" duration="2s"/></spine></fcpxml>');
41 if ("error" in p) throw new Error(p.error);
42 expect(p.timeline.note).toContain("24 fps is assumed");
43 });
44
45 test("malformed, empty or oversized input shows the source view", () => {
46 expect(fcpxml(input(text.slice(0, text.length >> 1))).fallback).toContain("not drawn");
47 expect(fcpxml(input("")).fallback).toBeDefined();
48 expect(fcpxml(input("<fcpxml><spine></spine></fcpxml>")).fallback).toBeDefined();
49 expect(fcpxml(input("<other/>")).fallback).toBeDefined();
50 });
51 });
52
53 describe("fcpxml row cap", () => {
54 test("a lane of 501 clips draws 500 rows and counts the rest", () => {
55 const clips = Array.from({ length: 501 }, (_, i) => `<asset-clip name="c${i}" offset="${i}s" duration="1s"/>`).join("");
56 const s = `<fcpxml version="1.9"><library><event><project name="P"><sequence><spine>${clips}</spine></sequence></project></event></library></fcpxml>`;
57 const out = String(fcpxml(input(s)).content);
58 expect(out.match(/<td>c\d+<\/td>/g)?.length).toBe(500);
59 expect(out).toContain("501");
60 });
61 });
test/render-kinds.test.ts +1
@@ -87,6 +87,7 @@ const SAMPLES: Record<string, [Uint8Array, FileKind, string]> = {
8787 ics: [enc("BEGIN:VCALENDAR\nEND:VCALENDAR\n"), "calendar", "application/octet-stream"],
8888 otio: [enc('{"OTIO_SCHEMA":"Timeline.1"}'), "otio", "application/octet-stream"],
8989 edl: [enc("TITLE: a\n"), "edl", "application/octet-stream"],
90 fcpxml: [enc("<fcpxml/>"), "fcpxml", "application/octet-stream"],
9091 gcode: [enc("G28\nG1 X1 E1\n"), "gcode", "application/octet-stream"],
9192 gco: [enc("G28\n"), "gcode", "application/octet-stream"],
9293 dxf: [enc("0\nSECTION\n2\nENTITIES\n0\nENDSEC\n0\nEOF\n"), "dxf", "application/octet-stream"],

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs