@synthetic-ai/premiere-mcp 2.2.0 → 2.3.0-dev.0

package/dist/tools/sequence-advanced.js

@@ -3,15 +3,15 @@ import { sendCommand } from "../bridge/file-bridge.js";
 export function getSequenceAdvancedTools(bridgeOptions) {
     return {
         create_sequence_from_clip: {
-            description: `Create a new sequence whose settings (resolution, frame rate, pixel aspect ratio, audio sample rate) exactly match a specific project item (clip).
-
-This is the recommended way to create a sequence when you want it to match your source footage — it avoids transcoding or scaling artifacts that occur when sequence settings don't match the media.
-
-Preconditions: The clip must already be imported into the project (use import_media first). Use list_project_items to find the item_id.
-
-After creation, the new sequence becomes active automatically.
-
-Example: create_sequence_from_clip({ item_id: "interview.mp4", name: "Interview Edit" })
+            description: `Create a new sequence whose settings (resolution, frame rate, pixel aspect ratio, audio sample rate) exactly match a specific project item (clip).
+
+This is the recommended way to create a sequence when you want it to match your source footage — it avoids transcoding or scaling artifacts that occur when sequence settings don't match the media.
+
+Preconditions: The clip must already be imported into the project (use import_media first). Use list_project_items to find the item_id.
+
+After creation, the new sequence becomes active automatically.
+
+Example: create_sequence_from_clip({ item_id: "interview.mp4", name: "Interview Edit" })
 Example: create_sequence_from_clip({ item_id: "abc123-node-id", name: "4K Sequence" })`,
             parameters: {
                 type: "object",
@@ -28,156 +28,156 @@ Example: create_sequence_from_clip({ item_id: "abc123-node-id", name: "4K Sequen
                 required: ["item_id", "name"],
             },
             handler: async (args) => {
-                const script = buildToolScript(`
-          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
-          if (!item) return __error("Project item not found: ${escapeForExtendScript(args.item_id)}");
-
-          // PP 2026: createNewSequenceFromClip does NOT exist. Use qe.project.newSequence()
-          // with a default preset, then conform the sequence settings to match the clip.
-          app.enableQE();
-          var seqName = "${escapeForExtendScript(args.name)}";
-
-          // The default preset path is version-resilient: try several known
-          // install locations (Windows and macOS) and use the first
-          // .sqpreset file that exists.
-          var presetCandidates = [
-            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro 2026\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
-            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro 2025\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
-            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro 2024\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
-            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro CC 2023\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
-            "/Applications/Adobe Premiere Pro 2026/Adobe Premiere Pro 2026.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset",
-            "/Applications/Adobe Premiere Pro 2025/Adobe Premiere Pro 2025.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset",
-            "/Applications/Adobe Premiere Pro 2024/Adobe Premiere Pro 2024.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset",
-            "/Applications/Adobe Premiere Pro CC 2023/Adobe Premiere Pro CC 2023.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset"
-          ];
-          var defaultPreset = null;
-          for (var pc = 0; pc < presetCandidates.length; pc++) {
-            try {
-              var pf = new File(presetCandidates[pc]);
-              if (pf.exists) { defaultPreset = presetCandidates[pc]; break; }
-            } catch(ePf) {}
-          }
-          if (!defaultPreset) return __error("No default sequence preset (.sqpreset) could be found on this system. Use create_sequence with an explicit preset_path to make the sequence first, then match settings manually.");
-
-          var ok = qe.project.newSequence(seqName, defaultPreset);
-          if (!ok) return __error("Failed to create sequence via qe.project.newSequence (preset: " + defaultPreset + ")");
-
-          var seq = null;
-          for (var i = 0; i < app.project.sequences.numSequences; i++) {
-            if (app.project.sequences[i].name === seqName) {
-              seq = app.project.sequences[i];
-              break;
-            }
-          }
-          if (!seq) return __error("Sequence created but not found by name");
-
-          // --- Conform sequence to clip video properties ---------------------
-          // Gather the clip's real video props from multiple sources, since no
-          // single API exposes all of width/height/frameRate/PAR.
-          var clipW = 0, clipH = 0, clipFps = 0, clipPar = 0;
-          var sources = [];
-
-          // 1) getVideoMetaData() -> frameWidth/frameHeight/frameRate (best for dimensions)
-          try {
-            var vmd = item.getVideoMetaData ? item.getVideoMetaData() : null;
-            if (vmd) {
-              if (vmd.frameWidth) { clipW = vmd.frameWidth; }
-              if (vmd.frameHeight) { clipH = vmd.frameHeight; }
-              if (vmd.frameRate) { clipFps = vmd.frameRate; }
-              sources.push("getVideoMetaData");
-            }
-          } catch(eVmd) {}
-
-          // 2) getFootageInterpretation() -> frameRate / pixelAspectRatio (locale-independent)
-          try {
-            var interp = item.getFootageInterpretation ? item.getFootageInterpretation() : null;
-            if (interp) {
-              if (interp.frameRate && !clipFps) { clipFps = interp.frameRate; }
-              if (interp.pixelAspectRatio) { clipPar = interp.pixelAspectRatio; }
-              sources.push("getFootageInterpretation");
-            }
-          } catch(eInterp) {}
-
-          // 3) Fallback for dimensions: probe the clip's videoComponents / direct width-height
-          if (!clipW || !clipH) {
-            try {
-              if (item.width && item.height) {
-                clipW = clipW || item.width;
-                clipH = clipH || item.height;
-                sources.push("item.width/height");
-              }
-            } catch(eWH) {}
-          }
-
-          // Apply gathered props onto the sequence settings.
-          var conformed = false;
-          var applied = {};
-          try {
-            var settings = seq.getSettings();
-            if (settings) {
-              if (clipW) { settings.videoFrameWidth = clipW; applied.videoFrameWidth = clipW; }
-              if (clipH) { settings.videoFrameHeight = clipH; applied.videoFrameHeight = clipH; }
-              if (clipFps && settings.videoFrameRate) {
-                var frTicks = Math.round(TICKS_PER_SECOND / clipFps);
-                settings.videoFrameRate.ticks = String(frTicks);
-                applied.videoFrameRate = clipFps;
-              }
-              if (clipPar) {
-                try { settings.videoPixelAspectRatio = clipPar; applied.videoPixelAspectRatio = clipPar; } catch(ePar) {}
-              }
-              seq.setSettings(settings);
-              // Verify the change actually took effect (some props are read-only per preset).
-              var verify = seq.getSettings();
-              if (verify && ((clipW && verify.videoFrameWidth === clipW) || (clipH && verify.videoFrameHeight === clipH))) {
-                conformed = true;
-              } else if ((clipW || clipH || clipFps || clipPar) && verify) {
-                // setSettings did not throw; treat any applied prop as conformed best-effort.
-                conformed = true;
-              }
-            }
-          } catch(eConf) {
-            applied.error = eConf.toString();
-          }
-
-          var conformNote;
-          if (conformed) {
-            conformNote = "conformed to clip (sources: " + sources.join(",") + ")";
-          } else if (!clipW && !clipH && !clipFps && !clipPar) {
-            conformNote = "default preset used (could not read clip video props)";
-          } else {
-            conformNote = "default preset used (setSettings did not apply clip props)";
-          }
-
-          app.project.activeSequence = seq;
-          return __result({
-            created: true,
-            name: seq.name,
-            id: seq.sequenceID,
-            width: seq.frameSizeHorizontal,
-            height: seq.frameSizeVertical,
-            conformed: conformed,
-            appliedSettings: applied,
-            clipProps: { width: clipW, height: clipH, frameRate: clipFps, pixelAspectRatio: clipPar },
-            note: conformNote
-          });
+                const script = buildToolScript(`
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Project item not found: ${escapeForExtendScript(args.item_id)}");
+
+          // PP 2026: createNewSequenceFromClip does NOT exist. Use qe.project.newSequence()
+          // with a default preset, then conform the sequence settings to match the clip.
+          app.enableQE();
+          var seqName = "${escapeForExtendScript(args.name)}";
+
+          // The default preset path is version-resilient: try several known
+          // install locations (Windows and macOS) and use the first
+          // .sqpreset file that exists.
+          var presetCandidates = [
+            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro 2026\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
+            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro 2025\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
+            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro 2024\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
+            "C:\\\\Program Files\\\\Adobe\\\\Adobe Premiere Pro CC 2023\\\\Settings\\\\SequencePresets\\\\HD 1080p\\\\HD 1080p 23.976 fps.sqpreset",
+            "/Applications/Adobe Premiere Pro 2026/Adobe Premiere Pro 2026.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset",
+            "/Applications/Adobe Premiere Pro 2025/Adobe Premiere Pro 2025.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset",
+            "/Applications/Adobe Premiere Pro 2024/Adobe Premiere Pro 2024.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset",
+            "/Applications/Adobe Premiere Pro CC 2023/Adobe Premiere Pro CC 2023.app/Contents/SequencePresets/HD 1080p/HD 1080p 23.976 fps.sqpreset"
+          ];
+          var defaultPreset = null;
+          for (var pc = 0; pc < presetCandidates.length; pc++) {
+            try {
+              var pf = new File(presetCandidates[pc]);
+              if (pf.exists) { defaultPreset = presetCandidates[pc]; break; }
+            } catch(ePf) {}
+          }
+          if (!defaultPreset) return __error("No default sequence preset (.sqpreset) could be found on this system. Use create_sequence with an explicit preset_path to make the sequence first, then match settings manually.");
+
+          var ok = qe.project.newSequence(seqName, defaultPreset);
+          if (!ok) return __error("Failed to create sequence via qe.project.newSequence (preset: " + defaultPreset + ")");
+
+          var seq = null;
+          for (var i = 0; i < app.project.sequences.numSequences; i++) {
+            if (app.project.sequences[i].name === seqName) {
+              seq = app.project.sequences[i];
+              break;
+            }
+          }
+          if (!seq) return __error("Sequence created but not found by name");
+
+          // --- Conform sequence to clip video properties ---------------------
+          // Gather the clip's real video props from multiple sources, since no
+          // single API exposes all of width/height/frameRate/PAR.
+          var clipW = 0, clipH = 0, clipFps = 0, clipPar = 0;
+          var sources = [];
+
+          // 1) getVideoMetaData() -> frameWidth/frameHeight/frameRate (best for dimensions)
+          try {
+            var vmd = item.getVideoMetaData ? item.getVideoMetaData() : null;
+            if (vmd) {
+              if (vmd.frameWidth) { clipW = vmd.frameWidth; }
+              if (vmd.frameHeight) { clipH = vmd.frameHeight; }
+              if (vmd.frameRate) { clipFps = vmd.frameRate; }
+              sources.push("getVideoMetaData");
+            }
+          } catch(eVmd) {}
+
+          // 2) getFootageInterpretation() -> frameRate / pixelAspectRatio (locale-independent)
+          try {
+            var interp = item.getFootageInterpretation ? item.getFootageInterpretation() : null;
+            if (interp) {
+              if (interp.frameRate && !clipFps) { clipFps = interp.frameRate; }
+              if (interp.pixelAspectRatio) { clipPar = interp.pixelAspectRatio; }
+              sources.push("getFootageInterpretation");
+            }
+          } catch(eInterp) {}
+
+          // 3) Fallback for dimensions: probe the clip's videoComponents / direct width-height
+          if (!clipW || !clipH) {
+            try {
+              if (item.width && item.height) {
+                clipW = clipW || item.width;
+                clipH = clipH || item.height;
+                sources.push("item.width/height");
+              }
+            } catch(eWH) {}
+          }
+
+          // Apply gathered props onto the sequence settings.
+          var conformed = false;
+          var applied = {};
+          try {
+            var settings = seq.getSettings();
+            if (settings) {
+              if (clipW) { settings.videoFrameWidth = clipW; applied.videoFrameWidth = clipW; }
+              if (clipH) { settings.videoFrameHeight = clipH; applied.videoFrameHeight = clipH; }
+              if (clipFps && settings.videoFrameRate) {
+                var frTicks = Math.round(TICKS_PER_SECOND / clipFps);
+                settings.videoFrameRate.ticks = String(frTicks);
+                applied.videoFrameRate = clipFps;
+              }
+              if (clipPar) {
+                try { settings.videoPixelAspectRatio = clipPar; applied.videoPixelAspectRatio = clipPar; } catch(ePar) {}
+              }
+              seq.setSettings(settings);
+              // Verify the change actually took effect (some props are read-only per preset).
+              var verify = seq.getSettings();
+              if (verify && ((clipW && verify.videoFrameWidth === clipW) || (clipH && verify.videoFrameHeight === clipH))) {
+                conformed = true;
+              } else if ((clipW || clipH || clipFps || clipPar) && verify) {
+                // setSettings did not throw; treat any applied prop as conformed best-effort.
+                conformed = true;
+              }
+            }
+          } catch(eConf) {
+            applied.error = eConf.toString();
+          }
+
+          var conformNote;
+          if (conformed) {
+            conformNote = "conformed to clip (sources: " + sources.join(",") + ")";
+          } else if (!clipW && !clipH && !clipFps && !clipPar) {
+            conformNote = "default preset used (could not read clip video props)";
+          } else {
+            conformNote = "default preset used (setSettings did not apply clip props)";
+          }
+
+          app.project.activeSequence = seq;
+          return __result({
+            created: true,
+            name: seq.name,
+            id: seq.sequenceID,
+            width: seq.frameSizeHorizontal,
+            height: seq.frameSizeVertical,
+            conformed: conformed,
+            appliedSettings: applied,
+            clipProps: { width: clipW, height: clipH, frameRate: clipFps, pixelAspectRatio: clipPar },
+            note: conformNote
+          });
         `);
                 return sendCommand(script, bridgeOptions);
             },
         },
         add_audio_track: {
-            description: `Add a new audio track to the active sequence.
-
-Preconditions: An active sequence must exist.
-
-Track types:
-- "standard" (default): Standard stereo audio track — works with most clips.
-- "5.1": 5.1 surround audio track.
-- "adaptive": Adaptive audio track (multi-channel routing).
-- "mono": Mono audio track.
-
-The new track is added at the bottom of the audio tracks (highest index). Its index can be found via list_sequence_tracks after creation.
-
-Example: add_audio_track({})  — adds a standard stereo track
+            description: `Add a new audio track to the active sequence.
+
+Preconditions: An active sequence must exist.
+
+Track types:
+- "standard" (default): Standard stereo audio track — works with most clips.
+- "5.1": 5.1 surround audio track.
+- "adaptive": Adaptive audio track (multi-channel routing).
+- "mono": Mono audio track.
+
+The new track is added at the bottom of the audio tracks (highest index). Its index can be found via list_sequence_tracks after creation.
+
+Example: add_audio_track({})  — adds a standard stereo track
 Example: add_audio_track({ track_type: "mono", name: "Narration" })`,
             parameters: {
                 type: "object",
@@ -204,59 +204,59 @@ Example: add_audio_track({ track_type: "mono", name: "Narration" })`,
                     mono: "3", // kAudioTrackType_Mono
                 };
                 const typeCode = typeMap[trackType] ?? "0";
-                const script = buildToolScript(`
-          var seq = app.project.activeSequence;
-          if (!seq) return __error("No active sequence");
-
-          var tracksBefore = seq.audioTracks.numTracks;
-          // TrackCollection has no addTrack. Use seq.addTrack (pre-PP2026) then QE fallback.
-          app.enableQE();
-          var __added = false;
-          try { if (seq.addTrack) { seq.addTrack("audio", 1); __added = true; } } catch(e) {}
-          if (!__added) {
-            try {
-              var __qs = qe.project.getActiveSequence();
-              if (__qs && __qs.addAudioTrack) { __qs.addAudioTrack(${typeCode}); __added = true; }
-            } catch(e2) {}
-          }
-
-          var tracksAfter = seq.audioTracks.numTracks;
-          if (tracksAfter <= tracksBefore) return __error("Failed to add audio track — adding tracks is not supported via ExtendScript in this Premiere Pro version. Use Sequence > Add Tracks in the UI.");
-
-          var newTrackIndex = tracksAfter - 1;
-          var newTrack = seq.audioTracks[newTrackIndex];
-
-          ${args.name ? `
-          if (newTrack && newTrack.name !== undefined) {
-            newTrack.name = "${escapeForExtendScript(args.name)}";
-          }
-          ` : ""}
-
-          return __result({
-            added: true,
-            trackIndex: newTrackIndex,
-            trackType: "${trackType}",
-            totalAudioTracks: tracksAfter
-          });
+                const script = buildToolScript(`
+          var seq = app.project.activeSequence;
+          if (!seq) return __error("No active sequence");
+
+          var tracksBefore = seq.audioTracks.numTracks;
+          // TrackCollection has no addTrack. Use seq.addTrack (pre-PP2026) then QE fallback.
+          app.enableQE();
+          var __added = false;
+          try { if (seq.addTrack) { seq.addTrack("audio", 1); __added = true; } } catch(e) {}
+          if (!__added) {
+            try {
+              var __qs = qe.project.getActiveSequence();
+              if (__qs && __qs.addAudioTrack) { __qs.addAudioTrack(${typeCode}); __added = true; }
+            } catch(e2) {}
+          }
+
+          var tracksAfter = seq.audioTracks.numTracks;
+          if (tracksAfter <= tracksBefore) return __error("Failed to add audio track — adding tracks is not supported via ExtendScript in this Premiere Pro version. Use Sequence > Add Tracks in the UI.");
+
+          var newTrackIndex = tracksAfter - 1;
+          var newTrack = seq.audioTracks[newTrackIndex];
+
+          ${args.name ? `
+          if (newTrack && newTrack.name !== undefined) {
+            newTrack.name = "${escapeForExtendScript(args.name)}";
+          }
+          ` : ""}
+
+          return __result({
+            added: true,
+            trackIndex: newTrackIndex,
+            trackType: "${trackType}",
+            totalAudioTracks: tracksAfter
+          });
         `);
                 return sendCommand(script, bridgeOptions);
             },
         },
         set_track_volume: {
-            description: `Set the volume level for an entire audio track in the active sequence.
-
-This sets the track-level volume (the fader in the Audio Track Mixer), which affects all clips on the track. To set individual clip volume, use set_clip_properties or add_keyframe on the clip's Volume property instead.
-
-Preconditions: An active sequence must exist with audio tracks.
-
-Volume is specified in decibels (dB):
-- 0 dB = unity gain (no change from original level)
-- Positive values (e.g., +6 dB) boost the level
-- Negative values (e.g., -12 dB) reduce the level
-- -∞ (use -96 or lower) effectively mutes the track
-
-Example: set_track_volume({ track_index: 0, volume_db: -6 })   — reduce A1 by 6 dB
-Example: set_track_volume({ track_index: 1, volume_db: 0 })    — set A2 to unity gain
+            description: `Set the volume level for an entire audio track in the active sequence.
+
+This sets the track-level volume (the fader in the Audio Track Mixer), which affects all clips on the track. To set individual clip volume, use set_clip_properties or add_keyframe on the clip's Volume property instead.
+
+Preconditions: An active sequence must exist with audio tracks.
+
+Volume is specified in decibels (dB):
+- 0 dB = unity gain (no change from original level)
+- Positive values (e.g., +6 dB) boost the level
+- Negative values (e.g., -12 dB) reduce the level
+- -∞ (use -96 or lower) effectively mutes the track
+
+Example: set_track_volume({ track_index: 0, volume_db: -6 })   — reduce A1 by 6 dB
+Example: set_track_volume({ track_index: 1, volume_db: 0 })    — set A2 to unity gain
 Example: set_track_volume({ track_index: 2, volume_db: -96 })  — effectively mute A3`,
             parameters: {
                 type: "object",
@@ -273,120 +273,120 @@ Example: set_track_volume({ track_index: 2, volume_db: -96 })  — effectively m
                 required: ["track_index", "volume_db"],
             },
             handler: async (args) => {
-                const script = buildToolScript(`
-          var seq = app.project.activeSequence;
-          if (!seq) return __error("No active sequence");
-
-          if (${args.track_index} >= seq.audioTracks.numTracks) {
-            return __error("Audio track index out of range: " + ${args.track_index} + " (sequence has " + seq.audioTracks.numTracks + " audio tracks)");
-          }
-
-          var track = seq.audioTracks[${args.track_index}];
-          if (!track) return __error("Track is undefined at index " + ${args.track_index});
-
-          var volumeSet = false;
-          var attemptedPaths = [];
-
-          // Try 1: DOM track components (older PP exposed track-level volume here;
-          // verified absent in PP 2026)
-          if (track.components && track.components.numItems) {
-            attemptedPaths.push("DOM components");
-            var tcomp = __findComponent(track,
-              ["AE.ADBE Audio Levels", "audioVolume", "audioGain", "ADBE Audio Levels"],
-              ["Volume", "Volumen", "Audio Levels", "Niveles de audio", "Lautstärke"]
-            );
-            if (tcomp) {
-              var tprop = __findProp(tcomp, ["Level", "Volume", "Nivel", "Volumen"]);
-              if (tprop) { try { tprop.setValue(${args.volume_db}, true); volumeSet = true; } catch (e1) {} }
-            }
-          }
-
-          // Try 2: direct track.volume property (older PP)
-          if (!volumeSet && track.volume !== undefined) {
-            attemptedPaths.push("track.volume");
-            try { track.volume = ${args.volume_db}; volumeSet = true; } catch (e2) {}
-          }
-
-          // Try 3: QE audio track setVolume (PP 2026 has setMute/setLock/setName only,
-          // verified at runtime; setVolume undefined)
-          if (!volumeSet) {
-            attemptedPaths.push("QE setVolume");
-            try {
-              app.enableQE();
-              var qeATrack = qe.project.getActiveSequence().getAudioTrackAt(${args.track_index});
-              if (qeATrack && typeof qeATrack.setVolume === "function") {
-                qeATrack.setVolume(${args.volume_db});
-                volumeSet = true;
-              }
-            } catch (e3) {}
-          }
-
-          // PP 2026 WORKAROUND: apply the volume_db to all clips on the track
-          // individually. This is the practical equivalent of setting the track
-          // fader since Premiere mixes clip volume into the master output.
-          // Returns success with workaround=true so callers know it's per-clip.
-          if (!volumeSet) {
-            attemptedPaths.push("per-clip fallback");
-            var clipsAffected = 0;
-            var clipsTotal = track.clips.numItems;
-            for (var ci = 0; ci < clipsTotal; ci++) {
-              var aClip = track.clips[ci];
-              // Use locale-resilient lookup
-              var volComp = __findIntrinsic(aClip, "volume");
-              if (volComp) {
-                var levelProp = __findProp(volComp, ["Level", "Nivel", "Volume", "Volumen", "Pegel"]);
-                if (levelProp) {
-                  try { levelProp.setValue(${args.volume_db}, true); clipsAffected++; } catch (eClip) {}
-                }
-              }
-            }
-            if (clipsAffected > 0) {
-              return __result({
-                trackIndex: ${args.track_index},
-                volumeDb: ${args.volume_db},
-                trackName: track.name || ("A" + (${args.track_index} + 1)),
-                workaround: "per-clip-volume",
-                clipsAffected: clipsAffected,
-                clipsTotal: clipsTotal,
-                note: "PP 2026 doesn't expose track-level volume via ExtendScript. Applied " + ${args.volume_db} + "dB to each of the " + clipsAffected + " clips on this track — equivalent net mixing effect to the track fader."
-              });
-            }
-            return __error("set_track_volume: track-level API not available in PP 2026 and no clips on this track to apply per-clip workaround. Attempted: " + attemptedPaths.join(", ") + ". Add clips to the track or adjust the fader manually in the Audio Track Mixer panel.");
-          }
-
-          if (!volumeSet) {
-            return __error("Could not set volume on track " + ${args.track_index} + ". Track may not support direct volume setting via this API. Try using add_keyframe on the track's Volume property instead.");
-          }
-
-          return __result({
-            trackIndex: ${args.track_index},
-            volumeDb: ${args.volume_db},
-            trackName: track.name || ("A" + (${args.track_index} + 1))
-          });
+                const script = buildToolScript(`
+          var seq = app.project.activeSequence;
+          if (!seq) return __error("No active sequence");
+
+          if (${args.track_index} >= seq.audioTracks.numTracks) {
+            return __error("Audio track index out of range: " + ${args.track_index} + " (sequence has " + seq.audioTracks.numTracks + " audio tracks)");
+          }
+
+          var track = seq.audioTracks[${args.track_index}];
+          if (!track) return __error("Track is undefined at index " + ${args.track_index});
+
+          var volumeSet = false;
+          var attemptedPaths = [];
+
+          // Try 1: DOM track components (older PP exposed track-level volume here;
+          // verified absent in PP 2026)
+          if (track.components && track.components.numItems) {
+            attemptedPaths.push("DOM components");
+            var tcomp = __findComponent(track,
+              ["AE.ADBE Audio Levels", "audioVolume", "audioGain", "ADBE Audio Levels"],
+              ["Volume", "Volumen", "Audio Levels", "Niveles de audio", "Lautstärke"]
+            );
+            if (tcomp) {
+              var tprop = __findProp(tcomp, ["Level", "Volume", "Nivel", "Volumen"]);
+              if (tprop) { try { tprop.setValue(${args.volume_db}, true); volumeSet = true; } catch (e1) {} }
+            }
+          }
+
+          // Try 2: direct track.volume property (older PP)
+          if (!volumeSet && track.volume !== undefined) {
+            attemptedPaths.push("track.volume");
+            try { track.volume = ${args.volume_db}; volumeSet = true; } catch (e2) {}
+          }
+
+          // Try 3: QE audio track setVolume (PP 2026 has setMute/setLock/setName only,
+          // verified at runtime; setVolume undefined)
+          if (!volumeSet) {
+            attemptedPaths.push("QE setVolume");
+            try {
+              app.enableQE();
+              var qeATrack = qe.project.getActiveSequence().getAudioTrackAt(${args.track_index});
+              if (qeATrack && typeof qeATrack.setVolume === "function") {
+                qeATrack.setVolume(${args.volume_db});
+                volumeSet = true;
+              }
+            } catch (e3) {}
+          }
+
+          // PP 2026 WORKAROUND: apply the volume_db to all clips on the track
+          // individually. This is the practical equivalent of setting the track
+          // fader since Premiere mixes clip volume into the master output.
+          // Returns success with workaround=true so callers know it's per-clip.
+          if (!volumeSet) {
+            attemptedPaths.push("per-clip fallback");
+            var clipsAffected = 0;
+            var clipsTotal = track.clips.numItems;
+            for (var ci = 0; ci < clipsTotal; ci++) {
+              var aClip = track.clips[ci];
+              // Use locale-resilient lookup
+              var volComp = __findIntrinsic(aClip, "volume");
+              if (volComp) {
+                var levelProp = __findProp(volComp, ["Level", "Nivel", "Volume", "Volumen", "Pegel"]);
+                if (levelProp) {
+                  try { levelProp.setValue(${args.volume_db}, true); clipsAffected++; } catch (eClip) {}
+                }
+              }
+            }
+            if (clipsAffected > 0) {
+              return __result({
+                trackIndex: ${args.track_index},
+                volumeDb: ${args.volume_db},
+                trackName: track.name || ("A" + (${args.track_index} + 1)),
+                workaround: "per-clip-volume",
+                clipsAffected: clipsAffected,
+                clipsTotal: clipsTotal,
+                note: "PP 2026 doesn't expose track-level volume via ExtendScript. Applied " + ${args.volume_db} + "dB to each of the " + clipsAffected + " clips on this track — equivalent net mixing effect to the track fader."
+              });
+            }
+            return __error("set_track_volume: track-level API not available in PP 2026 and no clips on this track to apply per-clip workaround. Attempted: " + attemptedPaths.join(", ") + ". Add clips to the track or adjust the fader manually in the Audio Track Mixer panel.");
+          }
+
+          if (!volumeSet) {
+            return __error("Could not set volume on track " + ${args.track_index} + ". Track may not support direct volume setting via this API. Try using add_keyframe on the track's Volume property instead.");
+          }
+
+          return __result({
+            trackIndex: ${args.track_index},
+            volumeDb: ${args.volume_db},
+            trackName: track.name || ("A" + (${args.track_index} + 1))
+          });
         `);
                 return sendCommand(script, bridgeOptions);
             },
         },
         nest_sequence: {
-            description: `Nest the currently selected clips into a new sub-sequence (nested sequence).
-
-This replaces the selected clips on the timeline with a single clip that contains a new sub-sequence with the original clips. Nesting is useful for:
-- Grouping clips to apply a single effect to all of them
-- Organizing complex timelines
-- Applying motion/transform to a group of clips
-- Creating "packages" for reuse
-
-Preconditions:
-1. An active sequence must exist.
-2. Clips must be selected before calling this tool. Use set_clip_selection or select_clips_by_name to select clips first.
-3. At least one clip must be selected.
-
-After nesting, the new sub-sequence appears in the project panel and can be opened and edited independently.
-
-Example workflow:
-  1. select_clips_by_name({ names: ["clip1.mp4", "clip2.mp4"] })
-  2. nest_sequence({ name: "Intro Package" })
-
+            description: `Nest the currently selected clips into a new sub-sequence (nested sequence).
+
+This replaces the selected clips on the timeline with a single clip that contains a new sub-sequence with the original clips. Nesting is useful for:
+- Grouping clips to apply a single effect to all of them
+- Organizing complex timelines
+- Applying motion/transform to a group of clips
+- Creating "packages" for reuse
+
+Preconditions:
+1. An active sequence must exist.
+2. Clips must be selected before calling this tool. Use set_clip_selection or select_clips_by_name to select clips first.
+3. At least one clip must be selected.
+
+After nesting, the new sub-sequence appears in the project panel and can be opened and edited independently.
+
+Example workflow:
+  1. select_clips_by_name({ names: ["clip1.mp4", "clip2.mp4"] })
+  2. nest_sequence({ name: "Intro Package" })
+
 Example: nest_sequence({ name: "Color Grade Group" })`,
             parameters: {
                 type: "object",
@@ -399,74 +399,74 @@ Example: nest_sequence({ name: "Color Grade Group" })`,
                 required: ["name"],
             },
             handler: async (args) => {
-                const script = buildToolScript(`
-          var seq = app.project.activeSequence;
-          if (!seq) return __error("No active sequence");
-
-          // Check if any clips are selected
-          var selectedCount = 0;
-          for (var v = 0; v < seq.videoTracks.numTracks; v++) {
-            var track = seq.videoTracks[v];
-            for (var c = 0; c < track.clips.numItems; c++) {
-              if (track.clips[c].isSelected) selectedCount++;
-            }
-          }
-          for (var a = 0; a < seq.audioTracks.numTracks; a++) {
-            var atrack = seq.audioTracks[a];
-            for (var ac = 0; ac < atrack.clips.numItems; ac++) {
-              if (atrack.clips[ac].isSelected) selectedCount++;
-            }
-          }
-
-          if (selectedCount === 0) {
-            return __error("No clips are selected. Use set_clip_selection or select_clips_by_name to select clips before nesting.");
-          }
-
-          // IMPORTANT behavior note: the Premiere DOM does NOT expose a true
-          // "Nest selected clips" (which replaces the selection on the timeline
-          // with a nested-sequence clip). seq.createSubsequence() builds a NEW
-          // sub-sequence from the sequence's IN/OUT range (or the whole sequence
-          // when no in/out is set) — it does NOT consume the selection and does
-          // NOT replace clips on this timeline. We attempt it here, but report
-          // the real behavior so callers are not misled.
-          var nestedSeq = null;
-          var createError = null;
-          try {
-            // Some versions accept a boolean (ignoreMapping/ignoreTrackTargeting); guard with try/catch.
-            try {
-              nestedSeq = seq.createSubsequence(true);
-            } catch(eArg) {
-              nestedSeq = seq.createSubsequence();
-            }
-          } catch(eSub) {
-            createError = eSub.toString();
-          }
-
-          if (!nestedSeq) {
-            return __error("createSubsequence failed" + (createError ? (": " + createError) : "") + ". The Premiere DOM has no true nest-selection API; this builds a sub-sequence from the sequence in/out range. Set sequence in/out points around the clips first, or nest manually in the UI.");
-          }
-
-          // Rename the resulting sub-sequence to the requested name (createSubsequence
-          // does not accept a name argument in current versions).
-          var renamed = false;
-          try {
-            if (nestedSeq.projectItem && nestedSeq.projectItem.name !== undefined) {
-              nestedSeq.projectItem.name = "${escapeForExtendScript(args.name)}";
-              renamed = true;
-            } else if (nestedSeq.name !== undefined) {
-              nestedSeq.name = "${escapeForExtendScript(args.name)}";
-              renamed = true;
-            }
-          } catch(eName) {}
-
-          return __result({
-            nested: true,
-            nestedSequenceName: nestedSeq.name,
-            nestedSequenceId: nestedSeq.sequenceID,
-            renamed: renamed,
-            selectedClips: selectedCount,
-            behaviorNote: "createSubsequence builds a sub-sequence from the sequence IN/OUT range (whole sequence if no in/out set). It does NOT replace the selected clips on this timeline and does NOT perform a true 'Nest'. The selection count is reported for reference only."
-          });
+                const script = buildToolScript(`
+          var seq = app.project.activeSequence;
+          if (!seq) return __error("No active sequence");
+
+          // Check if any clips are selected
+          var selectedCount = 0;
+          for (var v = 0; v < seq.videoTracks.numTracks; v++) {
+            var track = seq.videoTracks[v];
+            for (var c = 0; c < track.clips.numItems; c++) {
+              if (track.clips[c].isSelected) selectedCount++;
+            }
+          }
+          for (var a = 0; a < seq.audioTracks.numTracks; a++) {
+            var atrack = seq.audioTracks[a];
+            for (var ac = 0; ac < atrack.clips.numItems; ac++) {
+              if (atrack.clips[ac].isSelected) selectedCount++;
+            }
+          }
+
+          if (selectedCount === 0) {
+            return __error("No clips are selected. Use set_clip_selection or select_clips_by_name to select clips before nesting.");
+          }
+
+          // IMPORTANT behavior note: the Premiere DOM does NOT expose a true
+          // "Nest selected clips" (which replaces the selection on the timeline
+          // with a nested-sequence clip). seq.createSubsequence() builds a NEW
+          // sub-sequence from the sequence's IN/OUT range (or the whole sequence
+          // when no in/out is set) — it does NOT consume the selection and does
+          // NOT replace clips on this timeline. We attempt it here, but report
+          // the real behavior so callers are not misled.
+          var nestedSeq = null;
+          var createError = null;
+          try {
+            // Some versions accept a boolean (ignoreMapping/ignoreTrackTargeting); guard with try/catch.
+            try {
+              nestedSeq = seq.createSubsequence(true);
+            } catch(eArg) {
+              nestedSeq = seq.createSubsequence();
+            }
+          } catch(eSub) {
+            createError = eSub.toString();
+          }
+
+          if (!nestedSeq) {
+            return __error("createSubsequence failed" + (createError ? (": " + createError) : "") + ". The Premiere DOM has no true nest-selection API; this builds a sub-sequence from the sequence in/out range. Set sequence in/out points around the clips first, or nest manually in the UI.");
+          }
+
+          // Rename the resulting sub-sequence to the requested name (createSubsequence
+          // does not accept a name argument in current versions).
+          var renamed = false;
+          try {
+            if (nestedSeq.projectItem && nestedSeq.projectItem.name !== undefined) {
+              nestedSeq.projectItem.name = "${escapeForExtendScript(args.name)}";
+              renamed = true;
+            } else if (nestedSeq.name !== undefined) {
+              nestedSeq.name = "${escapeForExtendScript(args.name)}";
+              renamed = true;
+            }
+          } catch(eName) {}
+
+          return __result({
+            nested: true,
+            nestedSequenceName: nestedSeq.name,
+            nestedSequenceId: nestedSeq.sequenceID,
+            renamed: renamed,
+            selectedClips: selectedCount,
+            behaviorNote: "createSubsequence builds a sub-sequence from the sequence IN/OUT range (whole sequence if no in/out set). It does NOT replace the selected clips on this timeline and does NOT perform a true 'Nest'. The selection count is reported for reference only."
+          });
         `);
                 return sendCommand(script, bridgeOptions);
             },