Final Cut Pro

---
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.<br>2. Select *File $\rightarrow$ Delete Generated Library Files*.<br>3. Check **Delete Render Files (All)** and click OK.<br>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.