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

A .kdenlive project file shows its timeline as a list of tracks and clips, like .fcpxml does #14693

Merged opened this

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

Merged

scout/forge:scout/14670-a-kdenlive-project-file-shows-its-timeli → main 5 commits fork

  • Merged. scout/14670-a-kdenlive-project-file-shows-its-timeli was merged into main as 6535db4.

Review

Sign in to review this change.
9 files changed +257 −1
docs/features/file-kinds.md +1
@@ -40,6 +40,7 @@ The forge draws a file on its page when its kind is below and it is within the s
4040 - **OpenTimelineIO**, drawn up to 1 MB: `.otio`
4141 - **Edit list**, drawn up to 1 MB: `.edl`
4242 - **Final Cut XML**, drawn up to 1 MB: `.fcpxml`
43 - **Kdenlive project**, drawn up to 1 MB: `.kdenlive`
4344 - **Contacts**, drawn up to 1 MB: `.vcf`, `.vcard`
4445 - **Email**, drawn up to 5 MB: `.eml`
4546 - **G-code**, drawn up to 50 MB: `.gcode`, `.gco`
docs/features/timeline-cut-list.md +1
@@ -20,3 +20,4 @@ Open a `.otio` (OpenTimelineIO), `.edl` (CMX3600 edit decision list) or `.fcpxml
2020 - **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.
2121 - **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.
2222 - **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.
23 - **Kdenlive `.kdenlive`.** A project is MLT XML, so the file must open on an `<mlt>` root; any other `.kdenlive` stays source. One table per `playlist` that holds `entry` clips (the project bin is skipped), named by `kdenlive:track_name` on the playlist or its wrapping `tractor`, else the playlist id. Each clip shows its `kdenlive:clipname` (else the file name of its `resource`), in, out (inclusive, as MLT counts) and duration at the profile's frame rate; with no profile, 25 fps is assumed and the page says it. Blanks, transitions, filters and nested sequences are not shown. Rows are capped at 500 a track, with one line counting the rest.
scripts/kinds-guide.ts +1 −1
@@ -13,7 +13,7 @@ export const NAMES: Readonly<Record<FileKind, string>> = {
1313 sqlite: "SQLite database", parquet: "Parquet", model3d: "3D model", archive: "Archive", sheet: "Spreadsheet", document: "Word document",
1414 slides: "Slides", layers: "Layered image", font: "Font", psd: "Photoshop", config: "Config", markdown: "Markdown",
1515 notebook: "Notebook", patch: "Patch", log: "Log", subtitles: "Subtitles", gpx: "GPS track", har: "HTTP archive",
16 geojson: "GeoJSON", kml: "KML", calendar: "Calendar", otio: "OpenTimelineIO", edl: "Edit list", fcpxml: "Final Cut XML",
16 geojson: "GeoJSON", kml: "KML", calendar: "Calendar", otio: "OpenTimelineIO", edl: "Edit list", fcpxml: "Final Cut XML", kdenlive: "Kdenlive project",
1717 contacts: "Contacts", mail: "Email", gcode: "G-code", dxf: "DXF drawing", gerber: "Gerber layer", mermaid: "Mermaid diagram", drawio: "draw.io diagram",
1818 excalidraw: "Excalidraw", step: "STEP model", sarif: "SARIF report", lcov: "Coverage (lcov)", junit: "JUnit report",
1919 opml: "OPML", feed: "RSS or Atom feed", env: "Env example", openapi: "OpenAPI", package: "package.json", makefile: "Makefile",
src/web/render/kdenlive.ts added +159
@@ -0,0 +1,159 @@
1 /**
2 * A Kdenlive project (`.kdenlive`, MLT XML) as a cut list: one table per track
3 * with each clip's name, source, in point, out point and duration. A track is a
4 * `playlist` that holds `entry` elements and is not the project bin; its name
5 * is the `kdenlive:track_name` property of the playlist or of the `tractor`
6 * that wraps it, else the playlist id. A clip is named by `kdenlive:clipname`,
7 * else the file name of its `resource`, else its producer id. Blanks,
8 * transitions, filters and nested sequences are not read, and the page says so.
9 *
10 * In and out are MLT times: `HH:MM:SS.mmm` or a frame count, at the profile's
11 * frame rate (25 fps is assumed, and said, when there is none). MLT's out is
12 * inclusive, so a clip lasts out - in + 1 frames.
13 *
14 * It reuses the tag scanner of `gpx.ts` (no XML engine, no entity expansion).
15 * A file whose root is not `<mlt>`, tags that do not nest, or a project with
16 * no clip, fall back to the source.
17 */
18
19 import { html } from "../html.ts";
20 import { TAG, attr, decode, local } from "./gpx.ts";
21 import { drawTimeline, timecode, type Cut, type Timeline } from "./timeline-table.ts";
22 import type { Rendered, RenderInput } from "./renderers.ts";
23
24 export type Parsed = { readonly timeline: Timeline } | { readonly error: string };
25
26 /** An MLT time as frames: `00:00:05.040`, or a plain frame count; undefined for anything else. */
27 export function frames(v: string | undefined, rate: number): number | undefined {
28 const s = (v ?? "").trim();
29 if (/^-?\d{1,12}$/.test(s)) return Number(s);
30 const m = /^(\d{1,4}):(\d{2}):(\d{2})(?:[.,](\d{1,6}))?$/.exec(s);
31 if (m === null) return undefined;
32 const sec = Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]) + (m[4] === undefined ? 0 : Number(`0.${m[4]}`));
33 return Math.round(sec * rate);
34 }
35
36 interface Entry { producer: string; in: string; out: string }
37 interface Playlist { id: string; name: string; entries: Entry[] }
38
39 const base = (p: string): string => p.slice(Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\")) + 1);
40
41 export function parseKdenlive(text: string): Parsed {
42 const stack: { tag: string; prop?: string; text: string }[] = [];
43 const names = new Map<string, string>();
44 const sources = new Map<string, string>();
45 const playlists: Playlist[] = [];
46 const wrapped = new Map<string, string>();
47 let tractorName = "";
48 let tractorRefs: string[] = [];
49 let num = 25;
50 let den = 1;
51 let sawRoot = false;
52 try {
53 for (const m of text.replace(/^/, "").matchAll(TAG)) {
54 const [, , closing, rawTag, attrs, selfClose, chars] = m;
55 if (chars !== undefined) {
56 const top = stack[stack.length - 1];
57 if (top === undefined) {
58 if (chars.trim() !== "") throw new Error("text outside root");
59 } else if (top.prop !== undefined && top.text.length < 4096) top.text += chars;
60 continue;
61 }
62 if (rawTag === undefined) continue;
63 const tag = local(rawTag);
64 const a = attrs ?? "";
65 if (closing === "/") {
66 const top = stack.pop();
67 if (top?.tag !== tag) throw new Error("mismatch");
68 const parent = stack[stack.length - 1];
69 if (tag === "property" && top.prop !== undefined && parent !== undefined) {
70 const value = decode(top.text).trim();
71 if (parent.tag === "producer" || parent.tag === "chain") {
72 const id = parent.prop ?? "";
73 if (top.prop === "kdenlive:clipname" && value !== "") names.set(id, value);
74 else if (top.prop === "resource" && value !== "") sources.set(id, base(value));
75 } else if (top.prop === "kdenlive:track_name" && value !== "") {
76 if (parent.tag === "playlist") playlists[playlists.length - 1]!.name = value;
77 else if (parent.tag === "tractor") tractorName = value;
78 }
79 } else if (tag === "tractor") {
80 for (const r of tractorRefs) if (tractorName !== "") wrapped.set(r, tractorName);
81 tractorName = "";
82 tractorRefs = [];
83 }
84 continue;
85 }
86 if (stack.length === 0) {
87 if (sawRoot || tag !== "mlt") throw new Error("root");
88 sawRoot = true;
89 }
90 const parent = stack[stack.length - 1]?.tag;
91 const id = attr(a, "id") ?? "";
92 let entry: { tag: string; prop?: string; text: string } = { tag, text: "" };
93 if (tag === "profile") {
94 const n = Number(attr(a, "frame_rate_num"));
95 const d = Number(attr(a, "frame_rate_den"));
96 if (n > 0 && d > 0 && n / d <= 1000) { num = n; den = d; }
97 } else if (tag === "producer" || tag === "chain") {
98 entry = { tag, prop: id, text: "" };
99 } else if (tag === "playlist") {
100 playlists.push({ id, name: "", entries: [] });
101 } else if (tag === "entry" && parent === "playlist") {
102 playlists[playlists.length - 1]!.entries.push({
103 producer: attr(a, "producer") ?? "",
104 in: attr(a, "in") ?? "0",
105 out: attr(a, "out") ?? "",
106 });
107 } else if (tag === "track" && parent === "tractor") {
108 tractorRefs.push(attr(a, "producer") ?? "");
109 } else if (tag === "property" && attr(a, "name") !== undefined) {
110 entry = { tag, prop: decode(attr(a, "name") ?? ""), text: "" };
111 }
112 if (selfClose !== "/") stack.push(entry);
113 else if (tag === "tractor") { tractorName = ""; tractorRefs = []; }
114 }
115 } catch {
116 return { error: "it is not well-formed XML" };
117 }
118 if (!sawRoot || stack.length > 0) return { error: "it is not well-formed XML" };
119
120 const rate = num / den;
121 const tracks = [];
122 let end = 0;
123 for (const p of playlists) {
124 if (p.entries.length === 0 || p.id === "main_bin" || p.id === "") continue;
125 const cuts: Cut[] = [];
126 for (const e of p.entries) {
127 const i = frames(e.in, rate) ?? 0;
128 const o = frames(e.out, rate) ?? i - 1;
129 const dur = Math.max(0, o - i + 1);
130 end = Math.max(end, dur);
131 cuts.push({
132 name: names.get(e.producer) || sources.get(e.producer) || e.producer || "(unnamed)",
133 source: sources.get(e.producer) ?? "",
134 in: timecode(i, rate),
135 out: timecode(o, rate),
136 duration: timecode(dur, rate),
137 });
138 }
139 tracks.push({ name: p.name || wrapped.get(p.id) || p.id, cuts });
140 }
141 if (tracks.length === 0) return { error: "it holds no track with clips" };
142 const fps = Math.round(rate * 1000) / 1000;
143 return {
144 timeline: {
145 title: "Kdenlive project",
146 tracks,
147 total: `${tracks.reduce((n, t) => n + t.cuts.length, 0).toLocaleString()} clips at ${fps} fps`,
148 note:
149 "Only the clips on each track are read; blanks, transitions, filters and nested sequences are not shown. Out points are inclusive." +
150 (num > 0 && /<profile\b/.test(text) ? "" : " The project names no profile; 25 fps is assumed."),
151 },
152 };
153 }
154
155 export function kdenlive(input: RenderInput): Rendered {
156 const p = parseKdenlive(new TextDecoder().decode(input.body));
157 if ("error" in p) return { content: html``, lines: 0, fallback: `This file is not drawn as a cut list: ${p.error}.` };
158 return drawTimeline(input, p.timeline);
159 }
src/web/render/kinds.ts +11
@@ -46,6 +46,7 @@ export type FileKind =
4646 | "otio"
4747 | "edl"
4848 | "fcpxml"
49 | "kdenlive"
4950 | "contacts"
5051 | "mail"
5152 | "gcode"
@@ -132,6 +133,7 @@ export const RENDER_CAP: Readonly<Record<FileKind, number>> = {
132133 otio: 1 * MB,
133134 edl: 1 * MB,
134135 fcpxml: 1 * MB,
136 kdenlive: 1 * MB,
135137 contacts: 1 * MB,
136138 mail: 5 * MB,
137139 gcode: 50 * MB,
@@ -291,6 +293,7 @@ const TEXTUAL: Readonly<Record<string, FileKind>> = {
291293 otio: "otio",
292294 edl: "edl",
293295 fcpxml: "fcpxml",
296 kdenlive: "kdenlive",
294297 vcf: "contacts",
295298 vcard: "contacts",
296299 eml: "mail",
@@ -460,6 +463,12 @@ function xmlFeedKind(path: string, head: Uint8Array): "opml" | "feed" | undefine
460463 return root === "rss" || root === "feed" || root === "rdf:RDF" ? "feed" : undefined;
461464 }
462465
466 /** The root element (past the prolog and comments) is `<mlt>`. */
467 function isMltHead(head: Uint8Array): boolean {
468 const text = new TextDecoder().decode(head).replace(/^\uFEFF/, "").replace(/<\?[\s\S]*?\?>|<!--[\s\S]*?-->/g, "");
469 return /^\s*<mlt[\s>/]/.test(text);
470 }
471
463472 /** Git's own heuristic: a NUL in the first 8 KB means binary. */
464473 const looksBinary = (head: Uint8Array): boolean => head.subarray(0, 8000).includes(0);
465474
@@ -498,6 +507,8 @@ export function fileKind(path: string, head: Uint8Array): FileKind {
498507 const ext = extension(path);
499508 // Collada opens on a `<COLLADA` root: a `.dae` that does not is only text.
500509 if (ext === "dae") return /<COLLADA[\s>]/.test(new TextDecoder().decode(head)) ? "model3d" : "text";
510 // A Kdenlive project is MLT XML: a `.kdenlive` whose root is not `<mlt>` is only text.
511 if (ext === "kdenlive") return isMltHead(head) ? "kdenlive" : "text";
501512 if (ext === "step" || ext === "stp") return isStepHead(head) ? "step" : "text";
502513 if (ext === "gbr" || ext === "gtl" || ext === "gbl") return isGerberHead(head) ? "gerber" : "text";
503514 // RTF opens on `{\rtf`: a `.rtf` whose bytes say otherwise is only text.
src/web/render/renderers.ts +2
@@ -35,6 +35,7 @@ import { ics } from "./ics.ts";
3535 import { otio } from "./otio.ts";
3636 import { edl } from "./edl.ts";
3737 import { fcpxml } from "./fcpxml.ts";
38 import { kdenlive } from "./kdenlive.ts";
3839 import { junit } from "./junit.ts";
3940 import { feedXml } from "./feed-xml.ts";
4041 import { vcf } from "./vcf.ts";
@@ -156,6 +157,7 @@ export const RENDERERS: Partial<Readonly<Record<FileKind, Renderer>>> = {
156157 otio,
157158 edl,
158159 fcpxml,
160 kdenlive,
159161 contacts: vcf,
160162 sarif,
161163 lcov,
test/fuzz-renderers.test.ts +6
@@ -276,6 +276,12 @@ export const SAMPLES: Readonly<Record<string, { path: string; files: readonly st
276276 '<?xml version="1.0"?><fcpxml version="1.9"><resources><format id="r1" frameDuration="1/24s"/><asset id="r2" name="A" src="file:///a.mov"/></resources><library><event><project name="P"><sequence format="r1"><spine><asset-clip ref="r2" name="&lt;b&gt;c&lt;/b&gt;" offset="0s" start="0s" duration="2s"/></spine></sequence></project></event></library></fcpxml>',
277277 ],
278278 },
279 kdenlive: {
280 path: "cut.kdenlive",
281 files: [
282 '<?xml version="1.0"?><mlt><profile frame_rate_num="25" frame_rate_den="1"/><producer id="p"><property name="resource">/a/b.mp4</property><property name="kdenlive:clipname">&lt;b&gt;c&lt;/b&gt;</property></producer><playlist id="t"><entry producer="p" in="0" out="24"/></playlist></mlt>',
283 ],
284 },
279285 junit: {
280286 path: "results.junit.xml",
281287 files: [
test/kdenlive-render.test.ts added +75
@@ -0,0 +1,75 @@
1 /**
2 * Kdenlive `.kdenlive` (MLT XML) as a cut list: good, not a project, malformed, capped, hostile
3 * text.
4 */
5 import { describe, expect, test } from "bun:test";
6 import { fileKind, RENDER_CAP } from "../src/web/render/kinds.ts";
7 import { RENDERERS } from "../src/web/render/renderers.ts";
8 import { frames, kdenlive, parseKdenlive } from "../src/web/render/kdenlive.ts";
9
10 const enc = (s: string) => new TextEncoder().encode(s);
11 const input = (s: string) => ({ path: "a.kdenlive", size: s.length, body: enc(s), media: "/m", download: "/d" });
12
13 const project = `<?xml version="1.0" encoding="utf-8"?>
14 <mlt LC_NUMERIC="C" version="7.0.0">
15 <profile description="HD 1080p 25 fps" frame_rate_num="25" frame_rate_den="1"/>
16 <producer id="p1" in="00:00:00.000" out="00:00:10.000">
17 <property name="resource">/home/me/clips/beach.mp4</property>
18 <property name="kdenlive:clipname">Beach &lt;b&gt;day&lt;/b&gt;</property>
19 </producer>
20 <producer id="p2"><property name="resource">C:\\v\\talk.mkv</property></producer>
21 <playlist id="main_bin"><entry producer="p1" in="0" out="10"/></playlist>
22 <playlist id="playlist0"><property name="kdenlive:track_name">V1</property>
23 <entry producer="p1" in="00:00:01.000" out="00:00:03.960"/>
24 <blank length="25"/>
25 <entry producer="p2" in="0" out="49"/>
26 </playlist>
27 <playlist id="playlist1"/>
28 <tractor id="tractor0"><property name="kdenlive:track_name">A1</property><track producer="playlist2"/></tractor>
29 <playlist id="playlist2"><entry producer="p1" in="0" out="24"/></playlist>
30 </mlt>`;
31
32 describe("kdenlive", () => {
33 test("is a kind decided by the root element, drawn by its renderer", () => {
34 expect(fileKind("x/a.kdenlive", enc(project))).toBe("kdenlive");
35 expect(fileKind("a.kdenlive", enc("<other/>"))).toBe("text");
36 expect(fileKind("a.xml", enc(project))).toBe("xml");
37 expect(RENDERERS.kdenlive).toBe(kdenlive);
38 expect(RENDER_CAP.kdenlive).toBe(RENDER_CAP.edl);
39 });
40
41 test("reads times as frames", () => {
42 expect(frames("00:00:01.040", 25)).toBe(26);
43 expect(frames("49", 25)).toBe(49);
44 expect(frames("nope", 25)).toBeUndefined();
45 });
46
47 test("tracks list each clip's name, in, out and duration", () => {
48 const p = parseKdenlive(project);
49 if (!("timeline" in p)) throw new Error(p.error);
50 expect(p.timeline.tracks.map((t) => t.name)).toEqual(["V1", "A1"]);
51 const [a, b] = p.timeline.tracks[0]!.cuts;
52 expect(a).toMatchObject({ name: "Beach <b>day</b>", source: "beach.mp4", in: "00:00:01:00", out: "00:00:03:24", duration: "00:00:03:00" });
53 expect(b).toMatchObject({ name: "talk.mkv", in: "00:00:00:00", out: "00:00:01:24", duration: "00:00:02:00" });
54 });
55
56 test("output is escaped", () => {
57 const out = String(kdenlive(input(project)).content);
58 expect(out).toContain("Beach &lt;b&gt;day&lt;/b&gt;");
59 expect(out).not.toContain("<b>day");
60 });
61
62 test("a file that is not a project, or is malformed, falls back and never throws", () => {
63 for (const s of ["", "<other/>", "<mlt></mlt>", "<mlt><playlist id='x'></mlt>", project.slice(0, 400), "<mlt/>junk", "\0\u0001<<>>"]) {
64 expect(kdenlive(input(s)).fallback).toContain("not drawn");
65 }
66 });
67
68 test("a track of 501 clips draws 500 rows and counts the rest", () => {
69 const e = Array.from({ length: 501 }, (_, i) => `<entry producer="p" in="${i}" out="${i}"/>`).join("");
70 const s = `<mlt><producer id="p"><property name="kdenlive:clipname">c</property></producer><playlist id="t">${e}</playlist></mlt>`;
71 const out = String(kdenlive(input(s)).content);
72 expect(out.match(/<td>c<\/td>/g)?.length).toBe(500);
73 expect(out).toContain("1 more clips");
74 });
75 });
test/render-kinds.test.ts +1
@@ -94,6 +94,7 @@ const SAMPLES: Record<string, [Uint8Array, FileKind, string]> = {
9494 otio: [enc('{"OTIO_SCHEMA":"Timeline.1"}'), "otio", "application/octet-stream"],
9595 edl: [enc("TITLE: a\n"), "edl", "application/octet-stream"],
9696 fcpxml: [enc("<fcpxml/>"), "fcpxml", "application/octet-stream"],
97 kdenlive: [enc("<mlt/>"), "kdenlive", "application/octet-stream"],
9798 gcode: [enc("G28\nG1 X1 E1\n"), "gcode", "application/octet-stream"],
9899 gco: [enc("G28\n"), "gcode", "application/octet-stream"],
99100 dxf: [enc("0\nSECTION\n2\nENTITIES\n0\nENDSEC\n0\nEOF\n"), "dxf", "application/octet-stream"],

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs