# FCPXML MCP — Agent Skill

Use when working with Final Cut Pro XML files (.fcpxml) — timeline analysis, quality control, batch editing, rough cut generation, marker management, cross-NLE export, and multi-track workflows.

TRIGGER when: user mentions FCPXML, Final Cut Pro, FCP, timeline analysis, video editing XML, markers, rough cuts, or any post-production workflow involving XML files.

## Tool Categories

### Read & Analyze (non-destructive)
| Tool | Use when... |
|------|-------------|
| `list_projects` | Finding FCPXML files in a directory (default: ~/Movies) |
| `analyze_timeline` | Getting stats — duration, resolution, clip count, frame rate, pacing metrics |
| `analyze_pacing` | Evaluating edit rhythm — cuts/min, pacing curve, suggestions |
| `list_clips` | Listing all clips with timecodes, durations, metadata |
| `list_markers` | Extracting markers (chapter, todo, standard). Use `format: "youtube"` for YouTube chapters |
| `list_keywords` | Showing keyword tags applied to clips |
| `list_library_clips` | Showing source clips available in the library (for rough cut planning) |
| `list_connected_clips` | Showing clips on connected lanes (B-roll, titles, SFX) |
| `list_compound_clips` | Showing compound clip structure |
| `list_roles` | Showing audio/video role assignments |
| `list_effects` | Showing applied effects and filters |
| `list_templates` | Showing available timeline templates |

### QC & Detection (non-destructive)
| Tool | Use when... |
|------|-------------|
| `validate_timeline` | Getting a 0-100 health score with issue breakdown |
| `detect_flash_frames` | Finding ultra-short clips (accidental 1-2 frame cuts) |
| `detect_gaps` | Finding unintentional gaps in the timeline |
| `detect_duplicates` | Finding repeated source clips |
| `detect_silence_candidates` | Finding dead air / silence regions |
| `diff_timelines` | Comparing two versions of a timeline (added/removed/moved/trimmed) |

### Edit & Fix (creates _modified output files, never overwrites originals)
| Tool | Use when... |
|------|-------------|
| `add_marker` | Adding a single marker (chapter, todo, standard) at a timecode |
| `batch_add_markers` | Adding multiple markers at once (chapter lists, beat markers) |
| `trim_clip` | Adjusting in/out points of a clip |
| `split_clip` | Splitting a clip at a specific timecode |
| `delete_clips` | Removing clips by index or name |
| `insert_clip` | Inserting a clip at a position in the timeline |
| `reorder_clips` | Rearranging clip order |
| `add_transition` | Adding cross-dissolve or other transitions between clips |
| `change_speed` | Applying speed changes (slow-mo, fast-forward, reverse) |
| `add_connected_clip` | Adding a clip to a connected lane (B-roll, titles) |
| `add_audio` | Adding audio clips to the timeline |
| `create_compound_clip` | Grouping clips into a compound clip |
| `flatten_compound_clip` | Expanding a compound clip back to individual clips |
| `assign_role` | Setting audio/video roles on clips |
| `apply_template` | Applying a timeline template |

### Auto-Fix (batch operations)
| Tool | Use when... |
|------|-------------|
| `fix_flash_frames` | Automatically extending adjacent clips to cover flash frames |
| `rapid_trim` | Quick batch trim operations |
| `fill_gaps` | Closing gaps by extending adjacent clips |
| `remove_silence_candidates` | Removing or marking detected silence regions |

### Generate (creates new FCPXML files)
| Tool | Use when... |
|------|-------------|
| `auto_rough_cut` | Building a rough cut from library clips with keyword filters and target duration |
| `generate_montage` | Creating a montage from tagged clips with pacing control |
| `generate_ab_roll` | Creating documentary-style A/B roll edits |

### Music & Markers
| Tool | Use when... |
|------|-------------|
| `import_beat_markers` | Importing beat timestamps from JSON for music-synced editing |
| `snap_to_beats` | Snapping all cuts to the nearest beat marker |
| `import_srt_markers` | Importing markers from SRT/VTT subtitle files |
| `import_transcript_markers` | Importing markers from transcript text |

### Export & Reformat
| Tool | Use when... |
|------|-------------|
| `export_edl` | Exporting an EDL (Edit Decision List) |
| `export_csv` | Exporting timeline data as CSV |
| `export_resolve_xml` | Exporting FCPXML v1.9 for DaVinci Resolve |
| `export_fcp7_xml` | Exporting FCP7 XMEML v5 for Premiere / legacy NLEs |
| `export_role_stems` | Exporting separate XMLs per audio role (dialogue, music, SFX) |
| `filter_by_role` | Filtering timeline to only show clips with a specific role |
| `reformat_timeline` | Changing format — presets: `9:16`, `1:1`, `4:5`, `4:3`, `16:9`, or custom |

## Workflow Chains

When the user describes a high-level intent, chain tools in this order:

### QC Pipeline
`analyze_timeline` → `detect_flash_frames` → `detect_gaps` → `detect_duplicates` → `validate_timeline`
Then offer fixes: `fix_flash_frames` → `fill_gaps`

### YouTube Chapter Export
`list_markers` (format: "youtube") → format output for copy-paste
If no chapters exist: `analyze_pacing` → suggest chapter points → `batch_add_markers`

### Rough Cut Assembly
`list_library_clips` → `list_keywords` → discuss structure → `auto_rough_cut` or `generate_montage`

### Beat-Synced Music Video
`import_beat_markers` → `auto_rough_cut` or `generate_montage` → `snap_to_beats`

### Cross-NLE Handoff
`export_resolve_xml` (for Resolve) + `export_fcp7_xml` (for Premiere/Pro Tools)

### Silence Cleanup
`detect_silence_candidates` → review results → `remove_silence_candidates`

### Timeline Comparison
`diff_timelines` → summarize changes for revision log

### Social Reformat
`reformat_timeline` with preset → note that framing adjustments still needed in FCP

## Key Rules

1. **Never overwrite originals.** All write operations create `_modified`, `_chapters`, etc. suffixed files.
2. **Times are rational fractions.** FCPXML uses `"600/2400s"` format — never convert to floats.
3. **Always analyze before fixing.** Run detection tools first, show the user what was found, then offer batch fixes.
4. **Connected clips use lanes.** Positive lane = above primary storyline (video/titles), negative = below (audio).
5. **Compound clips can be nested.** Use `list_compound_clips` to understand structure before flattening.
6. **Export formats differ.** Resolve XML flattens compounds. FCP7 XML converts spine-based to track-based model.