davinci-resolve-mcp 2.58.0 → 2.59.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.59.0
+
+First-class conform ingest for **AAF** and **DRP**, an offline **Premiere `.prproj`** reader with
+a conform bridge, and a unified sequence enumerator — so an editorial turnover in any of these
+formats can be previewed, picked, and brought into Resolve. Everything keeps the honest-refuse
+philosophy: no format is ever faked; an unreadable file yields a clear, actionable error.
+
+### Added
+
+- **AAF** — offline preview via the advanced server's `editorial.parse_interchange` (format `aaf`)
+  and `list_sequences`, backed by the pure-Python `aaf2` (pyaaf2) reader (shelled out from Node;
+  honest-refuses with an install/convert hint when unavailable). Live AAF import now works through
+  `timeline.import_timeline_checked` — the XML sanitize pass is skipped for the binary format and,
+  when `relink_search_roots` is passed, a post-import media-pool relink runs (fuzzy-relink parity
+  via `RelinkClips`), reported in a `relink` block.
+- **DRP** — `drt.list_sequences` enumerates the timelines inside a `.drp`/`.drt`
+  (`[{id, name, eventCount}]`) to drive a picker; `timeline.import_from_drp` extracts the chosen
+  timelines (offline zip surgery → temp `.drt`) and imports each into a running Resolve.
+- **Premiere `.prproj`** — a from-scratch offline reader (gunzip + object-reference-graph walk, no
+  new dependencies) exposed through `parse_interchange` / `list_sequences`. Derives cuts, source
+  in/out, timeline positions, speed/retime, reverse, transitions, markers, and media paths. Effects
+  and Lumetri color are not translated (the Premiere→Resolve semantic gap, flagged not faked).
+- **Conform bridge** — `editorial.convert_to_interchange` authors OTIO / EDL / DRT that Resolve
+  imports, from normalized events or a parsed source. This lets a `.prproj` be conformed into
+  Resolve with no Premiere in the loop.
+- **Unified enumeration** — `editorial.list_sequences(path)` is one picker entry point across
+  xml/edl/otio/drt/drp/aaf/prproj.
+
+### Dependencies
+
+- New optional-but-default `requirements.txt` pins `pyaaf2` (pure-Python, MIT, ~1 MB) for the
+  offline AAF reader; the installer points the advanced server's `AAF_PROBE_PYTHON` at the project
+  venv so it works out of the box. Without it, AAF preview honest-refuses; nothing else needs it.
+
+### Validation
+
+- Static checks, drift guards, and focused unit tests pass (advanced Node suite 455 pass / 9 skip;
+  new `test_import_from_drp.py` and `prproj-bridge.test.mjs` / `aaf-sequences.test.mjs`). Offline
+  AAF parse validated end-to-end against a real `aaf2`-authored AAF.
+- **Not yet live-validated in Resolve**: AAF import, the post-import relink, `import_from_drp`, and
+  importing an authored OTIO/DRT from a real `.prproj`. These paths are offline-tested (fake Resolve)
+  and guarded; confirm against a live session with disposable projects before relying on them.
+
 ## What's New in v2.58.0
 
 Major expansion of the optional **advanced** Node server (`davinci-resolve-advanced-mcp`,

package/README.md

@@ -1,9 +1,10 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.58.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.59.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)
+[![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
@@ -171,7 +172,8 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **32** compound / **341** granular |
+| MCP Tools | **34** compound / **341** granular (live server) |
+| Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **336/336** (100%) |
 | Methods Live Tested | **331/336** (98.5%) |
@@ -234,12 +236,3 @@ Samuel Gursky (samgursky@gmail.com)
 
 - Blackmagic Design for DaVinci Resolve and its scripting API
 - The Model Context Protocol team for enabling AI assistant integration
-- Anthropic for Claude Code, used extensively in development and testing
-
-### Community contributions
-
-- [@rgxdev](https://github.com/rgxdev) — configurable Media Pool inventory walk
-  (exclude bins + inventory limit), [#69](https://github.com/samuelgursky/davinci-resolve-mcp/pull/69) (v2.53.0)
-- [@swayll](https://github.com/swayll) — Source Track Selector investigation
-  ([#74](https://github.com/samuelgursky/davinci-resolve-mcp/issues/74)); confirmed
-  + documented API limitation (v2.57.1)

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.58.0"
+VERSION = "2.59.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -666,17 +666,25 @@ def write_client_config(client, python_path, server_path, api_path, lib_path, dr
     return True, str(config_path)
 
 
-def build_advanced_entry(server_path):
+def build_advanced_entry(server_path, python_path=None):
     """Build the config entry for the optional 'davinci-resolve-advanced' server.
 
     This is the Node, beyond-the-scripting-API sibling (file/.drp/.drt/.drx
     authoring + conform + editorial, no live Resolve required). It ships in the
     same package as a second bin. Opt-in: include it only if you want the
     file-level tools alongside the live server.
+
+    The Node server shells out to Python for the OFFLINE AAF reader (aaf_probe.py,
+    pyaaf2). We pin AAF_PROBE_PYTHON to the project venv's interpreter — the same
+    venv install.py installs pyaaf2 into — so AAF preview works out of the box
+    instead of depending on whatever `python3` happens to be on PATH.
     """
     project_dir = Path(server_path).resolve().parents[1]  # .../src/server.py -> repo root
     advanced_bin = project_dir / "bin" / "davinci-resolve-advanced-mcp.mjs"
-    return {"command": "node", "args": [str(advanced_bin)]}
+    entry = {"command": "node", "args": [str(advanced_bin)]}
+    if python_path:
+        entry["env"] = {"AAF_PROBE_PYTHON": str(python_path)}
+    return entry
 
 
 def generate_manual_config(python_path, server_path, api_path, lib_path):
@@ -684,7 +692,7 @@ def generate_manual_config(python_path, server_path, api_path, lib_path):
     entry = build_server_entry(python_path, server_path, api_path, lib_path)
     zed_entry = build_zed_entry(python_path, server_path, api_path, lib_path)
     opencode_entry = build_opencode_entry(python_path, server_path, api_path, lib_path)
-    advanced = build_advanced_entry(server_path)
+    advanced = build_advanced_entry(server_path, python_path)
 
     # Standard snippet includes BOTH servers: the live Python server and the
     # optional Node 'advanced' server (file-level, no Resolve). Drop the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.58.0",
+  "version": "2.59.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/README.md

@@ -91,7 +91,11 @@ Each dispatches on an `action`. Highlights:
 - **`media`** — media front-end / AE: `ingest_verify` (hash seal/verify/dupes-by-hash), `media_inventory`
   (fps/codec/colorspace/TC + card gaps), `sync` (TC picture↔sound + drift/MOS), `relink_manifest`,
   `rename_plan` (refuses camera originals) / `reel_normalize`, `turnover_package`, `project_hygiene`.
-- **`editorial`** — editorial integrity: `parse_interchange` (EDL/OTIO/XMEML; AAF = honest refuse),
+- **`editorial`** — editorial integrity: `parse_interchange` (EDL/OTIO/XMEML natively, AAF via pyaaf2,
+  **.prproj via gunzip+XML** — pass the file PATH for the binary ones), `list_sequences` (one picker entry
+  point across xml/edl/otio/drt/drp/aaf/prproj), `convert_to_interchange` (author OTIO/EDL/DRT that Resolve
+  imports, from events or a parsed source — **the .prproj→Resolve conform bridge**, no Premiere needed;
+  editorial timing/cuts/transitions/speed carry, per-clip effects/color do not),
   `turnover_changelist` (moved/retimed/replaced/new/gone + timing silent-lie guards), `conform_manifest`,
   `marker_roundtrip`.
 - **`provenance`** — provenance / audit: `gallery_lineage`, `grade_provenance` ("why is this graded this
@@ -161,6 +165,7 @@ status + install hints):
 | grading/QC catalog, `conform.verify` (frame compare) | `sharp` (optional) | native module; `npm i sharp` |
 | `pipeline` (project DB), `fairlight` live-DB path, conform lineage/reverse | `better-sqlite3` (optional) | native module; `npm i better-sqlite3`. (The `.drp`-zip Fairlight path needs none.) |
 | YAML authoring (`pipeline compile` from a YAML dir) | `js-yaml` (optional) | pure JS; `npm i js-yaml` |
+| `editorial` AAF offline preview (`parse_interchange` format `aaf`, `list_sequences` on `.aaf`) | **Python 3 + `pyaaf2`** | AAF is binary; no trustworthy pure-JS reader. The server shells out to `aaf_probe.py` (pure-Python `aaf2`). `pip install pyaaf2`. Without it, AAF **honest-refuses** with a convert-upstream hint (EDL/OTIO/`.drt` need nothing). Live AAF import is on the Python `davinci-resolve` MCP (Resolve reads AAF natively). |
 
 Missing features fail with a clear, actionable message rather than crashing; the server logs a one-line
 "needs setup" summary to stderr at startup.

package/resolve-advanced/server/aaf.mjs

@@ -0,0 +1,104 @@
+/**
+ * AAF (.aaf) offline reader — the honest bridge for `parse_interchange` / `list_sequences`.
+ *
+ * AAF is a binary Structured-Storage container; no pure-JS reader is trustworthy, so we shell
+ * out to `aaf_probe.py` (pure-Python `aaf2`/pyaaf2). This keeps the honest-refuse philosophy:
+ *   - real parse when pyaaf2 is available,
+ *   - a CLEAR, actionable error otherwise (never a fake/empty parse).
+ *
+ * The live import path does NOT use this — Resolve reads AAF natively via
+ * timeline.import_timeline_checked. This is only for the offline picker+preview.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const PROBE = fileURLToPath(new URL('./aaf_probe.py', import.meta.url));
+
+/** python interpreter — overridable for environments/tests (must have `aaf2` importable). */
+function pythonCmd() {
+  return process.env.AAF_PROBE_PYTHON || process.env.PYTHON || 'python3';
+}
+
+const REMEDIATION =
+  'Install the offline AAF reader (`pip install pyaaf2`) to preview AAF without Resolve, ' +
+  'OR convert to OTIO/EDL/FCP7-XML upstream, OR import it live via timeline.import_timeline_checked ' +
+  '(Resolve reads AAF natively).';
+
+function runProbe(aafPath) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(pythonCmd(), [PROBE, aafPath]);
+    } catch (e) {
+      reject(new Error(`AAF offline preview needs Python + pyaaf2, but Python could not start (${e.message}). ${REMEDIATION}`));
+      return;
+    }
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', (e) => {
+      // ENOENT etc. — python not found.
+      reject(new Error(`AAF offline preview needs Python + pyaaf2, but '${pythonCmd()}' could not start (${e.message}). ${REMEDIATION}`));
+    });
+    child.on('close', (code) => {
+      if (code === 0) {
+        try {
+          resolve(JSON.parse(out));
+        } catch (e) {
+          reject(new Error(`AAF probe returned unreadable output: ${e.message}`));
+        }
+        return;
+      }
+      if (code === 3 || /AAF_PROBE_NO_PYAAF2/.test(err)) {
+        reject(new Error(`AAF offline preview needs the pure-Python 'aaf2' package (pyaaf2), which is not installed. ${REMEDIATION}`));
+        return;
+      }
+      if (code === 4 || /AAF_PROBE_UNREADABLE/.test(err)) {
+        const detail = (err.match(/AAF_PROBE_UNREADABLE:\s*(.*)/) || [, err.trim()])[1];
+        reject(new Error(`AAF could not be read: ${detail || 'unreadable or not a valid AAF file'}.`));
+        return;
+      }
+      reject(new Error(`AAF probe failed (exit ${code}): ${err.trim() || 'unknown error'}. ${REMEDIATION}`));
+    });
+  });
+}
+
+/** Resolve the AAF path from the tool's `content`/`path` arg (AAF is binary — must be a path). */
+export function resolveAafPath(contentOrPath) {
+  const p = typeof contentOrPath === 'string' ? contentOrPath.trim() : '';
+  if (!p) {
+    throw new Error('AAF is a binary format — pass the .aaf file PATH as `content` (or `path`), not inline bytes/text.');
+  }
+  if (!existsSync(p)) {
+    throw new Error(`AAF path does not exist: ${p}`);
+  }
+  return path.resolve(p);
+}
+
+/**
+ * Parse an AAF into a FLAT normalized-event list (mirrors parseEDL/parseOTIO/parseXMEML output),
+ * concatenating every top-level sequence. Use listAafSequences() when you need per-sequence split.
+ * @param {string} contentOrPath absolute .aaf path
+ * @returns {Promise<Array>} normalized events
+ */
+export async function parseAAF(contentOrPath) {
+  const aafPath = resolveAafPath(contentOrPath);
+  const { sequences } = await runProbe(aafPath);
+  const events = [];
+  for (const seq of sequences || []) for (const ev of seq.events || []) events.push(ev);
+  return events;
+}
+
+/**
+ * Enumerate the sequences inside an AAF for the picker.
+ * @param {string} contentOrPath absolute .aaf path
+ * @returns {Promise<Array<{id:string,name:string,eventCount:number}>>}
+ */
+export async function listAafSequences(contentOrPath) {
+  const aafPath = resolveAafPath(contentOrPath);
+  const { sequences } = await runProbe(aafPath);
+  return (sequences || []).map((s) => ({ id: String(s.id), name: String(s.name), eventCount: Number(s.eventCount || 0) }));
+}

package/resolve-advanced/server/author-interchange.mjs

@@ -0,0 +1,152 @@
+/**
+ * Author an interchange (OTIO / EDL / DRT) FROM a normalized-event list — the write-side of the
+ * conform bridge. Its purpose: turn a parsed turnover (esp. .prproj, which Resolve can't import
+ * natively) into a format Resolve DOES import, WITHOUT round-tripping through Premiere.
+ *
+ * OTIO is the default target: it carries gaps, per-clip speed (LinearTimeWarp) and transitions, and
+ * round-trips through this repo's own parseOTIO. EDL is CMX3600 (cuts + M2 speed). DRT is authored
+ * via the vendored buildDRT (Resolve-native). Editorial timing/structure survives with high
+ * fidelity; per-clip effects/color do NOT (the Premiere→Resolve semantic gap, flagged not faked).
+ */
+import { drt } from './libs.mjs';
+
+const pad = (n, w = 2) => String(Math.max(0, Math.floor(n))).padStart(w, '0');
+
+/** frames → CMX timecode at fps (non-drop). */
+export function framesToTc(frames, fps) {
+  const f = Math.max(0, Math.round(Number(frames) || 0));
+  const r = Math.max(1, Math.round(fps || 24));
+  const ff = f % r;
+  const s = Math.floor(f / r);
+  return `${pad(Math.floor(s / 3600))}:${pad(Math.floor((s % 3600) / 60))}:${pad(s % 60)}:${pad(ff)}`;
+}
+
+const byTrack = (events) => {
+  const groups = { V: [], A: [] };
+  for (const e of events) groups[e.track === 'A' ? 'A' : 'V'].push(e);
+  for (const k of Object.keys(groups)) groups[k].sort((a, b) => (a.recIn ?? 0) - (b.recIn ?? 0));
+  return groups;
+};
+
+/**
+ * Build an OTIO timeline doc (plain object) from normalized events. Inserts gaps so record
+ * positions are exact; emits LinearTimeWarp for speed/reverse and Transition items where present.
+ */
+export function eventsToOTIO(events, opts = {}) {
+  const fps = opts.fps || events.find((e) => e.fps)?.fps || 24;
+  const groups = byTrack(events);
+  const tracks = [];
+  for (const [kind, list] of [
+    ['Video', groups.V],
+    ['Audio', groups.A],
+  ]) {
+    if (!list.length) continue;
+    const children = [];
+    let rec = 0;
+    for (const e of list) {
+      const recIn = e.recIn ?? rec;
+      if (recIn > rec) {
+        children.push({
+          OTIO_SCHEMA: 'Gap.1',
+          source_range: { OTIO_SCHEMA: 'TimeRange.1', duration: { OTIO_SCHEMA: 'RationalTime.1', value: recIn - rec, rate: fps } },
+        });
+        rec = recIn;
+      }
+      const recDur = (e.recOut ?? recIn) - recIn;
+      const clip = {
+        OTIO_SCHEMA: 'Clip.1',
+        name: e.source || 'UNKNOWN',
+        source_range: {
+          OTIO_SCHEMA: 'TimeRange.1',
+          start_time: { OTIO_SCHEMA: 'RationalTime.1', value: e.srcIn ?? 0, rate: e.fps || fps },
+          duration: { OTIO_SCHEMA: 'RationalTime.1', value: recDur, rate: e.fps || fps },
+        },
+        media_reference: { OTIO_SCHEMA: 'ExternalReference.1', target_url: e.source || '' },
+        effects: [],
+        markers: [],
+      };
+      if ((e.speed ?? 100) !== 100 || e.reverse) {
+        clip.effects.push({ OTIO_SCHEMA: 'LinearTimeWarp.1', name: 'Speed', time_scalar: (e.reverse ? -1 : 1) * ((e.speed ?? 100) / 100) });
+      }
+      if (e.transition) {
+        children.push({
+          OTIO_SCHEMA: 'Transition.1',
+          transition_type: 'SMPTE_Dissolve',
+          in_offset: { OTIO_SCHEMA: 'RationalTime.1', value: Math.ceil((e.transition.duration || 0) / 2), rate: fps },
+          out_offset: { OTIO_SCHEMA: 'RationalTime.1', value: Math.floor((e.transition.duration || 0) / 2), rate: fps },
+        });
+      }
+      children.push(clip);
+      rec = recIn + recDur;
+    }
+    tracks.push({ OTIO_SCHEMA: 'Track.1', name: `${kind[0]}1`, kind, children });
+  }
+  return { OTIO_SCHEMA: 'Timeline.1', name: opts.name || 'Conformed', tracks: { OTIO_SCHEMA: 'Stack.1', name: 'tracks', children: tracks } };
+}
+
+/** Build a CMX3600 EDL string (cuts + M2 speed). Video events only, per EDL convention. */
+export function eventsToEDL(events, opts = {}) {
+  const fps = opts.fps || events.find((e) => e.fps)?.fps || 24;
+  const vids = events.filter((e) => e.track !== 'A').sort((a, b) => (a.recIn ?? 0) - (b.recIn ?? 0));
+  const lines = [`TITLE: ${opts.name || 'CONFORMED'}`, 'FCM: NON-DROP FRAME'];
+  vids.forEach((e, i) => {
+    const num = pad(i + 1, 3);
+    const reel =
+      String(e.source || 'AX')
+        .replace(/\.[^.]+$/, '')
+        .replace(/[^A-Za-z0-9]/g, '')
+        .slice(0, 8)
+        .toUpperCase() || 'AX';
+    lines.push(
+      `${num}  ${reel} V     C        ${framesToTc(e.srcIn, fps)} ${framesToTc(e.srcOut, fps)} ${framesToTc(e.recIn, fps)} ${framesToTc(e.recOut, fps)}`,
+    );
+    if ((e.speed ?? 100) !== 100 || e.reverse) {
+      const play = (e.reverse ? -1 : 1) * (fps * ((e.speed ?? 100) / 100));
+      lines.push(`M2   ${reel}       ${play.toFixed(1)}             ${framesToTc(e.srcIn, fps)}`);
+    }
+  });
+  return lines.join('\n') + '\n';
+}
+
+/** Build a buildDRT spec (Resolve-native .drt) from normalized events. */
+export function eventsToDrtSpec(events, opts = {}) {
+  const fps = opts.fps || events.find((e) => e.fps)?.fps || 24;
+  const groups = byTrack(events);
+  const mkTrack = (list) => ({
+    clips: list.map((e) => ({ start: e.recIn ?? 0, duration: (e.recOut ?? 0) - (e.recIn ?? 0), in: e.srcIn ?? 0, mediaFilePath: e.source || '' })),
+  });
+  return {
+    timelines: [
+      {
+        name: opts.name || 'Conformed',
+        frameRate: fps,
+        startTimecode: opts.startTimecode || '01:00:00:00',
+        resolution: opts.resolution || '1920x1080',
+        videoTracks: groups.V.length ? [mkTrack(groups.V)] : [],
+        audioTracks: groups.A.length ? [mkTrack(groups.A)] : [],
+      },
+    ],
+    metadata: { source: 'author-interchange', ...(opts.metadata || {}) },
+  };
+}
+
+/**
+ * Author `events` into `target` interchange. Returns { target, content?, spec?, bytes? }.
+ * For 'drt', when outputPath is given the .drt bytes are written; otherwise the spec is returned.
+ */
+export async function authorInterchange(events, target, opts = {}) {
+  const t = String(target || 'otio').toLowerCase();
+  if (t === 'otio') {
+    const doc = eventsToOTIO(events, opts);
+    return { target: 'otio', content: JSON.stringify(doc, null, 2), doc };
+  }
+  if (t === 'edl') {
+    return { target: 'edl', content: eventsToEDL(events, opts) };
+  }
+  if (t === 'drt') {
+    const spec = eventsToDrtSpec(events, opts);
+    const buf = await drt().buildDRT(spec);
+    return { target: 'drt', spec, buffer: buf, bytes: buf.length };
+  }
+  throw new Error(`authorInterchange: unknown target '${target}' (otio|edl|drt)`);
+}

package/resolve-advanced/server/editorial.mjs

@@ -10,9 +10,11 @@
  * timing analogue of a faked grade.
  *
  * Interchange breadth AT INGEST: EDL (CMX3600) + OTIO (JSON) parse natively here; XMEML via a
- * light clipitem parse. AAF is binary — honest refuse (convert to OTIO/EDL upstream).
+ * light clipitem parse. AAF is binary — parsed offline via aaf.mjs → pyaaf2 (async, out-of-band);
+ * parseInterchange() itself stays PURE and points AAF callers at that async path. Premiere .prproj
+ * is a closed binary project — honest refuse with an actionable convert-upstream message.
  *
- * PURE + deterministic. No Resolve, no LLM.
+ * PURE + deterministic (edl/otio/xmeml). No Resolve, no LLM.
  */
 import { createRequire } from 'node:module';
 
@@ -193,7 +195,11 @@ export function parseXMEMLEvents(xml, opts = {}) {
   return events;
 }
 
-/** Dispatch by format. AAF is an honest refuse (binary — convert to OTIO/EDL upstream). */
+/**
+ * Dispatch by format (SYNC, pure over TEXT). Binary formats are handled out-of-band by their own
+ * path-based readers — AAF via aaf.mjs `parseAAF` (async, pyaaf2), .prproj via prproj.mjs
+ * `parsePrproj` (gunzip+XML). This throws to route callers there rather than faking a parse.
+ */
 export function parseInterchange(format, content, opts = {}) {
   switch (String(format).toLowerCase()) {
     case 'edl':
@@ -205,9 +211,15 @@ export function parseInterchange(format, content, opts = {}) {
     case 'fcp7':
       return parseXMEMLEvents(content, opts);
     case 'aaf':
-      throw new Error('parse_interchange: AAF is binary — not parseable offline in pure JS. Convert to OTIO or EDL upstream (e.g. via OpenTimelineIO).');
+      throw new Error(
+        'parse_interchange: AAF is binary — parse it via the async AAF path (aaf.mjs `parseAAF`, backed by pyaaf2), not the sync parseInterchange().',
+      );
+    case 'prproj':
+      throw new Error(
+        'parse_interchange: .prproj is gzip-compressed XML — parse it via the path-based reader (prproj.mjs `parsePrproj`), not the sync parseInterchange().',
+      );
     default:
-      throw new Error(`parse_interchange: unknown format '${format}' (edl|otio|xml|aaf)`);
+      throw new Error(`parse_interchange: unknown format '${format}' (edl|otio|xml|xmeml|fcp7|aaf|prproj)`);
   }
 }