premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/set-override-pixel-aspect-ratio.jsx

@@ -0,0 +1,129 @@
+// Command: set-override-pixel-aspect-ratio → ppb_setOverridePixelAspectRatio
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND, ...)
+// are already defined there.
+//
+// Ports the reference project's media.ts set_override_pixel_aspect_ratio
+// tool. Item resolution by nodeId/name uses children-presence recursion
+// (NOT an isBin() gate), per get-project-item-info.jsx's live-debugged
+// finding. previousValue/newValue are read via item.getFootageInterpretation().
+// pixelAspectRatio before/after calling
+// item.setOverridePixelAspectRatio(numerator, denominator). Undo is
+// non-functional on this build — previousValue is the only restoration
+// path.
+
+function ppbSetOverridePAR_findByNodeId(item, nodeId, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.nodeId === nodeId) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbSetOverridePAR_findByNodeId(item.children[i], nodeId, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbSetOverridePAR_findByName(item, name, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.name === name) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbSetOverridePAR_findByName(item.children[i], name, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbSetOverridePAR_readPAR(item) {
+  try {
+    var interp = item.getFootageInterpretation();
+    if (interp) {
+      return interp.pixelAspectRatio;
+    }
+  } catch (e) {
+    // fall through
+  }
+  return null;
+}
+
+function ppb_setOverridePixelAspectRatio(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var hasNodeId = typeof args.nodeId === "string" && args.nodeId.length > 0;
+    var hasName = typeof args.name === "string" && args.name.length > 0;
+    if (!hasNodeId && !hasName) {
+      return JSON.stringify({ ok: false, error: "either nodeId or name is required" });
+    }
+    if (typeof args.numerator !== "number" || args.numerator <= 0) {
+      return JSON.stringify({ ok: false, error: "numerator must be a positive number" });
+    }
+    if (typeof args.denominator !== "number" || args.denominator <= 0) {
+      return JSON.stringify({ ok: false, error: "denominator must be a positive number" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = hasNodeId
+      ? ppbSetOverridePAR_findByNodeId(app.project.rootItem, args.nodeId, 0)
+      : ppbSetOverridePAR_findByName(app.project.rootItem, args.name, 0);
+    if (!item) {
+      return JSON.stringify({ ok: false, error: "no project item found matching the given nodeId/name" });
+    }
+
+    var previousValue = ppbSetOverridePAR_readPAR(item);
+
+    try {
+      item.setOverridePixelAspectRatio(args.numerator, args.denominator);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "setOverridePixelAspectRatio() failed: " + e.toString() });
+    }
+
+    var newValue = ppbSetOverridePAR_readPAR(item);
+    var requestedRatio = args.numerator / args.denominator;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        nodeId: item.nodeId,
+        name: item.name,
+        previousValue: previousValue,
+        requestedNumerator: args.numerator,
+        requestedDenominator: args.denominator,
+        newValue: newValue,
+        verified: newValue !== null && Math.abs(newValue - requestedRatio) < 0.001
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-poster-frame.jsx

@@ -0,0 +1,192 @@
+// Command: set-poster-frame → ppb_setPosterFrame
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Ported from leancoderkavy's premiere-pro-mcp set_poster_frame tool —
+// but that reference implementation is itself an admitted non-starter:
+// it calls item.setOverrideFrameRate(0) "to trigger an internal update"
+// and returns a note saying the real effect "may require UI interaction".
+// No poster-frame API is documented anywhere in PREMIERE_API_NOTES.md
+// (built from three separate MCP repos) — this is genuinely uncertain
+// API territory. This command instead PROBES a short list of plausible
+// method names in turn (none confirmed to exist on any Premiere build we
+// have notes on) rather than repeating the reference's known-fake call.
+//
+// Project-item addressing matches get-item-metadata.jsx (nodeId/name,
+// depth-first bin walk, duplicated locally per this panel's convention).
+//
+// MUTATION RULE / HONESTY NOTE: if a setter call succeeds (doesn't throw),
+// this command tries a short list of plausible GETTER names to read the
+// poster frame back for verification. If none of those exist either
+// (likely, since none of this is confirmed API), the result reports
+// verified: false and says so explicitly — it does NOT claim success
+// just because a call didn't throw, per this wave's mutation rules.
+
+function ppbSetPosterFrame_walk(item, args, depth) {
+  if (depth > 32) {
+    return null;
+  }
+
+  var isBin = false;
+  try {
+    isBin = typeof ProjectItemType !== "undefined" && item.type === ProjectItemType.BIN;
+  } catch (e) {
+    isBin = false;
+  }
+
+  var matched = false;
+  if (args.nodeId !== null) {
+    try { matched = item.nodeId === args.nodeId; } catch (e) { matched = false; }
+  } else if (args.name !== null) {
+    try { matched = item.name === args.name; } catch (e) { matched = false; }
+  }
+  if (matched) {
+    return item;
+  }
+
+  if (isBin && item.children) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbSetPosterFrame_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbSetPosterFrame_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbSetPosterFrame_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppb_setPosterFrame(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var hasNodeId = typeof args.nodeId === "string" && args.nodeId.length > 0;
+    var hasName = typeof args.name === "string" && args.name.length > 0;
+    if (!hasNodeId && !hasName) {
+      return JSON.stringify({ ok: false, error: "either nodeId or name is required" });
+    }
+
+    if (typeof args.seconds !== "number" || isNaN(args.seconds) || args.seconds < 0) {
+      return JSON.stringify({ ok: false, error: "seconds must be a non-negative number" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = ppbSetPosterFrame_resolve({
+      nodeId: hasNodeId ? args.nodeId : null,
+      name: hasNodeId ? null : args.name
+    });
+    if (!item) {
+      return JSON.stringify({ ok: false, error: "no project item found matching the given nodeId/name" });
+    }
+
+    var ticksString = String(Math.round(args.seconds * TICKS_PER_SECOND));
+    var timeObj = null;
+    try {
+      timeObj = new Time();
+      timeObj.seconds = args.seconds;
+    } catch (e) {
+      timeObj = null;
+    }
+
+    // Candidate setter forms — none of these are confirmed to exist on
+    // any Premiere build documented in PREMIERE_API_NOTES.md; probed
+    // defensively in a plausible-to-least-plausible order.
+    var setAttempts = [];
+    var setSucceeded = false;
+    var setMethod = null;
+
+    function trySet(label, fn) {
+      if (setSucceeded) {
+        return;
+      }
+      try {
+        fn();
+        setAttempts.push({ method: label, success: true });
+        setSucceeded = true;
+        setMethod = label;
+      } catch (e) {
+        setAttempts.push({ method: label, success: false, error: e.toString() });
+      }
+    }
+
+    trySet("setPosterFrame(secondsNumber)", function () { item.setPosterFrame(args.seconds); });
+    trySet("setPosterFrame(ticksString)", function () { item.setPosterFrame(ticksString); });
+    trySet("setPosterFrame(TimeObject)", function () { item.setPosterFrame(timeObj); });
+    trySet("setPosterFrameTime(TimeObject)", function () { item.setPosterFrameTime(timeObj); });
+    trySet("setThumbnailFrame(ticksString)", function () { item.setThumbnailFrame(ticksString); });
+
+    if (!setSucceeded) {
+      return JSON.stringify({
+        ok: false,
+        error: "no known poster-frame setter API exists on this Premiere build — every candidate method threw or is undefined",
+        attempts: setAttempts
+      });
+    }
+
+    // Read-back attempt — also unconfirmed API, tried purely so an actual
+    // verification can be reported rather than trusting the setter alone.
+    var readAttempts = [];
+    var verifiedSeconds = null;
+    var verified = false;
+
+    function tryRead(label, fn) {
+      if (verified) {
+        return;
+      }
+      try {
+        var value = fn();
+        readAttempts.push({ method: label, success: true });
+        if (typeof value === "number") {
+          verifiedSeconds = value;
+        } else if (value && typeof value.seconds === "number") {
+          verifiedSeconds = value.seconds;
+        } else if (value && typeof value.ticks !== "undefined") {
+          verifiedSeconds = Number(value.ticks) / TICKS_PER_SECOND;
+        }
+        verified = verifiedSeconds !== null;
+      } catch (e) {
+        readAttempts.push({ method: label, success: false, error: e.toString() });
+      }
+    }
+
+    tryRead("getPosterFrame", function () { return item.getPosterFrame(); });
+    tryRead("getPosterFrameTime", function () { return item.getPosterFrameTime(); });
+    tryRead("posterFrame", function () { return item.posterFrame; });
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        item: (function () { try { return item.name; } catch (e) { return null; } })(),
+        requestedSeconds: args.seconds,
+        setMethod: setMethod,
+        setAttempts: setAttempts,
+        verified: verified,
+        verifiedSeconds: verifiedSeconds,
+        readAttempts: readAttempts,
+        note: verified
+          ? "poster frame set and confirmed via a read-back getter"
+          : "the setter call did not throw, but no known getter API could confirm the change actually took effect — treat this as UNCONFIRMED, not a verified success"
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-project-panel-metadata.jsx

@@ -0,0 +1,69 @@
+// Command: set-project-panel-metadata → ppb_setProjectPanelMetadata
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Write-side counterpart of the existing get-project-panel-metadata.jsx
+// (which reads app.project.getProjectPanelMetadata() as an XML string).
+// Ported from leancoderkavy/premiere-pro-mcp's project.ts
+// set_project_panel_metadata: app.project.setProjectPanelMetadata(xml)
+// REPLACES the Project panel's entire column/metadata configuration —
+// not a merge/patch, same caveat as this repo's existing
+// set-xmp-metadata.jsx for item-level XMP. previousValue/newValue are
+// read via getProjectPanelMetadata() before/after; `verified` is a
+// straightforward string comparison of newValue against the requested
+// XML. Undo is NON-FUNCTIONAL on this build — previousValue is the only
+// restoration path.
+
+function ppb_setProjectPanelMetadata(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (typeof args.metadata !== "string" || args.metadata.length === 0) {
+      return JSON.stringify({ ok: false, error: "metadata (XML string) is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+    if (typeof app.project.setProjectPanelMetadata !== "function") {
+      return JSON.stringify({ ok: false, error: "setProjectPanelMetadata is not available on this Premiere build" });
+    }
+
+    var previousValue = null;
+    if (typeof app.project.getProjectPanelMetadata === "function") {
+      try { previousValue = app.project.getProjectPanelMetadata(); } catch (e) { previousValue = null; }
+    }
+
+    try {
+      app.project.setProjectPanelMetadata(args.metadata);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "setProjectPanelMetadata() failed: " + e.toString() });
+    }
+
+    var newValue = null;
+    if (typeof app.project.getProjectPanelMetadata === "function") {
+      try { newValue = app.project.getProjectPanelMetadata(); } catch (e) { newValue = null; }
+    }
+
+    var verified = typeof newValue === "string" && newValue === args.metadata;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        set: true,
+        requestedValue: args.metadata,
+        previousValue: previousValue,
+        newValue: newValue,
+        verified: verified,
+        note: "REPLACES the entire Project panel column/metadata configuration — not a merge; get-project-panel-metadata first and modify. Undo is NON-FUNCTIONAL on this build — previousValue is the only restoration path."
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-scale-to-frame-size.jsx

@@ -0,0 +1,101 @@
+// Command: set-scale-to-frame-size → ppb_setScaleToFrameSize
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND, ...)
+// are already defined there.
+//
+// Ports the reference project's media.ts set_scale_to_frame_size tool.
+// Item resolution by nodeId/name uses children-presence recursion (NOT an
+// isBin() gate), per get-project-item-info.jsx's live-debugged finding.
+// item.setScaleToFrameSize() has no confirmed getter to read the flag
+// back, so success here only confirms the call didn't throw — same
+// honesty pattern as refresh-media.
+
+function ppbSetScaleToFrameSize_findByNodeId(item, nodeId, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.nodeId === nodeId) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbSetScaleToFrameSize_findByNodeId(item.children[i], nodeId, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbSetScaleToFrameSize_findByName(item, name, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.name === name) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbSetScaleToFrameSize_findByName(item.children[i], name, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppb_setScaleToFrameSize(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var hasNodeId = typeof args.nodeId === "string" && args.nodeId.length > 0;
+    var hasName = typeof args.name === "string" && args.name.length > 0;
+    if (!hasNodeId && !hasName) {
+      return JSON.stringify({ ok: false, error: "either nodeId or name is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = hasNodeId
+      ? ppbSetScaleToFrameSize_findByNodeId(app.project.rootItem, args.nodeId, 0)
+      : ppbSetScaleToFrameSize_findByName(app.project.rootItem, args.name, 0);
+    if (!item) {
+      return JSON.stringify({ ok: false, error: "no project item found matching the given nodeId/name" });
+    }
+
+    try {
+      item.setScaleToFrameSize();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "setScaleToFrameSize() failed: " + e.toString() });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        nodeId: item.nodeId,
+        name: item.name,
+        called: true,
+        note: "setScaleToFrameSize() has no confirmed getter to read the flag back — this only confirms the call didn't throw"
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-scale-width-height.jsx

@@ -0,0 +1,140 @@
+// Command: set-scale-width-height → ppb_setScaleWidthHeight
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// findClipComponent, setComponentProperty, ...) are already defined there.
+//
+// Standard-DOM only — no QE needed. Ported from leancoderkavy's
+// premiere-pro-mcp `set_scale_width_height` tool (track-targeting.ts),
+// addressed here by trackType/trackIndex/clipIndex (same convention as
+// get-full-clip-info) instead of node_id. Sets the Motion component's
+// Scale Width and/or Scale Height properties independently — this ONLY
+// takes effect while Uniform Scale is off. Unlike the reference tool
+// (which silently force-disables Uniform Scale before writing), this
+// command reads Uniform Scale first and fails with an informative error if
+// it's on, so a caller never gets a silent no-op — see set-uniform-scale
+// to turn it off first. Mutating — undo is non-functional on this build,
+// so previousValue in the result is the caller's only restoration path.
+
+function ppb_setScaleWidthHeight(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 hasWidth = typeof args.scaleWidth === "number";
+    var hasHeight = typeof args.scaleHeight === "number";
+    if (!hasWidth && !hasHeight) {
+      return JSON.stringify({ ok: false, error: "at least one of scaleWidth or scaleHeight is required" });
+    }
+
+    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 motion = findClipComponent(clip, ["AE.ADBE Motion"], ["Motion"]);
+    if (!motion) {
+      return JSON.stringify({ ok: false, error: "Motion component not found on clip" });
+    }
+
+    var uniformScaleProp = findComponentProperty(motion, ["Uniform Scale"]);
+    if (!uniformScaleProp) {
+      return JSON.stringify({ ok: false, error: "Uniform Scale property not found on the Motion component — cannot verify it is safe to set Scale Width/Height independently" });
+    }
+    var uniformScaleValue = null;
+    try { uniformScaleValue = uniformScaleProp.getValue(); } catch (e) { uniformScaleValue = null; }
+    if (uniformScaleValue === true || uniformScaleValue === 1) {
+      return JSON.stringify({
+        ok: false,
+        error: "Uniform Scale is currently ON — Scale Width/Scale Height cannot be set independently while it's on. Call set-uniform-scale with uniform:false first."
+      });
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      clipIndex: args.clipIndex,
+      clipName: clipName
+    };
+
+    if (hasWidth) {
+      var widthResult = setComponentProperty(motion, ["Scale Width"], args.scaleWidth);
+      if (!widthResult.found) {
+        return JSON.stringify({ ok: false, error: "Scale Width property not found on the Motion component" });
+      }
+      result.scaleWidth = {
+        previousValue: widthResult.previousValue,
+        requestedValue: widthResult.requestedValue,
+        newValue: widthResult.newValue,
+        verified: widthResult.verified
+      };
+    }
+
+    if (hasHeight) {
+      // Live-discovered 2026-07-17: the Motion component has NO "Scale
+      // Height" property on this build — with Uniform Scale off, the plain
+      // "Scale" property IS the height, and "Scale Width" is the width.
+      var heightResult = setComponentProperty(motion, ["Scale", "Scale Height"], args.scaleHeight);
+      if (!heightResult.found) {
+        return JSON.stringify({ ok: false, error: "Scale (height) property not found on the Motion component" });
+      }
+      result.scaleHeight = {
+        previousValue: heightResult.previousValue,
+        requestedValue: heightResult.requestedValue,
+        newValue: heightResult.newValue,
+        verified: heightResult.verified
+      };
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}