playrig 0.0.0-stage → 0.1.0

package/editions/pr/organize.default.json

@@ -0,0 +1,245 @@
+{
+  "version": 1,
+  "name": "Dan Mace scheme",
+  "help": [
+    "bins: the structure. 'path' uses / for sub-bins. 'meaning' is documentation for people. 'create: true' = the Organize button creates it when missing.",
+    "archive: bin for things added but not used. Items are only moved there on request, never deleted.",
+    "protect: bins whose contents are never moved by organizing (the archive is a deliberate decision).",
+    "rules: checked in order, the first match wins. 'when' can have: kind (sequence | media | generated), name (regex on the item name),",
+    "       path (regex on the media file path, case-insensitive), ext (list of file extensions without the dot). 'bin' = destination, 'skip: true' = leave alone.",
+    "       Items no rule matches are reported as 'needs a decision' and not moved.",
+    "auto-filing (after every job) only files NEW loose items at the project root; the Organize button also corrects items in the wrong scheme bin."
+  ],
+  "archive": "99_ARCHIVE",
+  "protect": [
+    "99_ARCHIVE"
+  ],
+  "bins": [
+    {
+      "path": "1_MASTER",
+      "create": true,
+      "meaning": "The deliverables (what gets exported). Several allowed, one per format. Name them 'MASTER - Title (Format)'."
+    },
+    {
+      "path": "2_FOOTAGE/IMAGES",
+      "create": true,
+      "meaning": "Stills to insert somewhere."
+    },
+    {
+      "path": "2_FOOTAGE/RAW",
+      "create": true,
+      "meaning": "Camera recordings and other raw source video."
+    },
+    {
+      "path": "2_FOOTAGE/RENDERS",
+      "create": true,
+      "meaning": "Video rendered elsewhere (e.g. After Effects renders) and used as source."
+    },
+    {
+      "path": "2_FOOTAGE/GRADED",
+      "create": true,
+      "meaning": "Graded versions of the raw footage."
+    },
+    {
+      "path": "3_SELECTS",
+      "create": true,
+      "meaning": "Sequences that are scenes / parts of the video, later merged into the master. Name them 'SEL nn - <scene>'."
+    },
+    {
+      "path": "4_INTERVIEW",
+      "create": false,
+      "meaning": "Only for podcast / interview projects. Set create to true to use it."
+    },
+    {
+      "path": "5_SOUND",
+      "create": true,
+      "meaning": "Voiceovers, recorded audio, sound effects."
+    },
+    {
+      "path": "6_MUSIC",
+      "create": true,
+      "meaning": "Music (non-diegetic)."
+    },
+    {
+      "path": "7_LAYERS",
+      "create": true,
+      "meaning": "Adjustment layers, mattes and other generated layers."
+    },
+    {
+      "path": "99_ARCHIVE",
+      "create": true,
+      "meaning": "Things added but not used in the project."
+    }
+  ],
+  "rules": [
+    {
+      "when": {
+        "kind": "sequence",
+        "name": " Copy( \\d+)?$"
+      },
+      "skip": true,
+      "note": "scratch clones"
+    },
+    {
+      "when": {
+        "kind": "sequence",
+        "name": "^Sequence Template$"
+      },
+      "skip": true,
+      "note": "the template for new sequences"
+    },
+    {
+      "when": {
+        "kind": "sequence",
+        "name": "^MASTER\\b"
+      },
+      "bin": "1_MASTER"
+    },
+    {
+      "when": {
+        "kind": "sequence",
+        "name": "^SEL\\b"
+      },
+      "bin": "3_SELECTS"
+    },
+    {
+      "when": {
+        "kind": "generated"
+      },
+      "bin": "7_LAYERS",
+      "note": "items with no media file: adjustment layers, mattes, bars"
+    },
+    {
+      "when": {
+        "kind": "media",
+        "ext": [
+          "mp4",
+          "mov",
+          "mxf",
+          "m4v",
+          "avi",
+          "mkv",
+          "r3d",
+          "braw",
+          "webm",
+          "mts"
+        ],
+        "path": "/graded/"
+      },
+      "bin": "2_FOOTAGE/GRADED"
+    },
+    {
+      "when": {
+        "kind": "media",
+        "ext": [
+          "mp4",
+          "mov",
+          "mxf",
+          "m4v",
+          "avi",
+          "mkv",
+          "r3d",
+          "braw",
+          "webm",
+          "mts"
+        ],
+        "name": "^V\\d+-\\d+_"
+      },
+      "bin": "2_FOOTAGE/GRADED",
+      "note": "DaVinci Resolve render names"
+    },
+    {
+      "when": {
+        "kind": "media",
+        "ext": [
+          "mp4",
+          "mov",
+          "mxf",
+          "m4v",
+          "avi",
+          "mkv",
+          "r3d",
+          "braw",
+          "webm",
+          "mts"
+        ],
+        "path": "/(ae_motion|renders?|ae_renders?)/"
+      },
+      "bin": "2_FOOTAGE/RENDERS"
+    },
+    {
+      "when": {
+        "kind": "media",
+        "ext": [
+          "mp4",
+          "mov",
+          "mxf",
+          "m4v",
+          "avi",
+          "mkv",
+          "r3d",
+          "braw",
+          "webm",
+          "mts"
+        ]
+      },
+      "bin": "2_FOOTAGE/RAW"
+    },
+    {
+      "when": {
+        "kind": "media",
+        "ext": [
+          "png",
+          "jpg",
+          "jpeg",
+          "tif",
+          "tiff",
+          "psd",
+          "ai",
+          "gif",
+          "bmp",
+          "exr",
+          "dpx",
+          "heic",
+          "webp",
+          "svg"
+        ]
+      },
+      "bin": "2_FOOTAGE/IMAGES"
+    },
+    {
+      "when": {
+        "kind": "media",
+        "ext": [
+          "wav",
+          "mp3",
+          "aif",
+          "aiff",
+          "m4a",
+          "flac",
+          "aac",
+          "ogg"
+        ],
+        "path": "/(\\d+_)?music/"
+      },
+      "bin": "6_MUSIC",
+      "note": "audio from a music folder"
+    },
+    {
+      "when": {
+        "kind": "media",
+        "ext": [
+          "wav",
+          "mp3",
+          "aif",
+          "aiff",
+          "m4a",
+          "flac",
+          "aac",
+          "ogg"
+        ]
+      },
+      "bin": "5_SOUND"
+    }
+  ]
+}

package/editions/pr/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "playrig-pr",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Playrig for Premiere Pro: the UXP panel and skills. Versioned on its own (tags pr-v*).",
+  "license": "SEE LICENSE IN LICENSE"
+}

package/editions/pr/plugin/actions.js

@@ -0,0 +1,79 @@
+// The defined set of ACTIONS a bridge job can be. This is what the "Action" column of the jobs table shows, so a person can tell at a glance
+// what happened to the project. Each job has exactly one action id.
+//
+// How a job gets its action:
+//   1. It declares one: a header line in the job script `// @action score.place`, or `aeb run ... --action score.place`.
+//   2. Otherwise the panel infers it from what the script does (see inferAction); old jobs are classified the same way when listed.
+//   3. If nothing fits it is "custom" (Custom action). Prefer declaring an action; add a new entry here when a new kind of job appears.
+// Labels and summaries are display text only: renaming one here renames it for every past and future job.
+
+const ACTIONS = {
+  "bridge.test":       { label: "Playrig test",                   summary: "Checked that Playrig can run a job. No project changes." },
+  "project.inspect":   { label: "Inspect project",               summary: "Read sequences, tracks, clips or bins. No project changes." },
+  "frame.export":      { label: "Export frames",                 summary: "Exported still frames from a sequence." },
+  "media.import":      { label: "Import media",                  summary: "Imported files into the project." },
+  "sequence.clone":    { label: "Duplicate sequence",            summary: "Made a copy of a sequence." },
+  "sequence.rename":   { label: "Rename sequence",               summary: "Renamed a sequence or bin." },
+  "sequence.delete":   { label: "Delete sequence",               summary: "Removed a sequence from the project." },
+  "clip.place":        { label: "Place clips",                   summary: "Added clips to a sequence." },
+  "clip.edit":         { label: "Edit clips",                    summary: "Moved, trimmed or removed clips on the timeline." },
+  "score.place":       { label: "Add music and sound effects",   summary: "Imported and placed music and sound effects on a sequence." },
+  "score.sync":        { label: "Re-time sound effects",         summary: "Moved, swapped or removed bridge-owned sound clips to match a new timing." },
+  "audio.level":       { label: "Adjust audio levels",           summary: "Changed clip volume or its automation." },
+  "audio.effect":      { label: "Add audio effect",              summary: "Added an audio effect (such as reverb) to a clip." },
+  "organize.project":  { label: "Organize project",              summary: "Created bins and filed items into the project's bin structure." },
+  "organize.archive":  { label: "Archive unused items",          summary: "Moved unused items into the archive bin." },
+  "organize.structure":{ label: "Update organization structure", summary: "Wrote or changed the project's bin structure file." },
+  "scratch.baseline":  { label: "Check test items",              summary: "Recorded or listed the temporary items created while experimenting. No project changes." },
+  "scratch.cleanup":   { label: "Clean up test items",           summary: "Removed temporary sequences and items created while experimenting." },
+  "job.rejected":      { label: "Rejected job",                  summary: "The job was refused before it ran." },
+  "custom":            { label: "Custom action",                 summary: "A job with no declared action." }
+};
+
+const actionInfo = (id) => ACTIONS[id] || ACTIONS.custom;
+
+// First `// ...` lines of a job script: `// @action <id>` declares the action; the first other comment line is the description.
+function parseJobHeader(src) {
+  const out = { action: null, description: null };
+  for (const line of String(src || "").split(/\r\n|\r|\n/).slice(0, 10)) {
+    const m = /^\s*\/\/\s?(.*)$/.exec(line);
+    if (!m) { if (line.trim()) break; else continue; }
+    const t = m[1].trim(), a = /^@action\s+([A-Za-z0-9_.-]+)/.exec(t);
+    if (a) out.action = a[1]; else if (t && !out.description) out.description = t.slice(0, 240);
+  }
+  return out;
+}
+
+// Best guess from what the script calls. Order matters: the first rule that matches wins. Unknown declared ids are treated as "custom".
+function inferAction(src, id) {
+  let s = String(src || "");
+  if (/^scratch-clean/i.test(String(id || ""))) return "scratch.cleanup";
+  if (/^scratch-(start|status)/i.test(String(id || ""))) return "scratch.baseline";
+  // jobs that inline the organizer library mention every API name in it: judge only the part after the library
+  const lib = s.lastIndexOf("return { organizeScan");
+  if (lib >= 0) { const end = s.indexOf("\n}", lib); if (end >= 0) s = s.slice(end + 2); }
+  const rules = [
+    [/deleteSequence/, "sequence.delete"],
+    [/createCloneAction/, "sequence.clone"],
+    [/writeStructure/, "organize.structure"],
+    [/moveItem\([^)]*99_ARCHIVE|99_ARCHIVE[^\n]*moveItem\(/, "organize.archive"],
+    [/organizeProject|fileStrays|createBinAction|createMoveItemAction|ensureBin|moveItem\(/, "organize.project"],
+    [/importFiles|importInto/, null],
+    [/(?:PLAYRIG|PLAYPILOT|BRIDGE)\.sync\(|(?:PLAYRIG|PLAYPILOT|BRIDGE)\.adopt\(/, "score.sync"],
+    [/AudioFilterFactory|createAppendComponentAction/, "audio.effect"],
+    [/levelKeys|setLevelDb|createAddKeyframeAction|createSetTimeVaryingAction/, "audio.level"],
+    [/createOverwriteItemAction|(?:PLAYRIG|PLAYPILOT|BRIDGE)\.place\(/, "clip.place"],
+    [/createSetNameAction/, "sequence.rename"],
+    [/createMoveAction|createSetInPointAction|createSetOutPointAction|createSetEndAction|createRemoveItemsAction|(?:PLAYRIG|PLAYPILOT|BRIDGE)\.remove\(/, "clip.edit"],
+    [/(?:PLAYRIG|PLAYPILOT|BRIDGE)\.inspect|getSequences\(|getTrackItems|getVideoTrack|getAudioTrack|getRootItem/, "project.inspect"],
+    [/hi from Premiere|(?:PLAYRIG|PLAYPILOT|BRIDGE)\.log\(["']hi/, "bridge.test"],
+    [/lstat|readdir|openPath|getMedia\(\)/, "project.inspect"]
+  ];
+  for (const [re, act, also] of rules) {
+    if (!re.test(s)) continue;
+    if (also && !also.test(s)) continue;
+    if (act === null) return /createOverwriteItemAction|(?:PLAYRIG|PLAYPILOT|BRIDGE)\.place\(/.test(s) ? "score.place" : "media.import";
+    return act;
+  }
+  return "custom";
+}

package/editions/pr/plugin/dev.js

@@ -0,0 +1,19 @@
+// DEV ONLY. Developer-facing extras for the panel. This whole file (and its <script> line in index.html) is left out of packaged builds:
+// index.js checks `typeof DEV !== "undefined"` before using anything here, so removing the file removes these features without other changes.
+// Currently: the "Job script" section in the job detail window (the source of the job as it was run, for debugging jobs).
+
+const DEV = {
+  // Called by openJobDetail() with { body, el, job, ws, readText }; appends dev-only sections to the detail window.
+  async jobDetail({ body, el, job, ws, readText }) {
+    if (!ws) return;
+    let script = null;
+    try { script = await readText(ws + "/jobs/" + job.id + ".js"); } catch (e) { }
+    if (script) {
+      const lines = script.split(/\r\n|\r|\n/);
+      body.appendChild(el("div", "jd-h", "Job script (dev only, " + lines.length + " lines)"));
+      body.appendChild(el("div", "jd-pre", lines.slice(0, 60).join("\n") + (lines.length > 60 ? "\n... " + (lines.length - 60) + " more lines in jobs/" + job.id + ".js" : "")));
+    }
+    body.appendChild(el("div", "jd-h", "Script file (dev only)"));
+    body.appendChild(el("div", "jd-pre", ws + "/jobs/" + job.id + ".js"));
+  }
+};

package/editions/pr/plugin/icons/README.md

@@ -0,0 +1,4 @@
+Icons are from Tabler Icons (https://tabler.io/icons), MIT License, (c) 2020-2024 Pawel Kuna. Outline set v3.34.1.
+Every path carries its own fill="none" and stroke attributes: the UXP SVG renderer ignores the ones Tabler puts on the root <svg> and fills shapes black. The stroke colour is baked in too (currentColor does not resolve in an image).
+Settings uses stroke-width 1; the power icon is power-off.svg (gray) and power-on.svg (green, stroke #3fb950), swapped by the panel.
+To add an icon: curl https://cdn.jsdelivr.net/npm/@tabler/icons@3.34.1/icons/outline/<name>.svg, then move fill="none", stroke, stroke-width, stroke-linecap and stroke-linejoin onto every <path> and drop the 24x24 bounding-box path.

package/editions/pr/plugin/icons/file-code.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M14 3v4a1 1 0 0 0 1 1h4" fill="none" stroke="#c8c8c8" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M17 21h-10a2 2 0 0 1 -2 -2v-14a2 2 0 0 1 2 -2h7l5 5v11a2 2 0 0 1 -2 2z" fill="none" stroke="#c8c8c8" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M10 13l-1 2l1 2" fill="none" stroke="#c8c8c8" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M14 13l1 2l-1 2" fill="none" stroke="#c8c8c8" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/folder.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M5 4h4l3 3h7a2 2 0 0 1 2 2v8a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2v-11a2 2 0 0 1 2 -2" fill="none" stroke="#c8c8c8" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/power-off.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M7 6a7.75 7.75 0 1 0 10 0" fill="none" stroke="#8c8c8c" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M12 4l0 8" fill="none" stroke="#8c8c8c" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/power-on.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M7 6a7.75 7.75 0 1 0 10 0" fill="none" stroke="#3fb950" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M12 4l0 8" fill="none" stroke="#3fb950" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/settings.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M10.325 4.317c.426 -1.756 2.924 -1.756 3.35 0a1.724 1.724 0 0 0 2.573 1.066c1.543 -.94 3.31 .826 2.37 2.37a1.724 1.724 0 0 0 1.065 2.572c1.756 .426 1.756 2.924 0 3.35a1.724 1.724 0 0 0 -1.066 2.573c.94 1.543 -.826 3.31 -2.37 2.37a1.724 1.724 0 0 0 -2.572 1.065c-.426 1.756 -2.924 1.756 -3.35 0a1.724 1.724 0 0 0 -2.573 -1.066c-1.543 .94 -3.31 -.826 -2.37 -2.37a1.724 1.724 0 0 0 -1.065 -2.572c-1.756 -.426 -1.756 -2.924 0 -3.35a1.724 1.724 0 0 0 1.066 -2.573c-.94 -1.543 .826 -3.31 2.37 -2.37c1 .608 2.296 .07 2.572 -1.065z" fill="none" stroke="#c8c8c8" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M9 12a3 3 0 1 0 6 0a3 3 0 0 0 -6 0" fill="none" stroke="#c8c8c8" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/status-error.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M12 12m-9 0a9 9 0 1 0 18 0a9 9 0 1 0 -18 0" fill="none" stroke="#f85149" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M10 10l4 4m0 -4l-4 4" fill="none" stroke="#f85149" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/status-ok.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M12 12m-9 0a9 9 0 1 0 18 0a9 9 0 1 0 -18 0" fill="none" stroke="#3fb950" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M9 12l2 2l4 -4" fill="none" stroke="#3fb950" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/status-rejected.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M12 12m-9 0a9 9 0 1 0 18 0a9 9 0 1 0 -18 0" fill="none" stroke="#f0883e" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M5.7 5.7l12.6 12.6" fill="none" stroke="#f0883e" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/status-timeout.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M3 12a9 9 0 1 0 18 0a9 9 0 0 0 -18 0" fill="none" stroke="#e3b341" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M12 7v5l3 3" fill="none" stroke="#e3b341" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/icons/status-unknown.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M3 12a9 9 0 1 0 18 0a9 9 0 0 0 -18 0" fill="none" stroke="#8c8c8c" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M12 16v.01" fill="none" stroke="#8c8c8c" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M12 13a2 2 0 0 0 .914 -3.782a1.98 1.98 0 0 0 -2.414 .483" fill="none" stroke="#8c8c8c" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/editions/pr/plugin/incremental.js

@@ -0,0 +1,212 @@
+// Incremental editing helpers for jobs (PLAYRIG.owned / sync / adopt / remove / place / levelKeys ...).
+// Premiere counterpart of the the AE edition's "--replace": the bridge tags the clips it creates, and a re-run changes only
+// those clips, in place (move / swap / add / remove), instead of deleting a track or sequence and rebuilding it.
+//
+// Ownership tag = a suffix on the clip NAME:  "pop_glass_ui_lv.wav [pb:sfx:chip3]"  ->  family "sfx", key "chip3".
+// (Premiere track items have no comment field; the name follows the clip when it is moved or trimmed.)
+// Everything here needs the premierepro module and the open project; it never touches clips without a tag.
+
+function makeIncremental(ppro, project, B) {
+  const TAG_RE = /\s*\[pb:([A-Za-z0-9_-]+):([A-Za-z0-9_-]+)\]\s*$/;
+  const SNAP = 0.05;                       // seconds; Premiere snaps placements to frames (1 frame at 24 fps = 0.042 s)
+  const UNITY = 0.17782799899578094;       // Volume > Level value for 0 dB on Premiere's scale
+  const tk = (s) => ppro.TickTime.createWithSeconds(s);
+  const sec = (t) => Math.round(t.seconds * 1000) / 1000;
+  const ID_RE = /^[A-Za-z0-9_-]{1,32}$/;
+
+  const tagOf = (family, key) => {
+    if (!ID_RE.test(family) || !ID_RE.test(key)) throw new Error("BRIDGE tag: family and key must match ^[A-Za-z0-9_-]{1,32}$ (got '" + family + "', '" + key + "')");
+    return "[pb:" + family + ":" + key + "]";
+  };
+  const parse = (name) => { const m = TAG_RE.exec(name || ""); return m ? { family: m[1], key: m[2], base: String(name).replace(TAG_RE, "") } : null; };
+  const trackCount = async (seq, kind) => (kind === "video" ? seq.getVideoTrackCount() : seq.getAudioTrackCount());
+  const getTrack = async (seq, kind, i) => (kind === "video" ? seq.getVideoTrack(i) : seq.getAudioTrack(i));
+
+  // Every clip on every track as { kind, track, clip, name, start, end, tag } (tag = parsed ownership or null).
+  async function clips(seq) {
+    const out = [];
+    for (const kind of ["video", "audio"]) {
+      const n = await trackCount(seq, kind);
+      for (let i = 0; i < n; i++) {
+        for (const clip of await (await getTrack(seq, kind, i)).getTrackItems(1, false)) {
+          const name = await clip.getName();
+          out.push({ kind, track: i, clip, name, start: sec(await clip.getStartTime()), end: sec(await clip.getEndTime()), tag: parse(name) });
+        }
+      }
+    }
+    return out;
+  }
+
+  // Clips this bridge owns in `seq`, optionally only one family.
+  async function owned(seq, family) {
+    return (await clips(seq)).filter((c) => c.tag && (!family || c.tag.family === family))
+      .map((c) => ({ kind: c.kind, track: c.track, clip: c.clip, family: c.tag.family, key: c.tag.key, base: c.tag.base, start: c.start, end: c.end }));
+  }
+
+  async function rename(clip, name) {
+    await B.transact("Playrig: tag " + name, (ca) => { ca.addAction(clip.createSetNameAction(name)); });
+  }
+
+  // Tag an existing clip (adopt it) or re-tag an owned one.
+  async function tag(clip, family, key) {
+    const p = parse(await clip.getName());
+    const base = p ? p.base : await clip.getName();
+    await rename(clip, base + " " + tagOf(family, key));
+  }
+  async function untag(clip) {
+    const p = parse(await clip.getName());
+    if (p) await rename(clip, p.base);
+  }
+
+  // Tag untagged clips that match `select(info)` as family/key; key = keyOf(info, indexInMatch) (default family + order).
+  // Use once to bring clips placed by hand or by an earlier job under management.
+  async function adopt(seq, family, select, keyOf) {
+    const hits = (await clips(seq)).filter((c) => !c.tag && select(c)).sort((a, b) => a.start - b.start);
+    const keys = [];
+    for (let i = 0; i < hits.length; i++) {
+      const key = keyOf ? keyOf(hits[i], i) : family + (i + 1);
+      await tag(hits[i].clip, family, key);
+      keys.push(key + "@" + hits[i].start);
+    }
+    return keys;
+  }
+
+  // Remove clips (items from owned()/clips()) without rippling; gaps stay where they were.
+  async function remove(seq, items) {
+    if (!items.length) return 0;
+    const ed = ppro.SequenceEditor.getEditor(seq);
+    await B.transact("Playrig: remove " + items.length + " owned clip(s)", (ca) => {
+      ppro.TrackItemSelection.createEmptySelection((sel) => {
+        for (const it of items) sel.addItem(it.clip, true);
+        ca.addAction(ed.createRemoveItemsAction(sel, false, ppro.Constants.MediaType.ANY, false));
+      });
+    });
+    return items.length;
+  }
+
+  // Source length of a project item in seconds, or null when Premiere will not say (still images, sequences).
+  async function lenOf(item) {
+    try { const m = await ppro.ClipProjectItem.cast(item).getMedia(); const d = await m.getDuration(); return d && d.seconds !== undefined ? d.seconds : null; }
+    catch (e) { return null; }
+  }
+  // Overlaps among ranges [{label, kind, track, start, end}] on the same track (touching ends are fine; frame snapping gets 20 ms slack).
+  function overlaps(ranges) {
+    const out = [], by = {};
+    for (const r of ranges) (by[r.kind + r.track] = by[r.kind + r.track] || []).push(r);
+    for (const k in by) {
+      const rs = by[k].sort((a, b) => a.start - b.start);
+      for (let i = 1; i < rs.length; i++) if (rs[i].start < rs[i - 1].end - 0.02) out.push(rs[i - 1].label + " (" + rs[i - 1].start + "-" + rs[i - 1].end + ") overlaps " + rs[i].label + " (" + rs[i].start + "-" + rs[i].end + ") on " + rs[i].kind + " " + (rs[i].track + 1));
+    }
+    return out;
+  }
+
+  // Place project item at `start` s and tag it. opts: { kind:'audio'|'video', track:0, audioTrack:0 (for video items with audio), family, key }
+  // Premiere overwrites whatever is there; clips this would overwrite that are not ours are listed in the result.
+  async function place(seq, item, start, opts) {
+    const kind = opts.kind || "audio", track = opts.track || 0, tag_ = tagOf(opts.family, opts.key);
+    const ed = ppro.SequenceEditor.getEditor(seq);
+    const vIdx = kind === "video" ? track : 0, aIdx = kind === "audio" ? track : (opts.audioTrack || 0);
+    const before = (await clips(seq)).filter((c) => c.kind === kind && c.track === track);
+    if (!opts.allowOverwrite) {
+      const len = await lenOf(item);
+      const hit = len === null ? [] : before.filter((c) => c.start < start + len - 0.02 && c.end > start + 0.02);
+      if (hit.length) throw new Error("PLAYRIG.place: would overwrite " + hit.map((c) => c.name + " (" + c.start + "-" + c.end + ")").join(", ") + " on " + kind + " " + (track + 1) + "; free the space, use another track, or pass allowOverwrite:true");
+    }
+    await B.transact("Playrig: place " + tag_, (ca) => { ca.addAction(ed.createOverwriteItemAction(item, tk(start), vIdx, aIdx)); });
+    const itemId = String(await item.getId());
+    const after = (await clips(seq)).filter((c) => c.kind === kind && c.track === track);
+    const known = new Set(before.map((c) => c.start + "|" + c.end + "|" + c.name));
+    let fresh = null, bestD = 1e9;
+    for (const c of after) {
+      if (c.tag || known.has(c.start + "|" + c.end + "|" + c.name)) continue;
+      const d = Math.abs(c.start - start);
+      if (d <= SNAP && d < bestD && String(await (await c.clip.getProjectItem()).getId()) === itemId) { fresh = c; bestD = d; }
+    }
+    if (!fresh) throw new Error("PLAYRIG.place: could not find the clip just placed at " + start + " s on " + kind + " " + (track + 1));
+    await rename(fresh.clip, fresh.name + " " + tag_);
+    return { start: fresh.start, end: fresh.end, kind, track };
+  }
+
+  // Desired-state sync for one family of clips. desired = [{ key, item, start, kind?, track?, audioTrack? }].
+  //  - same key, same source, same track, start within a frame -> unchanged
+  //  - same key, start differs                                 -> moved in place (no delete)
+  //  - same key, different source or track                     -> replaced (old removed, new placed at the new spot)
+  //  - key not owned yet                                       -> placed + tagged
+  //  - owned key not in desired                                -> removed
+  // opts.dryRun returns the plan without changing anything. Running the same call twice is a no-op.
+  async function sync(seq, family, desired, opts) {
+    opts = opts || {};
+    const seen = {};
+    for (const d of desired) { tagOf(family, d.key); if (seen[d.key]) throw new Error("PLAYRIG.sync: duplicate key '" + d.key + "'"); seen[d.key] = 1; }
+    const have = {};
+    for (const o of await owned(seq, family)) have[o.key] = o;
+    const plan = { unchanged: [], moved: [], replaced: [], placed: [], removed: [] };
+    const moves = [], swaps = [], adds = [];
+    for (const d of desired) {
+      const kind = d.kind || "audio", track = d.track || 0, o = have[d.key];
+      delete have[d.key];
+      if (!o) { adds.push(d); plan.placed.push(d.key + " @ " + d.start); continue; }
+      const sameItem = String(await (await o.clip.getProjectItem()).getId()) === String(await d.item.getId());
+      if (!sameItem || o.kind !== kind || o.track !== track) { swaps.push({ o, d }); plan.replaced.push(d.key + " -> " + d.start); }
+      else if (Math.abs(o.start - d.start) > SNAP) { moves.push({ o, d, delta: d.start - o.start }); plan.moved.push(d.key + ": " + o.start + " -> " + d.start); }
+      else plan.unchanged.push(d.key);
+    }
+    const extras = Object.keys(have).map((k) => have[k]);
+    for (const e of extras) plan.removed.push(e.key + " @ " + e.start);
+    // Final layout check, before anything changes: nothing may end up overwriting another clip.
+    {
+      const gone = new Set(extras.concat(swaps.map((s) => s.o)).map((o) => o.clip));
+      const moved = new Map(moves.map((m) => [m.o.clip, m.d.start]));
+      const final = [];
+      for (const c of await clips(seq)) {
+        if (gone.has(c.clip)) continue;
+        const st = moved.has(c.clip) ? moved.get(c.clip) : c.start;
+        final.push({ label: c.name, kind: c.kind, track: c.track, start: st, end: st + (c.end - c.start) });
+      }
+      for (const x of swaps.map((s) => s.d).concat(adds)) {
+        const len = await lenOf(x.item);
+        if (len === null) { plan.unchecked = (plan.unchecked || []).concat(x.key + " (length unknown)"); continue; }
+        final.push({ label: "new " + x.key, kind: x.kind || "audio", track: x.track || 0, start: x.start, end: x.start + len });
+      }
+      plan.collisions = overlaps(final);
+    }
+    if (opts.dryRun) return plan;
+    if (plan.collisions.length) throw new Error("PLAYRIG.sync refused, nothing was changed:\n  " + plan.collisions.join("\n  "));
+    // 1. remove what is gone or about to be swapped, 2. move (away from the direction of travel first so clips never land on each other), 3. place.
+    await remove(seq, extras.concat(swaps.map((s) => s.o)));
+    const pos = moves.filter((m) => m.delta > 0).sort((a, b) => b.o.start - a.o.start), neg = moves.filter((m) => m.delta < 0).sort((a, b) => a.o.start - b.o.start);
+    for (const m of pos.concat(neg)) await B.transact("Playrig: move " + m.d.key, (ca) => { ca.addAction(m.o.clip.createMoveAction(tk(m.delta))); });
+    for (const x of swaps.map((s) => s.d).concat(adds)) await place(seq, x.item, x.start, { kind: x.kind || "audio", track: x.track || 0, audioTrack: x.audioTrack, family, key: x.key, allowOverwrite: true });
+    return plan;
+  }
+
+  // ---- audio level helpers. Premiere's scale: 0 dB = 0.1778. Keyframe times are SOURCE time (clip in-point based), not timeline time.
+  const dbToLevel = (db) => UNITY * Math.pow(10, db / 20);
+  const levelToDb = (v) => 20 * Math.log10(v / UNITY);
+  async function levelParam(clip) { return (await clip.getComponentChain()).getComponentAtIndex(0).getParam(1); }
+
+  // Static level, replacing any keyframes.
+  async function setLevelDb(clip, db) {
+    const lv = await levelParam(clip);
+    await clearKeys(lv);
+    await B.transact("Playrig: level " + db + " dB", (ca) => { ca.addAction(lv.createSetValueAction(lv.createKeyframe(dbToLevel(db)))); });
+  }
+  async function clearKeys(lv) {
+    const keys = await lv.getKeyframeListAsTickTimes();
+    if (!keys.length && !(await lv.isTimeVarying())) return;
+    await B.transact("Playrig: clear level keys", (ca) => { for (const k of keys) ca.addAction(lv.createRemoveKeyframeAction(k)); ca.addAction(lv.createSetTimeVaryingAction(false)); });
+  }
+  // Level automation as absolute state: points = [[timelineSeconds, dB], ...]; existing keys are removed first, so re-running is safe.
+  async function levelKeys(clip, points) {
+    const lv = await levelParam(clip);
+    const shift = (await clip.getInPoint()).seconds - (await clip.getStartTime()).seconds;     // source time = timeline time + shift
+    await clearKeys(lv);
+    await B.transact("Playrig: level keys", (ca) => {
+      ca.addAction(lv.createSetTimeVaryingAction(true));
+      for (const p of points) { const k = lv.createKeyframe(dbToLevel(p[1])); k.position = tk(p[0] + shift); ca.addAction(lv.createAddKeyframeAction(k)); }
+    });
+    return points.length;
+  }
+
+  return { tag, untag, tagOf, clips, owned, adopt, remove, place, sync, lenOf, dbToLevel, levelToDb, setLevelDb, levelKeys };
+}