premiere-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{premiere_cli-0.3.0/src/premiere_cli.egg-info → premiere_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: premiere-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Drive Adobe Premiere Pro from the command line: a Python CLI plus a bundled CEP bridge panel exposing Premiere's scripting APIs over local HTTP
 License: CC-BY-SA-4.0
 Project-URL: Repository, https://github.com/stefanwebb/premiere-cli

{premiere_cli-0.3.0 → premiere_cli-0.3.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "premiere-cli"
 # Keep in lockstep with premiere_cli.__version__ and PANEL_VERSION in
 # src/premiere_cli/panel/js/main.js.
-version = "0.3.0"
+version = "0.3.1"
 description = "Drive Adobe Premiere Pro from the command line: a Python CLI plus a bundled CEP bridge panel exposing Premiere's scripting APIs over local HTTP"
 readme = "README.md"
 license = {text = "CC-BY-SA-4.0"}

{premiere_cli-0.3.0 → premiere_cli-0.3.1}/src/premiere_cli/__init__.py

@@ -8,4 +8,4 @@ server (port 47823).
 # Kept in lockstep with PANEL_VERSION in panel/js/main.js and the version in
 # pyproject.toml — `premiere-cli doctor` compares the installed panel's
 # version against this one.
-__version__ = "0.3.0"
+__version__ = "0.3.1"

premiere_cli-0.3.1/src/premiere_cli/panel/host/commands/export-frame.jsx

@@ -0,0 +1,257 @@
+// Command: export-frame → ppb_exportFrame
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// findBundledPresetByRelativePath, trySetSequenceRange, getSequenceFps,
+// timecodeToSeconds, ...) are already defined there.
+
+// A bundled still-image preset for the AME single-frame export below —
+// confirmed present on this machine's Premiere Pro 2026 install at this
+// relative path; re-verify after a Premiere version upgrade, same caveat
+// as extract-audio-track's FORMAT_PRESET_RELATIVE_PATHS. "Match Source"
+// means the preset inherits the sequence's own frame size, so no
+// width/height override is needed when using it.
+var STILL_IMAGE_PRESET_RELATIVE_PATH =
+  "Contents/MediaIO/systempresets/3F3F3F3F_504E4720/PNG Sequence (Match Source).epr";
+
+// Premiere treats a still-image preset as a one-frame image *sequence*,
+// appending a frame number to the base name ("frame.png" → "frame0.png",
+// confirmed live; padding may vary by preset/duration). Finds whichever
+// variant was actually written and renames it to the exact requested path
+// so callers reliably get the file where they asked for it.
+//
+// Known variants are checked DIRECTLY by path, not found via a directory
+// scan: enumerating the parent directory returns an empty list on this
+// machine for some directories (e.g. /tmp — same macOS TCC/sandboxing
+// behavior already documented for /Applications in
+// findBundledPresetByRelativePath's notes in host/index.jsx) even though
+// the files themselves are readable at their exact paths. A directory
+// scan runs only as a last resort, for variant names not in the known
+// list.
+function locateAndNormalizeExportedFrame(outputPath) {
+  var exact = new File(outputPath);
+  if (exact.exists && exact.length > 0) {
+    return exact;
+  }
+
+  var fullName = decodeURI(exact.name);
+  var dot = fullName.lastIndexOf(".");
+  var base = dot === -1 ? fullName : fullName.substring(0, dot);
+  var ext = dot === -1 ? "" : fullName.substring(dot);
+  var parentPath = exact.path;
+
+  function normalize(produced) {
+    if (produced.length <= 0) {
+      return null;
+    }
+    try {
+      if (produced.fsName !== exact.fsName) {
+        produced.rename(fullName);
+      }
+    } catch (e) {
+      // rename best-effort — still report the file under whatever name it has
+      return produced;
+    }
+    return exact.exists ? exact : produced;
+  }
+
+  var knownVariants = [
+    parentPath + "/" + base + "0" + ext,      // AME frame-number suffix
+    parentPath + "/" + base + "00" + ext,
+    parentPath + "/" + base + "000" + ext,
+    parentPath + "/" + base + "0000" + ext
+  ];
+  for (var v = 0; v < knownVariants.length; v++) {
+    var candidate = new File(knownVariants[v]);
+    if (candidate.exists && candidate.length > 0) {
+      return normalize(candidate);
+    }
+  }
+
+  // Last resort: scan the parent directory (returns nothing at all in
+  // enumeration-blocked directories — see comment above).
+  var dir = exact.parent;
+  if (!dir || !dir.exists) {
+    return null;
+  }
+
+  var matches = dir.getFiles(function (item) {
+    if (item instanceof Folder) {
+      return false;
+    }
+    var name = decodeURI(item.name);
+    if (name.indexOf(base) !== 0) {
+      return false;
+    }
+    var lowerExt = ext.toLowerCase();
+    return lowerExt === "" || name.toLowerCase().substring(name.length - lowerExt.length) === lowerExt;
+  });
+
+  if (!matches || matches.length === 0) {
+    return null;
+  }
+
+  return normalize(matches[0]);
+}
+
+// Exports a single frame of a sequence, at a given timecode, to a PNG file.
+//
+// qe.project.getActiveSequence().exportFramePNG was tried first in an
+// earlier version of this command (guessing at its version-dependent arg
+// order per PREMIERE_API_NOTES.md), judging success only by whether a file
+// was produced. That check is NOT sufficient: confirmed live 2026-07-20
+// that on this Premiere build, exportFramePNG ignores its position
+// argument in every arg-order variant tried (ticksString, Time object,
+// output-path-as-position, ticks-then-path, path-then-ticks) and always
+// exports whatever frame is currently rendered in the Program Monitor,
+// regardless of the requested timecode — while still writing a real file
+// and returning normally, so the file-existence check reported false
+// positives. Two exports requested 30 seconds apart came back
+// pixel-identical. Neither seq.setPlayerPosition() (standard DOM) nor
+// qeSequence.setCTI() (QE DOM) changed this.
+//
+// This command now exports exclusively via Adobe Media Encoder's
+// exportAsMediaDirect() — the same documented, blocking mechanism
+// ppb_extractAudioTrack already uses successfully — narrowing the
+// sequence's in/out points to exactly one frame around the target
+// timecode. Confirmed live to produce genuinely different, timecode-
+// correct frames (verified via pixel diff, not just file existence).
+function ppb_exportFrame(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (!args.outputPath || typeof args.outputPath !== "string") {
+      return JSON.stringify({ ok: false, error: "outputPath is required" });
+    }
+    var timecodeRe = /^\d{2,3}:\d{2}:\d{2}$/;
+    if (!args.timecode || typeof args.timecode !== "string" || !timecodeRe.test(args.timecode)) {
+      return JSON.stringify({ ok: false, error: "timecode must be a \"MM:SS:FF\" string" });
+    }
+
+    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 fps = getSequenceFps(seq);
+    var timeSeconds = timecodeToSeconds(args.timecode, fps);
+
+    var width = null;
+    var height = null;
+    try {
+      var settings = seq.getSettings();
+      width = settings.videoFrameWidth;
+      height = settings.videoFrameHeight;
+    } catch (e) {
+      // best-effort only — reported in the result, not required for export
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      timecode: args.timecode,
+      timeSeconds: timeSeconds,
+      outputPath: args.outputPath,
+      width: width,
+      height: height
+    };
+
+    // Clear any stale leftover from an earlier failed run — the exact
+    // requested path plus every known frame-numbered variant Premiere
+    // might write it under (see locateAndNormalizeExportedFrame) — so a
+    // leftover file's mere existence can't be mistaken for this run's
+    // output.
+    for (var staleRound = 0; staleRound < 8; staleRound++) {
+      var stale = locateAndNormalizeExportedFrame(args.outputPath);
+      if (stale === null) {
+        break;
+      }
+      try {
+        stale.remove();
+      } catch (e) {
+        // best-effort — a failed cleanup doesn't block the export attempt
+        break;
+      }
+    }
+
+    var amePresetPath = findBundledPresetByRelativePath(STILL_IMAGE_PRESET_RELATIVE_PATH);
+    if (!amePresetPath) {
+      return JSON.stringify({
+        ok: false,
+        error: "no bundled still-image preset found for the Media Encoder export"
+      });
+    }
+
+    var originalInPoint = null;
+    var originalOutPoint = null;
+    try {
+      originalInPoint = seq.getInPoint();
+      originalOutPoint = seq.getOutPoint();
+    } catch (e) {
+      // best-effort only — if these can't be read, we simply won't restore them
+    }
+
+    var frameDurationSeconds = 1 / fps;
+    var ameProducedFile = null;
+    var ameError = null;
+
+    try {
+      var rangeOutcome = trySetSequenceRange(seq, timeSeconds, timeSeconds + frameDurationSeconds);
+      if (!rangeOutcome.ok) {
+        ameError = "could not set sequence in/out points with any known argument form (seconds, ticks string, Time object)";
+      } else {
+        try {
+          seq.exportAsMediaDirect(args.outputPath, amePresetPath, 1 /* ENCODE_IN_TO_OUT */);
+        } catch (e) {
+          ameError = "exportAsMediaDirect failed: " + e.toString();
+        }
+      }
+    } finally {
+      if (originalInPoint !== null && originalOutPoint !== null) {
+        try {
+          trySetSequenceRange(seq, originalInPoint.seconds, originalOutPoint.seconds);
+        } catch (e) {
+          // best-effort
+        }
+      }
+    }
+
+    if (ameError === null) {
+      ameProducedFile = locateAndNormalizeExportedFrame(args.outputPath);
+    }
+
+    if (ameProducedFile === null) {
+      return JSON.stringify({
+        ok: false,
+        error: "Media Encoder export failed" + (ameError ? ": " + ameError : " (no file produced)")
+      });
+    }
+
+    result.method = "ame";
+    result.presetPath = amePresetPath;
+    result.fileSizeBytes = ameProducedFile.length;
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

{premiere_cli-0.3.0 → premiere_cli-0.3.1}/src/premiere_cli/panel/js/main.js

@@ -5,7 +5,7 @@ const PORT = 47823;
 // Kept in lockstep with the premiere-cli Python package version —
 // `premiere-cli doctor` compares the two and warns when the installed
 // panel is stale relative to the CLI that ships it.
-const PANEL_VERSION = '0.3.0';
+const PANEL_VERSION = '0.3.1';
 const VALID_LEVELS = ['info', 'warn', 'error'];
 
 // main.js is loaded via a plain <script src="js/main.js"> tag, not

{premiere_cli-0.3.0 → premiere_cli-0.3.1/src/premiere_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: premiere-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Drive Adobe Premiere Pro from the command line: a Python CLI plus a bundled CEP bridge panel exposing Premiere's scripting APIs over local HTTP
 License: CC-BY-SA-4.0
 Project-URL: Repository, https://github.com/stefanwebb/premiere-cli

premiere_cli-0.3.0/src/premiere_cli/panel/host/commands/export-frame.jsx

@@ -1,381 +0,0 @@
-// Command: export-frame → ppb_exportFrame
-// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
-// same global ExtendScript context — shared helpers (ensureQEEnabled,
-// findSequenceByName, findBundledPresetByRelativePath, trySetSequenceRange,
-// getSequenceFps, timecodeToSeconds, ...) are already defined there.
-
-// A bundled still-image preset for the ppb_exportFrame AME fallback (see
-// below) — confirmed present on this machine's Premiere Pro 2026 install
-// at this relative path; re-verify after a Premiere version upgrade, same
-// caveat as extract-audio-track's FORMAT_PRESET_RELATIVE_PATHS. "Match
-// Source" means the preset inherits the sequence's own frame size, so no
-// width/height override is needed when using it.
-var STILL_IMAGE_PRESET_RELATIVE_PATH =
-  "Contents/MediaIO/systempresets/3F3F3F3F_504E4720/PNG Sequence (Match Source).epr";
-
-// The QE exportFramePNG call (see ppb_exportFrame) and the AME
-// image-sequence export below can both write under a name other than the
-// exact path requested — QE appends ".png" even to an already-.png-
-// suffixed path ("frame.png" → "frame.png.png", confirmed live), and
-// Premiere treats a still-image preset as a one-frame image *sequence*,
-// appending a frame number to the base name ("frame.png" → "frame0.png",
-// confirmed live; padding may vary by preset/duration). Finds whichever
-// variant was actually written and renames it to the exact requested
-// path so callers reliably get the file where they asked for it.
-//
-// Known variants are checked DIRECTLY by path, not found via a directory
-// scan: enumerating the parent directory returns an empty list on this
-// machine for some directories (e.g. /tmp — same macOS TCC/sandboxing
-// behavior already documented for /Applications in
-// findBundledPresetByRelativePath's notes in host/index.jsx) even though
-// the files themselves are readable at their exact paths. A directory
-// scan runs only as a last resort, for variant names not in the known
-// list.
-function locateAndNormalizeExportedFrame(outputPath) {
-  var exact = new File(outputPath);
-  if (exact.exists && exact.length > 0) {
-    return exact;
-  }
-
-  var fullName = decodeURI(exact.name);
-  var dot = fullName.lastIndexOf(".");
-  var base = dot === -1 ? fullName : fullName.substring(0, dot);
-  var ext = dot === -1 ? "" : fullName.substring(dot);
-  var parentPath = exact.path;
-
-  function normalize(produced) {
-    if (produced.length <= 0) {
-      return null;
-    }
-    try {
-      if (produced.fsName !== exact.fsName) {
-        produced.rename(fullName);
-      }
-    } catch (e) {
-      // rename best-effort — still report the file under whatever name it has
-      return produced;
-    }
-    return exact.exists ? exact : produced;
-  }
-
-  var knownVariants = [
-    outputPath + ".png",                      // QE double-extension quirk
-    parentPath + "/" + base + "0" + ext,      // AME frame-number suffix
-    parentPath + "/" + base + "00" + ext,
-    parentPath + "/" + base + "000" + ext,
-    parentPath + "/" + base + "0000" + ext
-  ];
-  for (var v = 0; v < knownVariants.length; v++) {
-    var candidate = new File(knownVariants[v]);
-    if (candidate.exists && candidate.length > 0) {
-      return normalize(candidate);
-    }
-  }
-
-  // Last resort: scan the parent directory (returns nothing at all in
-  // enumeration-blocked directories — see comment above).
-  var dir = exact.parent;
-  if (!dir || !dir.exists) {
-    return null;
-  }
-
-  var matches = dir.getFiles(function (item) {
-    if (item instanceof Folder) {
-      return false;
-    }
-    var name = decodeURI(item.name);
-    if (name.indexOf(base) !== 0) {
-      return false;
-    }
-    var lowerExt = ext.toLowerCase();
-    return lowerExt === "" || name.toLowerCase().substring(name.length - lowerExt.length) === lowerExt;
-  });
-
-  if (!matches || matches.length === 0) {
-    return null;
-  }
-
-  return normalize(matches[0]);
-}
-
-// Exports a single frame of a sequence, at a given timecode, to a PNG file.
-// qeSeq.exportFramePNG's argument order is version-dependent (per
-// PREMIERE_API_NOTES.md) and can silently write nothing on some builds —
-// this brute-forces a short list of plausible signatures and judges success
-// only by checking the filesystem for a real output file afterward, never
-// by trusting the call's own return value (same pattern as
-// remove-track-intervals' rippleDelete()/remove() guessing).
-function ppb_exportFrame(argsJson) {
-  try {
-    var args;
-    try {
-      args = JSON.parse(argsJson);
-    } catch (e) {
-      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
-    }
-
-    if (!args.outputPath || typeof args.outputPath !== "string") {
-      return JSON.stringify({ ok: false, error: "outputPath is required" });
-    }
-    var timecodeRe = /^\d{2,3}:\d{2}:\d{2}$/;
-    if (!args.timecode || typeof args.timecode !== "string" || !timecodeRe.test(args.timecode)) {
-      return JSON.stringify({ ok: false, error: "timecode must be a \"MM:SS:FF\" string" });
-    }
-
-    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" });
-      }
-    }
-
-    // QE DOM only ever operates on the active sequence tab — switch to it
-    // rather than erroring if the resolved sequence isn't already active
-    // (same approach as ppb_removeTrackIntervals).
-    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 qeSequence = qe.project.getActiveSequence();
-    if (!qeSequence) {
-      return JSON.stringify({ ok: false, error: "qe.project.getActiveSequence() returned nothing after activating the sequence" });
-    }
-
-    var fps = getSequenceFps(seq);
-    var timeSeconds = timecodeToSeconds(args.timecode, fps);
-
-    var width = null;
-    var height = null;
-    try {
-      var settings = seq.getSettings();
-      width = settings.videoFrameWidth;
-      height = settings.videoFrameHeight;
-    } catch (e) {
-      // best-effort only — width/height-based attempts below are simply skipped if unreadable
-    }
-
-    // --- Snapshot playhead position, to restore afterward regardless of outcome ---
-    var originalPosition = null;
-    try {
-      originalPosition = seq.getPlayerPosition();
-    } catch (e) {
-      originalPosition = null;
-    }
-
-    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() });
-      }
-    }
-
-    var result = {
-      sequenceName: seq.name,
-      timecode: args.timecode,
-      timeSeconds: timeSeconds,
-      outputPath: args.outputPath,
-      width: width,
-      height: height
-    };
-
-    try {
-      if (!positionSet) {
-        return JSON.stringify({
-          ok: false,
-          error: "could not move the playhead to the requested timecode with any known argument form (ticks string, Time object)",
-          attempts: positionAttempts
-        });
-      }
-
-      // Clear any stale leftovers from an earlier failed run — the exact
-      // requested path plus every known name variant Premiere might have
-      // written it under (see locateAndNormalizeExportedFrame) — so a
-      // leftover file's mere existence can't be mistaken for this run's
-      // output. Loops because multiple variants can coexist (e.g. one QE
-      // double-extension file AND one AME frame-numbered file).
-      for (var staleRound = 0; staleRound < 8; staleRound++) {
-        var stale = locateAndNormalizeExportedFrame(args.outputPath);
-        if (stale === null) {
-          break;
-        }
-        try {
-          stale.remove();
-        } catch (e) {
-          // best-effort — a failed cleanup doesn't block the export attempt
-          break;
-        }
-      }
-
-      // --- Path 1: QE DOM's exportFramePNG. Version-inconsistent arg
-      // order (per PREMIERE_API_NOTES.md) and confirmed live to sometimes
-      // return false / write nothing regardless of a syntactically
-      // correct call — verify by scanning the filesystem afterward, never
-      // by trusting the call's return value.
-      var guesses = [];
-      guesses.push({ args: [args.outputPath], call: [args.outputPath] });
-      if (width !== null && height !== null) {
-        guesses.push({ args: [args.outputPath, String(width), String(height)], call: [args.outputPath, String(width), String(height)] });
-      }
-      // Confirmed live on this Premiere build: passing the output path as
-      // BOTH arguments succeeds where sensible width/height strings do
-      // not — an undocumented quirk of this exportFramePNG build, kept as
-      // a guess rather than relied on, since other builds may differ.
-      guesses.push({ args: [args.outputPath, args.outputPath], call: [args.outputPath, args.outputPath] });
-      if (timeObj !== null) {
-        guesses.push({ args: ["<Time seconds=" + timeSeconds + ">", args.outputPath], call: [timeObj, args.outputPath] });
-      }
-      guesses.push({ args: [ticksString, args.outputPath], call: [ticksString, args.outputPath] });
-
-      var attempts = [];
-      var succeededWithArgs = null;
-      var qeProducedFile = null;
-
-      for (var g = 0; g < guesses.length && succeededWithArgs === null; g++) {
-        var guess = guesses[g];
-        try {
-          qeSequence.exportFramePNG.apply(qeSequence, guess.call);
-        } catch (e) {
-          attempts.push({ args: guess.args, success: false, error: e.toString() });
-          continue;
-        }
-
-        var producedFile = locateAndNormalizeExportedFrame(args.outputPath);
-        if (producedFile !== null) {
-          attempts.push({ args: guess.args, success: true });
-          succeededWithArgs = guess.args;
-          qeProducedFile = producedFile;
-        } else {
-          attempts.push({ args: guess.args, success: false, error: "no file produced" });
-        }
-      }
-
-      if (succeededWithArgs !== null) {
-        result.method = "qe";
-        result.attempts = attempts;
-        result.succeededWithArgs = succeededWithArgs;
-        result.fileSizeBytes = qeProducedFile.length;
-        return JSON.stringify({ ok: true, result: result });
-      }
-
-      // --- Path 2: every QE guess failed — fall back to a one-frame
-      // export through Adobe Media Encoder via the standard DOM's
-      // exportAsMediaDirect(), the same documented, blocking mechanism
-      // ppb_extractAudioTrack already uses successfully. Narrows the
-      // sequence's in/out points to exactly one frame (using the
-      // sequence's own frame duration, seq.timebase) around the target
-      // timecode, then restores the original in/out points afterward.
-      var amePresetPath = findBundledPresetByRelativePath(STILL_IMAGE_PRESET_RELATIVE_PATH);
-      if (!amePresetPath) {
-        return JSON.stringify({
-          ok: false,
-          error: "exportFramePNG failed with all known arg-order variants, and no bundled still-image preset was found for the Media Encoder fallback",
-          attempts: attempts
-        });
-      }
-
-      var originalInPoint = null;
-      var originalOutPoint = null;
-      try {
-        originalInPoint = seq.getInPoint();
-        originalOutPoint = seq.getOutPoint();
-      } catch (e) {
-        // best-effort only — if these can't be read, we simply won't restore them
-      }
-
-      var frameDurationSeconds = 1 / fps;
-      var ameProducedFile = null;
-      var ameError = null;
-
-      try {
-        var rangeOutcome = trySetSequenceRange(seq, timeSeconds, timeSeconds + frameDurationSeconds);
-        if (!rangeOutcome.ok) {
-          ameError = "could not set sequence in/out points with any known argument form (seconds, ticks string, Time object)";
-        } else {
-          try {
-            seq.exportAsMediaDirect(args.outputPath, amePresetPath, 1 /* ENCODE_IN_TO_OUT */);
-          } catch (e) {
-            ameError = "exportAsMediaDirect failed: " + e.toString();
-          }
-        }
-      } finally {
-        if (originalInPoint !== null && originalOutPoint !== null) {
-          try {
-            trySetSequenceRange(seq, originalInPoint.seconds, originalOutPoint.seconds);
-          } catch (e) {
-            // best-effort
-          }
-        }
-      }
-
-      if (ameError === null) {
-        ameProducedFile = locateAndNormalizeExportedFrame(args.outputPath);
-      }
-
-      if (ameProducedFile === null) {
-        return JSON.stringify({
-          ok: false,
-          error: "exportFramePNG failed with all known arg-order variants, and the Media Encoder fallback also failed" +
-            (ameError ? ": " + ameError : " (no file produced)"),
-          attempts: attempts
-        });
-      }
-
-      result.method = "ame";
-      result.attempts = attempts;
-      result.presetPath = amePresetPath;
-      result.fileSizeBytes = ameProducedFile.length;
-
-      return JSON.stringify({ ok: true, result: result });
-    } finally {
-      // Always restore the original playhead position, even if export threw.
-      if (originalPosition !== null) {
-        try {
-          seq.setPlayerPosition(originalPosition.ticks);
-        } catch (e) {
-          // best-effort — restoration failure doesn't change the command's outcome
-        }
-      }
-    }
-  } catch (e) {
-    return JSON.stringify({ ok: false, error: e.toString() });
-  }
-}