> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Final Cut Pro Integration

> AI-powered video editing automation for Final Cut Pro

# Final Cut Pro Integration

PraisonAI provides seamless integration with Final Cut Pro through FCPXML generation and CommandPost automation. Convert natural language editing instructions to professional video edits with zero manual import steps.

## Overview

The FCP integration pipeline:

```
Instruction → EditIntent JSON → FCPXML → CommandPost Watch Folder → FCP Auto-Import
```

## Prerequisites

<CardGroup cols={2}>
  <Card title="macOS" icon="apple">
    Required for Final Cut Pro
  </Card>

  <Card title="Final Cut Pro" icon="video">
    Apple's professional video editing software
  </Card>

  <Card title="CommandPost" icon="terminal">
    Download from [commandpost.io](https://commandpost.io)
  </Card>

  <Card title="OpenAI API Key" icon="key">
    Set `OPENAI_API_KEY` environment variable
  </Card>
</CardGroup>

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai openai
```

## Quick Start

### CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple concatenation (no LLM required)
praisonai fcp autoedit --simple \
  --media /path/to/clip1.mov \
  --media /path/to/clip2.mov

# AI-powered editing
praisonai fcp autoedit \
  --instruction "Create a highlight reel with the best moments" \
  --media /path/to/clip1.mov \
  --media /path/to/clip2.mov

# Dry run (generate without importing)
praisonai fcp autoedit \
  --instruction "Add background music" \
  --media /path/to/video.mov \
  --media /path/to/music.mp3 \
  --dry-run --print-fcpxml
```

### Python API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.integrations.fcp import (
    generate_edit_intent,
    FCPXMLGenerator,
    Injector,
)

# Generate EditIntent from natural language
intent, warnings = generate_edit_intent(
    instruction="Concatenate all clips with crossfades",
    media_paths=["/path/to/clip1.mov", "/path/to/clip2.mov"],
    project_name="My Project",
    format_preset="1080p25",
)

# Generate FCPXML
generator = FCPXMLGenerator(intent)
fcpxml = generator.generate()

# Inject into Final Cut Pro
injector = Injector()
job_id, path, messages = injector.inject_one_shot(fcpxml)
print(f"Injected: {job_id}")
```

## Commands

### `praisonai fcp autoedit`

Generate and inject FCPXML from natural language instructions.

| Flag                     | Description                                |
| ------------------------ | ------------------------------------------ |
| `--instruction, -i`      | Natural language editing instruction       |
| `--instruction-file, -f` | Path to file containing instruction        |
| `--media, -m`            | Media file path (repeatable)               |
| `--project-name, -n`     | Project name (default: "Untitled Project") |
| `--format`               | Format preset (default: "1080p25")         |
| `--dry-run`              | Generate without injecting                 |
| `--print-intent`         | Print EditIntent JSON                      |
| `--print-fcpxml`         | Print generated FCPXML                     |
| `--simple`               | Use simple concatenation (no LLM)          |
| `--model`                | OpenAI model (default: "gpt-4o")           |

### `praisonai fcp doctor`

Run health checks for FCP integration.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai fcp doctor
```

Output:

```
============================================================
FCP Integration Health Check
============================================================

  ✓ macOS: Running on macOS 14.0
  ✓ Final Cut Pro: Found at /Applications/Final Cut Pro.app
  ✓ CommandPost App: Found at /Applications/CommandPost.app
  ✓ cmdpost CLI: Found at /Applications/CommandPost.app/...
  ✓ Watch Folder: Exists at ~/.praisonai/fcp/watch/fcpxml
  ✓ Auto-Import: Enabled in CommandPost
  ✓ OpenAI API Key: Set (ending in ...abc1)

============================================================
All checks passed! FCP integration is ready.
============================================================
```

### `praisonai fcp bootstrap-commandpost`

One-time setup for CommandPost integration.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai fcp bootstrap-commandpost
```

### `praisonai fcp daemon`

Manage the injection daemon for batch processing.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start daemon
praisonai fcp daemon start

# Check status
praisonai fcp daemon status

# Stop daemon
praisonai fcp daemon stop
```

## Format Presets

| Preset    | Resolution | FPS |
| --------- | ---------- | --- |
| `1080p25` | 1920x1080  | 25  |
| `1080p30` | 1920x1080  | 30  |
| `1080p24` | 1920x1080  | 24  |
| `1080p50` | 1920x1080  | 50  |
| `1080p60` | 1920x1080  | 60  |
| `4k25`    | 3840x2160  | 25  |
| `4k30`    | 3840x2160  | 30  |
| `4k24`    | 3840x2160  | 24  |
| `720p25`  | 1280x720   | 25  |
| `720p30`  | 1280x720   | 30  |

## Supported Operations

### Implemented (v1)

* ✅ Create projects with primary storyline
* ✅ Place asset clips in sequence
* ✅ Set audio roles (dialogue, music, effects)
* ✅ Add chapter markers
* ✅ Basic volume adjustments

### Planned

* ⏳ Silence/pause removal
* ⏳ Audio normalization (LUFS)
* ⏳ Zoom/Ken Burns effects
* ⏳ Transitions

## EditIntent Schema

The EditIntent JSON schema defines the structure for video editing instructions:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "version": "1",
  "project": {
    "name": "My Project",
    "format": {"width": 1920, "height": 1080, "fps": 25.0},
    "audio": {"layout": "stereo", "rate": 48000, "channels": 2}
  },
  "assets": [
    {
      "id": "r2",
      "name": "interview",
      "path": "/path/to/interview.mov",
      "has_video": true,
      "has_audio": true
    }
  ],
  "timeline": {
    "segments": [
      {
        "asset_id": "r2",
        "offset": "0/2500s",
        "start": "0/2500s",
        "duration": "5000/2500s",
        "role": "dialogue"
      }
    ],
    "markers": []
  }
}
```

## Agent Recipe

Use the `fcp-autoedit` recipe for multi-agent workflows:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run fcp-autoedit "Create a 30-second highlight reel" \
  --media /videos/clip1.mov \
  --media /videos/clip2.mov
```

## Troubleshooting

### CommandPost not found

1. Download CommandPost from [commandpost.io](https://commandpost.io)
2. Move to `/Applications/CommandPost.app`
3. Launch CommandPost at least once
4. Run `praisonai fcp bootstrap-commandpost`

### Auto-import not working

1. Ensure CommandPost is running
2. Check watch folder exists: `ls ~/.praisonai/fcp/watch/fcpxml`
3. Verify auto-import is enabled in CommandPost preferences
4. Run `praisonai fcp doctor` for diagnostics

### FCPXML import errors

1. Use `--print-fcpxml` to inspect the generated XML
2. Validate with `--validate-dtd` flag
3. Check media file paths are absolute and files exist