premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/add-transition.jsx

@@ -0,0 +1,134 @@
+// Command: add-transition → ppb_addTransition
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (ensureQEEnabled,
+// activateSequenceForQE, qeFindNthNonEmptyClip, ppbApplyTransitionToClip,
+// ...) are already defined there.
+//
+// Merges the reference project's add_transition (track+cut-point
+// addressing) and add_transition_to_clip (node_id+position addressing)
+// into one command, addressed the same way as get-full-clip-info
+// (trackType/trackIndex/clipIndex) rather than either reference's own
+// scheme — video-only (no reference repo demonstrates an audio-transition
+// "add" API). `atEnd: true` applies the transition at the clip's end
+// (matching add_transition_to_clip's "end" position and the cut-point
+// between this clip and its successor); `atEnd: false` applies it at the
+// clip's start. The reference's "both" position is intentionally dropped
+// — call this command twice (once per atEnd value) to reproduce it.
+// `transitionName` omitted/null = the default transition, per ayushozha's
+// addTransition(null, true, "1.0") convention. All the actual apply-and-
+// verify work (disputed addTransition signature, transitions-count
+// verification) lives in the shared ppbApplyTransitionToClip helper.
+function ppb_addTransition(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") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"video\" — no reference API demonstrates adding a transition to an audio track" });
+    }
+    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.atEnd !== "boolean") {
+      return JSON.stringify({ ok: false, error: "atEnd must be a boolean (true = end of clip, false = start of clip)" });
+    }
+    var transitionName = null;
+    if (typeof args.transitionName === "string" && args.transitionName.length > 0) {
+      transitionName = args.transitionName;
+    } else if (args.transitionName !== undefined && args.transitionName !== null) {
+      return JSON.stringify({ ok: false, error: "transitionName must be a non-empty string, or omitted/null for the default transition" });
+    }
+
+    // Live-tested 2026-07-17: the null-transition ("default") form
+    // no-throws but adds NOTHING on this build, while a NAMED transition
+    // works and verifies. Substitute Cross Dissolve (Premiere's factory
+    // default) rather than burning attempts on a known-dead path.
+    if (transitionName === null) {
+      transitionName = "Cross Dissolve";
+    }
+    var durationSeconds = 1.0;
+    if (typeof args.durationSeconds === "number") {
+      if (args.durationSeconds <= 0) {
+        return JSON.stringify({ ok: false, error: "durationSeconds must be a positive number" });
+      }
+      durationSeconds = args.durationSeconds;
+    } else if (args.durationSeconds !== undefined && args.durationSeconds !== null) {
+      return JSON.stringify({ ok: false, error: "durationSeconds must be a 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" });
+      }
+    }
+
+    try {
+      ensureQEEnabled();
+      activateSequenceForQE(seq);
+    } catch (e2) {
+      return JSON.stringify({ ok: false, error: "app.enableQE()/sequence activation failed: " + e2.toString() });
+    }
+    if (typeof qe === "undefined" || !qe.project) {
+      return JSON.stringify({ ok: false, error: "QE DOM not available after enableQE()" });
+    }
+
+    var transitionQE = null;
+    if (transitionName !== null) {
+      try {
+        if (qe.project.getVideoTransitionByName) {
+          transitionQE = qe.project.getVideoTransitionByName(transitionName);
+        }
+      } catch (e3) {
+        transitionQE = null;
+      }
+      if (!transitionQE) {
+        return JSON.stringify({ ok: false, error: "transition not found: \"" + transitionName + "\" (try list-available-transitions)" });
+      }
+    }
+
+    var applyResult = ppbApplyTransitionToClip(seq, args.trackIndex, args.clipIndex, transitionQE, args.atEnd, durationSeconds);
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: "video",
+      trackIndex: args.trackIndex,
+      clipIndex: args.clipIndex,
+      clipName: applyResult.clipName,
+      transitionName: transitionName,
+      atEnd: args.atEnd,
+      durationSeconds: durationSeconds,
+      previousTransitionCount: applyResult.previousCount,
+      newTransitionCount: applyResult.newCount,
+      addedTransitionName: applyResult.addedTransitionName,
+      verified: applyResult.verified,
+      attempts: applyResult.attempts,
+      succeededWithArgs: applyResult.succeededWithArgs
+    };
+
+    if (!applyResult.verified) {
+      return JSON.stringify({ ok: false, error: applyResult.error, result: result });
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/adjust-audio-levels.jsx

@@ -0,0 +1,132 @@
+// Command: adjust-audio-levels → ppb_adjustAudioLevels
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// findVolumeLevelProperty, dbToLinearCalibrated, linearToDbCalibrated, ...)
+// are already defined there.
+//
+// Standard-DOM mutation. Ported from leancoderkavy's premiere-pro-mcp
+// `adjust_audio_levels` tool (audio.ts) — but note that reference handler
+// actually SETS the Level property directly to the raw `level_db` argument
+// (an absolute set, same bug as set_clip_volume's reference, and also not
+// really "adjust" semantics despite the tool's name). This command instead
+// implements true relative-adjustment semantics: read the clip's current
+// linear Level, convert it to an estimated dB via the same calibration
+// formula as set-clip-volume, add the requested `db` delta, convert back to
+// linear, and apply. See set-clip-volume.jsx's header for the calibration-
+// uncertainty caveat — it applies here identically, compounded because this
+// command both reads AND writes through the same unverified formula.
+function ppb_adjustAudioLevels(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.db !== "number" || isNaN(args.db)) {
+      return JSON.stringify({ ok: false, error: "db must be a number (a DELTA relative to the clip's current level)" });
+    }
+
+    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 levelProp = findVolumeLevelProperty(clip);
+    if (!levelProp) {
+      return JSON.stringify({ ok: false, error: "could not find Volume/Level property on clip — is this an audio clip?" });
+    }
+
+    var previousLinear = null;
+    try { previousLinear = levelProp.getValue(); } catch (e) { previousLinear = null; }
+    if (previousLinear === null) {
+      return JSON.stringify({ ok: false, error: "could not read the clip's current Level value" });
+    }
+
+    var previousDbEstimate = linearToDbCalibrated(previousLinear);
+    if (previousDbEstimate === null) {
+      return JSON.stringify({ ok: false, error: "current Level value (" + previousLinear + ") is not a valid positive amplitude — cannot estimate its dB" });
+    }
+
+    var requestedDbTotal = previousDbEstimate + args.db;
+    var requestedLinear = dbToLinearCalibrated(requestedDbTotal);
+
+    try {
+      levelProp.setValue(requestedLinear, true);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "levelProp.setValue() failed: " + e.toString() });
+    }
+
+    var newLinear = null;
+    try { newLinear = levelProp.getValue(); } catch (e) { newLinear = null; }
+
+    var verified = newLinear !== null && Math.abs(newLinear - requestedLinear) < 0.0005;
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      clipIndex: args.clipIndex,
+      clipName: clipName,
+      requestedDeltaDb: args.db,
+      previousValue: previousLinear,
+      previousDbEstimate: previousDbEstimate,
+      requestedValue: requestedLinear,
+      requestedDbTotal: requestedDbTotal,
+      newValue: newLinear,
+      verified: verified,
+      calibrationNote: "Level is LINEAR AMPLITUDE, not dB — this command estimates the clip's " +
+        "current dB from its linear value via hetpatel's UNVERIFIED calibration formula " +
+        "(linear = 10^((db-15)/20)), adds the requested delta, then converts back. Compounds " +
+        "the same calibration uncertainty documented in set-clip-volume.jsx."
+    };
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/apply-audio-effect.jsx

@@ -0,0 +1,118 @@
+// Command: apply-audio-effect → ppb_applyAudioEffect
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ensureQEEnabled, activateSequenceForQE, resolveTimelineClip,
+// resolveQeClip, serializeClipComponents, findQeAudioEffectByName, ...) are
+// already defined there.
+//
+// Audio counterpart of apply-effect: qe.project.getAudioEffectByName() (or a
+// getAudioEffectList() scan fallback) + qeClip.addAudioEffect(fx). Same
+// verification approach — clip.components.numItems increasing by exactly 1,
+// never trusting addAudioEffect()'s own return value.
+function ppb_applyAudioEffect(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 !== "audio") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"audio\" — apply-audio-effect applies an AUDIO effect (use apply-effect for video clips)" });
+    }
+    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.effectName !== "string" || !args.effectName) {
+      return JSON.stringify({ ok: false, error: "effectName must be a non-empty 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" });
+      }
+    }
+
+    var resolvedClip = resolveTimelineClip(seq, "audio", args.trackIndex, args.clipIndex);
+    if (resolvedClip.error) {
+      return JSON.stringify({ ok: false, error: resolvedClip.error });
+    }
+    var clip = resolvedClip.clip;
+    var clipName = null;
+    try { clipName = clip.name; } catch (e) { clipName = null; }
+
+    var previousComponents = serializeClipComponents(clip);
+
+    try {
+      ensureQEEnabled();
+      activateSequenceForQE(seq);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.enableQE()/sequence activation 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() });
+    }
+
+    var qeResolved = resolveQeClip(qeSeq, "audio", args.trackIndex, args.clipIndex);
+    if (qeResolved.error) {
+      return JSON.stringify({ ok: false, error: qeResolved.error });
+    }
+
+    var fx = findQeAudioEffectByName(args.effectName);
+    if (!fx) {
+      return JSON.stringify({ ok: false, error: "audio effect not found in this Premiere install's QE effect catalog: \"" + args.effectName + "\"" });
+    }
+
+    try {
+      qeResolved.qeClip.addAudioEffect(fx);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "qeClip.addAudioEffect() failed: " + e.toString() });
+    }
+
+    var newComponents = serializeClipComponents(clip);
+    var verified = newComponents.length === previousComponents.length + 1;
+    var newComponent = verified ? newComponents[newComponents.length - 1] : null;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: "audio",
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        clipName: clipName,
+        effectName: args.effectName,
+        verified: verified,
+        newComponent: newComponent,
+        previousComponentCount: previousComponents.length,
+        newComponentCount: newComponents.length,
+        previousComponents: previousComponents,
+        newComponents: newComponents
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/apply-effect.jsx

@@ -0,0 +1,122 @@
+// Command: apply-effect → ppb_applyEffect
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ensureQEEnabled, activateSequenceForQE, resolveTimelineClip,
+// resolveQeClip, serializeClipComponents, findQeVideoEffectByName, ...) are
+// already defined there.
+//
+// Applies a video effect to a clip via the "universal dance" documented in
+// PREMIERE_API_NOTES.md's "Effects, transitions, keyframes" section:
+// look up the effect in the QE catalog (getVideoEffectByName, falling back
+// to a getVideoEffectList() scan), call qeClip.addVideoEffect(fx), then read
+// the standard-DOM clip.components back — the new component is appended
+// LAST. Mutation is verified by clip.components.numItems increasing by
+// exactly 1, not by trusting addVideoEffect()'s return value (undocumented
+// on this build, like every other QE mutation call here).
+function ppb_applyEffect(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") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"video\" — apply-effect applies a VIDEO effect (use apply-audio-effect for audio clips)" });
+    }
+    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.effectName !== "string" || !args.effectName) {
+      return JSON.stringify({ ok: false, error: "effectName must be a non-empty 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" });
+      }
+    }
+
+    var resolvedClip = resolveTimelineClip(seq, "video", args.trackIndex, args.clipIndex);
+    if (resolvedClip.error) {
+      return JSON.stringify({ ok: false, error: resolvedClip.error });
+    }
+    var clip = resolvedClip.clip;
+    var clipName = null;
+    try { clipName = clip.name; } catch (e) { clipName = null; }
+
+    var previousComponents = serializeClipComponents(clip);
+
+    try {
+      ensureQEEnabled();
+      activateSequenceForQE(seq);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.enableQE()/sequence activation 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() });
+    }
+
+    var qeResolved = resolveQeClip(qeSeq, "video", args.trackIndex, args.clipIndex);
+    if (qeResolved.error) {
+      return JSON.stringify({ ok: false, error: qeResolved.error });
+    }
+
+    var fx = findQeVideoEffectByName(args.effectName);
+    if (!fx) {
+      return JSON.stringify({ ok: false, error: "video effect not found in this Premiere install's QE effect catalog: \"" + args.effectName + "\"" });
+    }
+
+    try {
+      qeResolved.qeClip.addVideoEffect(fx);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "qeClip.addVideoEffect() failed: " + e.toString() });
+    }
+
+    var newComponents = serializeClipComponents(clip);
+    var verified = newComponents.length === previousComponents.length + 1;
+    var newComponent = verified ? newComponents[newComponents.length - 1] : null;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: "video",
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        clipName: clipName,
+        effectName: args.effectName,
+        verified: verified,
+        newComponent: newComponent,
+        previousComponentCount: previousComponents.length,
+        newComponentCount: newComponents.length,
+        previousComponents: previousComponents,
+        newComponents: newComponents
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/apply-lut.jsx

@@ -0,0 +1,107 @@
+// Command: apply-lut → ppb_applyLut
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// resolveTimelineClip, serializeClipComponents,
+// ensureLumetriColorComponent, findComponentProperty, ...) are already
+// defined there.
+//
+// Ensures Lumetri Color is applied (adding it if missing, same helper
+// color-correct uses), then sets its "Input LUT" property to a path string
+// per PREMIERE_API_NOTES.md. This is a plain string setValue — no numeric
+// falsy-check concern here, but the same "0 is legit" caveat from
+// color-correct doesn't apply since a LUT path is never numeric.
+function ppb_applyLut(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") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"video\" — Lumetri Color is a video effect" });
+    }
+    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.lutPath !== "string" || !args.lutPath) {
+      return JSON.stringify({ ok: false, error: "lutPath must be a non-empty 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" });
+      }
+    }
+
+    var resolvedClip = resolveTimelineClip(seq, "video", args.trackIndex, args.clipIndex);
+    if (resolvedClip.error) {
+      return JSON.stringify({ ok: false, error: resolvedClip.error });
+    }
+    var clip = resolvedClip.clip;
+    var clipName = null;
+    try { clipName = clip.name; } catch (e) { clipName = null; }
+
+    var previousComponents = serializeClipComponents(clip);
+
+    var lumetri = ensureLumetriColorComponent(seq, "video", args.trackIndex, args.clipIndex, clip);
+    if (lumetri.error) {
+      return JSON.stringify({ ok: false, error: lumetri.error });
+    }
+    var lumetriComp = lumetri.component;
+
+    var prop = findComponentProperty(lumetriComp, ["Input LUT"]);
+    if (!prop) {
+      return JSON.stringify({ ok: false, error: "could not find an \"Input LUT\" property on Lumetri Color" });
+    }
+
+    var previousValue = null;
+    try { previousValue = prop.getValue(); } catch (e) { previousValue = null; }
+
+    try {
+      prop.setValue(args.lutPath, true);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "prop.setValue(lutPath) failed: " + e.toString() });
+    }
+
+    var newValue = null;
+    try { newValue = prop.getValue(); } catch (e) { newValue = null; }
+
+    var newComponents = serializeClipComponents(clip);
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: "video",
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        clipName: clipName,
+        lumetriApplied: lumetri.applied,
+        previousValue: previousValue,
+        requestedValue: args.lutPath,
+        newValue: newValue,
+        verified: newValue === args.lutPath,
+        previousComponents: previousComponents,
+        newComponents: newComponents
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/attach-custom-property.jsx

@@ -0,0 +1,66 @@
+// Command: attach-custom-property → ppb_attachCustomProperty
+// 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 sequence.ts
+// attach_custom_property tool: `seq.attachCustomProperty(id, value)` per
+// PREMIERE_API_NOTES.md's Sequences table. No confirmed getter/read-back
+// API exists for custom sequence properties in ANY of the reference
+// repos studied — this command can only confirm the setter call didn't
+// throw, never that the value actually persisted or is retrievable
+// later. value is coerced to a string (attachCustomProperty's own
+// signature is key/value strings per the reference tool).
+function ppb_attachCustomProperty(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" });
+    }
+    if (!args.propertyId || typeof args.propertyId !== "string") {
+      return JSON.stringify({ ok: false, error: "propertyId is required" });
+    }
+    if (typeof args.value === "undefined" || args.value === null) {
+      return JSON.stringify({ ok: false, error: "value is required" });
+    }
+
+    var seq;
+    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 valueString = String(args.value);
+
+    try {
+      seq.attachCustomProperty(args.propertyId, valueString);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "seq.attachCustomProperty() failed: " + e.toString() });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        propertyId: args.propertyId,
+        value: valueString,
+        note: "no confirmed getter exists for custom sequence properties across any reference repo studied — this result confirms only that attachCustomProperty() did not throw, not that the value actually persisted or is retrievable"
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}