premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/list-available-transitions.jsx

@@ -0,0 +1,74 @@
+// Command: list-available-transitions → ppb_listAvailableTransitions
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (ensureQEEnabled, ...)
+// are already defined there.
+//
+// QE-only enumeration: qe.project.getVideoTransitionList(). Per
+// PREMIERE_API_NOTES.md, PPro 2026 is known to return an EMPTY list here
+// even though by-name lookup (getVideoTransitionByName) still resolves
+// real transitions — an empty result is surfaced honestly (source:
+// "list") rather than treated as an error, and a probe of common
+// transition names via getVideoTransitionByName is appended as a
+// best-effort fallback (source: "byName") when the list came back empty.
+
+var PPB_LIST_TRANSITIONS_PROBE_NAMES = [
+  "Cross Dissolve", "Dip to Black", "Dip to White", "Film Dissolve",
+  "Additive Dissolve", "Morph Cut", "Push", "Slide", "Wipe",
+  "Iris Round", "Iris Box"
+];
+
+function ppb_listAvailableTransitions(argsJson) {
+  try {
+    ensureQEEnabled();
+
+    if (typeof qe === "undefined" || !qe.project) {
+      return JSON.stringify({ ok: false, error: "QE DOM not available (app.enableQE() did not expose qe.project)" });
+    }
+
+    var transitions = [];
+    var listError = null;
+    try {
+      var list = qe.project.getVideoTransitionList();
+      for (var i = 0; i < list.numItems; i++) {
+        var entry = { name: null, index: i, source: "list" };
+        try { entry.name = list[i].name; } catch (e) { entry.name = null; }
+        transitions.push(entry);
+      }
+    } catch (e) {
+      listError = e.toString();
+    }
+
+    var probedByName = false;
+    if (transitions.length === 0) {
+      try {
+        if (qe.project.getVideoTransitionByName) {
+          probedByName = true;
+          for (var n = 0; n < PPB_LIST_TRANSITIONS_PROBE_NAMES.length; n++) {
+            try {
+              var found = qe.project.getVideoTransitionByName(PPB_LIST_TRANSITIONS_PROBE_NAMES[n]);
+              if (found) {
+                transitions.push({ name: PPB_LIST_TRANSITIONS_PROBE_NAMES[n], index: null, source: "byName" });
+              }
+            } catch (e2) {
+              // this probe name isn't available on this build — skip it
+            }
+          }
+        }
+      } catch (e3) {
+        // leave probedByName as-is
+      }
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        transitions: transitions,
+        count: transitions.length,
+        listError: listError,
+        probedByName: probedByName
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/list-markers.jsx

@@ -0,0 +1,69 @@
+// Command: list-markers → ppb_listMarkers
+// 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.
+//
+// Standard-DOM read only. Same marker iteration pattern as
+// get-full-sequence-info.jsx (getFirstMarker/getNextMarker, capped at
+// 10000 to guard against a pathological linked list) — duplicated locally
+// since each command file loads independently and cannot rely on helpers
+// defined only in another command file.
+
+function ppbListMarkers_serialize(seq) {
+  var markers = [];
+  var m = seq.markers.getFirstMarker();
+  var iterations = 0;
+  while (m !== null && typeof m !== "undefined" && iterations < 10000) {
+    var entry = { name: null, comments: null, type: null, startSeconds: null, endSeconds: null, guid: null };
+    try { entry.name = m.name; } catch (e) { entry.name = null; }
+    try { entry.comments = m.comments; } catch (e) { entry.comments = null; }
+    try { entry.type = m.type; } catch (e) { entry.type = null; }
+    try { entry.startSeconds = timeValueToSeconds(m.start); } catch (e) { entry.startSeconds = null; }
+    try { entry.endSeconds = timeValueToSeconds(m.end); } catch (e) { entry.endSeconds = null; }
+    try { entry.guid = m.guid; } catch (e) { entry.guid = null; }
+    markers.push(entry);
+
+    m = seq.markers.getNextMarker(m);
+    iterations++;
+  }
+  return markers;
+}
+
+function ppb_listMarkers(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 markers = [];
+    try {
+      markers = ppbListMarkers_serialize(seq);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "failed to read markers: " + e.toString() });
+    }
+
+    return JSON.stringify({ ok: true, result: { sequenceName: seq.name, markers: markers, markerCount: markers.length } });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/list-project-items.jsx

@@ -0,0 +1,105 @@
+// Command: list-project-items → ppb_listProjectItems
+// 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.
+//
+// Recursive depth-first walk of app.project.rootItem.children, descending
+// into bins. Helper names are prefixed ppbListProjectItems_ to avoid
+// colliding with same-purpose helpers in other lazily-loaded command files
+// evaluated into this same global context.
+
+function ppbListProjectItems_typeToString(item) {
+  var raw = item.type;
+  try {
+    if (typeof ProjectItemType !== "undefined") {
+      if (raw === ProjectItemType.BIN) {
+        return "BIN";
+      }
+      if (raw === ProjectItemType.CLIP) {
+        return "CLIP";
+      }
+      if (raw === ProjectItemType.FILE) {
+        return "FILE";
+      }
+      if (raw === ProjectItemType.ROOT) {
+        return "ROOT";
+      }
+    }
+  } catch (e) {
+    // fall through to raw number below
+  }
+  return String(raw);
+}
+
+function ppbListProjectItems_isBin(item) {
+  try {
+    return typeof ProjectItemType !== "undefined" && item.type === ProjectItemType.BIN;
+  } catch (e) {
+    return false;
+  }
+}
+
+// Capped at depth 32 to defend against pathological/circular bin
+// structures rather than looping forever.
+function ppbListProjectItems_walk(item, parentPath, depth, results) {
+  if (depth > 32) {
+    return;
+  }
+
+  var treePath = null;
+  try {
+    treePath = item.treePath;
+  } catch (e) {
+    treePath = null;
+  }
+  if (!treePath) {
+    treePath = parentPath + "/" + item.name;
+  }
+
+  var isSequence = null;
+  try {
+    isSequence = item.isSequence();
+  } catch (e) {
+    isSequence = null;
+  }
+
+  var mediaPath = null;
+  try {
+    mediaPath = item.getMediaPath();
+  } catch (e) {
+    mediaPath = null;
+  }
+
+  results.push({
+    name: item.name,
+    treePath: treePath,
+    nodeId: item.nodeId,
+    type: ppbListProjectItems_typeToString(item),
+    isSequence: isSequence,
+    mediaPath: mediaPath
+  });
+
+  if (ppbListProjectItems_isBin(item) && item.children) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      ppbListProjectItems_walk(item.children[i], treePath, depth + 1, results);
+    }
+  }
+}
+
+function ppb_listProjectItems(argsJson) {
+  try {
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var results = [];
+    var root = app.project.rootItem;
+    for (var i = 0; i < root.children.numItems; i++) {
+      ppbListProjectItems_walk(root.children[i], "", 1, results);
+    }
+
+    return JSON.stringify({ ok: true, result: { items: results, count: results.length } });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/lock-track.jsx

@@ -0,0 +1,114 @@
+// Command: lock-track → ppb_lockTrack
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ...) are already defined there.
+//
+// Standard-DOM mutation. Ported from leancoderkavy's premiere-pro-mcp
+// `lock_track` tool (tracks.ts), generalized here to accept trackType
+// video|audio (the reference only locked video tracks) since
+// track.setLocked() is not video-specific. Tries setLocked(1|0) then
+// setLock(bool) [ayushozha probes both; our build's QE reflect list shows
+// "setLock" so the standard-DOM equivalent may or may not share the name —
+// try both rather than assume]. Verified by reading isLocked() back.
+function ppb_lockTrack(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.locked !== "boolean") {
+      return JSON.stringify({ ok: false, error: "locked 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 attempts = [];
+    var applied = false;
+
+    try {
+      track.setLocked(args.locked ? 1 : 0);
+      attempts.push({ form: "setLocked", success: true });
+      applied = true;
+    } catch (e) {
+      attempts.push({ form: "setLocked", success: false, error: e.toString() });
+    }
+
+    if (!applied) {
+      try {
+        track.setLock(args.locked);
+        attempts.push({ form: "setLock", success: true });
+        applied = true;
+      } catch (e) {
+        attempts.push({ form: "setLock", success: false, error: e.toString() });
+      }
+    }
+
+    if (!applied) {
+      return JSON.stringify({
+        ok: false,
+        error: "could not lock/unlock the track with any known form (setLocked, setLock)",
+        attempts: attempts
+      });
+    }
+
+    var isLockedNow = null;
+    try {
+      isLockedNow = track.isLocked();
+    } catch (e) {
+      isLockedNow = null;
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      trackName: null,
+      requestedLocked: args.locked,
+      isLocked: isLockedNow,
+      attempts: attempts
+    };
+    try { result.trackName = track.name; } catch (e) { result.trackName = null; }
+
+    if (isLockedNow !== null && isLockedNow !== args.locked) {
+      result.warning = "isLocked() read back " + isLockedNow + " after requesting " + args.locked + " — 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/manage-proxies.jsx

@@ -0,0 +1,176 @@
+// Command: manage-proxies → ppb_manageProxies
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Three distinct, unrelated semantics per action (deliberately narrower
+// than the reference tool this ports, leancoderkavy's premiere-pro-mcp
+// manage_proxies, which also offers a "create" action — dropped here since
+// it's just add-to-render-queue/encode-project-item aimed at a proxy
+// preset with an extra manual "attach once AME finishes" step; compose
+// those existing commands instead of duplicating the fire-and-forget
+// caveat a third time):
+//
+//   - "attach": attaches an ALREADY-RENDERED proxy file to one project
+//     item via item.attachProxy(path, isHiRes01) (PREMIERE_API_NOTES.md
+//     line 285). Requires nodeId/name (item) + proxyPath. Verified via a
+//     hasProxy()/getProxyPath() read-back where available.
+//   - "enable": turns proxy playback ON project-wide via
+//     app.project.setProxyEnabled(true). No item required.
+//   - "disable": turns proxy playback OFF project-wide via
+//     app.project.setProxyEnabled(false). No item required.
+
+// Project-item addressing (nodeId or name) — duplicated per command file,
+// same walk as get-item-metadata.jsx's ppbFindItemGetItemMetadata_*
+// helpers, prefixed for this file.
+function ppbFindItemManageProxies_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 = ppbFindItemManageProxies_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbFindItemManageProxies_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbFindItemManageProxies_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppb_manageProxies(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (!args.action || (args.action !== "attach" && args.action !== "enable" && args.action !== "disable")) {
+      return JSON.stringify({ ok: false, error: "action must be one of \"attach\", \"enable\", \"disable\"" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    if (args.action === "enable" || args.action === "disable") {
+      var enabled = args.action === "enable";
+      try {
+        app.project.setProxyEnabled(enabled);
+      } catch (e) {
+        return JSON.stringify({ ok: false, error: "app.project.setProxyEnabled(" + enabled + ") failed: " + e.toString() });
+      }
+
+      var readBack = null;
+      try {
+        readBack = app.project.isProxyEnabled();
+      } catch (e) {
+        readBack = null;
+      }
+
+      return JSON.stringify({
+        ok: true,
+        result: {
+          action: args.action,
+          requestedEnabled: enabled,
+          proxiesEnabled: readBack,
+          verified: readBack === null ? null : readBack === enabled
+        }
+      });
+    }
+
+    // action === "attach"
+    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 address the project item for \"attach\"" });
+    }
+    if (!args.proxyPath || typeof args.proxyPath !== "string") {
+      return JSON.stringify({ ok: false, error: "proxyPath is required for \"attach\"" });
+    }
+
+    var proxyFile = new File(args.proxyPath);
+    if (!proxyFile.exists) {
+      return JSON.stringify({ ok: false, error: "proxy file not found: " + args.proxyPath });
+    }
+
+    var item = ppbFindItemManageProxies_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 isHiRes = args.isHiRes === true;
+
+    var attachResult = null;
+    try {
+      attachResult = item.attachProxy(args.proxyPath, isHiRes ? 1 : 0);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "item.attachProxy() failed: " + e.toString() });
+    }
+
+    // attachProxy()'s own return value isn't necessarily trustworthy (same
+    // lesson as exportFramePNG/createSubClip elsewhere in this panel) —
+    // confirm via whatever read-back API exists on this build instead.
+    var hasProxyAfter = null;
+    try { hasProxyAfter = item.hasProxy(); } catch (e) { hasProxyAfter = null; }
+    var proxyPathAfter = null;
+    try { proxyPathAfter = item.getProxyPath(); } catch (e) { proxyPathAfter = null; }
+
+    var verified = null;
+    if (hasProxyAfter !== null) {
+      verified = hasProxyAfter === true;
+    } else if (proxyPathAfter !== null) {
+      verified = proxyPathAfter === args.proxyPath;
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        action: "attach",
+        item: item.name || null,
+        nodeId: item.nodeId || null,
+        proxyPath: args.proxyPath,
+        isHiRes: isHiRes,
+        attachReturnValue: attachResult,
+        hasProxyAfter: hasProxyAfter,
+        proxyPathAfter: proxyPathAfter,
+        verified: verified,
+        note: verified === null
+          ? "attachProxy() did not throw, but neither hasProxy() nor getProxyPath() is available on this build to confirm — treat as unconfirmed"
+          : undefined
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/match-frame.jsx

@@ -0,0 +1,141 @@
+// Command: match-frame → ppb_matchFrame
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// TICKS_PER_SECOND, timeValueToSeconds, ...) are already defined there.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's utility.ts match_frame.
+// Finds the clip covering `seconds` (or the sequence's own playhead if
+// omitted) on video track 0 by default, computes the equivalent SOURCE
+// time within that clip's media (offset = timelinePosition - clip.start +
+// clip.inPoint, per the reference's own formula), then attempts to load
+// that source into the Source Monitor via
+// `app.sourceMonitor.openProjectItem(item)` (documented in
+// PREMIERE_API_NOTES.md's "Source monitor 3-point editing" line) — this
+// is the part the reference tool itself never actually does (its handler
+// only computes and returns the numbers); this command goes one step
+// further and attempts the real "load the source frame into the source
+// monitor" behavior implied by the command's name.
+//
+// No confirmed API exists to seek the Source Monitor to an exact offset
+// after opening a clip (only .play(speed)/.getPosition()/.closeClip() are
+// documented) — openProjectItem() itself is reported as
+// sourceMonitorOpened; the offset is reported for the caller to act on
+// (e.g. scrub manually, or once a seek API is confirmed).
+function ppb_matchFrame(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 trackType = args.trackType === "audio" ? "audio" : "video";
+    var trackIndex = typeof args.trackIndex === "number" ? args.trackIndex : 0;
+    var tracks = trackType === "video" ? seq.videoTracks : seq.audioTracks;
+    var numTracks = 0;
+    try { numTracks = tracks.numTracks; } catch (e) { numTracks = 0; }
+    if (trackIndex >= numTracks) {
+      return JSON.stringify({ ok: false, error: "trackIndex " + trackIndex + " is out of range — sequence has " + numTracks + " " + trackType + " track(s)" });
+    }
+
+    var atSeconds;
+    if (typeof args.seconds === "number" && !isNaN(args.seconds)) {
+      atSeconds = args.seconds;
+    } else {
+      try {
+        atSeconds = seq.getPlayerPosition().seconds;
+      } catch (e) {
+        return JSON.stringify({ ok: false, error: "seconds was omitted and the playhead position could not be read: " + e.toString() });
+      }
+    }
+    var posTicks = atSeconds * TICKS_PER_SECOND;
+
+    var track = tracks[trackIndex];
+    var found = null;
+    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 startTicks = null;
+      var endTicks = null;
+      try { startTicks = Number(clip.start.ticks); } catch (e) { startTicks = null; }
+      try { endTicks = Number(clip.end.ticks); } catch (e) { endTicks = null; }
+      if (startTicks !== null && endTicks !== null && startTicks <= posTicks && endTicks > posTicks) {
+        found = clip;
+        break;
+      }
+    }
+
+    if (!found) {
+      return JSON.stringify({ ok: false, error: "no clip at " + atSeconds + "s on " + trackType + " track " + trackIndex });
+    }
+
+    var clipName = null;
+    var clipNodeId = null;
+    try { clipName = found.name; } catch (e) { clipName = null; }
+    try { clipNodeId = found.nodeId; } catch (e) { clipNodeId = null; }
+
+    var offsetTicks = null;
+    try {
+      offsetTicks = posTicks - Number(found.start.ticks) + Number(found.inPoint.ticks);
+    } catch (e) {
+      offsetTicks = null;
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: trackType,
+      trackIndex: trackIndex,
+      timelineSeconds: atSeconds,
+      clipName: clipName,
+      clipNodeId: clipNodeId,
+      sourceSeconds: offsetTicks !== null ? (offsetTicks / TICKS_PER_SECOND) : null,
+      sourceItem: null,
+      sourceMediaPath: null,
+      sourceMonitorOpened: false,
+      sourceMonitorError: null
+    };
+
+    var src = null;
+    try { src = found.projectItem; } catch (e) { src = null; }
+    if (src) {
+      try { result.sourceItem = { name: src.name, nodeId: src.nodeId }; } catch (e) { result.sourceItem = null; }
+      try { result.sourceMediaPath = src.getMediaPath(); } catch (e) { result.sourceMediaPath = null; }
+
+      try {
+        if (app.sourceMonitor && typeof app.sourceMonitor.openProjectItem === "function") {
+          app.sourceMonitor.openProjectItem(src);
+          result.sourceMonitorOpened = true;
+        } else {
+          result.sourceMonitorError = "app.sourceMonitor.openProjectItem is not available on this build";
+        }
+      } catch (e) {
+        result.sourceMonitorError = e.toString();
+      }
+    } else {
+      result.sourceMonitorError = "clip has no projectItem (source) to open";
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}