premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/move-playhead.jsx

@@ -0,0 +1,137 @@
+// Command: move-playhead → ppb_movePlayhead
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND,
+// findSequenceByName, getSequenceFps, timecodeToSeconds, ...) are already
+// defined there.
+
+// Moves the given (or active) sequence's playhead to a target time, given
+// as either a "MM:SS:FF" timecode or a raw seconds value. Reuses the exact
+// playhead-move pattern from ppb_exportFrame (host/commands/export-frame.jsx)
+// — ticksString first, a Time-object fallback, collecting a positionAttempts
+// array of {form, success, error?} — which is live-confirmed working on
+// this Premiere build. Unlike export-frame, there is nothing to restore
+// afterward: moving the playhead IS the point of this command.
+function ppb_movePlayhead(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var hasTimecode = args.timecode !== undefined && args.timecode !== null;
+    var hasSeconds = args.seconds !== undefined && args.seconds !== null;
+
+    if (hasTimecode === hasSeconds) {
+      return JSON.stringify({ ok: false, error: "exactly one of timecode or seconds must be provided" });
+    }
+
+    if (hasTimecode) {
+      var timecodeRe = /^\d{2,3}:\d{2}:\d{2}$/;
+      if (typeof args.timecode !== "string" || !timecodeRe.test(args.timecode)) {
+        return JSON.stringify({ ok: false, error: "timecode must be a \"MM:SS:FF\" string" });
+      }
+    } else {
+      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 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" });
+      }
+    }
+
+    // Moving the playhead implies the user wants to see it — make the
+    // resolved sequence the active one if it isn't already (same approach
+    // as ppb_removeTrackIntervals / ppb_exportFrame). No QE DOM needed here.
+    if (app.project.activeSequence !== seq) {
+      app.project.activeSequence = seq;
+    }
+
+    var timeSeconds;
+    if (hasTimecode) {
+      var fps = getSequenceFps(seq);
+      timeSeconds = timecodeToSeconds(args.timecode, fps);
+    } else {
+      timeSeconds = args.seconds;
+    }
+
+    var positionAttempts = [];
+    var ticksString = String(Math.round(timeSeconds * TICKS_PER_SECOND));
+    var timeObj = null;
+    try {
+      timeObj = new Time();
+      timeObj.seconds = timeSeconds;
+    } catch (e) {
+      timeObj = null;
+    }
+
+    var positionSet = false;
+    try {
+      seq.setPlayerPosition(ticksString);
+      positionAttempts.push({ form: "ticksString", success: true });
+      positionSet = true;
+    } catch (e) {
+      positionAttempts.push({ form: "ticksString", success: false, error: e.toString() });
+    }
+    if (!positionSet && timeObj !== null) {
+      try {
+        seq.setPlayerPosition(timeObj);
+        positionAttempts.push({ form: "TimeObject", success: true });
+        positionSet = true;
+      } catch (e) {
+        positionAttempts.push({ form: "TimeObject", success: false, error: e.toString() });
+      }
+    }
+
+    if (!positionSet) {
+      return JSON.stringify({
+        ok: false,
+        error: "could not move the playhead to the requested time with any known argument form (ticks string, Time object)",
+        attempts: positionAttempts
+      });
+    }
+
+    var playheadSeconds = null;
+    try {
+      var currentPosition = seq.getPlayerPosition();
+      if (currentPosition !== null && typeof currentPosition !== "undefined") {
+        if (typeof currentPosition.seconds === "number") {
+          playheadSeconds = currentPosition.seconds;
+        } else {
+          playheadSeconds = Number(currentPosition.ticks) / TICKS_PER_SECOND;
+        }
+      }
+    } catch (e) {
+      playheadSeconds = null;
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      requestedSeconds: timeSeconds,
+      playheadSeconds: playheadSeconds,
+      attempts: positionAttempts
+    };
+    if (hasTimecode) {
+      result.timecode = args.timecode;
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/nest-clips.jsx

@@ -0,0 +1,179 @@
+// Command: nest-clips → ppb_nestClips
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ...) are already defined there.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's utility.ts nest_clips.
+// Nests the CURRENTLY SELECTED clips into a new nested sequence via
+// `seq.createSubsequence(ignoreTrackTargetingBool)` per
+// PREMIERE_API_NOTES.md's Sequences table (selection is a precondition —
+// select clips first, e.g. via select-clips-by-name/select-all-clips).
+// createSubsequence() itself gives the new sequence a Premiere-generated
+// default name; there is no confirmed API to pass a name directly to it,
+// so this command renames the resulting sequence (and its Project-panel
+// item, per the "renaming gotcha" documented alongside seq.clone() in
+// PREMIERE_API_NOTES.md — seq.name = x does NOT propagate to the panel)
+// afterward if `name` was given.
+//
+// Semi-destructive (restructures the timeline): the selected clips are
+// replaced by one nested-sequence clip. Undo is non-functional on this
+// build per README.md.
+//
+// Verification: the sequence count increases by exactly one, and the new
+// sequence is identified as whichever sequence appeared that wasn't in
+// the "before" snapshot (createSubsequence()'s own return value is not
+// trusted, matching every other QE/structural command in this panel).
+function ppb_snapshotSequenceIds(project) {
+  var ids = {};
+  for (var i = 0; i < project.sequences.numSequences; i++) {
+    var s = project.sequences[i];
+    var id = null;
+    try { id = s.sequenceID; } catch (e) { id = null; }
+    ids[id !== null ? id : ("idx" + i)] = true;
+  }
+  return ids;
+}
+
+function ppb_nestClips(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" });
+      }
+    }
+    if (app.project.activeSequence !== seq) {
+      app.project.activeSequence = seq;
+    }
+
+    var selectedCount = 0;
+    function countSelected(tracks) {
+      for (var t = 0; t < tracks.numTracks; t++) {
+        for (var c = 0; c < tracks[t].clips.numItems; c++) {
+          var isSel = false;
+          try { isSel = tracks[t].clips[c].isSelected(); } catch (e) { isSel = false; }
+          if (isSel) {
+            selectedCount++;
+          }
+        }
+      }
+    }
+    countSelected(seq.videoTracks);
+    countSelected(seq.audioTracks);
+
+    if (selectedCount === 0) {
+      return JSON.stringify({ ok: false, error: "no clips selected — select clips first (e.g. select-clips-by-name/select-clips-in-range)" });
+    }
+
+    var numSequencesBefore = app.project.sequences.numSequences;
+    var idsBefore = ppb_snapshotSequenceIds(app.project);
+
+    var createError = null;
+    try {
+      seq.createSubsequence(true);
+    } catch (e) {
+      createError = e.toString();
+    }
+
+    var numSequencesAfter = app.project.sequences.numSequences;
+
+    if (createError !== null || numSequencesAfter <= numSequencesBefore) {
+      return JSON.stringify({
+        ok: false,
+        error: createError !== null
+          ? ("seq.createSubsequence(true) failed: " + createError)
+          : "createSubsequence() did not throw, but the project's sequence count did not increase",
+        numSequencesBefore: numSequencesBefore,
+        numSequencesAfter: numSequencesAfter
+      });
+    }
+
+    var newSeq = null;
+    for (var i = 0; i < app.project.sequences.numSequences; i++) {
+      var candidate = app.project.sequences[i];
+      var candidateId = null;
+      try { candidateId = candidate.sequenceID; } catch (e) { candidateId = null; }
+      var key = candidateId !== null ? candidateId : ("idx" + i);
+      if (!idsBefore[key]) {
+        newSeq = candidate;
+        break;
+      }
+    }
+
+    if (!newSeq) {
+      return JSON.stringify({
+        ok: false,
+        error: "sequence count increased but the new sequence could not be identified",
+        numSequencesBefore: numSequencesBefore,
+        numSequencesAfter: numSequencesAfter
+      });
+    }
+
+    var previousName = null;
+    try { previousName = newSeq.name; } catch (e) { previousName = null; }
+
+    var renamed = false;
+    var renameNote = null;
+    if (args.name && typeof args.name === "string") {
+      try {
+        newSeq.name = args.name;
+      } catch (e) {
+        renameNote = "renaming the sequence object failed: " + e.toString();
+      }
+      // "renaming gotcha" per PREMIERE_API_NOTES.md: seq.name = x does not
+      // propagate to the Project panel item — find and rename it too.
+      try {
+        var rootChildren = app.project.rootItem.children;
+        for (var ri = 0; ri < rootChildren.numItems; ri++) {
+          var it = rootChildren[ri];
+          var itSeq = null;
+          try { itSeq = it.getSequence ? it.getSequence() : null; } catch (e2) { itSeq = null; }
+          if (itSeq && itSeq.sequenceID === newSeq.sequenceID) {
+            it.name = args.name;
+            break;
+          }
+        }
+      } catch (e3) {
+        // best-effort — panel-item rename is a bonus, not required for success
+      }
+      var readBackName = null;
+      try { readBackName = newSeq.name; } catch (e4) { readBackName = null; }
+      renamed = readBackName === args.name;
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sourceSequenceName: seq.name,
+        selectedClipCount: selectedCount,
+        numSequencesBefore: numSequencesBefore,
+        numSequencesAfter: numSequencesAfter,
+        newSequenceName: newSeq.name,
+        newSequenceID: newSeq.sequenceID,
+        previousDefaultName: previousName,
+        requestedName: args.name || null,
+        renamed: renamed,
+        renameNote: renameNote
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/open-in-source.jsx

@@ -0,0 +1,117 @@
+// Command: open-in-source → ppb_openInSource
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Ported from leancoderkavy's premiere-pro-mcp source-monitor.ts
+// open_in_source. Resolves a project item by nodeId/name (same recursive
+// bin walk as add-to-timeline/replace-clip) and opens it in the Source
+// Monitor via app.sourceMonitor.openProjectItem(item).
+//
+// MUTATION RULE: verified by reading app.sourceMonitor.getProjectItem()
+// back afterward and confirming its nodeId matches the requested item —
+// never trusting openProjectItem()'s own (undocumented) return value.
+
+function ppbFindItemOpenInSource_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 = ppbFindItemOpenInSource_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbFindItemOpenInSource_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbFindItemOpenInSource_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppb_openInSource(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 to identify the project item" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = ppbFindItemOpenInSource_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 itemNodeId = null;
+    var itemName = null;
+    try { itemNodeId = item.nodeId; } catch (e1) { itemNodeId = null; }
+    try { itemName = item.name; } catch (e2) { itemName = null; }
+
+    try {
+      app.sourceMonitor.openProjectItem(item);
+    } catch (e3) {
+      return JSON.stringify({ ok: false, error: "app.sourceMonitor.openProjectItem() failed: " + e3.toString() });
+    }
+
+    var verifiedItem = null;
+    var verified = false;
+    try {
+      verifiedItem = app.sourceMonitor.getProjectItem();
+      if (verifiedItem) {
+        var verifiedNodeId = null;
+        try { verifiedNodeId = verifiedItem.nodeId; } catch (e4) { verifiedNodeId = null; }
+        verified = verifiedNodeId !== null && verifiedNodeId === itemNodeId;
+      }
+    } catch (e5) {
+      verified = false;
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        opened: true,
+        item: { name: itemName, nodeId: itemNodeId },
+        verified: verified
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/open-project.jsx

@@ -0,0 +1,61 @@
+// Command: open-project → ppb_openProject
+// 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 open_project.
+// Calls app.openDocument(path). WARNING (per PREMIERE_API_NOTES.md and
+// set-active-project.jsx's header note): app.openDocument's behavior is
+// only loosely documented — it may pop a dialog (unsupported project
+// version, missing media relink prompts, etc.), and its behavior when the
+// path is already open elsewhere is unconfirmed. A blocking dialog will
+// freeze the CEP bridge until a human dismisses it in Premiere. Checks
+// the file exists on disk before calling, to at least rule out that
+// failure mode cheaply. Verified by reading app.project.path back
+// afterward.
+
+function ppb_openProject(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (!args.path || typeof args.path !== "string") {
+      return JSON.stringify({ ok: false, error: "path is required" });
+    }
+
+    var file = new File(args.path);
+    if (!file.exists) {
+      return JSON.stringify({ ok: false, error: "no file exists at path: " + args.path });
+    }
+
+    try {
+      app.openDocument(args.path);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.openDocument() failed: " + e.toString() });
+    }
+
+    var newPath = null;
+    var newName = null;
+    try { newPath = app.project ? app.project.path : null; } catch (e) { newPath = null; }
+    try { newName = app.project ? app.project.name : null; } catch (e) { newName = null; }
+
+    var verified = newPath !== null && newPath === args.path;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        opened: true,
+        requestedPath: args.path,
+        path: newPath,
+        name: newName,
+        verified: verified,
+        note: "app.openDocument() may pop a blocking dialog on this build (unsupported version, missing-media relink, etc.) — if the call hangs, a human needs to dismiss a dialog in Premiere itself"
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}