@synthetic-ai/premiere-mcp 2.0.0

package/dist/tools/effects.js

@@ -0,0 +1,554 @@
+import { buildToolScript, escapeForExtendScript } from "../bridge/script-builder.js";
+import { sendCommand } from "../bridge/file-bridge.js";
+export function getEffectsTools(bridgeOptions) {
+    return {
+        apply_effect: {
+            description: `Apply a video effect to a clip by name. Uses QE DOM for effect lookup.
+
+Preconditions: Active sequence required. The clip must exist on the timeline. Use list_available_effects to find exact effect names before calling this tool.
+
+Common effect names: "Gaussian Blur", "Lumetri Color", "Warp Stabilizer", "Unsharp Mask", "Fast Color Corrector", "Brightness & Contrast", "Hue/Saturation", "Sharpen", "Video Limiter", "Timecode".
+
+After applying, use get_effect_properties to see the effect's parameters, then set_effect_property or add_keyframe to adjust values.
+
+Example: apply_effect({ node_id: "abc123", effect_name: "Gaussian Blur" })
+Example: apply_effect({ node_id: "abc123", effect_name: "Lumetri Color" })`,
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip to apply the effect to",
+                    },
+                    effect_name: {
+                        type: "string",
+                        description: "Name of the effect (e.g., 'Gaussian Blur', 'Lumetri Color')",
+                    },
+                },
+                required: ["node_id", "effect_name"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          app.enableQE();
+          var qeSeq = qe.project.getActiveSequence();
+          if (!qeSeq) return __error("No active sequence (QE)");
+          
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          
+          // Find the effect in QE
+          var effectName = "${escapeForExtendScript(args.effect_name)}";
+          var qeTrack = result.trackType === "video" 
+            ? qeSeq.getVideoTrackAt(result.trackIndex)
+            : qeSeq.getAudioTrackAt(result.trackIndex);
+          
+          if (!qeTrack) return __error("QE track not found");
+          
+          var qeClip = qeTrack.getItemAt(result.clipIndex);
+          if (!qeClip) return __error("QE clip not found");
+          
+          // Search for the effect
+          var effects = qe.project.getVideoEffectList();
+          var found = false;
+          for (var i = 0; i < effects.numItems; i++) {
+            if (effects[i].name === effectName) {
+              qeClip.addVideoEffect(effects[i]);
+              found = true;
+              break;
+            }
+          }
+          
+          if (!found) return __error("Effect not found: " + effectName);
+          return __result({ applied: true, effect: effectName, clipName: result.clip.name });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        apply_audio_effect: {
+            description: "Apply an audio effect to a clip",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip",
+                    },
+                    effect_name: {
+                        type: "string",
+                        description: "Name of the audio effect",
+                    },
+                },
+                required: ["node_id", "effect_name"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          app.enableQE();
+          var qeSeq = qe.project.getActiveSequence();
+          if (!qeSeq) return __error("No active sequence (QE)");
+          
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          if (result.trackType !== "audio") return __error("node_id is not an audio clip");
+
+          var effectName = "${escapeForExtendScript(args.effect_name)}";
+          var qeTrack = qeSeq.getAudioTrackAt(result.trackIndex);
+          if (!qeTrack) return __error("QE audio track not found");
+          
+          var qeClip = qeTrack.getItemAt(result.clipIndex);
+          if (!qeClip) return __error("QE clip not found");
+          
+          var effects = qe.project.getAudioEffectList();
+          var found = false;
+          for (var i = 0; i < effects.numItems; i++) {
+            if (effects[i].name === effectName) {
+              qeClip.addAudioEffect(effects[i]);
+              found = true;
+              break;
+            }
+          }
+          
+          if (!found) return __error("Audio effect not found: " + effectName);
+          return __result({ applied: true, effect: effectName });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        remove_effect: {
+            description: "Remove an effect from a clip by its index or name",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip",
+                    },
+                    effect_index: {
+                        type: "number",
+                        description: "Index of the effect to remove (0-based). Use get_clip_properties to see effects list.",
+                    },
+                    effect_name: {
+                        type: "string",
+                        description: "Name of the effect to remove (alternative to effect_index)",
+                    },
+                },
+                required: ["node_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found");
+          
+          var clip = result.clip;
+          ${args.effect_index !== undefined ? `
+          if (${args.effect_index} >= clip.components.numItems) return __error("Effect index out of range");
+          var effectName = clip.components[${args.effect_index}].displayName;
+          clip.components[${args.effect_index}].remove();
+          return __result({ removed: true, effect: effectName });
+          ` : `
+          var effectName = "${escapeForExtendScript(args.effect_name || "")}";
+          var found = false;
+          for (var i = clip.components.numItems - 1; i >= 0; i--) {
+            if (clip.components[i].displayName === effectName) {
+              clip.components[i].remove();
+              found = true;
+              break;
+            }
+          }
+          if (!found) return __error("Effect not found: " + effectName);
+          return __result({ removed: true, effect: effectName });
+          `}
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        list_available_effects: {
+            description: "List all available video effects in Premiere Pro.",
+            parameters: {},
+            handler: async () => {
+                const effects = [
+                    // Color & Grading
+                    { name: "Lumetri Color", category: "Color Correction" },
+                    { name: "Brightness & Contrast", category: "Color Correction" },
+                    { name: "Hue/Saturation", category: "Color Correction" },
+                    { name: "Fast Color Corrector", category: "Color Correction" },
+                    { name: "Three-Way Color Corrector", category: "Color Correction" },
+                    { name: "Color Balance", category: "Color Correction" },
+                    { name: "Change to Color", category: "Color Correction" },
+                    { name: "Video Limiter", category: "Color Correction" },
+                    { name: "Luma Curve", category: "Color Correction" },
+                    { name: "RGB Curves", category: "Color Correction" },
+                    // Blur & Sharpen
+                    { name: "Gaussian Blur", category: "Blur & Sharpen" },
+                    { name: "Fast Blur", category: "Blur & Sharpen" },
+                    { name: "Directional Blur", category: "Blur & Sharpen" },
+                    { name: "Radial Blur", category: "Blur & Sharpen" },
+                    { name: "Sharpen", category: "Blur & Sharpen" },
+                    { name: "Unsharp Mask", category: "Blur & Sharpen" },
+                    { name: "Camera Blur", category: "Blur & Sharpen" },
+                    // Distort
+                    { name: "Warp Stabilizer", category: "Distort" },
+                    { name: "Lens Distortion", category: "Distort" },
+                    { name: "Corner Pin", category: "Distort" },
+                    { name: "Spherize", category: "Distort" },
+                    { name: "Mirror", category: "Distort" },
+                    { name: "Transform", category: "Distort" },
+                    { name: "Magnify", category: "Distort" },
+                    { name: "Offset", category: "Distort" },
+                    // Generate
+                    { name: "4-Color Gradient", category: "Generate" },
+                    { name: "Gradient", category: "Generate" },
+                    { name: "Cell Pattern", category: "Generate" },
+                    { name: "Checkerboard", category: "Generate" },
+                    { name: "Lens Flare", category: "Generate" },
+                    { name: "Lightning", category: "Generate" },
+                    // Keying
+                    { name: "Ultra Key", category: "Keying" },
+                    { name: "Chroma Key", category: "Keying" },
+                    { name: "Color Key", category: "Keying" },
+                    { name: "Luma Key", category: "Keying" },
+                    { name: "Track Matte Key", category: "Keying" },
+                    { name: "Difference Matte", category: "Keying" },
+                    // Noise & Grain
+                    { name: "Noise", category: "Noise & Grain" },
+                    { name: "Median", category: "Noise & Grain" },
+                    { name: "Dust & Scratches", category: "Noise & Grain" },
+                    // Stylize
+                    { name: "Mosaic", category: "Stylize" },
+                    { name: "Posterize", category: "Stylize" },
+                    { name: "Threshold", category: "Stylize" },
+                    { name: "Find Edges", category: "Stylize" },
+                    { name: "Emboss", category: "Stylize" },
+                    { name: "Solarize", category: "Stylize" },
+                    { name: "Strobe Light", category: "Stylize" },
+                    // Time
+                    { name: "Posterize Time", category: "Time" },
+                    { name: "Echo", category: "Time" },
+                    // Transition effects
+                    { name: "Block Dissolve", category: "Transition" },
+                    { name: "Gradient Wipe", category: "Transition" },
+                    { name: "Linear Wipe", category: "Transition" },
+                    // Utility
+                    { name: "Timecode", category: "Utility" },
+                    { name: "Clip Name", category: "Utility" },
+                    { name: "SDR Conform", category: "Utility" },
+                ];
+                return { success: true, data: { effects, count: effects.length, note: "Static list of common Premiere Pro video effects. Use apply_effect with these exact names." } };
+            },
+        },
+        list_available_audio_effects: {
+            description: "List all available audio effects in Premiere Pro.",
+            parameters: {},
+            handler: async () => {
+                const effects = [
+                    // Amplitude & Compression
+                    { name: "Dynamics Processing", category: "Amplitude & Compression" },
+                    { name: "Hard Limiter", category: "Amplitude & Compression" },
+                    { name: "Multiband Compressor", category: "Amplitude & Compression" },
+                    { name: "Single-band Compressor", category: "Amplitude & Compression" },
+                    { name: "Tube-modeled Compressor", category: "Amplitude & Compression" },
+                    // Delay & Echo
+                    { name: "Analog Delay", category: "Delay & Echo" },
+                    { name: "Delay", category: "Delay & Echo" },
+                    { name: "Multitap Delay", category: "Delay & Echo" },
+                    // Filter & EQ
+                    { name: "FFT Filter", category: "Filter & EQ" },
+                    { name: "Graphic Equalizer (10 Bands)", category: "Filter & EQ" },
+                    { name: "Graphic Equalizer (20 Bands)", category: "Filter & EQ" },
+                    { name: "Parametric Equalizer", category: "Filter & EQ" },
+                    { name: "Scientific Filter", category: "Filter & EQ" },
+                    // Modulation
+                    { name: "Chorus/Flanger", category: "Modulation" },
+                    { name: "Flanger", category: "Modulation" },
+                    { name: "Phaser", category: "Modulation" },
+                    // Noise Reduction / Restoration
+                    { name: "Adaptive Noise Reduction", category: "Noise Reduction" },
+                    { name: "Automatic Click Remover", category: "Noise Reduction" },
+                    { name: "DeNoise", category: "Noise Reduction" },
+                    { name: "DeHum", category: "Noise Reduction" },
+                    { name: "DeEsser", category: "Noise Reduction" },
+                    // Reverb
+                    { name: "Convolution Reverb", category: "Reverb" },
+                    { name: "Full Reverb", category: "Reverb" },
+                    { name: "Reverb", category: "Reverb" },
+                    // Special
+                    { name: "Pitch Shifter", category: "Special" },
+                    { name: "Vocal Enhancer", category: "Special" },
+                    // Stereo Imagery
+                    { name: "Center Channel Extractor", category: "Stereo Imagery" },
+                    { name: "Stereo Expander", category: "Stereo Imagery" },
+                    // Time & Pitch
+                    { name: "Pitch & Time", category: "Time & Pitch" },
+                ];
+                return { success: true, data: { effects, count: effects.length, note: "Static list of common Premiere Pro audio effects. Use apply_audio_effect with these exact names." } };
+            },
+        },
+        color_correct: {
+            description: `Apply color correction to a clip using Lumetri Color. Automatically applies the Lumetri Color effect if not already present, then sets the specified parameters.
+
+Preconditions: Active sequence required. Clip must exist on the timeline.
+
+All parameters are optional — only the ones you provide will be changed. Values outside their valid range are clamped by Premiere Pro.
+
+Parameter ranges:
+- exposure: -5.0 to +5.0 (EV stops; 0 = no change)
+- contrast: -100 to +100 (0 = no change)
+- highlights: -100 to +100
+- shadows: -100 to +100
+- whites: -100 to +100
+- blacks: -100 to +100
+- temperature: -100 to +100 (negative = cooler/blue, positive = warmer/orange)
+- tint: -100 to +100 (negative = green, positive = magenta)
+- saturation: 0 to 200 (100 = no change, 0 = grayscale)
+
+Example: color_correct({ node_id: "abc123", exposure: 0.5, contrast: 10, saturation: 110 })
+Example: color_correct({ node_id: "abc123", temperature: -20, highlights: -30, shadows: 15 })`,
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip",
+                    },
+                    exposure: { type: "number", description: "Exposure adjustment (-4.0 to 4.0)" },
+                    contrast: { type: "number", description: "Contrast adjustment (-100 to 100)" },
+                    highlights: { type: "number", description: "Highlights adjustment (-100 to 100)" },
+                    shadows: { type: "number", description: "Shadows adjustment (-100 to 100)" },
+                    whites: { type: "number", description: "Whites adjustment (-100 to 100)" },
+                    blacks: { type: "number", description: "Blacks adjustment (-100 to 100)" },
+                    temperature: { type: "number", description: "Color temperature adjustment" },
+                    tint: { type: "number", description: "Tint adjustment" },
+                    saturation: { type: "number", description: "Saturation (0-200, 100 = normal)" },
+                },
+                required: ["node_id"],
+            },
+            handler: async (args) => {
+                // First apply Lumetri Color effect, then set its properties
+                const script = buildToolScript(`
+          app.enableQE();
+          var qeSeq = qe.project.getActiveSequence();
+          if (!qeSeq) return __error("No active sequence (QE)");
+          
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found");
+          
+          // Apply Lumetri Color if not already present
+          var clip = result.clip;
+          var lumetri = __findIntrinsic(clip, "lumetri");
+
+          if (!lumetri) {
+            var qeTrack = qeSeq.getVideoTrackAt(result.trackIndex);
+            if (!qeTrack) return __error("QE video track not found");
+            var qeClip = qeTrack.getItemAt(result.clipIndex);
+            if (!qeClip) return __error("QE clip not found");
+            var effects = qe.project.getVideoEffectList();
+            // qe.project.getVideoEffectList() returns LOCALIZED displayNames in
+            // non-English Premiere installs (e.g. "Color Lumetri" in es-ES).
+            // Match against a list of candidate names across locales.
+            var lumetriNames = ["Lumetri Color", "Color Lumetri", "Lumetri-Farbe", "Couleur Lumetri", "Lumetri カラー", "色彩Lumetri"];
+            var lumetriEffect = null;
+            for (var i = 0; i < effects.numItems; i++) {
+              for (var n = 0; n < lumetriNames.length; n++) {
+                if (effects[i].name === lumetriNames[n]) {
+                  lumetriEffect = effects[i];
+                  break;
+                }
+              }
+              if (lumetriEffect) break;
+            }
+            // Fallback: any effect whose name contains "Lumetri"
+            if (!lumetriEffect) {
+              for (var j = 0; j < effects.numItems; j++) {
+                if (effects[j].name && effects[j].name.indexOf("Lumetri") !== -1) {
+                  lumetriEffect = effects[j];
+                  break;
+                }
+              }
+            }
+            if (!lumetriEffect) return __error("Lumetri Color effect not found in available video effects");
+            qeClip.addVideoEffect(lumetriEffect);
+            // Re-find the component after applying
+            lumetri = __findIntrinsic(clip, "lumetri");
+          }
+
+          if (!lumetri) return __error("Could not apply or find Lumetri Color effect");
+
+          // Set Lumetri properties. Params are nested in sub-groups; __findProp
+          // descends one level to locate them. Each setValue is guarded.
+          var changes = {};
+          var failed = {};
+
+          function __setLumetri(displayNames, value, key) {
+            var prop = __findProp(lumetri, displayNames);
+            if (!prop) { failed[key] = "property not found"; return; }
+            try {
+              prop.setValue(value, true);
+              changes[key] = value;
+            } catch (e) {
+              failed[key] = e.toString();
+            }
+          }
+
+          ${args.exposure !== undefined ? `__setLumetri(["Exposure", "Exposición", "Belichtung", "Exposition"], ${args.exposure}, "exposure");` : ""}
+          ${args.contrast !== undefined ? `__setLumetri(["Contrast", "Contraste", "Kontrast", "Contraste"], ${args.contrast}, "contrast");` : ""}
+          ${args.highlights !== undefined ? `__setLumetri(["Highlights", "Iluminaciones", "Lichter", "Hautes lumières"], ${args.highlights}, "highlights");` : ""}
+          ${args.shadows !== undefined ? `__setLumetri(["Shadows", "Sombras", "Schatten", "Ombres"], ${args.shadows}, "shadows");` : ""}
+          ${args.whites !== undefined ? `__setLumetri(["Whites", "Blancos", "Weißwerte", "Blancs"], ${args.whites}, "whites");` : ""}
+          ${args.blacks !== undefined ? `__setLumetri(["Blacks", "Negros", "Schwarzwerte", "Noirs"], ${args.blacks}, "blacks");` : ""}
+          ${args.temperature !== undefined ? `__setLumetri(["Temperature", "Temperatura", "Temperatur", "Température"], ${args.temperature}, "temperature");` : ""}
+          ${args.tint !== undefined ? `__setLumetri(["Tint", "Matiz", "Farbton", "Teinte"], ${args.tint}, "tint");` : ""}
+          ${args.saturation !== undefined ? `__setLumetri(["Saturation", "Saturación", "Sättigung", "Saturation"], ${args.saturation}, "saturation");` : ""}
+
+          return __result({ colorCorrected: true, clipName: clip.name, changes: changes, failed: failed });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        apply_lut: {
+            description: `Apply a LUT (Look-Up Table) file to a clip via Lumetri Color's Creative or Input LUT slot.
+
+Preconditions: Active sequence required. The LUT file must be accessible on disk at the specified path. Lumetri Color effect is automatically applied to the clip if not already present.
+
+Supported LUT formats: .cube, .look, .lut, .3dl, .mga.
+
+Parameters:
+- node_id: Clip to apply the LUT to.
+- lut_path: Absolute path to the LUT file (e.g., "C:\\LUTs\\rec709.cube" or "/Users/you/LUTs/film.cube").
+- lut_strength: Intensity of the LUT effect (0.0 = no effect, 1.0 = full strength, default: 1.0).
+
+Example: apply_lut({ node_id: "abc123", lut_path: "/Users/you/LUTs/orange-teal.cube", lut_strength: 0.8 })`,
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip",
+                    },
+                    lut_path: {
+                        type: "string",
+                        description: "Full path to the .cube or .3dl LUT file",
+                    },
+                },
+                required: ["node_id", "lut_path"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          app.enableQE();
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found");
+          
+          var clip = result.clip;
+
+          // Find or apply Lumetri Color
+          var lumetriComp = __findIntrinsic(clip, "lumetri");
+
+          if (!lumetriComp) {
+            var qeSeq = qe.project.getActiveSequence();
+            var qeTrack = qeSeq.getVideoTrackAt(result.trackIndex);
+            var qeClip = qeTrack.getItemAt(result.clipIndex);
+            var effects = qe.project.getVideoEffectList();
+            for (var i = 0; i < effects.numItems; i++) {
+              if (effects[i].name === "Lumetri Color") {
+                qeClip.addVideoEffect(effects[i]);
+                break;
+              }
+            }
+            // Re-find the component
+            lumetriComp = __findIntrinsic(clip, "lumetri");
+          }
+
+          if (!lumetriComp) return __error("Could not apply Lumetri Color effect");
+
+          // Set the LUT path (Input LUT is nested within Lumetri groups)
+          var lutProp = __findProp(lumetriComp, ["Input LUT", "Creative Look", "LUT de entrada"]);
+          if (!lutProp) return __error("Input LUT property not found on Lumetri Color");
+          lutProp.setValue("${escapeForExtendScript(args.lut_path)}", true);
+
+          return __result({ lutApplied: true, clipName: clip.name, lutPath: "${escapeForExtendScript(args.lut_path)}" });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+        stabilize_clip: {
+            description: "Apply the Warp Stabilizer effect to a clip for video stabilization. Uses QE DOM.",
+            parameters: {
+                type: "object",
+                properties: {
+                    node_id: {
+                        type: "string",
+                        description: "Node ID of the clip to stabilize",
+                    },
+                    smoothness: {
+                        type: "number",
+                        description: "Stabilization smoothness percentage (default: 50). Higher = smoother but more cropping.",
+                    },
+                    method: {
+                        type: "string",
+                        enum: ["Subspace Warp", "Position", "Position, Scale, Rotation"],
+                        description: "Stabilization method (default: 'Subspace Warp')",
+                    },
+                },
+                required: ["node_id"],
+            },
+            handler: async (args) => {
+                const script = buildToolScript(`
+          app.enableQE();
+          var qeSeq = qe.project.getActiveSequence();
+          if (!qeSeq) return __error("No active sequence (QE)");
+          
+          var result = __findClip("${escapeForExtendScript(args.node_id)}");
+          if (!result) return __error("Clip not found: ${escapeForExtendScript(args.node_id)}");
+          
+          var qeTrack = result.trackType === "video"
+            ? qeSeq.getVideoTrackAt(result.trackIndex)
+            : null;
+          if (!qeTrack) return __error("Warp Stabilizer can only be applied to video clips");
+          
+          var qeClip = qeTrack.getItemAt(result.clipIndex);
+          if (!qeClip) return __error("QE clip not found");
+          
+          // Find and apply Warp Stabilizer
+          var effects = qe.project.getVideoEffectList();
+          var found = false;
+          for (var i = 0; i < effects.numItems; i++) {
+            if (effects[i].name === "Warp Stabilizer") {
+              qeClip.addVideoEffect(effects[i]);
+              found = true;
+              break;
+            }
+          }
+          
+          if (!found) return __error("Warp Stabilizer effect not found");
+          
+          // Set properties if specified
+          var clip = result.clip;
+          var changes = { stabilized: true };
+          ${args.smoothness !== undefined || args.method !== undefined ? `
+          for (var i = 0; i < clip.components.numItems; i++) {
+            var comp = clip.components[i];
+            if (comp.displayName === "Warp Stabilizer") {
+              for (var p = 0; p < comp.properties.numItems; p++) {
+                var prop = comp.properties[p];
+                ${args.smoothness !== undefined ? `
+                if (prop.displayName === "Smoothness") {
+                  prop.setValue(${args.smoothness}, true);
+                  changes.smoothness = ${args.smoothness};
+                }` : ""}
+                ${args.method !== undefined ? `
+                if (prop.displayName === "Method") {
+                  prop.setValue("${escapeForExtendScript(args.method)}", true);
+                  changes.method = "${escapeForExtendScript(args.method)}";
+                }` : ""}
+              }
+              break;
+            }
+          }
+          ` : ""}
+          
+          return __result({ clipName: clip.name, info: "Warp Stabilizer applied. Analysis will begin automatically.", changes: changes });
+        `);
+                return sendCommand(script, bridgeOptions);
+            },
+        },
+    };
+}
+//# sourceMappingURL=effects.js.map