premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/set-sequence-in-out.jsx

@@ -0,0 +1,65 @@
+// Command: set-sequence-in-out → ppb_setSequenceInOut
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND,
+// findSequenceByName, trySetSequenceRange, ...) are already defined there.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's playhead.ts
+// set_sequence_in_out_points. Sets the given (or active) sequence's
+// in/out points (used for export range, etc.) — reuses the shared
+// trySetSequenceRange() helper (seconds, then ticksString, then Time
+// object) rather than a single-form seq.setInPoint()/setOutPoint() call,
+// since PREMIERE_API_NOTES.md flags that call's argument type as
+// disagreeing across the reference repos.
+function ppb_setSequenceInOut(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (typeof args.inSeconds !== "number" || isNaN(args.inSeconds) ||
+        typeof args.outSeconds !== "number" || isNaN(args.outSeconds)) {
+      return JSON.stringify({ ok: false, error: "inSeconds and outSeconds (numbers) are both 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 rangeResult = trySetSequenceRange(seq, args.inSeconds, args.outSeconds);
+    if (!rangeResult.ok) {
+      return JSON.stringify({
+        ok: false,
+        error: "could not set sequence in/out points with any known argument form",
+        attempts: rangeResult.attempts
+      });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        inSeconds: args.inSeconds,
+        outSeconds: args.outSeconds,
+        attempts: rangeResult.attempts
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-sequence-settings.jsx

@@ -0,0 +1,184 @@
+// Command: set-sequence-settings → ppb_setSequenceSettings
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// getSequenceFps, TICKS_PER_SECOND, ...) are already defined there.
+//
+// MERGES SEVEN reference tools into one command: leancoderkavy's
+// sequence.ts set_sequence_settings (generic width/height) PLUS utility.ts's
+// set_sequence_frame_rate, set_sequence_resolution, set_sequence_audio_settings
+// (sample rate only — channel type is not exposed here), set_sequence_pixel_
+// aspect_ratio (taken here as a numerator/denominator pair rather than a
+// single ratio float, so callers don't have to pre-divide), set_sequence_
+// field_type, and set_sequence_display_format (video format only). Any
+// combination of frameRate/width/height/audioSampleRate/(parNumerator+
+// parDenominator)/fieldType/displayFormat may be given; at least one is
+// required.
+//
+// ⚠️ setSettings() UNRELIABILITY (PREMIERE_API_NOTES.md's "Settings write"
+// line, and create-sequence.jsx's own comment): [leancoderkavy]/[ayushozha]
+// claim getSettings()→mutate→setSettings() works, [hetpatel] says settings
+// "cannot be changed after creation", and our own live create-sequence
+// testing found non-default fps/resolution doesn't reliably apply. This
+// command does NOT trust setSettings() not throwing as success — each
+// requested field is individually verified by a FRESH getSettings() call
+// after the write, exactly like create-sequence's settingsApplied/
+// settingsFailed pattern, but per-field here (result.fields[name].applied).
+function ppbSeqSettings_getFps(seq) {
+  try {
+    return getSequenceFps(seq);
+  } catch (e) {
+    return null;
+  }
+}
+
+function ppb_setSequenceSettings(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;
+    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 hasFrameRate = typeof args.frameRate === "number";
+    var hasWidth = typeof args.width === "number";
+    var hasHeight = typeof args.height === "number";
+    var hasAudioSampleRate = typeof args.audioSampleRate === "number";
+    var hasParNum = typeof args.parNumerator === "number";
+    var hasParDen = typeof args.parDenominator === "number";
+    var hasFieldType = typeof args.fieldType === "number";
+    var hasDisplayFormat = typeof args.displayFormat === "number";
+
+    if (hasParNum !== hasParDen) {
+      return JSON.stringify({ ok: false, error: "parNumerator and parDenominator must be given together" });
+    }
+    var hasPar = hasParNum && hasParDen;
+
+    if (!hasFrameRate && !hasWidth && !hasHeight && !hasAudioSampleRate && !hasPar && !hasFieldType && !hasDisplayFormat) {
+      return JSON.stringify({
+        ok: false,
+        error: "at least one of frameRate, width, height, audioSampleRate, parNumerator+parDenominator, fieldType, displayFormat is required"
+      });
+    }
+
+    var applied = [];
+    var failed = {};
+    var fields = {};
+
+    function applyOne(name, mutateFn, readFn, verifyFn) {
+      var previousValue = null;
+      try { previousValue = readFn(); } catch (e) { previousValue = null; }
+
+      try {
+        var settings = seq.getSettings();
+        mutateFn(settings);
+        seq.setSettings(settings);
+      } catch (e) {
+        failed[name] = "setSettings() threw: " + e.toString();
+        fields[name] = { previousValue: previousValue, newValue: null, applied: false };
+        return;
+      }
+
+      var newValue = null;
+      try { newValue = readFn(); } catch (e) { newValue = null; }
+
+      var ok = false;
+      try { ok = verifyFn(newValue); } catch (e) { ok = false; }
+
+      fields[name] = { previousValue: previousValue, newValue: newValue, applied: ok };
+      if (ok) {
+        applied.push(name);
+      } else {
+        failed[name] = "setSettings() did not throw, but a fresh getSettings() read-back does not match the requested value — matches the documented setSettings() unreliability on this build";
+      }
+    }
+
+    if (hasFrameRate) {
+      applyOne(
+        "frameRate",
+        function (s) { s.videoFrameRate = TICKS_PER_SECOND / args.frameRate; },
+        function () { return ppbSeqSettings_getFps(seq); },
+        function (v) { return v !== null && Math.abs(v - args.frameRate) < 0.05; }
+      );
+    }
+    if (hasWidth) {
+      applyOne(
+        "width",
+        function (s) { s.videoFrameWidth = args.width; },
+        function () { return seq.getSettings().videoFrameWidth; },
+        function (v) { return v === args.width; }
+      );
+    }
+    if (hasHeight) {
+      applyOne(
+        "height",
+        function (s) { s.videoFrameHeight = args.height; },
+        function () { return seq.getSettings().videoFrameHeight; },
+        function (v) { return v === args.height; }
+      );
+    }
+    if (hasAudioSampleRate) {
+      applyOne(
+        "audioSampleRate",
+        function (s) { s.audioSampleRate = args.audioSampleRate; },
+        function () { return seq.getSettings().audioSampleRate; },
+        function (v) { return v === args.audioSampleRate; }
+      );
+    }
+    if (hasPar) {
+      var ratio = args.parNumerator / args.parDenominator;
+      applyOne(
+        "pixelAspectRatio",
+        function (s) { s.videoPixelAspectRatio = ratio; },
+        function () { return seq.getSettings().videoPixelAspectRatio; },
+        function (v) { return v !== null && Math.abs(v - ratio) < 0.001; }
+      );
+    }
+    if (hasFieldType) {
+      applyOne(
+        "fieldType",
+        function (s) { s.videoFieldType = args.fieldType; },
+        function () { return seq.getSettings().videoFieldType; },
+        function (v) { return v === args.fieldType; }
+      );
+    }
+    if (hasDisplayFormat) {
+      applyOne(
+        "displayFormat",
+        function (s) { s.videoDisplayFormat = args.displayFormat; },
+        function () { return seq.getSettings().videoDisplayFormat; },
+        function (v) { return v === args.displayFormat; }
+      );
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        applied: applied,
+        failed: failed,
+        fields: fields,
+        note: "merges 7 reference tools (set_sequence_settings + utility.ts's 6 individual setters) into one command — see the file header comment. Undo is non-functional on this build; previousValue per field is the only restoration path."
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-source-in-out.jsx

@@ -0,0 +1,98 @@
+// Command: set-source-in-out → ppb_setSourceInOut
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — timeValueToSeconds is already
+// defined there.
+//
+// Ported from leancoderkavy's premiere-pro-mcp source-monitor.ts
+// set_source_in_out. Sets in/out points on whatever project item is
+// currently open in the Source Monitor via item.setInPoint()/
+// setOutPoint(), mediaType 4 ("all") per the reference's own call —
+// PREMIERE_API_NOTES.md documents mediaType as 1=video, 2=audio, 4=all.
+//
+// MUTATION RULE: previous in/out are read via item.getInPoint()/
+// getOutPoint() before mutating (same accessor get-source-monitor-info
+// uses), and the new values are read back afterward — verified is a
+// tolerance-aware comparison against what was requested.
+function ppb_setSourceInOut(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var hasIn = typeof args.inSeconds === "number" && !isNaN(args.inSeconds);
+    var hasOut = typeof args.outSeconds === "number" && !isNaN(args.outSeconds);
+    if (!hasIn && !hasOut) {
+      return JSON.stringify({ ok: false, error: "at least one of inSeconds/outSeconds is required" });
+    }
+
+    var item = null;
+    try {
+      item = app.sourceMonitor.getProjectItem();
+    } catch (e2) {
+      return JSON.stringify({ ok: false, error: "app.sourceMonitor.getProjectItem() failed: " + e2.toString() });
+    }
+    if (!item) {
+      return JSON.stringify({ ok: false, error: "no clip open in Source Monitor" });
+    }
+
+    var previousInSeconds = null;
+    var previousOutSeconds = null;
+    try { previousInSeconds = timeValueToSeconds(item.getInPoint()); } catch (e3) { previousInSeconds = null; }
+    try { previousOutSeconds = timeValueToSeconds(item.getOutPoint()); } catch (e4) { previousOutSeconds = null; }
+
+    var inSetError = null;
+    var outSetError = null;
+
+    if (hasIn) {
+      try {
+        var inTime = new Time();
+        inTime.seconds = args.inSeconds;
+        item.setInPoint(inTime.ticks, 4);
+      } catch (e5) {
+        inSetError = e5.toString();
+      }
+    }
+
+    if (hasOut) {
+      try {
+        var outTime = new Time();
+        outTime.seconds = args.outSeconds;
+        item.setOutPoint(outTime.ticks, 4);
+      } catch (e6) {
+        outSetError = e6.toString();
+      }
+    }
+
+    var newInSeconds = null;
+    var newOutSeconds = null;
+    try { newInSeconds = timeValueToSeconds(item.getInPoint()); } catch (e7) { newInSeconds = null; }
+    try { newOutSeconds = timeValueToSeconds(item.getOutPoint()); } catch (e8) { newOutSeconds = null; }
+
+    var tolerance = 0.05;
+    var inVerified = !hasIn || (inSetError === null && newInSeconds !== null && Math.abs(newInSeconds - args.inSeconds) <= tolerance);
+    var outVerified = !hasOut || (outSetError === null && newOutSeconds !== null && Math.abs(newOutSeconds - args.outSeconds) <= tolerance);
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        item: (function () { try { return item.name; } catch (e) { return null; } })(),
+        inSet: hasIn,
+        outSet: hasOut,
+        previousInSeconds: previousInSeconds,
+        previousOutSeconds: previousOutSeconds,
+        requestedInSeconds: hasIn ? args.inSeconds : null,
+        requestedOutSeconds: hasOut ? args.outSeconds : null,
+        newInSeconds: newInSeconds,
+        newOutSeconds: newOutSeconds,
+        inSetError: inSetError,
+        outSetError: outSetError,
+        verified: inVerified && outVerified
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-target-track.jsx

@@ -0,0 +1,91 @@
+// Command: set-target-track → ppb_setTargetTrack
+// 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
+// `set_target_track` tool (track-targeting.ts): track.setTargeted(targeted,
+// isVideoBool) — only one video and one audio track can be targeted at a
+// time, per Premiere's own UI behavior (targeting one track un-targets any
+// other track of the same type; this command does not do that itself, it
+// relies on Premiere's own setTargeted() semantics). Verified by reading
+// isTargeted() back.
+function ppb_setTargetTrack(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.targeted !== "boolean") {
+      return JSON.stringify({ ok: false, error: "targeted 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];
+
+    try {
+      track.setTargeted(args.targeted, args.trackType === "video");
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "track.setTargeted() failed: " + e.toString() });
+    }
+
+    var isTargetedNow = null;
+    try {
+      isTargetedNow = track.isTargeted();
+    } catch (e) {
+      isTargetedNow = null;
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      trackName: null,
+      requestedTargeted: args.targeted,
+      isTargeted: isTargetedNow
+    };
+    try { result.trackName = track.name; } catch (e) { result.trackName = null; }
+
+    if (isTargetedNow !== null && isTargetedNow !== args.targeted) {
+      result.warning = "isTargeted() read back " + isTargetedNow + " after requesting " + args.targeted + " — 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/set-time-interpolation.jsx

@@ -0,0 +1,141 @@
+// Command: set-time-interpolation → ppb_setTimeInterpolation
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ensureQEEnabled, activateSequenceForQE, qeFindNthNonEmptyClip, ...) are
+// already defined there.
+//
+// QE DOM mutation — `qeClip.setTimeInterpolationType(0|1|2)` per
+// PREMIERE_API_NOTES.md ("Interp/blend" line: 0=sampling, 1=blending,
+// 2=optical flow) and leancoderkavy's `set_time_interpolation` tool
+// (advanced.ts). Same QE clip-addressing care as set-frame-blend: the
+// resolved sequence is activated first, and the standard-DOM clipIndex is
+// mapped to the Nth non-"Empty" QE item via qeFindNthNonEmptyClip (QE
+// track item lists interleave gap items the standard DOM doesn't expose).
+function ppb_setTimeInterpolation(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 (args.type !== 0 && args.type !== 1 && args.type !== 2) {
+      return JSON.stringify({ ok: false, error: "type must be 0 (sampling), 1 (blending), or 2 (optical flow)" });
+    }
+
+    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 numClips = trackCollection[args.trackIndex].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 standardClipName = null;
+    try { standardClipName = trackCollection[args.trackIndex].clips[args.clipIndex].name; } catch (e) { standardClipName = null; }
+
+    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 qeTrack;
+    try {
+      qeTrack = args.trackType === "video" ? qeSeq.getVideoTrackAt(args.trackIndex) : qeSeq.getAudioTrackAt(args.trackIndex);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "QE track lookup failed: " + e.toString() });
+    }
+    if (!qeTrack) {
+      return JSON.stringify({ ok: false, error: "QE track not found at index " + args.trackIndex });
+    }
+
+    var qeClip;
+    try {
+      qeClip = qeFindNthNonEmptyClip(qeTrack, args.clipIndex);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "QE clip lookup failed: " + e.toString() });
+    }
+    if (!qeClip) {
+      return JSON.stringify({ ok: false, error: "could not locate the corresponding non-Empty QE clip at clipIndex " + args.clipIndex });
+    }
+
+    var typeNames = ["sampling", "blending", "optical-flow"];
+
+    var previousValue = null;
+    try { previousValue = qeClip.timeInterpolationType; } catch (e) { previousValue = null; }
+
+    try {
+      qeClip.setTimeInterpolationType(args.type);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "qeClip.setTimeInterpolationType() failed: " + e.toString() });
+    }
+
+    var newValue = null;
+    try { newValue = qeClip.timeInterpolationType; } catch (e) { newValue = null; }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      clipIndex: args.clipIndex,
+      clipName: standardClipName,
+      requestedValue: args.type,
+      requestedValueName: typeNames[args.type],
+      previousValue: previousValue,
+      newValue: newValue,
+      verified: newValue === args.type
+    };
+    if (newValue === null) {
+      result.note = "qeClip.timeInterpolationType was not readable on this build — setTimeInterpolationType() did not throw, but the result is unverified.";
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/set-track-mute.jsx

@@ -0,0 +1,91 @@
+// Command: set-track-mute → ppb_setTrackMute
+// 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's premiere-pro-mcp `mute_track` tool
+// (audio.ts) — renamed here from a bare "mute" toggle to an explicit
+// "set" (muted: bool) for idempotence. Generalized to accept trackType
+// video|audio (the reference only muted audio tracks); track.setMute() is
+// not audio-specific — see also set-track-visibility, which uses the same
+// call on video tracks for a different semantic purpose. Verified by
+// reading isMuted() back.
+function ppb_setTrackMute(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.muted !== "boolean") {
+      return JSON.stringify({ ok: false, error: "muted 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];
+
+    try {
+      track.setMute(args.muted ? 1 : 0);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "track.setMute() failed: " + e.toString() });
+    }
+
+    var isMutedNow = null;
+    try {
+      isMutedNow = track.isMuted();
+    } catch (e) {
+      isMutedNow = null;
+    }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      trackName: null,
+      requestedMuted: args.muted,
+      isMuted: isMutedNow
+    };
+    try { result.trackName = track.name; } catch (e) { result.trackName = null; }
+
+    if (isMutedNow !== null && isMutedNow !== args.muted) {
+      result.warning = "isMuted() read back " + isMutedNow + " after requesting " + args.muted + " — mutation may not have taken effect";
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}