premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/get-project-item-info.jsx

@@ -0,0 +1,247 @@
+// Command: get-project-item-info → ppb_getProjectItemInfo
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND,
+// ensureQEEnabled, findSequenceByName, ...) are already defined there.
+//
+// Full detail on a single project item, identified by nodeId or treePath
+// (at least one required). Merges the reference project's two near-
+// duplicate tools (get_project_item_info in inspection.ts, get_item_info in
+// media.ts) into one command — see the "Additional commands" doc note for
+// why get-media-item-info was skipped. Helper names are prefixed
+// ppbProjectItemInfo_ to avoid colliding with same-purpose helpers in other
+// lazily-loaded command files evaluated into this same global context.
+
+var PPB_PROJECT_ITEM_INFO_METADATA_MAX_CHARS = 10000;
+
+function ppbProjectItemInfo_isBin(item) {
+  try {
+    return typeof ProjectItemType !== "undefined" && item.type === ProjectItemType.BIN;
+  } catch (e) {
+    return false;
+  }
+}
+
+function ppbProjectItemInfo_typeToString(item) {
+  try {
+    if (typeof ProjectItemType !== "undefined") {
+      if (item.type === ProjectItemType.BIN) {
+        return "BIN";
+      }
+      if (item.type === ProjectItemType.CLIP) {
+        return "CLIP";
+      }
+      if (item.type === ProjectItemType.FILE) {
+        return "FILE";
+      }
+      if (item.type === ProjectItemType.ROOT) {
+        return "ROOT";
+      }
+    }
+  } catch (e) {
+    // fall through to raw number below
+  }
+  return String(item.type);
+}
+
+// Capped at depth 32 to defend against pathological/circular bin
+// structures rather than looping forever.
+function ppbProjectItemInfo_findByNodeId(item, nodeId, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.nodeId === nodeId) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  // Recurse into anything with children — the ROOT item's type is ROOT,
+  // not BIN, so an isBin() gate here would never descend past the root
+  // (live-debugged 2026-07-17: every lookup returned not-found).
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbProjectItemInfo_findByNodeId(item.children[i], nodeId, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+// Capped at depth 32, same reasoning as ppbProjectItemInfo_findByNodeId.
+function ppbProjectItemInfo_findByTreePath(item, treePath, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.treePath === treePath) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  // Recurse into anything with children — the ROOT item's type is ROOT,
+  // not BIN, so an isBin() gate here would never descend past the root
+  // (live-debugged 2026-07-17: every lookup returned not-found).
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbProjectItemInfo_findByTreePath(item.children[i], treePath, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppb_getProjectItemInfo(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 hasTreePath = typeof args.treePath === "string" && args.treePath.length > 0;
+
+    if (!hasNodeId && !hasTreePath) {
+      return JSON.stringify({ ok: false, error: "one of nodeId or treePath is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = null;
+    var root = app.project.rootItem;
+    if (hasNodeId) {
+      item = ppbProjectItemInfo_findByNodeId(root, args.nodeId, 0);
+      if (!item) {
+        return JSON.stringify({ ok: false, error: "no project item found with nodeId \"" + args.nodeId + "\"" });
+      }
+    } else {
+      item = ppbProjectItemInfo_findByTreePath(root, args.treePath, 0);
+      if (!item) {
+        return JSON.stringify({ ok: false, error: "no project item found with treePath \"" + args.treePath + "\"" });
+      }
+    }
+
+    var info = {
+      nodeId: null,
+      name: null,
+      type: null,
+      treePath: null,
+      mediaPath: null,
+      isOffline: null,
+      colorLabel: null,
+      canChangeMediaPath: null,
+      isSequence: null,
+      isMulticamClip: null,
+      isMergedClip: null,
+      frameRate: null,
+      pixelAspectRatio: null,
+      fieldType: null,
+      alphaUsage: null,
+      ignoreAlpha: null,
+      invertAlpha: null,
+      inPointSeconds: null,
+      outPointSeconds: null,
+      hasProxy: null,
+      canProxy: null,
+      projectMetadata: null,
+      projectMetadataLength: null,
+      xmpMetadata: null,
+      xmpMetadataLength: null,
+      markers: [],
+      childCount: null
+    };
+
+    try { info.nodeId = item.nodeId; } catch (e) { info.nodeId = null; }
+    try { info.name = item.name; } catch (e) { info.name = null; }
+    try { info.type = ppbProjectItemInfo_typeToString(item); } catch (e) { info.type = null; }
+    try { info.treePath = item.treePath; } catch (e) { info.treePath = null; }
+    try { info.mediaPath = item.getMediaPath(); } catch (e) { info.mediaPath = null; }
+    try { info.isOffline = item.isOffline(); } catch (e) { info.isOffline = null; }
+    try { info.colorLabel = item.getColorLabel(); } catch (e) { info.colorLabel = null; }
+    try { info.canChangeMediaPath = item.canChangeMediaPath(); } catch (e) { info.canChangeMediaPath = null; }
+    try { info.isSequence = item.isSequence(); } catch (e) { info.isSequence = null; }
+    try { info.isMulticamClip = item.isMulticamClip(); } catch (e) { info.isMulticamClip = null; }
+    try { info.isMergedClip = item.isMergedClip(); } catch (e) { info.isMergedClip = null; }
+
+    try {
+      var interp = item.getFootageInterpretation();
+      if (interp) {
+        try { info.frameRate = interp.frameRate; } catch (e) { info.frameRate = null; }
+        try { info.pixelAspectRatio = interp.pixelAspectRatio; } catch (e) { info.pixelAspectRatio = null; }
+        try { info.fieldType = interp.fieldType; } catch (e) { info.fieldType = null; }
+        try { info.alphaUsage = interp.alphaUsage; } catch (e) { info.alphaUsage = null; }
+        try { info.ignoreAlpha = interp.ignoreAlpha; } catch (e) { info.ignoreAlpha = null; }
+        try { info.invertAlpha = interp.invertAlpha; } catch (e) { info.invertAlpha = null; }
+      }
+    } catch (e) {
+      // leave footage-interpretation fields null
+    }
+
+    try { info.inPointSeconds = timeValueToSeconds(item.getInPoint()); } catch (e) { info.inPointSeconds = null; }
+    try { info.outPointSeconds = timeValueToSeconds(item.getOutPoint()); } catch (e) { info.outPointSeconds = null; }
+
+    try { info.hasProxy = item.hasProxy(); } catch (e) { info.hasProxy = null; }
+    try { info.canProxy = item.canProxy(); } catch (e) { info.canProxy = null; }
+
+    try {
+      var xmp = item.getProjectMetadata();
+      if (xmp && xmp.length > PPB_PROJECT_ITEM_INFO_METADATA_MAX_CHARS) {
+        info.projectMetadataLength = xmp.length;
+      } else if (xmp) {
+        info.projectMetadata = xmp;
+      }
+    } catch (e) {
+      // leave projectMetadata fields null
+    }
+
+    try {
+      var xmp2 = item.getXMPMetadata();
+      if (xmp2 && xmp2.length > PPB_PROJECT_ITEM_INFO_METADATA_MAX_CHARS) {
+        info.xmpMetadataLength = xmp2.length;
+      } else if (xmp2) {
+        info.xmpMetadata = xmp2;
+      }
+    } catch (e) {
+      // leave xmpMetadata fields null
+    }
+
+    try {
+      var markerCollection = item.getMarkers();
+      if (markerCollection) {
+        var m = markerCollection.getFirstMarker();
+        while (m) {
+          var markerEntry = { name: null, comments: null, startSeconds: null, guid: null };
+          try { markerEntry.name = m.name; } catch (e) { markerEntry.name = null; }
+          try { markerEntry.guid = m.guid; } catch (e) { markerEntry.guid = null; }
+          try { markerEntry.comments = m.comments; } catch (e) { markerEntry.comments = null; }
+          try { markerEntry.startSeconds = timeValueToSeconds(m.start); } catch (e) { markerEntry.startSeconds = null; }
+          info.markers.push(markerEntry);
+          m = markerCollection.getNextMarker(m);
+        }
+      }
+    } catch (e) {
+      // leave markers as whatever was collected so far
+    }
+
+    if (ppbProjectItemInfo_isBin(item)) {
+      try {
+        info.childCount = item.children.numItems;
+      } catch (e) {
+        info.childCount = null;
+      }
+    }
+
+    return JSON.stringify({ ok: true, result: info });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

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

@@ -0,0 +1,30 @@
+// Command: get-project-panel-metadata → ppb_getProjectPanelMetadata
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND,
+// ensureQEEnabled, findSequenceByName, ...) are already defined there.
+//
+// Thin read of app.project.getProjectPanelMetadata() — the Project panel's
+// column/metadata configuration, returned as an XML string.
+
+function ppb_getProjectPanelMetadata(argsJson) {
+  try {
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var metadata = null;
+    try {
+      metadata = app.project.getProjectPanelMetadata();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "getProjectPanelMetadata failed: " + e.toString() });
+    }
+
+    if (!metadata) {
+      return JSON.stringify({ ok: false, error: "could not retrieve project panel metadata" });
+    }
+
+    return JSON.stringify({ ok: true, result: { metadata: metadata } });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/get-qe-clip-info.jsx

@@ -0,0 +1,198 @@
+// Command: get-qe-clip-info → ppb_getQeClipInfo
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (ensureQEEnabled,
+// findSequenceByName, ...) are already defined there.
+//
+// QE DOM read — undocumented, version-dependent surface (see
+// PREMIERE_API_NOTES.md). QE items expose `.secs` on their time-like
+// properties, NOT `.seconds` like the standard DOM (ayushozha's finding,
+// confirmed in our notes) — qeTimeToSeconds below handles that. QE DOM
+// operates on qe.project.getActiveSequence() only, so this command
+// activates the resolved sequence first, same as remove-track-intervals.
+// Clip addressing (trackType/trackIndex/clipIndex) is validated against
+// the standard DOM's track/clip counts first — same range-check pattern
+// as get-full-clip-info — since the QE track/clip API surfaces no count
+// validation of its own. Ported from leancoderkavy's premiere-pro-mcp
+// `get_qe_clip_info` tool (track-targeting.ts).
+
+var GET_QE_CLIP_INFO_PROPS = [
+  "name", "type", "mediaType", "duration", "start", "end", "inPoint", "outPoint",
+  "speed", "audioChannelType", "numAudioChannels"
+];
+
+function qeTimeToSeconds(timeLike) {
+  if (timeLike === null || typeof timeLike === "undefined") {
+    return null;
+  }
+  if (typeof timeLike === "number") {
+    return timeLike;
+  }
+  if (typeof timeLike.secs === "number") {
+    return timeLike.secs;
+  }
+  if (typeof timeLike.seconds === "number") {
+    return timeLike.seconds;
+  }
+  if (typeof timeLike.ticks !== "undefined") {
+    return Number(timeLike.ticks) / TICKS_PER_SECOND;
+  }
+  return null;
+}
+
+function ppb_getQeClipInfo(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 (!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 numClips = trackCollection[args.trackIndex].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)"
+      });
+    }
+
+    // QE DOM only ever operates on the active sequence tab — switch to it
+    // rather than erroring if the resolved sequence isn't already active.
+    if (app.project.activeSequence !== seq) {
+      app.project.activeSequence = seq;
+    }
+
+    try {
+      ensureQEEnabled();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.enableQE() failed: " + e.toString() });
+    }
+    if (typeof qe === "undefined" || !qe.project) {
+      return JSON.stringify({ ok: false, error: "QE DOM not available after enableQE()" });
+    }
+
+    var qeSeq;
+    try {
+      qeSeq = qe.project.getActiveSequence();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "qe.project.getActiveSequence() failed: " + e.toString() });
+    }
+    if (!qeSeq) {
+      return JSON.stringify({ ok: false, error: "qe.project.getActiveSequence() returned nothing after activating the sequence" });
+    }
+
+    var qeTrack;
+    try {
+      qeTrack = args.trackType === "video" ? qeSeq.getVideoTrackAt(args.trackIndex) : qeSeq.getAudioTrackAt(args.trackIndex);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "QE track lookup failed: " + e.toString() });
+    }
+    if (!qeTrack) {
+      return JSON.stringify({ ok: false, error: "QE track not found at index " + args.trackIndex });
+    }
+
+    var qeClip;
+    try {
+      qeClip = qeTrack.getItemAt(args.clipIndex);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "QE clip lookup failed: " + e.toString() });
+    }
+    if (!qeClip) {
+      return JSON.stringify({ ok: false, error: "QE clip not found at index " + args.clipIndex });
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      clipIndex: args.clipIndex
+    };
+
+    var TIME_FIELDS = { duration: true, start: true, end: true, inPoint: true, outPoint: true };
+
+    for (var i = 0; i < GET_QE_CLIP_INFO_PROPS.length; i++) {
+      var propName = GET_QE_CLIP_INFO_PROPS[i];
+      try {
+        var raw = qeClip[propName];
+        if (TIME_FIELDS[propName]) {
+          result[propName + "Seconds"] = qeTimeToSeconds(raw);
+        } else {
+          result[propName] = raw;
+        }
+      } catch (e) {
+        // leave this field absent — best-effort per PPB_COMMANDS convention
+      }
+    }
+
+    var availableProperties = [];
+    try {
+      for (var key in qeClip) {
+        try {
+          if (typeof qeClip[key] !== "function") {
+            availableProperties.push(key);
+          }
+        } catch (e) {
+          // some QE keys throw on access — skip
+        }
+      }
+    } catch (e) {
+      // for-in itself failed — leave list empty
+    }
+    result.availableProperties = availableProperties;
+
+    var availableMethods = [];
+    try {
+      for (var mkey in qeClip) {
+        try {
+          if (typeof qeClip[mkey] === "function") {
+            availableMethods.push(mkey);
+          }
+        } catch (e) {
+          // some QE keys throw on access — skip
+        }
+      }
+    } catch (e) {
+      // for-in itself failed — leave list empty
+    }
+    result.availableMethods = availableMethods;
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/get-render-queue-status.jsx

@@ -0,0 +1,35 @@
+// Command: get-render-queue-status → ppb_getRenderQueueStatus
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Standard DOM only (app.encoder), no QE needed. Per PREMIERE_API_NOTES.md
+// ("No progress API — fire and forget"), Adobe Media Encoder exposes no
+// real queue-introspection API from ExtendScript — this surfaces whatever
+// `app.encoder.isRunning()` reports (if the method exists on this
+// Premiere build) rather than inventing queue detail that doesn't exist.
+
+function ppb_getRenderQueueStatus(argsJson) {
+  try {
+    if (typeof app.encoder === "undefined" || !app.encoder) {
+      return JSON.stringify({ ok: false, error: "Adobe Media Encoder is not available (app.encoder is undefined)" });
+    }
+
+    var isRunning = null;
+    try {
+      if (typeof app.encoder.isRunning === "function") {
+        isRunning = app.encoder.isRunning();
+      }
+    } catch (e) {
+      isRunning = null;
+    }
+
+    var result = {
+      isRunning: isRunning,
+      info: "Premiere's ExtendScript API has no render-queue introspection — check Adobe Media Encoder itself for detailed job/progress status."
+    };
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/get-sequence-count.jsx

@@ -0,0 +1,24 @@
+// Command: get-sequence-count → ppb_getSequenceCount
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use.
+//
+// Standard-DOM read only, no args. Ported from leancoderkavy's
+// premiere-pro-mcp `get_sequence_count` tool (utility.ts).
+
+function ppb_getSequenceCount() {
+  try {
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var count = null;
+    try {
+      count = app.project.sequences.numSequences;
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "could not read sequence count: " + e.toString() });
+    }
+
+    return JSON.stringify({ ok: true, result: { count: count } });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/get-sequence-in-out.jsx

@@ -0,0 +1,76 @@
+// Command: get-sequence-in-out → ppb_getSequenceInOut
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND,
+// findSequenceByName, timeValueToSeconds, ...) are already defined there.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's playhead.ts
+// get_sequence_in_out_points. Reads the given (or active) sequence's
+// in/out points via seq.getInPoint()/getOutPoint().
+//
+// Live-tested 2026-07-17 on Premiere Pro 2026: getInPoint()/getOutPoint()
+// return SECONDS as a string (setting in=10s reads back "10"), NOT ticks —
+// the original raw-ticks interpretation shrank real values by 11 orders of
+// magnitude. An UNSET point reads as Premiere's -400000 sentinel, reported
+// here as null. Time-like objects (other builds) still go through
+// timeValueToSeconds.
+function ppb_pointValueToSeconds(value) {
+  if (value === null || typeof value === "undefined") {
+    return null;
+  }
+  if (typeof value === "object") {
+    return timeValueToSeconds(value);
+  }
+  var seconds = Number(value);
+  if (isNaN(seconds)) {
+    return null;
+  }
+  if (seconds <= -399999) {
+    // Premiere's "no in/out point set" sentinel
+    return null;
+  }
+  return seconds;
+}
+
+function ppb_getSequenceInOut(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 inSeconds = null;
+    var outSeconds = null;
+    try { inSeconds = ppb_pointValueToSeconds(seq.getInPoint()); } catch (e) { inSeconds = null; }
+    try { outSeconds = ppb_pointValueToSeconds(seq.getOutPoint()); } catch (e) { outSeconds = null; }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        inSeconds: inSeconds,
+        outSeconds: outSeconds
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}