---
name: final-cut-pro
description: "Automate Final Cut Pro interchange with FCPXML, prepare Motion or Compressor workflows, and troubleshoot media rendering."
category: video-editing
risk: safe
source: self
source_type: self
date_added: "2026-08-26"
tags: ["final-cut-pro", "fcpxml-v11", "apple-silicon-media-engine", "prores-raw", "magnetic-timeline", "compressor-cli", "claude"]
tools: ["claude", "cursor", "gemini", "codex"]
---
# Apple Final Cut Pro NLE AI Skill Guide (Claude)
## Overview & Engine Architecture
Apple Final Cut Pro is a non-linear video editing (NLE) application engineered exclusively for macOS, Metal, and the Apple Silicon Media Engine (dedicated hardware ProRes/HEVC encode/decode accelerators). Final Cut Pro's core architecture centers around the **Magnetic Timeline (collision-free ripple editing & connected clips)**, native **ProRes / ProRes RAW / Apple Log** processing, **FCPXML (v1.11 / v1.12)** metadata interchange schemas, **Motion 5 Template integration**, and headless batch encoding via the **Apple Compressor CLI (`compressor`)**. Claude operates as a Principal macOS Post-Production Systems Architect and Final Cut Pro Automation Specialist, specializing in **FCPXML sequence synthesis**, **Apple Silicon Media Engine optimization**, **Library (`.fcpbundle`) storage maintenance**, and **Compressor batch render automation**.
### Final Cut Pro Engine & FCPXML Dataflow Stack
```
┌─────────────────────────────────────────────────────────────┐
│ Final Cut Pro Architecture │
│ │
│ Magnetic Timeline & Editing Core │
│ ├── Primary Storyline & Connected B-Roll Audio/Video Clips │
│ ├── Compound Clips, Multicam Sync (Up to 64 Angles) │
│ └── Object Tracker & Cinematic Mode AI Depth Maps │
│ │
│ Apple Silicon & Metal Hardware Pipeline │
│ ├── Apple Silicon Media Engine (Hardware ProRes Accelerator│
│ ├── Metal 3 Shaders & Wide Gamut HDR (Rec.2020 PQ / HLG) │
│ └── Background Render Cache & Automatic Optical Flow Warp │
│ │
│ Interchange & Automation Subsystem │
│ ├── FCPXML Interchange Engine (DTD v1.11 / v1.12 XML) │
│ ├── Apple Compressor Command Line (`compressor -batchname`)│
│ └── Motion 5 Template Pipeline (`~/Movies/Motion Templates`)│
└─────────────────────────────────────────────────────────────┘
```
---
## Operational Capabilities & Agent Directives
1. **Programmatic FCPXML Generation**: Author Python scripts to construct valid FCPXML documents specifying project formats, assets, synchronized audio/video storylines, connected titles, and chapter markers.
2. **Library (`.fcpbundle`) Storage Triage**: Recover hundreds of gigabytes of disk space by automating the purging of redundant high-resolution ProRes 422 render files and optical flow caches.
3. **Apple Silicon Codec & Performance Tuning**: Optimize editing playback by configuring ProRes Proxy media pipelines and setting Viewer quality to "Better Performance".
4. **Apple Compressor CLI Batch Automation**: Construct bash scripts dispatching automated multi-format export jobs (ProRes master, web H.264, YouTube 4K) using the `compressor` command line tool.
---
## Production Python Automation: Automated FCPXML v1.11 Timeline Generator
Save this script as `generate_fcpxml.py` to programmatically build an importable Final Cut Pro project XML file:
```python
"""
Apple Final Cut Pro: Automated FCPXML v1.11 Sequence Generator
Generates a valid FCPXML sequence file containing video assets, audio b-roll, and markers.
"""
import sys
import xml.etree.ElementTree as ET
def generate_fcpxml_project(project_name: str, output_xml_path: str):
print(f"--- [GENERATING APPLE FCPXML PROJECT: {project_name}] ---")
# 1. Root Element & DTD Version
root = ET.Element("fcpxml", {"version": "1.11"})
# 2. Resources Element (Formats and Media Assets)
resources = ET.SubElement(root, "resources")
# 4K UHD 24fps Format (frameDuration="100/2400s")
ET.SubElement(resources, "format", {
"id": "r1",
"name": "FFVideoFormat3840x2160p24",
"frameDuration": "100/2400s",
"width": "3840",
"height": "2160",
"colorSpace": "1-1-1 (Rec. 709)"
})
# Asset Definition
asset = ET.SubElement(resources, "asset", {
"id": "r2",
"name": "Interview_A_Cam",
"src": "file:///Volumes/Media/Footage/Interview_01.mov",
"start": "0s",
"duration": "600s",
"hasVideo": "1",
"hasAudio": "1",
"format": "r1"
})
# 3. Library & Event Hierarchy
library = ET.SubElement(root, "library", {"location": "file:///Volumes/Media/AutoLibrary.fcpbundle"})
event = ET.SubElement(library, "event", {"name": "Automated_Assembly"})
project = ET.SubElement(event, "project", {"name": project_name})
# 4. Sequence & Spine (Primary Storyline)
sequence = ET.SubElement(project, "sequence", {
"format": "r1",
"duration": "120s",
"tcStart": "0s",
"tcFormat": "NDF"
})
spine = ET.SubElement(sequence, "spine")
# Primary Storyline Video Clip
clip = ET.SubElement(spine, "asset-clip", {
"ref": "r2",
"offset": "0s",
"name": "Interview_A_Cam_Take1",
"start": "10s",
"duration": "60s",
"format": "r1"
})
# Add Marker on Clip
ET.SubElement(clip, "marker", {
"start": "25s",
"duration": "100/2400s",
"value": "Subject begins intro statement",
"completed": "0"
})
# Write Output XML
tree = ET.ElementTree(root)
ET.indent(tree, space=" ", level=0)
tree.write(output_xml_path, encoding="utf-8", xml_declaration=True)
print(f"✅ Successfully generated Final Cut Pro XML: {output_xml_path}")
print("To import: In Final Cut Pro, select File -> Import -> XML -> select this file.")
if __name__ == "__main__":
out = sys.argv[1] if len(sys.argv) > 1 else "AutoAssembly_Project.fcpxml"
generate_fcpxml_project("Review_Assembly_V1", out)
```
---
## Technical Troubleshooting Matrix
| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **Library (`.fcpbundle`) Size Balloons to $>500\text{GB}$** | Background render files accumulating for every edit in ProRes 422 format. | 1. In Final Cut Pro, select Library in sidebar.
2. Select *File $\rightarrow$ Delete Generated Library Files*.
3. Check **Delete Render Files (All)** and click OK.
4. In Preferences $\rightarrow$ Playback, uncheck **Background render**. |
| **FCPXML Import Error: `DTD Validation Failed`** | Time values do not conform to rational frame fraction strings (e.g. `100/2400s` for 24fps or `100/3000s` for 30fps). | Ensure all `duration`, `start`, and `offset` attributes in FCPXML use exact rational fractions or integer seconds (`10s`). |
| **Motion Title / Effect Shows Red Warning Screen: `Missing Plugin`** | Custom Motion Template was moved or not installed in user template folder. | Verify template is located in `~/Movies/Motion Templates.localized/Titles/` with `.localized` extension intact. |
| **ProRes RAW Frame Drops on 8K Timeline** | External drive read throughput cannot sustain $>300\text{MB/s}$ continuous bandwidth. | In Viewer menu (top-right), switch from **Original/Optimized** to **Proxy Preferred** after generating 50% ProRes Proxies. |
---
## Command Line Syntax & Apple Compressor Recipes
```bash
# 1. Open Final Cut Pro Library via Terminal
open -a "Final Cut Pro" "/Volumes/Media/Production.fcpbundle"
# 2. Execute Apple Compressor Batch Export via CLI
compressor -batchname "WebDailyMaster" -jobpath "/Volumes/Media/Exports/" -settingpath "ProRes 422 4K.cmprstng"
# 3. Read Final Cut Pro User Preferences
defaults read com.apple.FinalCut
```
### Essential File Locations
- **FCP Libraries**: `*.fcpbundle` (macOS Packages)
- **Motion Templates**: `~/Movies/Motion Templates.localized/`
- **User Preferences**: `~/Library/Preferences/com.apple.FinalCut.plist`
---
## Agent Operational Directive
> **MANDATORY**: When generating FCPXML documents, always express frame durations as exact rational fractions (e.g. `100/2400s` for 23.976/24fps) to prevent timeline timecode drift across NLE roundtrips.