premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/log.py

@@ -0,0 +1,66 @@
+"""Send a log message to the Premiere Bridge CEP panel, if it's open."""
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+
+DEFAULT_PORT = 47823
+VALID_LEVELS = {"info", "warn", "error"}
+
+
+def log(message: str, level: str = "info", source: str | None = None, port: int = DEFAULT_PORT) -> None:
+    """POST a log message to the Premiere Bridge panel's /log endpoint.
+
+    Raises ValueError for an invalid level, ConnectionError if the panel
+    isn't reachable, or RuntimeError if the panel rejects the message.
+    """
+    if level not in VALID_LEVELS:
+        raise ValueError(f"level must be one of {sorted(VALID_LEVELS)}, got {level!r}")
+
+    payload = {"message": message, "level": level}
+    if source:
+        payload["source"] = source
+
+    data = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        f"http://127.0.0.1:{port}/log",
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=2) as response:
+            body = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = json.loads(exc.read().decode("utf-8"))
+        raise RuntimeError(f"panel rejected the log message: {body.get('error', 'unknown error')}") from exc
+    except OSError as exc:
+        raise ConnectionError(
+            f"could not reach the Premiere Bridge panel on port {port} "
+            f"(is the panel open in Premiere Pro?): {exc}"
+        ) from exc
+
+    if not body.get("ok"):
+        raise RuntimeError(f"panel rejected the log message: {body.get('error', 'unknown error')}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Send a log message to the Premiere Bridge CEP panel.")
+    parser.add_argument("message", help="Text to display in the panel's log")
+    parser.add_argument("--level", choices=sorted(VALID_LEVELS), default="info", help="Log level (default: info)")
+    parser.add_argument("--source", default=None, help="Name of the script/tool sending this message")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"Bridge panel port (default: {DEFAULT_PORT})")
+    args = parser.parse_args()
+
+    try:
+        log(args.message, level=args.level, source=args.source, port=args.port)
+    except (ConnectionError, RuntimeError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

premiere_cli/panel/.debug

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ExtensionList>
+  <Extension Id="com.generativegamedev.premierebridge.panel">
+    <HostList>
+      <Host Name="PPRO" Port="8088"/>
+    </HostList>
+  </Extension>
+</ExtensionList>

premiere_cli/panel/CSXS/manifest.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.generativegamedev.premierebridge" ExtensionBundleVersion="1.0.0" ExtensionBundleName="Premiere Bridge">
+  <ExtensionList>
+    <Extension Id="com.generativegamedev.premierebridge.panel" Version="1.0.0" />
+  </ExtensionList>
+  <ExecutionEnvironment>
+    <HostList>
+      <Host Name="PPRO" Version="[14.0,99.9]" />
+    </HostList>
+    <LocaleList>
+      <Locale Code="All" />
+    </LocaleList>
+    <RequiredRuntimeList>
+      <RequiredRuntime Name="CSXS" Version="11.0" />
+    </RequiredRuntimeList>
+  </ExecutionEnvironment>
+  <DispatchInfoList>
+    <Extension Id="com.generativegamedev.premierebridge.panel">
+      <DispatchInfo>
+        <Resources>
+          <MainPath>./index.html</MainPath>
+          <ScriptPath>./host/index.jsx</ScriptPath>
+          <CEFCommandLine>
+            <Parameter>--enable-nodejs</Parameter>
+            <Parameter>--mixed-context</Parameter>
+          </CEFCommandLine>
+        </Resources>
+        <Lifecycle>
+          <AutoVisible>true</AutoVisible>
+        </Lifecycle>
+        <UI>
+          <Type>Panel</Type>
+          <Menu>Premiere Bridge</Menu>
+          <Geometry>
+            <Size>
+              <Height>600</Height>
+              <Width>400</Width>
+            </Size>
+            <MinSize>
+              <Height>200</Height>
+              <Width>300</Width>
+            </MinSize>
+            <MaxSize>
+              <Height>2000</Height>
+              <Width>2000</Width>
+            </MaxSize>
+          </Geometry>
+        </UI>
+      </DispatchInfo>
+    </Extension>
+  </DispatchInfoList>
+</ExtensionManifest>

premiere_cli/panel/css/style.css

@@ -0,0 +1,53 @@
+html, body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  background: #1e1e1e;
+  color: #d4d4d4;
+  font-family: -apple-system, "Segoe UI", sans-serif;
+  font-size: 12px;
+}
+
+#toolbar {
+  padding: 6px 8px;
+  border-bottom: 1px solid #333;
+}
+
+#clear-button {
+  background: #2d2d2d;
+  color: #d4d4d4;
+  border: 1px solid #444;
+  border-radius: 3px;
+  padding: 4px 10px;
+  cursor: pointer;
+}
+
+#clear-button:hover {
+  background: #3a3a3a;
+}
+
+#log-view {
+  height: calc(100% - 37px);
+  overflow-y: auto;
+  padding: 6px 8px;
+  box-sizing: border-box;
+}
+
+.log-line {
+  white-space: pre-wrap;
+  word-break: break-word;
+  padding: 2px 0;
+  font-family: "SF Mono", Menlo, monospace;
+}
+
+.log-info {
+  color: #d4d4d4;
+}
+
+.log-warn {
+  color: #e5c07b;
+}
+
+.log-error {
+  color: #e06c75;
+}

premiere_cli/panel/host/commands/add-adjustment-layer.jsx

@@ -0,0 +1,190 @@
+// Command: add-adjustment-layer → ppb_addAdjustmentLayer
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (ensureQEEnabled,
+// findSequenceByName, TICKS_PER_SECOND, activateSequenceForQE, ...) are
+// already defined there.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's utility.ts
+// add_adjustment_layer, adapted to PREMIERE_API_NOTES.md's PPro 2026
+// finding: the legacy `qeSeq.addAdjustmentLayer(track)` one-call path was
+// REMOVED in Premiere 2026 — this build only has
+// `qe.project.newAdjustmentLayer()`, which creates a project-level
+// adjustment-layer ProjectItem but does NOT place it on the timeline by
+// itself. This command is therefore two independently-verified steps:
+//   1. Create the project item (qe.project.newAdjustmentLayer()) —
+//      verified by a root-bin children-count increase, matching the new
+//      item by name containing "adjustment" (case-insensitive) among the
+//      newly-appeared items (never trusting the call's own return value).
+//   2. Place it on the timeline at startSeconds on the given video track
+//      via qeTrack.insert()/insertClip() — verified by the target track's
+//      QE item count increasing.
+// Either step can succeed independently of the other — both are reported
+// so a caller can tell "item created but not placed" apart from total
+// failure.
+function ppb_addAdjustmentLayer(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var seq = null;
+    if (args.sequenceName && typeof args.sequenceName === "string") {
+      seq = findSequenceByName(args.sequenceName);
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no sequence named \"" + args.sequenceName + "\" is open" });
+      }
+    } else {
+      seq = app.project.activeSequence;
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no active sequence, and no sequenceName given" });
+      }
+    }
+
+    var trackIndex = typeof args.trackIndex === "number" ? args.trackIndex : 0;
+    if (trackIndex >= seq.videoTracks.numTracks) {
+      return JSON.stringify({ ok: false, error: "trackIndex " + trackIndex + " is out of range — sequence has " + seq.videoTracks.numTracks + " video track(s)" });
+    }
+
+    try {
+      ensureQEEnabled();
+      activateSequenceForQE(seq);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.enableQE()/sequence activation failed: " + e.toString() });
+    }
+    if (typeof qe === "undefined" || !qe.project) {
+      return JSON.stringify({ ok: false, error: "QE DOM not available after enableQE()" });
+    }
+    var qeSeq = qe.project.getActiveSequence();
+    if (!qeSeq) {
+      return JSON.stringify({ ok: false, error: "qe.project.getActiveSequence() returned nothing after activating the sequence" });
+    }
+
+    if (typeof qe.project.newAdjustmentLayer !== "function") {
+      return JSON.stringify({ ok: false, error: "qe.project.newAdjustmentLayer() is not available on this Premiere build" });
+    }
+
+    // --- Step 1: create the project item ---
+    var rootChildren = app.project.rootItem.children;
+    var namesBefore = {};
+    for (var b = 0; b < rootChildren.numItems; b++) {
+      var beforeName = null;
+      try { beforeName = rootChildren[b].name; } catch (e) { beforeName = null; }
+      namesBefore[b + ":" + beforeName] = true;
+    }
+    var countBefore = rootChildren.numItems;
+
+    var createError = null;
+    try {
+      qe.project.newAdjustmentLayer();
+    } catch (e) {
+      createError = e.toString();
+    }
+
+    var countAfter = app.project.rootItem.children.numItems;
+    var itemCreated = createError === null && countAfter > countBefore;
+
+    if (!itemCreated) {
+      return JSON.stringify({
+        ok: false,
+        error: createError !== null
+          ? ("qe.project.newAdjustmentLayer() failed: " + createError)
+          : "newAdjustmentLayer() did not throw, but the project's root item count did not increase",
+        countBefore: countBefore,
+        countAfter: countAfter
+      });
+    }
+
+    var adjItem = null;
+    var freshChildren = app.project.rootItem.children;
+    for (var c = freshChildren.numItems - 1; c >= 0; c--) {
+      var it = freshChildren[c];
+      var itName = null;
+      try { itName = it.name; } catch (e) { itName = null; }
+      if (itName && itName.toLowerCase().indexOf("adjustment") !== -1) {
+        adjItem = it;
+        break;
+      }
+    }
+    if (!adjItem) {
+      return JSON.stringify({
+        ok: false,
+        error: "project item count increased after newAdjustmentLayer() but no item with \"adjustment\" in its name could be found",
+        countBefore: countBefore,
+        countAfter: countAfter
+      });
+    }
+
+    // --- Step 2: place it on the timeline ---
+    var startSeconds = typeof args.startSeconds === "number" ? args.startSeconds : 0;
+    var startTicksString = String(Math.round(startSeconds * TICKS_PER_SECOND));
+
+    var qeTrack = null;
+    try {
+      qeTrack = qeSeq.getVideoTrackAt(trackIndex);
+    } catch (e) {
+      qeTrack = null;
+    }
+    if (!qeTrack) {
+      return JSON.stringify({
+        ok: false,
+        error: "QE video track " + trackIndex + " not found — the adjustment-layer project item was created but not placed on the timeline",
+        itemCreated: true,
+        projectItem: { name: adjItem.name, nodeId: adjItem.nodeId }
+      });
+    }
+
+    var placeCountBefore = null;
+    try { placeCountBefore = qeTrack.numItems; } catch (e) { placeCountBefore = null; }
+
+    var placeError = null;
+    var placeAttempts = [];
+    var placed = false;
+    try {
+      qeTrack.insert(adjItem, startTicksString);
+      placeAttempts.push({ form: "qeTrack.insert(item, ticksString)", success: true });
+      placed = true;
+    } catch (e1) {
+      placeAttempts.push({ form: "qeTrack.insert(item, ticksString)", success: false, error: e1.toString() });
+      try {
+        qeTrack.insertClip(adjItem, startTicksString);
+        placeAttempts.push({ form: "qeTrack.insertClip(item, ticksString)", success: true });
+        placed = true;
+      } catch (e2) {
+        placeAttempts.push({ form: "qeTrack.insertClip(item, ticksString)", success: false, error: e2.toString() });
+        placeError = e2.toString();
+      }
+    }
+
+    var placeCountAfter = null;
+    try { placeCountAfter = qeTrack.numItems; } catch (e) { placeCountAfter = null; }
+    var placedVerified = placeCountBefore !== null && placeCountAfter !== null && placeCountAfter > placeCountBefore;
+
+    return JSON.stringify({
+      ok: itemCreated && placedVerified,
+      result: {
+        sequenceName: seq.name,
+        trackIndex: trackIndex,
+        startSeconds: startSeconds,
+        durationSeconds: typeof args.durationSeconds === "number" ? args.durationSeconds : null,
+        itemCreated: itemCreated,
+        projectItem: { name: adjItem.name, nodeId: adjItem.nodeId },
+        placed: placed,
+        placedVerified: placedVerified,
+        placeCountBefore: placeCountBefore,
+        placeCountAfter: placeCountAfter,
+        placeAttempts: placeAttempts,
+        placeError: placedVerified ? null : placeError,
+        note: "durationSeconds is not applied here — no confirmed API trims an inserted QE clip's length directly; use set-item-in-out or trim via the standard DOM after placement if a specific duration is required"
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/add-audio-keyframes.jsx

@@ -0,0 +1,176 @@
+// Command: add-audio-keyframes → ppb_addAudioKeyframes
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// findVolumeLevelProperty, timeValueToSeconds, TICKS_PER_SECOND, ...) are
+// already defined there.
+//
+// Standard-DOM mutation. Ported from leancoderkavy's premiere-pro-mcp
+// `add_audio_keyframes` tool (audio.ts). Per PREMIERE_API_NOTES.md:
+// prop.setTimeVarying(true) is REQUIRED before addKey()/setValueAtKey(),
+// and keyframe times are in SEQUENCE time (not clip-relative) — so each
+// `seconds` value (documented as clip-relative, matching the reference's
+// own "time_seconds ... relative to clip start" description) is offset by
+// the clip's own start time before being converted to ticks.
+//
+// dB->linear conversion uses the SAME hetpatel-calibrated formula as
+// set-clip-volume/adjust-audio-levels (linear = 10^((dB-15)/20)) so dB
+// values are interchangeable across all three audio commands. Unified at
+// integration 2026-07-17 — the reference tool's own code used a raw
+// 10^(db/20), which disagreed with its sibling volume tools. The
+// calibration itself is still UNVERIFIED against this Premiere build.
+function ppb_addAudioKeyframes(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (args.trackType !== "video" && args.trackType !== "audio") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"video\" or \"audio\"" });
+    }
+    if (typeof args.trackIndex !== "number" || args.trackIndex < 0 || Math.floor(args.trackIndex) !== args.trackIndex) {
+      return JSON.stringify({ ok: false, error: "trackIndex must be a non-negative integer" });
+    }
+    if (typeof args.clipIndex !== "number" || args.clipIndex < 0 || Math.floor(args.clipIndex) !== args.clipIndex) {
+      return JSON.stringify({ ok: false, error: "clipIndex must be a non-negative integer" });
+    }
+
+    var keyframes;
+    if (typeof args.keyframes === "string") {
+      try {
+        keyframes = JSON.parse(args.keyframes);
+      } catch (e) {
+        return JSON.stringify({ ok: false, error: "keyframes could not be parsed as JSON: " + e.toString() });
+      }
+    } else {
+      return JSON.stringify({ ok: false, error: "keyframes must be a JSON string of [{seconds, db}, ...]" });
+    }
+    if (!(keyframes && typeof keyframes.length === "number")) {
+      return JSON.stringify({ ok: false, error: "keyframes must decode to a JSON array" });
+    }
+    if (keyframes.length === 0) {
+      return JSON.stringify({ ok: false, error: "keyframes array is empty — at least one keyframe is required" });
+    }
+    for (var v = 0; v < keyframes.length; v++) {
+      var kf = keyframes[v];
+      if (!kf || typeof kf.seconds !== "number" || typeof kf.db !== "number") {
+        return JSON.stringify({ ok: false, error: "keyframes[" + v + "] must be {seconds: number, db: number}" });
+      }
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var seq = null;
+    if (args.sequenceName && typeof args.sequenceName === "string") {
+      seq = findSequenceByName(args.sequenceName);
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no sequence named \"" + args.sequenceName + "\" is open" });
+      }
+    } else {
+      seq = app.project.activeSequence;
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no active sequence, and no sequenceName given" });
+      }
+    }
+
+    var trackCollection = args.trackType === "video" ? seq.videoTracks : seq.audioTracks;
+    var numTracks = trackCollection.numTracks;
+    if (args.trackIndex >= numTracks) {
+      return JSON.stringify({
+        ok: false,
+        error: "trackIndex " + args.trackIndex + " is out of range — sequence has " + numTracks + " " + args.trackType + " track(s)"
+      });
+    }
+
+    var track = trackCollection[args.trackIndex];
+    var numClips = track.clips.numItems;
+    if (args.clipIndex >= numClips) {
+      return JSON.stringify({
+        ok: false,
+        error: "clipIndex " + args.clipIndex + " is out of range — track " + args.trackIndex + " has " + numClips + " clip(s)"
+      });
+    }
+
+    var clip = track.clips[args.clipIndex];
+    var clipName = null;
+    try { clipName = clip.name; } catch (e) { clipName = null; }
+
+    var clipStartSeconds = 0;
+    try { clipStartSeconds = timeValueToSeconds(clip.start) || 0; } catch (e) { clipStartSeconds = 0; }
+
+    var levelProp = findVolumeLevelProperty(clip);
+    if (!levelProp) {
+      return JSON.stringify({ ok: false, error: "could not find Volume/Level property on clip — is this an audio clip?" });
+    }
+
+    var setTimeVaryingError = null;
+    try {
+      levelProp.setTimeVarying(true);
+    } catch (e) {
+      setTimeVaryingError = e.toString();
+    }
+
+    var results = [];
+    var succeeded = 0;
+    for (var i = 0; i < keyframes.length; i++) {
+      var seconds = keyframes[i].seconds;
+      var db = keyframes[i].db;
+      var linear = Math.pow(10, (db - 15) / 20);
+      if (linear < 0.0000001) {
+        linear = 0.0000001;
+      }
+      var sequenceSeconds = clipStartSeconds + seconds;
+      var ticksString = String(Math.round(sequenceSeconds * TICKS_PER_SECOND));
+
+      var entry = { seconds: seconds, db: db, linear: linear, sequenceSeconds: sequenceSeconds, addKeySuccess: false, setValueSuccess: false };
+
+      try {
+        levelProp.addKey(ticksString);
+        entry.addKeySuccess = true;
+      } catch (e1) {
+        entry.addKeyError = e1.toString();
+      }
+
+      try {
+        levelProp.setValueAtKey(ticksString, linear, true);
+        entry.setValueSuccess = true;
+      } catch (e2) {
+        try {
+          levelProp.setValueAtTime(ticksString, linear);
+          entry.setValueSuccess = true;
+          entry.setValueMethod = "setValueAtTime";
+        } catch (e3) {
+          entry.setValueError = e2.toString() + " / " + e3.toString();
+        }
+      }
+
+      if (entry.addKeySuccess && entry.setValueSuccess) {
+        succeeded++;
+      }
+      results.push(entry);
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      clipIndex: args.clipIndex,
+      clipName: clipName,
+      setTimeVaryingError: setTimeVaryingError,
+      keyframesRequested: keyframes.length,
+      keyframesSucceeded: succeeded,
+      keyframes: results,
+      calibrationNote: "dB->linear uses the reference tool's own UNCALIBRATED formula " +
+        "(10^(db/20), floored at 1e-7) — a DIFFERENT formula from set-clip-volume.jsx's " +
+        "hetpatel-calibrated one. Neither has been verified against this Premiere build."
+    };
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/add-custom-metadata-field.jsx

@@ -0,0 +1,63 @@
+// Command: add-custom-metadata-field → ppb_addCustomMetadataField
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's project.ts
+// add_custom_metadata_field. Calls app.project.
+// addPropertyToProjectMetadataSchema(name, label, type) per
+// PREMIERE_API_NOTES.md's Markers/metadata/misc section. `type` is a raw
+// int enum per the reference tool: 0 = Integer, 1 = Real, 2 = String,
+// 3 = Boolean.
+//
+// NOTE (per this task's brief): this is PROJECT-WIDE schema mutation, not
+// a per-item field — it adds a new column to every item's metadata in
+// this project, and is NOT removable from script (no
+// removePropertyFromProjectMetadataSchema-equivalent exists in any
+// reference repo studied). There is no reliable read-back API for the
+// metadata schema itself (get-project-panel-metadata reads the Project
+// panel's column *display* configuration, not the schema), so
+// verification here is call-level only (the call didn't throw) —
+// documented honestly rather than a fabricated "verified" flag.
+
+function ppb_addCustomMetadataField(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (!args.name || typeof args.name !== "string") {
+      return JSON.stringify({ ok: false, error: "name is required" });
+    }
+    var label = (typeof args.label === "string" && args.label.length > 0) ? args.label : args.name;
+    var type = typeof args.type === "number" ? args.type : 2; // default: String
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+    if (typeof app.project.addPropertyToProjectMetadataSchema !== "function") {
+      return JSON.stringify({ ok: false, error: "addPropertyToProjectMetadataSchema is not available on this Premiere build" });
+    }
+
+    try {
+      app.project.addPropertyToProjectMetadataSchema(args.name, label, type);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "addPropertyToProjectMetadataSchema() failed: " + e.toString() });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        added: true,
+        name: args.name,
+        label: label,
+        type: type,
+        note: "project-wide metadata schema change — this field is added to every item's metadata in this project and cannot be removed from script (no reference repo we studied has a removal API); verification here is call-level only, no read-back API exists for the schema itself"
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}