premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/get-unused-media.jsx

@@ -0,0 +1,99 @@
+// Command: get-unused-media → ppb_getUnusedMedia
+// 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.
+//
+// Two-pass: first collects every project-item nodeId referenced by any
+// clip in any sequence, then walks the whole bin tree (same shape as
+// list-project-items.jsx) reporting non-bin items whose nodeId was never
+// seen. Helper names are prefixed ppbUnusedMedia_ to avoid colliding with
+// same-purpose helpers in other lazily-loaded command files evaluated into
+// this same global context.
+
+function ppbUnusedMedia_isBin(item) {
+  try {
+    return typeof ProjectItemType !== "undefined" && item.type === ProjectItemType.BIN;
+  } catch (e) {
+    return false;
+  }
+}
+
+function ppbUnusedMedia_collectUsedIds(tracks, usedIds) {
+  for (var t = 0; t < tracks.numTracks; t++) {
+    var track = tracks[t];
+    var numClips = 0;
+    try {
+      numClips = track.clips.numItems;
+    } catch (e) {
+      numClips = 0;
+    }
+    for (var c = 0; c < numClips; c++) {
+      try {
+        var src = track.clips[c].projectItem;
+        if (src) {
+          usedIds[src.nodeId] = true;
+        }
+      } catch (e) {
+        // skip unreadable clip
+      }
+    }
+  }
+}
+
+// Capped at depth 32 to defend against pathological/circular bin
+// structures rather than looping forever.
+function ppbUnusedMedia_findUnused(item, depth, usedIds, results) {
+  if (depth > 32) {
+    return;
+  }
+
+  var isBin = ppbUnusedMedia_isBin(item);
+
+  if (!isBin) {
+    var nodeId = null;
+    try {
+      nodeId = item.nodeId;
+    } catch (e) {
+      nodeId = null;
+    }
+
+    if (nodeId && !usedIds[nodeId]) {
+      var entry = { nodeId: nodeId, name: null, treePath: null, mediaPath: null };
+      try { entry.name = item.name; } catch (e) { entry.name = null; }
+      try { entry.treePath = item.treePath; } catch (e) { entry.treePath = null; }
+      try { entry.mediaPath = item.getMediaPath(); } catch (e) { entry.mediaPath = null; }
+      results.push(entry);
+    }
+  }
+
+  if (isBin && item.children) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      ppbUnusedMedia_findUnused(item.children[i], depth + 1, usedIds, results);
+    }
+  }
+}
+
+function ppb_getUnusedMedia(argsJson) {
+  try {
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var usedIds = {};
+    for (var s = 0; s < app.project.sequences.numSequences; s++) {
+      var seq = app.project.sequences[s];
+      ppbUnusedMedia_collectUsedIds(seq.videoTracks, usedIds);
+      ppbUnusedMedia_collectUsedIds(seq.audioTracks, usedIds);
+    }
+
+    var results = [];
+    var root = app.project.rootItem;
+    for (var i = 0; i < root.children.numItems; i++) {
+      ppbUnusedMedia_findUnused(root.children[i], 1, usedIds, results);
+    }
+
+    return JSON.stringify({ ok: true, result: { unusedCount: results.length, items: results } });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/get-used-media-report.jsx

@@ -0,0 +1,125 @@
+// Command: get-used-media-report → ppb_getUsedMediaReport
+// 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.
+//
+// Standard-DOM read only, no QE DOM needed. Scans every clip on every
+// video/audio track of the resolved sequence, grouping by source
+// projectItem.nodeId. Helper names are prefixed ppbUsedMediaReport_ to
+// avoid colliding with same-purpose helpers in other lazily-loaded command
+// files evaluated into this same global context.
+
+function ppbUsedMediaReport_scanTracks(tracks, trackTypeLabel, mediaMap, order) {
+  for (var t = 0; t < tracks.numTracks; t++) {
+    var track = tracks[t];
+    var numClips = 0;
+    try {
+      numClips = track.clips.numItems;
+    } catch (e) {
+      numClips = 0;
+    }
+
+    for (var c = 0; c < numClips; c++) {
+      var clip = track.clips[c];
+      var src = null;
+      try {
+        src = clip.projectItem;
+      } catch (e) {
+        src = null;
+      }
+      if (!src) {
+        continue;
+      }
+
+      var key = null;
+      try {
+        key = src.nodeId;
+      } catch (e) {
+        key = null;
+      }
+      if (!key) {
+        continue;
+      }
+
+      if (!mediaMap[key]) {
+        var entry = { nodeId: key, name: null, mediaPath: null, offline: null, useCount: 0, tracksSet: {} };
+        try { entry.name = src.name; } catch (e) { entry.name = null; }
+        try { entry.mediaPath = src.getMediaPath(); } catch (e) { entry.mediaPath = null; }
+        try { entry.offline = src.isOffline(); } catch (e) { entry.offline = null; }
+        mediaMap[key] = entry;
+        order.push(key);
+      }
+
+      mediaMap[key].useCount++;
+      mediaMap[key].tracksSet[trackTypeLabel + t] = true;
+    }
+  }
+}
+
+function ppb_getUsedMediaReport(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 mediaMap = {};
+    var order = [];
+    ppbUsedMediaReport_scanTracks(seq.videoTracks, "V", mediaMap, order);
+    ppbUsedMediaReport_scanTracks(seq.audioTracks, "A", mediaMap, order);
+
+    var media = [];
+    var offlineUsedCount = 0;
+    for (var i = 0; i < order.length; i++) {
+      var entry = mediaMap[order[i]];
+      var trackList = [];
+      for (var k in entry.tracksSet) {
+        if (entry.tracksSet.hasOwnProperty(k)) {
+          trackList.push(k);
+        }
+      }
+      if (entry.offline === true) {
+        offlineUsedCount++;
+      }
+      media.push({
+        nodeId: entry.nodeId,
+        name: entry.name,
+        mediaPath: entry.mediaPath,
+        offline: entry.offline,
+        useCount: entry.useCount,
+        tracks: trackList
+      });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        uniqueMediaCount: media.length,
+        offlineUsedCount: offlineUsedCount,
+        media: media
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/get-value-at-time.jsx

@@ -0,0 +1,135 @@
+// Command: get-value-at-time → ppb_getValueAtTime
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// findClipComponent, findComponentProperty, timeValueToSeconds,
+// tryTimeForms, ...) are already defined there.
+//
+// Standard-DOM, READ-only. Ported from leancoderkavy's premiere-pro-mcp
+// `get_value_at_time` tool (keyframes.ts), addressed here by
+// trackType/trackIndex/clipIndex + componentName/propertyName. `seconds`
+// is clip-relative, offset by clip.start to sequence time, then passed to
+// prop.getValueAtTime() via tryTimeForms() (ticksString, then Time object,
+// then raw seconds — key-time argument form is disputed across builds per
+// PREMIERE_API_NOTES.md).
+function ppb_getValueAtTime(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.componentName !== "string" || !args.componentName) {
+      return JSON.stringify({ ok: false, error: "componentName is required" });
+    }
+    if (typeof args.propertyName !== "string" || !args.propertyName) {
+      return JSON.stringify({ ok: false, error: "propertyName is required" });
+    }
+    if (typeof args.seconds !== "number") {
+      return JSON.stringify({ ok: false, error: "seconds must be a number (clip-relative)" });
+    }
+
+    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 comp = findClipComponent(clip, [args.componentName], [args.componentName]);
+    if (!comp) {
+      return JSON.stringify({
+        ok: false,
+        error: "component \"" + args.componentName + "\" not found on clip (matched against matchName and displayName)"
+      });
+    }
+    var compDisplayName = null;
+    try { compDisplayName = comp.displayName; } catch (e) { compDisplayName = null; }
+
+    var prop = findComponentProperty(comp, [args.propertyName]);
+    if (!prop) {
+      return JSON.stringify({
+        ok: false,
+        error: "property \"" + args.propertyName + "\" not found on component \"" + compDisplayName + "\""
+      });
+    }
+
+    var sequenceSeconds = clipStartSeconds + args.seconds;
+
+    var attempt = tryTimeForms(sequenceSeconds, function (t) {
+      return prop.getValueAtTime(t);
+    });
+
+    if (!attempt.success) {
+      return JSON.stringify({
+        ok: false,
+        error: "getValueAtTime() failed with every known time-argument form (ticksString, Time object, seconds)",
+        attempts: attempt.attempts
+      });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: args.trackType,
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        clipName: clipName,
+        componentName: compDisplayName,
+        propertyName: args.propertyName,
+        seconds: args.seconds,
+        sequenceSeconds: sequenceSeconds,
+        value: attempt.result,
+        attempts: attempt.attempts
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/get-version-info.jsx

@@ -0,0 +1,33 @@
+// Command: get-version-info → ppb_getVersionInfo
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's track-targeting.ts
+// get_version_info. App-level — no project or sequence involved. Every
+// field is individually best-effort (null if unreadable), matching the
+// reference's per-field try/catch.
+function ppb_getVersionInfo(argsJson) {
+  try {
+    var version = null;
+    var buildNumber = null;
+    var isDocumentOpen = null;
+    var path = null;
+
+    try { version = app.version; } catch (e) { version = null; }
+    try { buildNumber = app.build; } catch (e) { buildNumber = null; }
+    try { isDocumentOpen = app.isDocumentOpen(); } catch (e) { isDocumentOpen = null; }
+    try { path = app.path; } catch (e) { path = null; }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        version: version,
+        buildNumber: buildNumber,
+        isDocumentOpen: isDocumentOpen,
+        path: path
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

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

@@ -0,0 +1,52 @@
+// Command: get-work-area → ppb_getWorkArea
+// 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_work_area.
+// Reads the given (or active) sequence's work area bar bounds
+// (seq.workInPoint/seq.workOutPoint — Time-like objects per
+// PREMIERE_API_NOTES.md's "Work area" row) and reports them in seconds.
+function ppb_getWorkArea(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 = timeValueToSeconds(seq.workInPoint); } catch (e) { inSeconds = null; }
+    try { outSeconds = timeValueToSeconds(seq.workOutPoint); } 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() });
+  }
+}

premiere_cli/panel/host/commands/get-workspaces.jsx

@@ -0,0 +1,29 @@
+// Command: get-workspaces → ppb_getWorkspaces
+// 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 get_workspaces.
+// App-level — no project or sequence involved.
+function ppb_getWorkspaces(argsJson) {
+  try {
+    var workspaces = null;
+    try {
+      workspaces = app.getWorkspaces();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "could not retrieve workspaces: " + e.toString() });
+    }
+
+    if (!workspaces) {
+      return JSON.stringify({ ok: false, error: "could not retrieve workspaces" });
+    }
+
+    var list = [];
+    for (var i = 0; i < workspaces.length; i++) {
+      list.push(workspaces[i]);
+    }
+
+    return JSON.stringify({ ok: true, result: { workspaces: list, count: list.length } });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

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

@@ -0,0 +1,107 @@
+// Command: get-xmp-metadata → ppb_getXmpMetadata
+// 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).
+//
+// XMP metadata can be a large XML blob — truncated to 100KB (102400
+// chars) with a `truncated` flag so callers aren't surprised by a huge
+// response.
+
+var PPB_XMP_METADATA_MAX_CHARS = 102400;
+
+function ppbFindItemGetXmpMetadata_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 = ppbFindItemGetXmpMetadata_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbFindItemGetXmpMetadata_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbFindItemGetXmpMetadata_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppb_getXmpMetadata(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 = ppbFindItemGetXmpMetadata_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 xmp = null;
+    try {
+      xmp = item.getXMPMetadata();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "getXMPMetadata() failed: " + e.toString() });
+    }
+
+    var truncated = false;
+    if (typeof xmp === "string" && xmp.length > PPB_XMP_METADATA_MAX_CHARS) {
+      xmp = xmp.substring(0, PPB_XMP_METADATA_MAX_CHARS);
+      truncated = true;
+    }
+
+    var result = { name: null, nodeId: null, xmpMetadata: xmp, truncated: truncated };
+    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() });
+  }
+}