@synthetic-ai/premiere-mcp 2.0.0

package/dist/tools/timeline.js

@@ -0,0 +1,575 @@
+import { buildToolScript, escapeForExtendScript } from "../bridge/script-builder.js";
+import { sendCommand } from "../bridge/file-bridge.js";
+export function getTimelineTools(bridgeOptions) {
+    return {
+        add_to_timeline: {
+            description: `Add a project item (clip, image, or audio file) to the active sequence timeline at a specific position.
+
+Preconditions: An active sequence must exist (use create_sequence or set_active_sequence first). The item must already be imported into the project (use import_media first).
+
+The clip is inserted using insert-edit semantics — content after the insertion point shifts forward. For overwrite-edit behavior, use overwrite_clip instead.
+
+Parameters:
+- item_id: The node ID from list_project_items, or the item's display name (partial match supported).
+- track_index: Video track index (0 = V1, 1 = V2, etc.). Higher tracks composite on top.
+- start_seconds: Timeline position in seconds where the clip should start (e.g., 10.5 = 10 seconds 12 frames at 24fps).
+- audio_track_index: Audio track index for the linked audio (default matches track_index).
+
+Example: add_to_timeline({ item_id: "interview.mp4", track_index: 0, start_seconds: 30, audio_track_index: 0 })`,
+            parameters: {
+                type: "object",
+                properties: {
+                    item_id: {
+                        type: "string",
+                        description: "Node ID or name of the project item to add",
+                    },
+                    track_index: {
+                        type: "number",
+                        description: "Video track index (0-based, default: 0)",
+                    },
+                    start_seconds: {
+                        type: "number",
+                        description: "Start time in seconds on the timeline (default: 0)",
+                    },
+                    audio_track_index: {
+                        type: "number",
+                        description: "Audio track index for the audio portion (default: 0)",
+                    },
+                },
+                required: ["item_id"],
+            },
+            handler: async (args) => {
+                const trackIndex = args.track_index ?? 0;
+                const startSeconds = args.start_seconds ?? 0;
+                const audioTrackIndex = args.audio_track_index ?? 0;
+                const script = buildToolScript(`
+          var seq = app.project.activeSequence;
+          if (!seq) return __error("No active sequence");
+          
+          var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
+          if (!item) return __error("Project item not found: ${escapeForExtendScript(args.item_id)}");
+          
+          var startTicks = __secondsToTicks(${startSeconds}).toString();
+          seq.insertClip(item, startTicks, ${trackIndex}, ${audioTrackIndex});
+          
+          return __result({
+            added: true,
+            item: item.name,
+            trackIndex: ${trackIndex},
+            startSeconds: ${startSeconds}
+          });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        remove_from_timeline: {
+            description: "Remove a clip from the timeline",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip to remove",
+                    },
+                    ripple: {
+                        type: "boolean",
+                        description: "Whether to ripple delete (close the gap). Default: false",
+                    },
+                },
+                required: ["node_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          
+          var clip = result.clip;
+          clip.remove(${args.ripple ? "true" : "false"}, ${args.ripple ? "true" : "false"});
+          return __result({ removed: true, clipName: clip.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        move_clip: {
+            description: `Move a clip to a new timeline position, optionally changing its track.
+
+Preconditions: An active sequence must exist and the clip's node_id must be valid (get node IDs from get_active_sequence or list_sequence_tracks).
+
+The clip moves to the exact start time specified in seconds. If new_track_index is provided, the clip is also moved to that track. The audio/video link is maintained during the move.
+
+Note: This uses clip.moveToTime() which is the correct ExtendScript API — clip.start is read-only and cannot be assigned directly.
+
+Example: move_clip({ node_id: "abc123", new_start_seconds: 45.5 })
+Example: move_clip({ node_id: "abc123", new_start_seconds: 10.0, new_track_index: 1 })`,
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip to move",
+                    },
+                    new_start_seconds: {
+                        type: "number",
+                        description: "New start time in seconds",
+                    },
+                    new_track_index: {
+                        type: "number",
+                        description: "Optional new track index to move the clip to",
+                    },
+                },
+                required: ["node_id", "new_start_seconds"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+
+          var clip = result.clip;
+
+          // clip.start is read-only; clip.move(newInPointTime) is the documented DOM reposition.
+          var newTime = new Time();
+          newTime.seconds = ${args.new_start_seconds};
+          clip.move(newTime);
+
+          var trackChangeNote = null;
+          ${args.new_track_index !== undefined ? `
+          // DOM TrackItem has no track-change method; route via QE if available.
+          try {
+            app.enableQE();
+            var qeSeq = qe.project.getActiveSequence();
+            var qeTrack = result.trackType === "video" ? qeSeq.getVideoTrackAt(result.trackIndex) : qeSeq.getAudioTrackAt(result.trackIndex);
+            var qeClip = qeTrack.getItemAt(result.clipIndex);
+            qeClip.moveToTrack(${args.new_track_index});
+          } catch (e) {
+            trackChangeNote = "DOM track-change isn't supported; QE move failed: " + e.toString();
+          }
+          ` : ""}
+
+          return __result({
+            moved: true,
+            clipName: clip.name,
+            newStart: ${args.new_start_seconds},
+            trackChangeNote: trackChangeNote
+          });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        trim_clip: {
+            description: `Trim a clip's in-point and/or out-point on the timeline.
+
+Preconditions: Clip must exist on the active sequence (use node_id from get_active_sequence).
+
+Time values are in seconds relative to the clip's source media (not the timeline position). For example, if a 60-second clip starts at timeline position 10s, setting new_in_seconds=5 trims the first 5 seconds of the source, making the clip start 5s into the original footage.
+
+Note: Uses clip.setInPoint(time, 2) and clip.setOutPoint(time, 2) — the alignment constant 2 (kTime) is required. Direct assignment to clip.inPoint / clip.outPoint does not work in ExtendScript.
+
+Example: trim_clip({ node_id: "abc123", new_in_seconds: 2.0 })  — trim 2s off the start
+Example: trim_clip({ node_id: "abc123", new_out_seconds: 58.5 }) — trim the end to 58.5s
+Example: trim_clip({ node_id: "abc123", new_in_seconds: 1.0, new_out_seconds: 59.0 }) — trim both ends`,
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip to trim",
+                    },
+                    new_in_seconds: {
+                        type: "number",
+                        description: "New in-point in seconds (relative to clip's source media)",
+                    },
+                    new_out_seconds: {
+                        type: "number",
+                        description: "New out-point in seconds (relative to clip's source media)",
+                    },
+                },
+                required: ["node_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+
+          var clip = result.clip;
+
+          // DOM TrackItem has no setInPoint/setOutPoint; route the trim via QE if available.
+          var qeClip = null;
+          try {
+            app.enableQE();
+            var qeSeq = qe.project.getActiveSequence();
+            var qeTrack = result.trackType === "video" ? qeSeq.getVideoTrackAt(result.trackIndex) : qeSeq.getAudioTrackAt(result.trackIndex);
+            qeClip = qeTrack.getItemAt(result.clipIndex);
+          } catch (e) {
+            qeClip = null;
+          }
+
+          if (!qeClip) {
+            return __error("Timeline trim isn't supported via this path (DOM TrackItem has no setInPoint/setOutPoint, and QE is unavailable)");
+          }
+
+          var didTrim = false;
+          ${args.new_in_seconds !== undefined ? `
+          qeClip.setInPoint(__secondsToTicks(${args.new_in_seconds}).toString());
+          didTrim = true;
+          ` : ""}
+          ${args.new_out_seconds !== undefined ? `
+          qeClip.setOutPoint(__secondsToTicks(${args.new_out_seconds}).toString());
+          didTrim = true;
+          ` : ""}
+
+          return __result({
+            trimmed: didTrim,
+            clipName: clip.name,
+            newInSeconds: ${args.new_in_seconds !== undefined ? args.new_in_seconds : "null"},
+            newOutSeconds: ${args.new_out_seconds !== undefined ? args.new_out_seconds : "null"}
+          });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        split_clip: {
+            description: `Split (razor cut) a clip at a specific timeline position. Uses QE DOM.
+
+Preconditions: An active sequence must exist with at least one clip on the specified track. The time_seconds must fall within a clip on the specified track — splitting empty space has no effect.
+
+After the split, the original clip becomes two separate clips that can be independently moved, trimmed, or deleted.
+
+Example: split_clip({ time_seconds: 30.0 })  — split V1 at 30 seconds
+Example: split_clip({ time_seconds: 15.5, track_index: 1, track_type: "video" })`,
+            parameters: {
+                type: "object",
+                properties: {
+                    time_seconds: {
+                        type: "number",
+                        description: "Time position in seconds where to split",
+                    },
+                    track_index: {
+                        type: "number",
+                        description: "Track index (0-based)",
+                    },
+                    track_type: {
+                        type: "string",
+                        enum: ["video", "audio"],
+                        description: "Track type (default: video)",
+                    },
+                },
+                required: ["time_seconds"],
+            },
+            handler: async (args) => {
+                const trackType = args.track_type || "video";
+                const trackIndex = args.track_index ?? 0;
+                const script = buildToolScript(`
+          app.enableQE();
+          var seq = qe.project.getActiveSequence();
+          if (!seq) return __error("No active sequence (QE)");
+          
+          var track = ${trackType === "video" ? `seq.getVideoTrackAt(${trackIndex})` : `seq.getAudioTrackAt(${trackIndex})`};
+          if (!track) return __error("Track not found");
+          
+          var timeTicks = __secondsToTicks(${args.time_seconds}).toString();
+          track.razor(timeTicks);
+          
+          return __result({ split: true, atSeconds: ${args.time_seconds}, trackIndex: ${trackIndex}, trackType: "${trackType}" });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        duplicate_clip: {
+            description: "Duplicate a clip on the timeline (copy to same position on next available track)",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip to duplicate",
+                    },
+                },
+                required: ["node_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          
+          var clip = result.clip;
+          var seq = app.project.activeSequence;
+          var projectItem = clip.projectItem;
+          
+          if (!projectItem) return __error("Cannot find source project item for clip");
+          
+          var newTrackIndex = result.trackIndex + 1;
+          var startTicks = clip.start.ticks;
+          
+          seq.insertClip(projectItem, startTicks, newTrackIndex, newTrackIndex);
+          
+          return __result({ duplicated: true, clipName: clip.name, newTrackIndex: newTrackIndex });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        enable_disable_clip: {
+            description: "Enable or disable a clip on the timeline",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip",
+                    },
+                    enabled: {
+                        type: "boolean",
+                        description: "Set to true to enable, false to disable",
+                    },
+                },
+                required: ["node_id", "enabled"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          
+          // PP 2026: clip.disabled is a property, clip.setDisabled() does not exist.
+          try {
+            result.clip.disabled = ${args.enabled ? "false" : "true"};
+          } catch(e1) {
+            try { result.clip.setDisabled(${args.enabled ? "false" : "true"}); } catch(e2) {}
+          }
+          return __result({ clipName: result.clip.name, enabled: ${args.enabled} });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        set_clip_properties: {
+            description: "Set properties on a clip (opacity, speed, etc.)",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip",
+                    },
+                    opacity: {
+                        type: "number",
+                        description: "Opacity value (0-100)",
+                    },
+                    speed: {
+                        type: "number",
+                        description: "Playback speed multiplier (1.0 = normal, 2.0 = double speed)",
+                    },
+                    scale: {
+                        type: "number",
+                        description: "Scale percentage (100 = original size)",
+                    },
+                    position_x: {
+                        type: "number",
+                        description: "Horizontal position",
+                    },
+                    position_y: {
+                        type: "number",
+                        description: "Vertical position",
+                    },
+                    rotation: {
+                        type: "number",
+                        description: "Rotation in degrees",
+                    },
+                },
+                required: ["node_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          
+          var clip = result.clip;
+          var changes = {};
+          
+          ${args.opacity !== undefined ? `
+          // Set opacity via the intrinsic Opacity component (locale-independent)
+          var opacityComp = __findIntrinsic(clip, "opacity");
+          if (opacityComp) {
+            var opacityProp = __findProp(opacityComp, ["Opacity", "Opacidad", "Deckkraft", "Opacité"]);
+            if (opacityProp) {
+              opacityProp.setValue(${args.opacity}, true);
+              changes.opacity = ${args.opacity};
+            }
+          }
+          ` : ""}
+
+          ${args.speed !== undefined ? `
+          // PP 2026 setSpeed: (percent, frameInterp, ripple, reverse, maintainAudioPitch).
+          app.enableQE();
+          var qeSeq = qe.project.getActiveSequence();
+          var qeTrack = result.trackType === "video" ? qeSeq.getVideoTrackAt(result.trackIndex) : qeSeq.getAudioTrackAt(result.trackIndex);
+          var qeClip = qeTrack.getItemAt(result.clipIndex);
+          var speedOk = false;
+          try { qeClip.setSpeed(${args.speed * 100}, "", false, false, false); speedOk = true; } catch (e1) {}
+          if (!speedOk) { try { qeClip.setSpeed(${args.speed * 100}, false, false); speedOk = true; } catch (e2) {} }
+          if (!speedOk) { try { qeClip.setSpeed(${args.speed * 100}); speedOk = true; } catch (e3) {} }
+          if (speedOk) { changes.speed = ${args.speed}; } else { changes.speedError = "setSpeed failed for all known signatures"; }
+          ` : ""}
+
+          ${args.scale !== undefined || args.position_x !== undefined || args.position_y !== undefined || args.rotation !== undefined ? `
+          // Set transform via the intrinsic Motion component (locale-independent)
+          var motionComp = __findIntrinsic(clip, "motion");
+          if (motionComp) {
+            ${args.scale !== undefined ? `
+            var scaleProp = __findProp(motionComp, ["Scale", "Escala", "Skalierung", "Échelle"]);
+            if (scaleProp) {
+              scaleProp.setValue(${args.scale}, true);
+              changes.scale = ${args.scale};
+            }` : ""}
+            ${args.position_x !== undefined || args.position_y !== undefined ? `
+            var posProp = __findProp(motionComp, ["Position", "Posición", "Position"]);
+            if (posProp) {
+              var posVal = posProp.getValue();
+              var px = posVal && typeof posVal === "object" && posVal.length >= 2 ? posVal[0] : 0;
+              var py = posVal && typeof posVal === "object" && posVal.length >= 2 ? posVal[1] : 0;
+              ${args.position_x !== undefined ? `px = ${args.position_x}; changes.position_x = ${args.position_x};` : ""}
+              ${args.position_y !== undefined ? `py = ${args.position_y}; changes.position_y = ${args.position_y};` : ""}
+              posProp.setValue([px, py], true);
+            }` : ""}
+            ${args.rotation !== undefined ? `
+            var rotProp = __findProp(motionComp, ["Rotation", "Rotación", "Drehung"]);
+            if (rotProp) {
+              rotProp.setValue(${args.rotation}, true);
+              changes.rotation = ${args.rotation};
+            }` : ""}
+          }
+          ` : ""}
+          
+          return __result({ updated: true, clipName: clip.name, changes: changes });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        replace_clip: {
+            description: "Replace a clip on the timeline with a different project item, preserving position and duration",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip to replace",
+                    },
+                    new_item_id: {
+                        type: "string",
+                        description: "Node ID or name of the new project item to replace with",
+                    },
+                },
+                required: ["node_id", "new_item_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var seq = app.project.activeSequence;
+          if (!seq) return __error("No active sequence");
+          
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          
+          var newItem = __findProjectItem("${escapeForExtendScript(args.new_item_id)}");
+          if (!newItem) return __error("Replacement project item not found: ${escapeForExtendScript(args.new_item_id)}");
+          
+          var clip = result.clip;
+          var oldName = clip.name;
+          var startTicks = clip.start.ticks;
+          var trackIndex = result.trackIndex;
+          var trackType = result.trackType;
+          
+          // Remove old clip
+          clip.remove(false, false);
+          
+          // Insert new clip at same position
+          if (trackType === "video") {
+            seq.insertClip(newItem, startTicks, trackIndex, trackIndex);
+          } else {
+            seq.insertClip(newItem, startTicks, 0, trackIndex);
+          }
+          
+          return __result({
+            replaced: true,
+            oldClip: oldName,
+            newClip: newItem.name,
+            trackIndex: trackIndex,
+            trackType: trackType
+          });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        speed_change: {
+            description: `Change the playback speed of a clip on the timeline.
+
+Preconditions: Active sequence required. Clip node_id must be valid.
+
+Speed is specified as a percentage number (NOT a multiplier):
+  - 100 = normal speed
+  - 200 = double speed (2x faster)
+  - 50  = half speed (slow motion)
+  - 25  = quarter speed
+
+Use reverse=true to play the clip backwards (negative speed). This internally uses a negative percentage.
+
+Note: setSpeed() expects a numeric percentage, not a string and not a decimal multiplier. Passing "50" as a string or 0.5 as a multiplier would fail.
+
+Example: speed_change({ node_id: "abc123", speed_percent: 200 })   — 2x speed
+Example: speed_change({ node_id: "abc123", speed_percent: 50, reverse: true }) — half speed, reversed`,
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip",
+                    },
+                    speed_percent: {
+                        type: "number",
+                        description: "Speed as percentage (100 = normal, 200 = double, 50 = half)",
+                    },
+                    reverse: {
+                        type: "boolean",
+                        description: "Reverse playback direction (default: false)",
+                    },
+                },
+                required: ["node_id", "speed_percent"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found");
+
+          var clip = result.clip;
+
+          // setSpeed expects a numeric percentage (50 = 50%, NOT 0.5 and NOT the string "50").
+          // Validate and ensure it is a positive number.
+          var speedPercent = parseFloat("${args.speed_percent}");
+          if (isNaN(speedPercent) || speedPercent <= 0) {
+            return __error("Invalid speed_percent: must be a positive number (e.g. 100 = normal, 50 = half, 200 = double)");
+          }
+
+          // qeClip.setSpeed signature in PP 2026: (percent, frameInterpolation:string,
+          // ripple:bool, reverse:bool, maintainAudioPitch:bool). Verified at runtime
+          // by exhaustive probing — older PP versions used (percent, ripple, reverse).
+          // Try PP 2026 signature first, then fall back to older 3-arg form.
+          app.enableQE();
+          var qeSeq = qe.project.getActiveSequence();
+          var qeTrack = result.trackType === "video" ? qeSeq.getVideoTrackAt(result.trackIndex) : qeSeq.getAudioTrackAt(result.trackIndex);
+          var qeClip = qeTrack.getItemAt(result.clipIndex);
+          var rev = ${args.reverse ? "true" : "false"};
+          var ok = false, lastErr = "";
+          // PP 2026: (percent, frameInterpolation, ripple, reverse, maintainAudioPitch)
+          // empty string accepts default frame sampling
+          try { qeClip.setSpeed(speedPercent, "", false, rev, false); ok = true; } catch (e1) { lastErr = e1.toString(); }
+          // Older PP: (percent, ripple, reverse)
+          if (!ok) { try { qeClip.setSpeed(speedPercent, false, rev); ok = true; } catch (e2) { lastErr = e2.toString(); } }
+          if (!ok) { try { qeClip.setSpeed(speedPercent, false); ok = true; } catch (e3) { lastErr = e3.toString(); } }
+          if (!ok) {
+            return __error("speed_change failed (last error: " + lastErr + "). Workaround: select the clip and use Clip > Speed/Duration in the UI.");
+          }
+
+          return __result({ speedChanged: true, clipName: clip.name, speedPercent: speedPercent, reverse: ${!!args.reverse}, currentSpeed: qeClip.speed });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+    };
+}
+//# sourceMappingURL=timeline.js.map