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

package/README.md

@@ -1,242 +1,242 @@
-# Premiere Pro MCP
-
-**Control Adobe Premiere Pro with natural language through Claude (or any MCP-compatible LLM).**
-
-[![Premiere Pro 2026](https://img.shields.io/badge/Premiere%20Pro-2026-blueviolet)](https://www.adobe.com/products/premiere.html)
-[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)
-[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
-
----
-
-## What it does
-
-```
-You: "Apply a cinematic look to all clips on V1, ducking the music
-      when there's voice, and export to YouTube 1080p."
-
-Claude: ✓ Applied Lumetri (-15K temperature, +10 contrast) to 4 clips
-        ✓ Added voiceover ducking on A2 (-12dB during A1 voice)
-        ✓ Queued H.264 1080p export to ~/Videos/final.mp4
-```
-
-437 tools exposed via MCP to drive Premiere Pro 2026 from any LLM agent.
-Tested in runtime against PP 2026.2.2 on Spanish-localized Windows install.
-
----
-
-## Highlights
-
-- **Locale-resilient**: works on Premiere Pro in Spanish, German, French, etc.
-  (most competitors hardcode English component names and silently fail)
-- **Honest errors**: when a Premiere host API genuinely doesn't expose
-  something (PP 2026 has known limitations), you get a clear error with
-  the recommended workaround — not a silent no-op
-- **Battle-tested**: 137 tools validated in live runtime against PP 2026 with
-  detailed bug fixes (see [CHANGELOG.md](CHANGELOG.md))
-- **AI-first**: built for LLM-driven workflows. Pair it with Whisper for
-  speech-to-text, ComfyUI for thumbnails, FFmpeg for analysis — chain MCPs
-
----
-
-## Quick start
-
-### 1. Install the CEP plugin
-
-Copy `cep-plugin/` to your Adobe CEP extensions folder:
-
-- **Windows**: `%APPDATA%\Adobe\CEP\extensions\MCPBridgeCEP\`
-- **macOS**: `~/Library/Application Support/Adobe/CEP/extensions/MCPBridgeCEP/`
-
-Enable CEP debugging:
-```powershell
-# Windows
-reg add HKCU\Software\Adobe\CSXS.11 /v PlayerDebugMode /t REG_SZ /d 1 /f
-```
-
-### 2. Build the MCP server
-
-```bash
-cd premiere-pro-mcp
-npm install
-npm run build
-```
-
-### 3. Register with Claude Desktop
-
-Add to `%APPDATA%\Claude\claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "premiere-pro": {
-      "command": "node",
-      "args": ["C:/path/to/premiere-pro-mcp/dist/index.js"]
-    }
-  }
-}
-```
-
-### 4. Open Premiere Pro
-
-- Launch Premiere Pro 2026
-- `Window > Extensions > MCPBridgeCEP` (the bridge panel)
-- Click "Start Bridge"
-
-### 5. Talk to Claude
-
-```
-"Show me the active sequence structure."
-"Add a 1-second fade-in to the audio clip on A2."
-"Apply Cross Dissolve at every cut on V1, 0.5 seconds each."
-```
-
----
-
-## What works (validated runtime, PP 2026 es-ES)
-
-### Project & Inspection
-- Full project / sequence / clip overviews
-- Bins, markers, metadata (XMP), color labels
-- Effect properties with all values, keyframes, source media details
-- Find/search project items, list sequences
-
-### Timeline editing
-- Add/remove/move/duplicate clips, split, trim
-- Set in/out points, playhead, work area
-- Selection by name/range/color, invert, deselect
-- Enable/disable clips, link/unlink
-
-### Transform & Motion
-- Position, scale, rotation, opacity (locale-resilient)
-- Anchor point, blend mode
-- Position/scale keyframes via `add_keyframe`
-
-### Color
-- Lumetri full parameter control: exposure, contrast, highlights/shadows,
-  whites/blacks, temperature/tint, saturation, vibrance, sharpen, vignette,
-  faded film
-- LUTs apply
-- Copy/paste color grade across clips
-- ⚠️ See limitations: applying Lumetri *for the first time* requires manual UI
-
-### Audio
-- Per-clip volume, fade in/out (locale-resilient)
-- Volume/panning keyframes
-- Audio FX pipeline: Compressor, EQ, De-Esser, De-Hum, De-Reverb, Limiter,
-  Noise Reduction
-- Voiceover ducking
-- Normalize, detect clipping
-
-### Effects & Transitions
-- 60+ video effects (Gaussian/Directional Blur, Sharpen, Warp Stabilizer,
-  Noise Reduction, Mirror, Spherize, Corner Pin, Lens Distortion, etc.)
-- Transitions with locale-aware name lookup (Cross Dissolve works on any
-  language install)
-- Batch apply across cuts
-
-### Captions
-- Import SRT files as caption tracks
-- Pipeline integration: Whisper-transcribe → SRT → MCP creates captions
-
-### Export
-- Single sequence + batch export via Adobe Media Encoder
-- Match Source presets, YouTube/Vimeo/Twitter/Facebook presets
-- Encode arbitrary files via AME
-- AAF, OMF, FCPXML export
-
-### Multicam
-- Create multicam sequences, switch angles, flatten
-
-### Markers
-- Add/update/delete on sequence or clip
-- Color labels, comments, in/out range
-- Import/export CSV
-
----
-
-## Known limitations (PP 2026 host)
-
-These are not bugs in this MCP — they're verified limitations of Premiere Pro
-2026's ExtendScript/QE-DOM surface. Each tool returns a clear actionable error
-with the recommended workaround.
-
-| Feature | Status | Workaround |
-|---------|--------|------------|
-| `capture_frame` programmatic | ❌ `qeSeq.exportFramePNG` reports success but never writes file | UI: File > Export > Media > Single Frame |
-| `set_track_volume` | ❌ Audio track DOM no longer exposes `.components` or `.volume`; QE has no `setVolume` | Use `add_audio_keyframes` per-clip, or Audio Track Mixer |
-| `speed_change` programmatic | ❌ `qeClip.setSpeed` signature changed in PP 2026 (rejects all known forms) | UI: Clip > Speed/Duration, or change duration with `trim_clip` |
-| Apply Lumetri for the first time | ❌ `addVideoEffect` reports success but doesn't add component | Apply Lumetri manually once; afterwards all 28 setters work perfectly |
-| LUFS integrated measurement | ❌ Not scriptable | Export and measure with ffmpeg-loudnorm |
-| Native PP Speech-to-Text | ❌ Adobe AI STT not exposed | Use Whisper + `create_caption_track` (works great) |
-| Adobe Libraries MOGRT | ❌ Adobe Libraries not scriptable | Use local `.mogrt` files via `import_mogrt` |
-| Dynamic Link with AE | ❌ `import_ae_comps` not implemented | Render from AE and import as video |
-| Async export completion | ⚠️ AME runs async, no callback | Poll `get_render_queue_status` |
-
----
-
-## Architecture
-
-```
-┌─────────────┐         ┌──────────────┐         ┌─────────────┐
-│   Claude    │         │   Node.js    │         │  Premiere   │
-│  (or LLM)   │◄───────►│  MCP server  │◄───────►│   Pro CEP   │
-└─────────────┘  stdio  └──────────────┘  files  │   plugin    │
-                                                  │   (panel)   │
-                                                  └─────────────┘
-                                                        │
-                                                        ▼
-                                                  ┌──────────────┐
-                                                  │ ExtendScript │
-                                                  │  DOM + QE    │
-                                                  └──────────────┘
-```
-
-The bridge automatically prepends locale-resilient helpers to every script:
-
-```javascript
-__findIntrinsic(clip, "motion" | "opacity" | "volume" | "lumetri" | "timeRemap")
-// tries matchName ("AE.ADBE Motion") first — locale-INDEPENDENT —
-// then localized displayName ("Movimiento", "Bewegung", "Mouvement", etc.)
-
-__findProp(component, ["Position", "Posición", "Position", "Position"])
-// also descends one level into nested groups (needed for Lumetri's
-// grouped parameters like Exposure inside Basic Correction)
-
-__readMaybe(obj, "isMuted", false)
-// reads members that are property in some PP versions, method in others
-
-__findTransition(name, "video")
-// resolves transition names across locales:
-// "Cross Dissolve" matches "Disolvencia cruzada" / "Fondu enchaîné"
-```
-
----
-
-## Development
-
-```bash
-npm run dev      # Watch mode
-npm run build    # Build dist/
-npx tsc --noEmit # Type-check only
-```
-
-When adding a tool, prefer:
-- `__findIntrinsic` / `__findComponent` over hardcoded `displayName === "Motion"`
-- `__readMaybe` for any `isSomething()` / `isSomething` property
-- Pass `.ticks` strings (not Time objects) to `insertClip`/`setInPoint`/etc.
-
----
-
-## Credits
-
-Built on top of work from
-[`AdobePremiereProMCP`](https://github.com/bdenney99/AdobePremiereProMCP)
-with extensive fixes for PP 2026 compatibility, locale resilience, and
-runtime-validated behavior. See [CHANGELOG.md](CHANGELOG.md) for the full
-fix log.
-
----
-
-## License
-
-MIT
+# Premiere Pro MCP
+
+**Control Adobe Premiere Pro with natural language through Claude (or any MCP-compatible LLM).**
+
+[![Premiere Pro 2026](https://img.shields.io/badge/Premiere%20Pro-2026-blueviolet)](https://www.adobe.com/products/premiere.html)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+---
+
+## What it does
+
+```
+You: "Apply a cinematic look to all clips on V1, ducking the music
+      when there's voice, and export to YouTube 1080p."
+
+Claude: ✓ Applied Lumetri (-15K temperature, +10 contrast) to 4 clips
+        ✓ Added voiceover ducking on A2 (-12dB during A1 voice)
+        ✓ Queued H.264 1080p export to ~/Videos/final.mp4
+```
+
+437 tools exposed via MCP to drive Premiere Pro 2026 from any LLM agent.
+Tested in runtime against PP 2026.2.2 on Spanish-localized Windows install.
+
+---
+
+## Highlights
+
+- **Locale-resilient**: works on Premiere Pro in Spanish, German, French, etc.
+  (most competitors hardcode English component names and silently fail)
+- **Honest errors**: when a Premiere host API genuinely doesn't expose
+  something (PP 2026 has known limitations), you get a clear error with
+  the recommended workaround — not a silent no-op
+- **Battle-tested**: 137 tools validated in live runtime against PP 2026 with
+  detailed bug fixes (see [CHANGELOG.md](CHANGELOG.md))
+- **AI-first**: built for LLM-driven workflows. Pair it with Whisper for
+  speech-to-text, ComfyUI for thumbnails, FFmpeg for analysis — chain MCPs
+
+---
+
+## Quick start
+
+### 1. Install the CEP plugin
+
+Copy `cep-plugin/` to your Adobe CEP extensions folder:
+
+- **Windows**: `%APPDATA%\Adobe\CEP\extensions\MCPBridgeCEP\`
+- **macOS**: `~/Library/Application Support/Adobe/CEP/extensions/MCPBridgeCEP/`
+
+Enable CEP debugging:
+```powershell
+# Windows
+reg add HKCU\Software\Adobe\CSXS.11 /v PlayerDebugMode /t REG_SZ /d 1 /f
+```
+
+### 2. Build the MCP server
+
+```bash
+cd premiere-pro-mcp
+npm install
+npm run build
+```
+
+### 3. Register with Claude Desktop
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "premiere-pro": {
+      "command": "node",
+      "args": ["C:/path/to/premiere-pro-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### 4. Open Premiere Pro
+
+- Launch Premiere Pro 2026
+- `Window > Extensions > MCPBridgeCEP` (the bridge panel)
+- Click "Start Bridge"
+
+### 5. Talk to Claude
+
+```
+"Show me the active sequence structure."
+"Add a 1-second fade-in to the audio clip on A2."
+"Apply Cross Dissolve at every cut on V1, 0.5 seconds each."
+```
+
+---
+
+## What works (validated runtime, PP 2026 es-ES)
+
+### Project & Inspection
+- Full project / sequence / clip overviews
+- Bins, markers, metadata (XMP), color labels
+- Effect properties with all values, keyframes, source media details
+- Find/search project items, list sequences
+
+### Timeline editing
+- Add/remove/move/duplicate clips, split, trim
+- Set in/out points, playhead, work area
+- Selection by name/range/color, invert, deselect
+- Enable/disable clips, link/unlink
+
+### Transform & Motion
+- Position, scale, rotation, opacity (locale-resilient)
+- Anchor point, blend mode
+- Position/scale keyframes via `add_keyframe`
+
+### Color
+- Lumetri full parameter control: exposure, contrast, highlights/shadows,
+  whites/blacks, temperature/tint, saturation, vibrance, sharpen, vignette,
+  faded film
+- LUTs apply
+- Copy/paste color grade across clips
+- ⚠️ See limitations: applying Lumetri *for the first time* requires manual UI
+
+### Audio
+- Per-clip volume, fade in/out (locale-resilient)
+- Volume/panning keyframes
+- Audio FX pipeline: Compressor, EQ, De-Esser, De-Hum, De-Reverb, Limiter,
+  Noise Reduction
+- Voiceover ducking
+- Normalize, detect clipping
+
+### Effects & Transitions
+- 60+ video effects (Gaussian/Directional Blur, Sharpen, Warp Stabilizer,
+  Noise Reduction, Mirror, Spherize, Corner Pin, Lens Distortion, etc.)
+- Transitions with locale-aware name lookup (Cross Dissolve works on any
+  language install)
+- Batch apply across cuts
+
+### Captions
+- Import SRT files as caption tracks
+- Pipeline integration: Whisper-transcribe → SRT → MCP creates captions
+
+### Export
+- Single sequence + batch export via Adobe Media Encoder
+- Match Source presets, YouTube/Vimeo/Twitter/Facebook presets
+- Encode arbitrary files via AME
+- AAF, OMF, FCPXML export
+
+### Multicam
+- Create multicam sequences, switch angles, flatten
+
+### Markers
+- Add/update/delete on sequence or clip
+- Color labels, comments, in/out range
+- Import/export CSV
+
+---
+
+## Known limitations (PP 2026 host)
+
+These are not bugs in this MCP — they're verified limitations of Premiere Pro
+2026's ExtendScript/QE-DOM surface. Each tool returns a clear actionable error
+with the recommended workaround.
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| `capture_frame` programmatic | ❌ `qeSeq.exportFramePNG` reports success but never writes file | UI: File > Export > Media > Single Frame |
+| `set_track_volume` | ❌ Audio track DOM no longer exposes `.components` or `.volume`; QE has no `setVolume` | Use `add_audio_keyframes` per-clip, or Audio Track Mixer |
+| `speed_change` programmatic | ❌ `qeClip.setSpeed` signature changed in PP 2026 (rejects all known forms) | UI: Clip > Speed/Duration, or change duration with `trim_clip` |
+| Apply Lumetri for the first time | ❌ `addVideoEffect` reports success but doesn't add component | Apply Lumetri manually once; afterwards all 28 setters work perfectly |
+| LUFS integrated measurement | ❌ Not scriptable | Export and measure with ffmpeg-loudnorm |
+| Native PP Speech-to-Text | ❌ Adobe AI STT not exposed | Use Whisper + `create_caption_track` (works great) |
+| Adobe Libraries MOGRT | ❌ Adobe Libraries not scriptable | Use local `.mogrt` files via `import_mogrt` |
+| Dynamic Link with AE | ❌ `import_ae_comps` not implemented | Render from AE and import as video |
+| Async export completion | ⚠️ AME runs async, no callback | Poll `get_render_queue_status` |
+
+---
+
+## Architecture
+
+```
+┌─────────────┐         ┌──────────────┐         ┌─────────────┐
+│   Claude    │         │   Node.js    │         │  Premiere   │
+│  (or LLM)   │◄───────►│  MCP server  │◄───────►│   Pro CEP   │
+└─────────────┘  stdio  └──────────────┘  files  │   plugin    │
+                                                  │   (panel)   │
+                                                  └─────────────┘
+                                                        │
+                                                        ▼
+                                                  ┌──────────────┐
+                                                  │ ExtendScript │
+                                                  │  DOM + QE    │
+                                                  └──────────────┘
+```
+
+The bridge automatically prepends locale-resilient helpers to every script:
+
+```javascript
+__findIntrinsic(clip, "motion" | "opacity" | "volume" | "lumetri" | "timeRemap")
+// tries matchName ("AE.ADBE Motion") first — locale-INDEPENDENT —
+// then localized displayName ("Movimiento", "Bewegung", "Mouvement", etc.)
+
+__findProp(component, ["Position", "Posición", "Position", "Position"])
+// also descends one level into nested groups (needed for Lumetri's
+// grouped parameters like Exposure inside Basic Correction)
+
+__readMaybe(obj, "isMuted", false)
+// reads members that are property in some PP versions, method in others
+
+__findTransition(name, "video")
+// resolves transition names across locales:
+// "Cross Dissolve" matches "Disolvencia cruzada" / "Fondu enchaîné"
+```
+
+---
+
+## Development
+
+```bash
+npm run dev      # Watch mode
+npm run build    # Build dist/
+npx tsc --noEmit # Type-check only
+```
+
+When adding a tool, prefer:
+- `__findIntrinsic` / `__findComponent` over hardcoded `displayName === "Motion"`
+- `__readMaybe` for any `isSomething()` / `isSomething` property
+- Pass `.ticks` strings (not Time objects) to `insertClip`/`setInPoint`/etc.
+
+---
+
+## Credits
+
+Built on top of work from
+[`AdobePremiereProMCP`](https://github.com/bdenney99/AdobePremiereProMCP)
+with extensive fixes for PP 2026 compatibility, locale resilience, and
+runtime-validated behavior. See [CHANGELOG.md](CHANGELOG.md) for the full
+fix log.
+
+---
+
+## License
+
+MIT

package/cep-plugin/.debug

@@ -1,8 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<ExtensionList>
-  <Extension Id="com.mcp.premiere.bridge.panel">
-    <HostList>
-      <Host Name="PPRO" Port="8088"/>
-    </HostList>
-  </Extension>
-</ExtensionList>
+<?xml version="1.0" encoding="UTF-8"?>
+<ExtensionList>
+  <Extension Id="com.mcp.premiere.bridge.panel">
+    <HostList>
+      <Host Name="PPRO" Port="8088"/>
+    </HostList>
+  </Extension>
+</ExtensionList>