premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/set-clip-speed.jsx

@@ -0,0 +1,160 @@
+// Command: set-clip-speed → ppb_setClipSpeed
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// resolveTimelineClip, resolveQeClip, ensureQEEnabled,
+// activateSequenceForQE, TICKS_PER_SECOND, ...) are already defined
+// there.
+//
+// Sets a clip's playback speed via QE. LIVE-CALIBRATED 2026-07-17 (see
+// BUILD_FINDINGS.md corrections): the working signature on this build is
+// the 5-arg
+//   qeClip.setSpeed(speedMultiplier, ticksString, reverse, false, false)
+// where:
+//   - arg1 is a MULTIPLIER (1 = 100%), NOT a percent — and the
+//     standard-DOM clip.getSpeed() read-back uses the same scale (a
+//     normal clip reads 1, not 100);
+//   - arg2 must be a plausible ticks string — garbage there (e.g. the
+//     literal "ticks") collapses the clip to ONE FRAME. The clip's own
+//     current duration in ticks is passed;
+//   - arg3 is the reverse flag (verified via isSpeedReversed()) —
+//     negative multipliers do NOT reverse, they clamp to a degenerate
+//     state, so reversal must go through this flag;
+//   - args 4/5 are unidentified; false/false is the tested-safe value.
+// Speed-up shortens the timeline item to source/speed ROUNDED UP to
+// whole frames (getSpeed() then reads the post-rounding actual — e.g.
+// requesting 50x on a 27.16s clip yields 48.5). Slow-down does NOT
+// extend the item; source usage truncates instead.
+//
+// MUTATION RULE: verified via the STANDARD-DOM clip.getSpeed()/
+// isSpeedReversed() read-back after the QE call — never trusting
+// setSpeed()'s own return value. Because of frame rounding the speed
+// comparison uses a 5% relative tolerance.
+
+function ppb_setClipSpeed(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" || typeof args.clipIndex !== "number") {
+      return JSON.stringify({ ok: false, error: "trackIndex and clipIndex are required" });
+    }
+    if (typeof args.speedPercent !== "number" || args.speedPercent === 0) {
+      return JSON.stringify({ ok: false, error: "speedPercent is required and must be non-zero (100 = normal, negative = reversed)" });
+    }
+
+    var reverse = args.speedPercent < 0;
+    var multiplier = Math.abs(args.speedPercent) / 100;
+
+    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 stdResolved = resolveTimelineClip(seq, args.trackType, args.trackIndex, args.clipIndex);
+    if (stdResolved.error) {
+      return JSON.stringify({ ok: false, error: stdResolved.error });
+    }
+    var stdClip = stdResolved.clip;
+
+    var previousSpeed = null;
+    var previousReversed = null;
+    try { previousSpeed = stdClip.getSpeed(); } catch (e2) { previousSpeed = null; }
+    try { previousReversed = stdClip.isSpeedReversed() === true || stdClip.isSpeedReversed() === 1; } catch (e3) { previousReversed = null; }
+
+    // arg2 of setSpeed must be a plausible ticks string — the clip's own
+    // current timeline duration.
+    var durTicks = null;
+    try {
+      durTicks = String(Math.round((stdClip.end.seconds - stdClip.start.seconds) * TICKS_PER_SECOND));
+    } catch (e4) {
+      return JSON.stringify({ ok: false, error: "could not read the clip's duration for setSpeed's ticks argument: " + e4.toString() });
+    }
+
+    try {
+      ensureQEEnabled();
+      activateSequenceForQE(seq);
+    } catch (e5) {
+      return JSON.stringify({ ok: false, error: "app.enableQE()/sequence activation failed: " + e5.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 (e6) {
+      return JSON.stringify({ ok: false, error: "qe.project.getActiveSequence() failed: " + e6.toString() });
+    }
+
+    var qeResolved = resolveQeClip(qeSeq, args.trackType, args.trackIndex, args.clipIndex);
+    if (qeResolved.error) {
+      return JSON.stringify({ ok: false, error: qeResolved.error });
+    }
+    var qeClip = qeResolved.qeClip;
+
+    try {
+      qeClip.setSpeed(multiplier, durTicks, reverse, false, false);
+    } catch (e7) {
+      return JSON.stringify({
+        ok: false,
+        error: "qeClip.setSpeed(multiplier, ticksString, reverse, false, false) threw: " + e7.toString(),
+        previousSpeed: previousSpeed,
+        previousReversed: previousReversed
+      });
+    }
+
+    var newSpeed = null;
+    var newReversed = null;
+    try { newSpeed = stdClip.getSpeed(); } catch (e8) { newSpeed = null; }
+    try { newReversed = stdClip.isSpeedReversed() === true || stdClip.isSpeedReversed() === 1; } catch (e9) { newReversed = null; }
+
+    // Frame rounding shifts the actual applied speed (see header) — 5%
+    // relative tolerance on the multiplier, exact match on the flag.
+    var speedVerified = newSpeed !== null && multiplier > 0 &&
+      Math.abs(newSpeed - multiplier) / multiplier <= 0.05;
+    var reverseVerified = newReversed !== null ? (newReversed === reverse) : null;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: args.trackType,
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        clipName: (function () { try { return stdClip.name; } catch (e) { return null; } })(),
+        requestedSpeedPercent: args.speedPercent,
+        requestedMultiplier: multiplier,
+        reverse: reverse,
+        previousSpeed: previousSpeed,
+        previousReversed: previousReversed,
+        newSpeed: newSpeed,
+        newSpeedPercent: newSpeed !== null ? newSpeed * 100 : null,
+        newReversed: newReversed,
+        verified: speedVerified && reverseVerified !== false,
+        note: "getSpeed() values are MULTIPLIERS on this build (1 = 100%); the applied speed is frame-rounded, so newSpeed can differ slightly from the request. Slow-motion does not extend the timeline item."
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-clip-volume.jsx

@@ -0,0 +1,128 @@
+// Command: set-clip-volume → ppb_setClipVolume
+// 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
+// `set_clip_volume` tool (track-targeting.ts), which sets the Volume
+// component's Level property directly to the raw dB number passed in —
+// but PREMIERE_API_NOTES.md is explicit that Level is LINEAR AMPLITUDE, not
+// dB, so setValue(dB) as the reference does is almost certainly wrong on
+// any real build. This command instead converts the requested dB to
+// linear amplitude via hetpatel's empirical calibration for this build
+// family (linear = 10^((dB-15)/20)) before calling setValue().
+//
+// *** CALIBRATION UNCERTAINTY — READ BEFORE TRUSTING THIS COMMAND ***
+// The three reference MCP repos studied for this port do NOT agree on the
+// dB->linear formula: hetpatel's calibrated 10^((dB-15)/20) (used here),
+// leancoderkavy's uncalibrated 10^(dB/20), and ayushozha's "mostly raw dB,
+// docs admit it's linear". None of this has been live-verified against
+// THIS Premiere build — do that before relying on the resulting level
+// sounding correct. Both the raw linear values (previous/requested/new)
+// AND the requested dB are returned so a caller can sanity-check/recalibrate
+// without re-running the mutation.
+function ppb_setClipVolume(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" });
+    }
+
+    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; }
+
+    var requestedLinear = dbToLinearCalibrated(args.db);
+
+    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,
+      requestedDb: args.db,
+      previousValue: previousLinear,
+      requestedValue: requestedLinear,
+      newValue: newLinear,
+      verified: verified,
+      previousDbEstimate: linearToDbCalibrated(previousLinear),
+      calibrationNote: "Level is LINEAR AMPLITUDE, not dB. Converted via hetpatel's empirical " +
+        "calibration linear = 10^((db-15)/20) — UNVERIFIED against this Premiere build; " +
+        "other reference repos use different formulas (see file header comment)."
+    };
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-color-label.jsx

@@ -0,0 +1,123 @@
+// Command: set-color-label → ppb_setColorLabel
+// 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).
+//
+// WRITE command — write-side counterpart of get-color-label. Undo is
+// NON-FUNCTIONAL on this build — `previousValue` is the only restoration
+// path. get-color-label degrades honestly when getColorLabel is absent
+// on a build; this command mirrors that for both the getter (used for
+// previousValue/newValue) and the setter itself.
+
+function ppbFindItemSetColorLabel_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 = ppbFindItemSetColorLabel_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbFindItemSetColorLabel_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbFindItemSetColorLabel_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppb_setColorLabel(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 (typeof args.colorLabel !== "number" || args.colorLabel < 0 || args.colorLabel > 15) {
+      return JSON.stringify({ ok: false, error: "colorLabel (integer 0-15) is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = ppbFindItemSetColorLabel_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" });
+    }
+
+    if (typeof item.setColorLabel !== "function") {
+      return JSON.stringify({ ok: false, error: "setColorLabel is not available on this Premiere build" });
+    }
+
+    var previousValue = null;
+    try { previousValue = item.getColorLabel(); } catch (e) { previousValue = null; }
+
+    try {
+      item.setColorLabel(args.colorLabel);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "setColorLabel() failed: " + e.toString() });
+    }
+
+    var newValue = null;
+    try { newValue = item.getColorLabel(); } catch (e) { newValue = null; }
+
+    var verified = newValue !== null && newValue === args.colorLabel;
+
+    var result = {
+      name: null,
+      nodeId: null,
+      previousValue: previousValue,
+      requestedValue: args.colorLabel,
+      newValue: newValue,
+      verified: verified
+    };
+    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() });
+  }
+}

premiere_cli/panel/host/commands/set-color-value.jsx

@@ -0,0 +1,155 @@
+// Command: set-color-value → ppb_setColorValue
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// findClipComponent, findComponentProperty, valuesApproximatelyEqual, ...)
+// are already defined there.
+//
+// Standard-DOM mutation. Ported from leancoderkavy's premiere-pro-mcp
+// `set_color_value` tool (advanced.ts), addressed here by
+// trackType/trackIndex/clipIndex + componentName/propertyName (same
+// convention as get-effect-properties/set-effect-property) instead of
+// node_id. Sets a color-typed property (e.g. a Lumetri tint, a title fill
+// color) via prop.setColorValue(alpha, red, green, blue, true) — each
+// channel 0-255, per PREMIERE_API_NOTES.md's Property API block. Mutating
+// — undo is non-functional on this build, so previousValue is the
+// caller's only restoration path.
+function ppb_setColorValue(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" });
+    }
+
+    var channels = ["alpha", "red", "green", "blue"];
+    for (var c = 0; c < channels.length; c++) {
+      var v = args[channels[c]];
+      if (typeof v !== "number" || v < 0 || v > 255) {
+        return JSON.stringify({ ok: false, error: channels[c] + " must be a number between 0 and 255" });
+      }
+    }
+
+    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 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 previousValue = null;
+    try { previousValue = prop.getValue(); } catch (e) { previousValue = null; }
+
+    var alpha = args.alpha, red = args.red, green = args.green, blue = args.blue;
+    var setError = null;
+    try {
+      prop.setColorValue(alpha, red, green, blue, true);
+    } catch (e2) {
+      setError = e2.toString();
+    }
+
+    var newValue = null;
+    try { newValue = prop.getValue(); } catch (e3) { newValue = null; }
+
+    var verified = false;
+    if (setError === null) {
+      if (newValue instanceof Array && newValue.length === 4) {
+        verified = valuesApproximatelyEqual(newValue, [alpha, red, green, blue], 1);
+      } else {
+        // No confirmed cross-build representation for a color value read
+        // back via getValue() (packed int vs. [a,r,g,b] array vs. other) —
+        // report the call succeeded without throwing, but don't claim a
+        // verified numeric match unless it's the expected 4-element array.
+        verified = false;
+      }
+    }
+
+    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,
+        requestedColor: { alpha: alpha, red: red, green: green, blue: blue },
+        previousValue: previousValue,
+        newValue: newValue,
+        setError: setError,
+        verified: verified,
+        note: "verified only asserts a match when newValue round-trips as a 4-element [a,r,g,b] array — " +
+          "this property's getValue() representation is unconfirmed on this build."
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-effect-property.jsx

@@ -0,0 +1,124 @@
+// Command: set-effect-property → ppb_setEffectProperty
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// findClipComponent, findComponentProperty, setComponentProperty, ...) are
+// already defined there.
+//
+// Standard-DOM only — no QE needed. Ported from leancoderkavy's
+// premiere-pro-mcp `set_effect_property` tool (keyframes.ts), addressed
+// here by trackType/trackIndex/clipIndex + componentName/propertyName
+// (same convention as get-effect-properties) instead of node_id. Unlike
+// the reference tool (numbers only), this accepts number/string/boolean
+// via an explicit valueType field for unambiguous typing over the wire —
+// premiere_cli.py coerces --value to the right JSON type before sending
+// based on --value-type. Mutating — undo is non-functional on this build,
+// so previousValue is the caller's only restoration path.
+function ppb_setEffectProperty(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 (args.valueType !== "number" && args.valueType !== "string" && args.valueType !== "boolean") {
+      return JSON.stringify({ ok: false, error: "valueType must be \"number\", \"string\", or \"boolean\"" });
+    }
+    if (typeof args.value === "undefined") {
+      return JSON.stringify({ ok: false, error: "value is required" });
+    }
+
+    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 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 setResult = setComponentProperty(comp, [args.propertyName], args.value);
+    if (!setResult.found) {
+      return JSON.stringify({
+        ok: false,
+        error: "property \"" + args.propertyName + "\" not found on component \"" + compDisplayName + "\""
+      });
+    }
+
+    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,
+        valueType: args.valueType,
+        previousValue: setResult.previousValue,
+        requestedValue: setResult.requestedValue,
+        newValue: setResult.newValue,
+        verified: setResult.verified
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}