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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13029-a-final-cut-fcpxml-project-opens-as-a-ti → main 4 commits fork 1 thread · 1 unresolved
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). | ||
| 244 | 244 | - [](config-form.md) |
| 245 | 245 | - [](vcf-view.md) |
| 246 | 246 | - [](csv-view.md) |
| 247 | - [](timeline-cut-list.md) | |
| 247 | - [](timeline-cut-list.md) | |
| 248 | 248 | - [](file-media.md) |
| 249 | 249 | - [](font.md) |
| 250 | 250 | - [](gcode.md) |
docs/features/timeline-cut-list.md +2 −1
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | # Video-edit timelines as a cut list |
| 2 | 2 | |
| 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. | |
| 4 | 4 | |
| 5 | 5 | ## What you see |
| 6 | 6 | |
| @@ -15,3 +15,4 @@ Open a `.otio` (OpenTimelineIO) or `.edl` (CMX3600 edit decision list) file in a | ||
| 15 | 15 | - A file that is cut off, is not a Timeline, or has no events also keeps its source, with the reason above it. |
| 16 | 16 | - **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. |
| 17 | 17 | - **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 | /** | |
| 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 { | ||
| 34 | 34 | |
| 35 | 35 | const ENTITIES: Readonly<Record<string, string>> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" }; |
| 36 | 36 | /** Predefined and numeric references only; any other `&name;` stays text. */ |
| 37 | const decode = (s: string): string => | |
| 37 | export const decode = (s: string): string => | |
| 38 | 38 | s.replace(/&(?:#(\d{1,6})|#x([0-9a-fA-F]{1,5})|(amp|lt|gt|quot|apos));/g, (m, d, h, n) => { |
| 39 | 39 | if (n !== undefined) return ENTITIES[n]!; |
| 40 | 40 | const code = d !== undefined ? Number(d) : parseInt(h, 16); |
| 41 | 41 | return code > 0x1f || code === 9 || code === 10 ? String.fromCodePoint(code) : m; |
| 42 | 42 | }); |
| 43 | 43 | |
| 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; | |
| 45 | 45 | const ATTR = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g; |
| 46 | 46 | |
| 47 | const attr = (src: string, name: string): string | undefined => { | |
| 47 | export const attr = (src: string, name: string): string | undefined => { | |
| 48 | 48 | for (const m of src.matchAll(ATTR)) if (m[1] === name) return m[2] ?? m[3]; |
| 49 | 49 | return undefined; |
| 50 | 50 | }; |
| 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(); | |
| 52 | 52 | const coord = (v: string | undefined, max: number): number | undefined => { |
| 53 | 53 | if (v === undefined || !/^\s*[+-]?\d+(\.\d+)?\s*$/.test(v)) return undefined; |
| 54 | 54 | const n = Number(v); |
src/web/render/kinds.ts +3
| @@ -42,6 +42,7 @@ export type FileKind = | ||
| 42 | 42 | | "calendar" |
| 43 | 43 | | "otio" |
| 44 | 44 | | "edl" |
| 45 | | "fcpxml" | |
| 45 | 46 | | "contacts" |
| 46 | 47 | | "mail" |
| 47 | 48 | | "gcode" |
| @@ -102,6 +103,7 @@ export const RENDER_CAP: Readonly<Record<FileKind, number>> = { | ||
| 102 | 103 | // not drawn. |
| 103 | 104 | otio: 1 * MB, |
| 104 | 105 | edl: 1 * MB, |
| 106 | fcpxml: 1 * MB, | |
| 105 | 107 | contacts: 5 * MB, |
| 106 | 108 | mail: 5 * MB, |
| 107 | 109 | gcode: 50 * MB, |
| @@ -240,6 +242,7 @@ const TEXTUAL: Readonly<Record<string, FileKind>> = { | ||
| 240 | 242 | ics: "calendar", |
| 241 | 243 | otio: "otio", |
| 242 | 244 | edl: "edl", |
| 245 | fcpxml: "fcpxml", | |
| 243 | 246 | vcf: "contacts", |
| 244 | 247 | vcard: "contacts", |
| 245 | 248 | eml: "mail", |
src/web/render/renderers.ts +2
| @@ -25,6 +25,7 @@ import { font } from "./font.ts"; | ||
| 25 | 25 | import { ics } from "./ics.ts"; |
| 26 | 26 | import { otio } from "./otio.ts"; |
| 27 | 27 | import { edl } from "./edl.ts"; |
| 28 | import { fcpxml } from "./fcpxml.ts"; | |
| 28 | 29 | import { junit } from "./junit.ts"; |
| 29 | 30 | import { vcf } from "./vcf.ts"; |
| 30 | 31 | import { htmlPreview } from "./html_preview.ts"; |
| @@ -119,6 +120,7 @@ export const RENDERERS: Partial<Readonly<Record<FileKind, Renderer>>> = { | ||
| 119 | 120 | calendar: ics, |
| 120 | 121 | otio, |
| 121 | 122 | edl, |
| 123 | fcpxml, | |
| 122 | 124 | contacts: vcf, |
| 123 | 125 | sarif, |
| 124 | 126 | 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 <b>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 <b>" 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 <b>"); | |
| 28 | expect(out).toContain("Cut <b>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]> = { | ||
| 87 | 87 | ics: [enc("BEGIN:VCALENDAR\nEND:VCALENDAR\n"), "calendar", "application/octet-stream"], |
| 88 | 88 | otio: [enc('{"OTIO_SCHEMA":"Timeline.1"}'), "otio", "application/octet-stream"], |
| 89 | 89 | edl: [enc("TITLE: a\n"), "edl", "application/octet-stream"], |
| 90 | fcpxml: [enc("<fcpxml/>"), "fcpxml", "application/octet-stream"], | |
| 90 | 91 | gcode: [enc("G28\nG1 X1 E1\n"), "gcode", "application/octet-stream"], |
| 91 | 92 | gco: [enc("G28\n"), "gcode", "application/octet-stream"], |
| 92 | 93 | dxf: [enc("0\nSECTION\n2\nENTITIES\n0\nENDSEC\n0\nEOF\n"), "dxf", "application/octet-stream"], |
new above
offline
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.