Skip to content
CutConvert

Generate FCPXML for Final Cut Pro programmatically

To generate FCPXML programmatically, send an Edit JSON document to the Edit API with the target finalcut, or pass it to writeFinalCutXml in the open package @cutconvert/edit once it's on npm. Both give the same FCPXML 1.10 file, which Final Cut Pro imports with File > Import > XML.

Final Cut Pro 11.2 imported all nine test projects and its library matched every edit, though retimed clips show one source frame early.

Updated

See the codeGet a free API key

3 exports a month without a key, 10 with a free one. API pricing

What you get for Final Cut Pro

The finalcut/ folder of the zip holds one .fcpxml named after the document. In Final Cut Pro, choose File > Import > XML and pick it.

Once it's on npm, the open package writes the same file in Node 18 and later or in any browser with ES2022. It reads no files, makes no network calls and has no dependencies.

Apple's reference for the format is the FCPXML Reference.

The code

With the Edit API

The same call as on the overview, with only finalcut in targets.

request.json
{
  "edit": {
    "cutconvert": "edit/1",
    "name": "Edit 09 minimal",
    "timeline": { "fps": 25, "width": 1280, "height": 720 },
    "media": [
      { "id": "silent", "name": "silent-25.mp4", "duration": 30.0, "fps": 25, "width": 1280, "height": 720 }
    ],
    "video": [
      { "clips": [{ "media": "silent", "start": 0, "in": 2, "out": 12 }] }
    ]
  },
  "targets": ["finalcut"]
}
Terminal
curl -sS https://cutconvert.com/api/edit/export \
  -H "Content-Type: application/json" \
  --data @request.json \
  -o edit.zip
edit.zip
finalcut/
  Edit 09 minimal.fcpxml
report.json

With the open package, writeFinalCutXml

writeFinalCutXml takes the same input and options as writePremiereXml and returns the FCPXML and its warnings. In a browser it takes the text of a file someone picked.

@cutconvert/edit isn't on npm yet. We'll publish it soon. Until then, npm install won't find it.

Terminal
npm install @cutconvert/edit
export.mjs
import { readFile, writeFile } from 'node:fs/promises';
import { writeFinalCutXml } from '@cutconvert/edit';

const edit = await readFile('episode-41.edit.json', 'utf8');
const { fcpxml, warnings } = writeFinalCutXml(edit, { name: 'episode-41' });
await writeFile('episode-41.fcpxml', fcpxml);
for (const warning of warnings) console.warn(warning.code, warning.message);

The package's documentation covers validateEdit, editToSequences and the warnings.

What carries over to Final Cut Pro

When a loss depends on the document, report.json also warns, with a code and a sentence. A dissolve under 3 frames that can't stretch, because a clip has no spare footage, comes back as fcpxml-short-transition.

Final Cut Pro
CaptionsBasic Titles on the top lane
TitlesBasic Titles
Stroke and boxStroke, not the box
BoldCarried
Audio fadesThe clip's own fade handles
Sound under a cross dissolveAudio Crossfade when centred with footage on both sides; otherwise each clip fades on its own side
Media with no pathOffline, in /CutConvert Offline Media; File > Relink Files finds it
Picture and soundSeparate connected clips, the picture above the storyline and the sound below it, not linked
Sound at −96 dB or lowerA disabled clip at −96 dB
Track namesNot carried: Final Cut has lanes, not tracks
Start timecodeCarried

Compare all four editors

Checked in Final Cut Pro 11.2

We opened the test documents' projects in the editor on October 29, 2026, on macOS, then read back what it kept from its own project file or export.

  • Every clip start, end and in point matched, and so did the dissolves. Fades are clip fade handles.
  • Captions are Basic Titles at their frames, white and bold with a black outline. Final Cut doesn't draw the box, and report.json warns with fcpxml-title-background.
  • Media with no path opened offline, and File > Relink Files matched the file.

Relinking media with no path

A document can name a file with no path. Each editor then opens the edit with that file's clips offline, under the file's name, until you link them. This is what Final Cut Pro 11.2 shows.

On openingTo relink
Nothing: the clips show "Missing File".File > Relink Files > Original Media… opens "Relink Clips to Original Media Files". Locate All…, pick the file ("Click Choose to verify match of file …"), and it reports "1 of 1 files matched"; Relink Files.

Limits

  • Final Cut shows retimed clips one source frame early. It keeps a retime's rate in floating point, so 200% is 199.99997%. The issue is open on every route into FCPXML.
  • Final Cut keeps a transition only from 3 frames. The writer stretches a shorter dissolve when both clips have the footage, and otherwise leaves it out with the warning fcpxml-short-transition.
  • Windows and UNC paths reach the FCPXML with no warning, and we haven't opened one in Final Cut yet.
  • Final Cut doesn't carry track names, because it has lanes, not tracks.
  • A call is at most 25 MB, media included, and the document on its own at most 8 MB. A document places up to 20,000 clips, captions and titles in all, and a video clip whose file has sound counts twice.
  • Version 1 of the format leaves out variable speed, nested timelines, transitions other than cross dissolve, effects, colour, multicam, still images, scale or opacity keyframes, marker colours, and trimming media on the server.

FAQ

How do I open the FCPXML in Final Cut Pro?

Choose File > Import > XML and pick the .fcpxml. In Final Cut Pro 11.2 it imported into a new library with no dialogs.

Can I generate FCPXML without calling an API?

Yes, with the open package @cutconvert/edit once it's on npm. Its writeFinalCutXml runs in Node or a browser, and on 696 test documents it wrote the same FCPXML as the Edit API, byte for byte. It's MIT licensed.

Are captions editable in Final Cut?

Yes. Captions are Basic Titles on the top lane, with their outline but not their box.

How do I relink media with no path?

The clips show "Missing File". Choose File > Relink Files > Original Media…, click Locate All…, pick the file and click Relink Files. Final Cut links a file only when it matches the frame rate, timecode range and sound channels the document declares, so give each file its own facts.

Why are retimed clips a frame early?

Final Cut keeps a retime's rate in floating point, 199.99997% for 200%, and shows the frame below. It happens on every route into FCPXML. We've drafted a writer fix but haven't shipped it.

More for developers

Questions about the Edit API: [email protected]