@ossclip/core 0.1.19 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/export-edl.ts

@@ -0,0 +1,99 @@
+import { basename } from "node:path";
+import { keptPauseLabel, keptPauses } from "./export-markers";
+import type { Production, RemovalReason, Segment } from "./schema";
+
+/**
+ * Resolve marker EDL export (§142). The FCPXML exporter's markers are real,
+ * but DaVinci Resolve's FCPXML import silently drops clip markers — verified
+ * in the field the day FCPXML shipped: timeline imported, 127 markers gone,
+ * marker display on. Resolve's dedicated path is `Timeline → Import →
+ * Timeline Markers from EDL`, and its format is Resolve's OWN marker-EDL
+ * dialect: a CMX3600-shaped event per marker plus a continuation line
+ * ` |C:ResolveColor<name> |M:<label> |D:<frames>`.
+ *
+ * This dialect is also where the §141 colour decision gets un-made for one
+ * consumer: FCPXML markers cannot carry colour, but |C: can — so here the
+ * cut REASON maps to a colour as well as living in the label.
+ */
+
+/**
+ * Reason → Resolve marker colour. Names must be from Resolve's fixed
+ * View → Show Markers list (verified against Resolve 20); an unknown name
+ * imports as the default colour rather than erroring, but stay exact anyway.
+ */
+const REASON_COLOURS: Record<RemovalReason, string> = {
+  silence: "Blue",
+  pause: "Sky",
+  filler: "Yellow",
+  retake: "Red",
+  user: "Green",
+  clip: "Purple",
+};
+
+/** Non-drop hh:mm:ss:ff at an integer frame rate. */
+export function framesToTimecode(frames: number, fps: number): string {
+  const ff = frames % fps;
+  const totalSec = Math.floor(frames / fps);
+  const ss = totalSec % 60;
+  const mm = Math.floor(totalSec / 60) % 60;
+  const hh = Math.floor(totalSec / 3600);
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${p(hh)}:${p(mm)}:${p(ss)}:${p(ff)}`;
+}
+
+/**
+ * ASCII on purpose, unlike the report and the FCPXML labels: EDL is a
+ * fixed-width 1970s interchange format and the true minus sign (U+2212) is
+ * exactly the kind of byte that a strict parser turns into a silently
+ * skipped line. Pipes are stripped because ` |` is the field separator.
+ */
+function label(seg: Segment): string {
+  const dur = (seg.srcOut - seg.srcIn).toFixed(2);
+  const conf = seg.confidence !== undefined ? ` (conf ${seg.confidence.toFixed(2)})` : "";
+  return `${seg.reason ?? "cut"} -${dur}s${conf}`.replaceAll("|", "/");
+}
+
+export function buildResolveMarkerEdl(production: Production): string {
+  const { path, probe } = production.source;
+  const fps = Math.round(probe.fps);
+  // SPANS, not 1-frame points (§142 round 2): |D: carries the whole
+  // suggested cut in frames, so Resolve draws the marker across the region —
+  // the field editor needs where content RESUMES as much as where the cut
+  // starts. Kept pauses (export-markers.ts) join the list in Lavender, a
+  // colour no cut reason uses, so suggestion and information stay distinct.
+  const items = [
+    ...(production.cutlist ?? [])
+      .filter((s) => s.kind === "remove")
+      .map((s) => ({
+        start: s.srcIn,
+        end: s.srcOut,
+        colour: REASON_COLOURS[s.reason ?? "user"] ?? "Green",
+        label: label(s),
+      })),
+    ...keptPauses(production).map((p) => ({
+      start: p.start,
+      end: p.end,
+      colour: "Lavender",
+      label: keptPauseLabel(p).replaceAll("|", "/"),
+    })),
+  ].sort((a, b) => a.start - b.start);
+  const lines: string[] = [
+    `TITLE: ${basename(path)} — ossclip markers`,
+    "FCM: NON-DROP FRAME",
+    "",
+  ];
+  items.forEach((m, i) => {
+    const inFrames = Math.round(m.start * fps);
+    // At least one frame — a zero-length marker is invisible.
+    const durFrames = Math.max(1, Math.round(m.end * fps) - inFrames);
+    const tcIn = framesToTimecode(inFrames, fps);
+    const tcOut = framesToTimecode(inFrames + durFrames, fps);
+    // Record TC = source TC: the FCPXML timeline this rides on starts at
+    // 00:00:00:00 (tcStart 0), so the marker lands at the source position.
+    const num = String(i + 1).padStart(3, "0");
+    lines.push(`${num}  001      V     C        ${tcIn} ${tcOut} ${tcIn} ${tcOut}  `);
+    lines.push(` |C:ResolveColor${m.colour} |M:${m.label} |D:${durFrames}`);
+    lines.push("");
+  });
+  return `${lines.join("\n")}\n`;
+}

package/src/export-fcpxml.ts

@@ -0,0 +1,127 @@
+import { basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { keptPauseLabel, keptPauses } from "./export-markers";
+import type { Production, Segment } from "./schema";
+
+/**
+ * FCPXML 1.10 marker export — the file format half of `ossclip analyse`
+ * (next-directions §2; design doc 2026-08-12-analyse-fcpxml-export-design.md).
+ * Pure by the house split: Production in, XML string out; the CLI owns the
+ * file write. The document is a project whose single asset-clip is the
+ * ORIGINAL source with one named marker per planned cut — markers, not
+ * applied cuts, because an editor wants to REVIEW "dead air here / blooper
+ * here" before acting on it, and both Resolve and Premiere read this format.
+ *
+ * No marker colours, resolved deliberately: stock FCPXML `<marker>` carries
+ * no colour attribute, and colour does not reliably survive a Resolve round
+ * trip — so the cut REASON travels in the marker name (the report.txt
+ * vocabulary), which every importer displays.
+ */
+
+/** A frame's duration as an exact rational — FCPXML's own time currency. */
+export interface FrameDuration {
+  num: number;
+  den: number;
+}
+
+/**
+ * NTSC rates have no integer-denominator form — 29.97 is exactly 30000/1001,
+ * and ffprobe reports it as a float that equals neither 29.97 nor the
+ * rational. Matched by tolerance for that reason; anything else is treated
+ * as the integer rate it rounds to.
+ */
+const NTSC_RATES: Array<{ fps: number; fd: FrameDuration }> = [
+  { fps: 24000 / 1001, fd: { num: 1001, den: 24000 } },
+  { fps: 30000 / 1001, fd: { num: 1001, den: 30000 } },
+  { fps: 60000 / 1001, fd: { num: 1001, den: 60000 } },
+];
+
+export function fpsToFrameDuration(fps: number): FrameDuration {
+  for (const { fps: ntsc, fd } of NTSC_RATES) {
+    if (Math.abs(fps - ntsc) < 0.01) return fd;
+  }
+  return { num: 1, den: Math.round(fps) };
+}
+
+/**
+ * A seconds value as a frame-aligned FCPXML rational (`"53/30s"`). A float
+ * like `1.77s` is legal FCPXML but frame-misaligned, and importers round it
+ * silently — quantizing here keeps the marker on the frame the report named,
+ * with the rounding visible in this codebase instead of implicit in theirs.
+ */
+export function quantizeToFrame(seconds: number, fd: FrameDuration): string {
+  const frames = Math.round((seconds * fd.den) / fd.num);
+  return `${frames * fd.num}/${fd.den}s`;
+}
+
+function esc(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/** The report.txt line, minus the timestamps the marker position already is. */
+function markerName(seg: Segment): string {
+  const dur = (seg.srcOut - seg.srcIn).toFixed(2);
+  const conf = seg.confidence !== undefined ? ` (conf ${seg.confidence.toFixed(2)})` : "";
+  return `${seg.reason ?? "cut"} −${dur}s${conf}`;
+}
+
+export function buildFcpxmlMarkers(production: Production): string {
+  const { path, probe } = production.source;
+  const fd = fpsToFrameDuration(probe.fps);
+  const dur = quantizeToFrame(probe.duration, fd);
+  const name = basename(path);
+  // SPANS, not points (§142 round 2): the 1-frame marker was a deliberate
+  // "don't overstate the suggestion" choice, and the first real editor
+  // reversed it — she needs where the cut starts AND where content resumes,
+  // and a span's two edges are exactly that. Kept pauses ride along as their
+  // own markers (see export-markers.ts); one time-ordered list, so the
+  // NLE's marker index reads like the take.
+  const spanFrames = (startSec: number, endSec: number) => {
+    const frames = (sec: number) => Math.round((sec * fd.den) / fd.num);
+    return Math.max(1, frames(endSec) - frames(startSec));
+  };
+  const removals = (production.cutlist ?? []).filter((s) => s.kind === "remove");
+  const items = [
+    ...removals.map((s) => ({ start: s.srcIn, end: s.srcOut, label: markerName(s) })),
+    ...keptPauses(production).map((p) => ({ start: p.start, end: p.end, label: keptPauseLabel(p) })),
+  ].sort((a, b) => a.start - b.start);
+  const markers = items
+    .map(
+      (m) =>
+        `            <marker start="${quantizeToFrame(m.start, fd)}" ` +
+        `duration="${spanFrames(m.start, m.end) * fd.num}/${fd.den}s" value="${esc(m.label)}"/>`,
+    )
+    .join("\n");
+  // pathToFileURL, not string concat: it percent-encodes the characters a
+  // URL cannot carry (spaces, #) while the XML escaping below handles the
+  // ones an ATTRIBUTE cannot (&) — two encodings, two owners.
+  const srcUrl = esc(pathToFileURL(path).href);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE fcpxml>
+<fcpxml version="1.10">
+  <resources>
+    <format id="r1" frameDuration="${fd.num}/${fd.den}s" width="${probe.width}" height="${probe.height}"/>
+    <asset id="r2" name="${esc(name)}" start="0/${fd.den}s" duration="${dur}" hasVideo="1" hasAudio="${probe.hasAudio ? 1 : 0}" format="r1">
+      <media-rep kind="original-media" src="${srcUrl}"/>
+    </asset>
+  </resources>
+  <library>
+    <event name="ossclip">
+      <project name="${esc(`${name} — ossclip markers`)}">
+        <sequence format="r1" duration="${dur}" tcStart="0/${fd.den}s">
+          <spine>
+            <asset-clip ref="r2" offset="0/${fd.den}s" name="${esc(name)}" start="0/${fd.den}s" duration="${dur}" format="r1">
+${markers ? `${markers}\n` : ""}            </asset-clip>
+          </spine>
+        </sequence>
+      </project>
+    </event>
+  </library>
+</fcpxml>
+`;
+}

package/src/export-markers.ts

@@ -0,0 +1,43 @@
+import type { Production, Span } from "./schema";
+
+/**
+ * Shared derivations for the NLE marker exporters (§142 round 2).
+ *
+ * The field editor's second complaint, verified frame-by-frame against her
+ * recorded feedback: real pauses sat visibly in her waveform with no marker
+ * on them. Those are pauses the analysis DETECTED but the cut rules KEPT —
+ * below the cut bar, or sentence-snapped away. The exports read only the
+ * cutlist, so a kept pause was invisible in exactly the tool she uses to
+ * find pauses. `analysis.cuttable` is the right pool: regions with no
+ * audible speech AFTER the transcript veto — the same candidates every
+ * silence/pause cut was drawn from.
+ */
+
+/**
+ * 0.25s, not `breaths`' 120ms floor: a 30-minute take carries hundreds of
+ * sub-quarter-second breaths, and a marker per breath buries the markers the
+ * editor asked for under the ones she didn't (§142 round 2 — marker-spam
+ * floor).
+ */
+export const MIN_KEPT_PAUSE_SEC = 0.25;
+
+/**
+ * Detected pauses the cut rules kept: cuttable regions no remove segment
+ * overlaps, at or above the floor. A PARTIALLY overlapped region is excluded
+ * too — the cut already marks that neighbourhood, and a second marker there
+ * would read as a second suggestion.
+ */
+export function keptPauses(production: Production): Span[] {
+  const cuttable = production.analysis?.cuttable ?? [];
+  const removes = (production.cutlist ?? []).filter((s) => s.kind === "remove");
+  return cuttable.filter(
+    (span) =>
+      span.end - span.start >= MIN_KEPT_PAUSE_SEC &&
+      !removes.some((r) => r.srcIn < span.end && r.srcOut > span.start),
+  );
+}
+
+/** The kept-pause label, shared so all three formats say the same words. */
+export function keptPauseLabel(span: Span): string {
+  return `pause ${(span.end - span.start).toFixed(2)}s (kept)`;
+}

package/src/export-premiere-xml.ts

@@ -0,0 +1,200 @@
+import { basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { keptPauseLabel, keptPauses } from "./export-markers";
+import type { Production, Segment } from "./schema";
+
+/**
+ * Premiere marker export — legacy FCP7 XML, "xmeml" (§142). The field test
+ * that shipped fcpxml killed its own premise within the hour: Premiere Pro
+ * does NOT import modern FCPXML ("File format not supported"); the format it
+ * lists as "Final Cut Pro XML" is the LEGACY xmeml interchange, a different
+ * document entirely. So: fcpxml serves actual Final Cut Pro, resolve-edl
+ * serves Resolve (whose fcpxml import drops markers), and THIS serves
+ * Premiere — an xmeml v4 sequence whose SEQUENCE-level markers carry the cut
+ * list onto the timeline ruler after File → Import.
+ *
+ * Same house split as the other two exporters: Production in, string out.
+ */
+
+/**
+ * xmeml has no rational time: a rate is an integer `timebase` plus an `ntsc`
+ * flag, and every position is a frame count at that timebase. 29.97 is
+ * "30 TRUE" — the flag, not the number, is where the 1001 lives.
+ */
+export function xmemlRate(fps: number): { timebase: number; ntsc: boolean } {
+  const rounded = Math.round(fps);
+  // The NTSC family sits ~0.1% under its integer; a probe float lands close
+  // to the exact rational, never on the integer itself.
+  const ntsc = Math.abs(fps - rounded) > 0.001;
+  return { timebase: ntsc ? Math.ceil(fps) : rounded, ntsc };
+}
+
+function esc(s: string): string {
+  return s
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/** ASCII hyphen like the EDL label — xmeml consumers are as old as it is. */
+function label(seg: Segment): string {
+  const dur = (seg.srcOut - seg.srcIn).toFixed(2);
+  const conf = seg.confidence !== undefined ? ` (conf ${seg.confidence.toFixed(2)})` : "";
+  return `${seg.reason ?? "cut"} -${dur}s${conf}`;
+}
+
+export function buildPremiereXmlMarkers(production: Production): string {
+  const { path, probe } = production.source;
+  const { timebase, ntsc } = xmemlRate(probe.fps);
+  const ntscStr = ntsc ? "TRUE" : "FALSE";
+  const toFrames = (sec: number) => Math.round(sec * probe.fps);
+  const durFrames = toFrames(probe.duration);
+  const name = esc(basename(path));
+  const rateXml = (indent: string) =>
+    `${indent}<rate>\n${indent}  <timebase>${timebase}</timebase>\n${indent}  <ntsc>${ntscStr}</ntsc>\n${indent}</rate>`;
+  // Emitted at BOTH levels, deliberately (field feedback, first real editor,
+  // §142). SEQUENCE markers sit at fixed timecode — the moment the editor
+  // ripple-deletes their first blooper, every downstream one points at the
+  // wrong moment, which is exactly why our field editor went back to manual.
+  // CLIP markers are anchored to the clip's MEDIA time, so they ride through
+  // razor cuts and ripple deletes and stay on the words they describe. The
+  // sequence copies stay too: they are the read-only overview of the
+  // untouched take, and the two agree while nothing is edited.
+  // SPANS, not points (§142 round 2). The original -1 (point marker) was a
+  // deliberate "a span overstates the suggestion" call — the first real
+  // editor reversed it: she needs the cut's END ("the video resumes from
+  // here") as much as its start, and a span's edges are both. Kept pauses
+  // (export-markers.ts) join the same time-ordered list.
+  const markerItems = [
+    ...(production.cutlist ?? [])
+      .filter((s) => s.kind === "remove")
+      .map((s) => ({
+        start: s.srcIn,
+        end: s.srcOut,
+        label: label(s),
+        comment: "ossclip suggested cut — review before applying",
+      })),
+    ...keptPauses(production).map((p) => ({
+      start: p.start,
+      end: p.end,
+      label: keptPauseLabel(p),
+      comment: "ossclip detected pause — kept, below the cut bar",
+    })),
+  ].sort((a, b) => a.start - b.start);
+  const markerXml = (indent: string) =>
+    markerItems
+      .map(
+        (m) =>
+          `${indent}<marker>\n` +
+          `${indent}  <name>${esc(m.label)}</name>\n` +
+          `${indent}  <comment>${esc(m.comment)}</comment>\n` +
+          `${indent}  <in>${toFrames(m.start)}</in>\n` +
+          // At least one frame: a zero-length span is as invisible as the
+          // point markers this replaced.
+          `${indent}  <out>${Math.max(toFrames(m.start) + 1, toFrames(m.end))}</out>\n` +
+          `${indent}</marker>`,
+      )
+      .join("\n");
+  const markers = markerXml("    ");
+  const clipMarkers = markerXml("            ");
+  // Both clipitems carry both links (xmeml convention): this is what makes
+  // Premiere treat V1+A1 as ONE linked clip instead of two strangers —
+  // field fix 2: without an audio clipitem at all, the sequence imported
+  // silent and the editor had to add and link the audio by hand.
+  const links = (indent: string) =>
+    !probe.hasAudio
+      ? ""
+      : `${indent}<link>\n` +
+    `${indent}  <linkclipref>ci-1</linkclipref>\n` +
+    `${indent}  <mediatype>video</mediatype>\n` +
+    `${indent}  <trackindex>1</trackindex>\n` +
+    `${indent}  <clipindex>1</clipindex>\n` +
+    `${indent}</link>\n` +
+    `${indent}<link>\n` +
+    `${indent}  <linkclipref>ci-2</linkclipref>\n` +
+    `${indent}  <mediatype>audio</mediatype>\n` +
+    `${indent}  <trackindex>1</trackindex>\n` +
+    `${indent}  <clipindex>1</clipindex>\n` +
+    `${indent}</link>`;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE xmeml>
+<xmeml version="4">
+  <sequence id="ossclip-markers">
+    <name>${name} — ossclip markers</name>
+    <duration>${durFrames}</duration>
+${rateXml("    ")}
+    <timecode>
+${rateXml("      ")}
+      <string>00:00:00:00</string>
+      <frame>0</frame>
+      <displayformat>${ntsc ? "DF" : "NDF"}</displayformat>
+    </timecode>
+    <media>
+      <video>
+        <format>
+          <samplecharacteristics>
+${rateXml("            ")}
+            <width>${probe.width}</width>
+            <height>${probe.height}</height>
+            <anamorphic>FALSE</anamorphic>
+            <pixelaspectratio>square</pixelaspectratio>
+            <fielddominance>none</fielddominance>
+          </samplecharacteristics>
+        </format>
+        <track>
+          <clipitem id="ci-1">
+            <name>${name}</name>
+            <duration>${durFrames}</duration>
+${rateXml("            ")}
+            <start>0</start>
+            <end>${durFrames}</end>
+            <in>0</in>
+            <out>${durFrames}</out>
+            <file id="f-1">
+              <name>${name}</name>
+              <pathurl>${esc(pathToFileURL(path).href)}</pathurl>
+${rateXml("              ")}
+              <duration>${durFrames}</duration>
+              <media>
+                <video>
+                  <samplecharacteristics>
+                    <width>${probe.width}</width>
+                    <height>${probe.height}</height>
+                  </samplecharacteristics>
+                </video>${probe.hasAudio ? "\n                <audio>\n                  <channelcount>2</channelcount>\n                </audio>" : ""}
+              </media>
+            </file>
+${clipMarkers ? `${clipMarkers}\n` : ""}${links("            ")}
+          </clipitem>
+        </track>
+      </video>${
+        probe.hasAudio
+          ? `
+      <audio>
+        <track>
+          <clipitem id="ci-2">
+            <name>${name}</name>
+            <duration>${durFrames}</duration>
+${rateXml("            ")}
+            <start>0</start>
+            <end>${durFrames}</end>
+            <in>0</in>
+            <out>${durFrames}</out>
+            <file id="f-1"/>
+            <sourcetrack>
+              <mediatype>audio</mediatype>
+              <trackindex>1</trackindex>
+            </sourcetrack>
+${links("            ")}
+          </clipitem>
+        </track>
+      </audio>`
+          : ""
+      }
+    </media>
+${markers ? `${markers}\n` : ""}  </sequence>
+</xmeml>
+`;
+}

package/src/index.ts

@@ -27,5 +27,9 @@ export * from "./face";
 export * from "./cover";
 export * from "./source-text";
 export * from "./report";
+export * from "./export-markers";
+export * from "./export-fcpxml";
+export * from "./export-edl";
+export * from "./export-premiere-xml";
 export * from "./config";
 export { run } from "./exec";