premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/set-track-visibility.jsx

@@ -0,0 +1,94 @@
+// Command: set-track-visibility → ppb_setTrackVisibility
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ...) are already defined there.
+//
+// Video-only. Ported from leancoderkavy's premiere-pro-mcp
+// `toggle_track_visibility` tool (tracks.ts) — renamed here from "toggle"
+// to an explicit "set" (visible: bool) for idempotence, matching this
+// panel's other set-* commands.
+//
+// IMPORTANT API caveat: there is no standard-DOM API for a video track's
+// "eye icon" visibility distinct from its mute flag — the reference
+// project's toggle_track_visibility tool itself calls track.setMute() on a
+// video track to implement "visibility" (visible=false -> setMute(1)).
+// That is what this command does too: it is NOT a separate visibility
+// property, it is track.setMute() applied to a video track, with the
+// boolean sense inverted (visible = !muted). Read back via isMuted() as
+// the verification proof, translated back to "visible" in the result.
+function ppb_setTrackVisibility(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.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.visible !== "boolean") {
+      return JSON.stringify({ ok: false, error: "visible must be a boolean" });
+    }
+
+    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 numTracks = seq.videoTracks.numTracks;
+    if (args.trackIndex >= numTracks) {
+      return JSON.stringify({
+        ok: false,
+        error: "trackIndex " + args.trackIndex + " is out of range — sequence has " + numTracks + " video track(s)"
+      });
+    }
+
+    var track = seq.videoTracks[args.trackIndex];
+
+    try {
+      track.setMute(args.visible ? 0 : 1);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "track.setMute() failed: " + e.toString() });
+    }
+
+    var isMutedNow = null;
+    try {
+      isMutedNow = track.isMuted();
+    } catch (e) {
+      isMutedNow = null;
+    }
+    var isVisibleNow = isMutedNow === null ? null : !isMutedNow;
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: "video",
+      trackIndex: args.trackIndex,
+      trackName: null,
+      requestedVisible: args.visible,
+      visible: isVisibleNow
+    };
+    try { result.trackName = track.name; } catch (e) { result.trackName = null; }
+
+    if (isVisibleNow !== null && isVisibleNow !== args.visible) {
+      result.warning = "read-back visibility (" + isVisibleNow + ") did not match requested (" + args.visible + ") — mutation may not have taken effect";
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-transcode-on-ingest.jsx

@@ -0,0 +1,78 @@
+// Command: set-transcode-on-ingest → ppb_setTranscodeOnIngest
+// 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
+// set_transcode_on_ingest, which calls
+// app.project.setEnableTranscodeOnIngest(0|1) — an API not mentioned
+// anywhere in PREMIERE_API_NOTES.md (none of the three studied repos'
+// other tools touch it either), so its presence on this Premiere build
+// is genuinely unconfirmed. Probes for the method before calling and
+// fails honestly if absent, rather than assuming it exists. No known
+// getter exists to read the setting back (getEnableTranscodeOnIngest is
+// not documented or referenced anywhere either) — probed defensively the
+// same way, and if present is used for a best-effort read-back;
+// otherwise verification is call-level only.
+
+function ppb_setTranscodeOnIngest(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.enabled !== "boolean") {
+      return JSON.stringify({ ok: false, error: "enabled (true or false) is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+    if (typeof app.project.setEnableTranscodeOnIngest !== "function") {
+      return JSON.stringify({
+        ok: false,
+        error: "setEnableTranscodeOnIngest is not available on this Premiere build — this API is unconfirmed outside the reference tool it was ported from"
+      });
+    }
+
+    var hasGetter = typeof app.project.getEnableTranscodeOnIngest === "function";
+    var before = null;
+    if (hasGetter) {
+      try { before = app.project.getEnableTranscodeOnIngest(); } catch (e) { before = null; }
+    }
+
+    try {
+      app.project.setEnableTranscodeOnIngest(args.enabled ? 1 : 0);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "setEnableTranscodeOnIngest() failed: " + e.toString() });
+    }
+
+    var after = null;
+    if (hasGetter) {
+      try { after = app.project.getEnableTranscodeOnIngest(); } catch (e) { after = null; }
+    }
+
+    var verified = null;
+    var note = null;
+    if (hasGetter && after !== null) {
+      verified = !!after === args.enabled;
+    } else {
+      note = "no read-back getter is available/confirmed on this build — verification is call-level only (setEnableTranscodeOnIngest() did not throw)";
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        set: true,
+        transcodeOnIngest: args.enabled,
+        previousValue: hasGetter ? before : null,
+        verified: verified,
+        note: note
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-uniform-scale.jsx

@@ -0,0 +1,104 @@
+// Command: set-uniform-scale → ppb_setUniformScale
+// 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_uniform_scale` 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
+// Uniform Scale property — a boolean-like 0/1 toggle that links (true) or
+// unlinks (false) Scale Width/Scale Height; see set-scale-width-height,
+// which requires this to be off. Mutating — undo is non-functional on this
+// build, so previousValue in the result is the caller's only restoration
+// path.
+
+function ppb_setUniformScale(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" });
+    }
+    if (typeof args.uniform !== "boolean") {
+      return JSON.stringify({ ok: false, error: "uniform must be a boolean" });
+    }
+
+    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 setResult = setComponentProperty(motion, ["Uniform Scale"], args.uniform);
+    if (!setResult.found) {
+      return JSON.stringify({ ok: false, error: "Uniform Scale property not found on the Motion component" });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: args.trackType,
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        clipName: clipName,
+        previousValue: setResult.previousValue,
+        requestedValue: setResult.requestedValue,
+        newValue: setResult.newValue,
+        verified: setResult.verified
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-work-area.jsx

@@ -0,0 +1,76 @@
+// Command: set-work-area → ppb_setWorkArea
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND,
+// findSequenceByName, ...) are already defined there.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's playhead.ts set_work_area.
+// Sets the given (or active) sequence's work area bar bounds via
+// seq.setWorkAreaInPoint()/setWorkAreaOutPoint(), each taking a ticks
+// string per PREMIERE_API_NOTES.md's "Work area" row.
+function ppb_setWorkArea(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.startSeconds !== "number" || isNaN(args.startSeconds) ||
+        typeof args.endSeconds !== "number" || isNaN(args.endSeconds)) {
+      return JSON.stringify({ ok: false, error: "startSeconds and endSeconds (numbers) are both 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 startTicks = String(Math.round(args.startSeconds * TICKS_PER_SECOND));
+    var endTicks = String(Math.round(args.endSeconds * TICKS_PER_SECOND));
+
+    try {
+      seq.setWorkAreaInPoint(startTicks);
+      seq.setWorkAreaOutPoint(endTicks);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "could not set work area: " + e.toString() });
+    }
+
+    // Read the values back rather than echoing the inputs — live testing
+    // 2026-07-17 showed the setters "succeed" (no throw) on Premiere 2026
+    // while the work-area reads stay null (the work area bar appears to
+    // have been dropped on this build, consistent with
+    // isWorkAreaBarEnabled() not existing). readBack lets callers detect
+    // that the set didn't actually take effect.
+    var readBackIn = null;
+    var readBackOut = null;
+    try { readBackIn = timeValueToSeconds(seq.workInPoint); } catch (e) { readBackIn = null; }
+    try { readBackOut = timeValueToSeconds(seq.workOutPoint); } catch (e) { readBackOut = null; }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        startSeconds: args.startSeconds,
+        endSeconds: args.endSeconds,
+        readBackInSeconds: readBackIn,
+        readBackOutSeconds: readBackOut,
+        applied: readBackIn !== null && readBackOut !== null
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-workspace.jsx

@@ -0,0 +1,35 @@
+// Command: set-workspace → ppb_setWorkspace
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's workspace.ts set_workspace.
+// App-level — no project or sequence involved.
+function ppb_setWorkspace(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.name !== "string" || args.name.length === 0) {
+      return JSON.stringify({ ok: false, error: "name (string) is required" });
+    }
+
+    var result = null;
+    try {
+      result = app.setWorkspace(args.name);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "failed to set workspace \"" + args.name + "\": " + e.toString() });
+    }
+
+    if (!result) {
+      return JSON.stringify({ ok: false, error: "failed to set workspace: " + args.name });
+    }
+
+    return JSON.stringify({ ok: true, result: { set: true, workspace: args.name } });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

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

@@ -0,0 +1,157 @@
+// Command: set-xmp-metadata → ppb_setXmpMetadata
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Project-item addressing: at least one of nodeId/name is required (see
+// get-item-metadata.jsx for the shared design note — the resolver is
+// duplicated per-file since command files load independently).
+//
+// WRITE command — write-side counterpart of get-xmp-metadata.
+// setXMPMetadata(xml) REPLACES THE ITEM'S ENTIRE XMP BLOCK — it is not a
+// merge/patch. Callers should run get-xmp-metadata first, modify the
+// returned XML, and pass the full result back here. XMP blobs are too
+// large for a command line, so this command's `xmp` wire arg is expected
+// to already be file contents — the CLI's --xmp-file flag reads a local
+// file and sends it, all in Python; this file never touches the
+// filesystem. Undo is NON-FUNCTIONAL on this build — `previousValue`
+// (truncated to 100KB, same as get-xmp-metadata) is the only restoration
+// path.
+
+var PPB_SET_XMP_METADATA_MAX_CHARS = 102400;
+
+function ppbFindItemSetXmpMetadata_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 = ppbFindItemSetXmpMetadata_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbFindItemSetXmpMetadata_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbFindItemSetXmpMetadata_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppbSetXmpMetadata_truncate(xmp) {
+  var truncated = false;
+  if (typeof xmp === "string" && xmp.length > PPB_SET_XMP_METADATA_MAX_CHARS) {
+    xmp = xmp.substring(0, PPB_SET_XMP_METADATA_MAX_CHARS);
+    truncated = true;
+  }
+  return { value: xmp, truncated: truncated };
+}
+
+function ppb_setXmpMetadata(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.xmp !== "string" || args.xmp.length === 0) {
+      return JSON.stringify({ ok: false, error: "xmp (non-empty string) is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = ppbFindItemSetXmpMetadata_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" });
+    }
+
+    if (typeof item.setXMPMetadata !== "function") {
+      return JSON.stringify({ ok: false, error: "setXMPMetadata is not available on this Premiere build" });
+    }
+
+    var previousRaw = null;
+    try { previousRaw = item.getXMPMetadata(); } catch (e) { previousRaw = null; }
+    var previousTruncation = ppbSetXmpMetadata_truncate(previousRaw);
+
+    try {
+      item.setXMPMetadata(args.xmp);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "setXMPMetadata() failed: " + e.toString() });
+    }
+
+    var newRaw = null;
+    try { newRaw = item.getXMPMetadata(); } catch (e) { newRaw = null; }
+    var newTruncation = ppbSetXmpMetadata_truncate(newRaw);
+
+    var verified = false;
+    var note = null;
+    if (typeof newRaw === "string") {
+      if (!newTruncation.truncated && !(args.xmp.length > PPB_SET_XMP_METADATA_MAX_CHARS)) {
+        verified = newRaw === args.xmp;
+      } else {
+        // Either the requested XMP or the read-back was too large to
+        // compare in full — only the truncated prefixes can be checked.
+        verified = newTruncation.value === args.xmp.substring(0, PPB_SET_XMP_METADATA_MAX_CHARS);
+        note = "requested value and/or read-back exceeded 100KB — verified against truncated prefixes only";
+      }
+    }
+
+    var result = {
+      name: null,
+      nodeId: null,
+      requestedValue: args.xmp,
+      previousValue: previousTruncation.value,
+      previousTruncated: previousTruncation.truncated,
+      newValue: newTruncation.value,
+      truncated: newTruncation.truncated,
+      verified: verified
+    };
+    if (note) {
+      result.note = note;
+    }
+    try { result.name = item.name; } catch (e) { result.name = null; }
+    try { result.nodeId = item.nodeId; } catch (e) { result.nodeId = null; }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}