Skip to main content
Glama
Cut Review

Cut Review

by DareDev256

Frame.io comments to Final Cut Pro markers: Cut Review

Cut Review is a free, open source command line tool and MCP server for Final Cut Pro. It writes client notes and Frame.io comment exports into your project's FCPXML as to-do markers on the clips they are about. After the recut it compares two FCPXML exports and shows, on one page, what changed and which notes the recut touched, whether you or an AI agent made the edit.

PyPI Python License: MIT

The Cut Review status page: six notes, three done, four touched, and the two lists where the editor's tick and the cut disagree

The status page from the demo round, on synthesized test media. Website: daredev256.github.io/frameio-to-final-cut-pro

Verified on Final Cut Pro 12.4: to-do markers, their note text and the editor's ticks survive a round trip (the proof).

What this is not

  • Not a review platform. There is no server, no account and no upload. Every page is one HTML file on your disk with nothing to load.

  • It says "touched", never "addressed". Touched means the cut changed near a note. Whether the change is what the reviewer asked for is your call, and the page never claims otherwise.

  • No AI in the notes path. Notes are read by rules you can read in src/cutreview/notes.py. A note with no timecode is listed as not placed; it is never given a time. A line that cannot be read is listed with the reason; it is never dropped.

  • Not an editor. It writes markers and nothing else. It never changes a clip, and it never opens or drives Final Cut.

Related MCP server: fcp-mcp-server

Quick start (60 seconds)

You need uv (brew install uv), Python 3.10 or newer, and an XML export of your project from Final Cut Pro (File > Export XML).

  1. Write your notes, one per line, timecode first, in notes.txt:

    00:00:05:00 Too long on B, cut it down
    00:00:13:00 Drone could breathe, slow it down
  2. Put them on the cut as to-do markers:

    uvx cutreview notes cut.fcpxmld notes.txt

    This writes cut_notes.fcpxmld and prints where each note landed. In Final Cut, File > Import > XML and open the Timeline Index (Shift-Command-2) to see the to-dos.

  3. Recut. Tick each to-do you dealt with. File > Export XML again, say as cut_v2.fcpxmld.

  4. See which notes the recut touched, and what changed:

    uvx cutreview status cut_notes.fcpxmld cut_v2.fcpxmld -o status.html
    uvx cutreview diff cut_notes.fcpxmld cut_v2.fcpxmld -o review.html

ffmpeg on the path adds before and after frames (optional). Final Cut Pro on the same Mac lets every write be checked against Apple's own FCPXML DTD (optional; without it the check says it did not run).

What it does

notes.txt ──► cutreview notes ──► cut_notes.fcpxml  (to-do markers on the clips)
                                       │
                         you, or an agent, recut it in Final Cut
                                       │
              cut_notes.fcpxml + next export ──► cutreview status ──► status.html
  1. cutreview notes writes each note as a Final Cut to-do marker (completed="0") on the clip whose picture shows at that time, in that clip's own source time, so the marker travels with the clip through the recut. The full note goes in the marker's note field.

  2. You recut. Tick a to-do in Final Cut when you have dealt with it. Export XML.

  3. cutreview status reads the next export. Each note is done or open (your tick, which Final Cut writes into the XML) and touched or untouched (did the cut change within a second of it). The page leads with the two places those disagree: ticked but untouched, and changed but not ticked. A note whose clip is gone reads "removed with its clip".

Two more commands work on any two exports, notes or not:

  • cutreview diff old.fcpxml new.fcpxml -o review.html: the change page. Every clip added, removed, trimmed, moved, retimed or adjusted, and every transition added or removed, with a strip of the timeline and before and after frames when the media is on this machine. A clip that only slid because something before it got shorter is counted and not listed.

  • cutreview blame old.fcpxml new.fcpxml: the same page, with each change attributed to the fcp-mcp-server tool call that made it, read from that server's write journal. A change the journal does not explain reads "not in the journal".

Screens from the demo round (synthesized media): change page, status page, status page on a phone, blame page on a phone, light mode.

FAQ

How do I get Frame.io comments into Final Cut Pro?

Export the comments from Frame.io as a CSV (in Frame.io V4: the three-dot menu in the Comments tab), then run uvx cutreview notes cut.fcpxmld comments.csv and import the result with File > Import > XML. Cut Review finds a Frame.io export by its Commenter and Comment columns, writes each comment as a to-do marker on the clip under it, folds replies into the comment they answer, flags drawn-on comments, and writes comments already marked complete as completed markers.

Does it work with Final Cut Pro 12.4?

Yes. Final Cut Pro 12.4 imported the six to-do markers Cut Review wrote at the exact times and on the right clips, showed their note text in the Timeline Index, and wrote the editor's ticks into its XML export as completed="1". Cut Review read that export back as one trim, two notes ticked but untouched and one changed but not ticked, which is what happened. The run, on test media, is written up in docs/final-cut-proof.md and kept as a test.

Does it work with Frame.io V4?

Frame.io documents V4's comment export as CSV or plain text but publishes no column list. Cut Review reads the columns by name, never by position, and has been tested on a file rebuilt from the published V3-era names, not yet on a real V4 export. If your export does not read, open an issue with its header row.

How do I import a CSV of notes as Final Cut Pro markers?

Any CSV with a header row works: Cut Review finds the time column by name (timecode, time, tc, in, start...) and the note column likewise (note, comment, text, feedback...), with an author column if there is one. uvx cutreview notes cut.fcpxmld notes.csv writes them as to-do markers. A row with no time is listed as not placed, never guessed.

How do I compare two FCPXML files and see what changed between two Final Cut exports?

uvx cutreview diff cut_v1.fcpxmld cut_v2.fcpxmld -o review.html writes one HTML page listing every clip added, removed, trimmed, moved, retimed or adjusted, and every transition change, with a timeline strip and before and after frames. Clips are matched by source material, not by name, so a ripple, a head trim or a cut built on connected clips reads correctly.

How do I check what an AI agent changed in my edit?

Run cutreview diff on the export before and after the agent worked. If the agent edited through fcp-mcp-server, uvx cutreview blame before.fcpxml after.fcpxml names the tool call behind each change from that server's write journal, and marks anything done by hand as "not in the journal". If your notes were on the cut, cutreview status shows which of them the agent's changes touched.

How do I track which client notes the recut dealt with?

Put the notes on the cut as to-do markers with cutreview notes, tick them in Final Cut as you work, then run cutreview status on the next export. Each note comes back done or open (your tick) and touched or untouched (whether the cut changed within a second of it), and the page starts with the notes where those two disagree.

Is Cut Review a Frame.io alternative?

No. It does not host video or collect comments from clients. It works on the notes you already get, from Frame.io, email, texts or a call, and on Final Cut's own XML exports.

Is there an MCP server for Final Cut Pro?

Yes: fcp-mcp-server lets Claude and other MCP clients read and edit Final Cut Pro timelines through FCPXML. Cut Review is the review step beside it, as one MCP tool, review, with the actions diff, blame, notes and status (see As an MCP tool).

How it compares

Cut Review

Change List X

Marker Toolbox

Frame.io V4

What it is

Free, open source command line tool and MCP server (MIT)

Mac app, US$199.99

Final Cut workflow extension, US$19.99

Hosted review platform, free and paid plans

Notes into Final Cut as markers

Yes: plain text, any CSV, Frame.io comment CSV, as to-do markers on the clip

No

Yes: Frame.io FIOJSON (including the V4 beta), Vimeo, Wipster, Dropbox Replay, Premiere CSV, Timecode+, email text; resolved comments arrive completed

Comment export as CSV or text; its V3 "Import Comments into FCP" article now redirects to the help center home

Compares two versions of the cut

Any two FCPXML exports, every lane, matched by source material

Primary storylines of two projects, as a PDF or TSV change list with pull and discard lists

No

Plays two uploaded versions side by side or overlaid: the pictures, not the timeline's clips

Which notes the recut touched

Yes: done or open, against touched or untouched

No

No

No

Which agent tool call made each change

Yes, from fcp-mcp-server's journal

No

No

No

Read from each product's own page on 2026-11-12: Change List X, Marker Toolbox, Frame.io comment export, Frame.io Comparison Viewer. Prices are the US Mac App Store's.

Use Change List X when you need a conform change list for sound or VFX, in feet and frames, with pull and discard lists. Use Marker Toolbox when your notes come from Vimeo, Wipster, Dropbox Replay or Frame.io's FIOJSON download, or when you want drawn annotations brought across. Cut Review is for the step after the notes are on the cut: knowing which ones the recut actually changed.

The notes door

$ cutreview notes music-video.fcpxml music-video.notes.txt
6 notes written as to-do markers into music-video_notes.fcpxml
Times counted from the sequence's start timecode.
  #1   00:00:00:12  on SHOT A 1: Open on something brighter, this feels flat
  #2   00:00:05:00  on SHOT B 1: Too long on B, cut it down
  #3   00:00:02:12  on OVERLAY 1: Overlay 1 is too busy, lose it
  #4   00:00:10:12  on OVERLAY 3: Overlay 3 distracts from the lyric
  #5   00:00:13:00  on DRONE 1: Drone could breathe, slow it down
  #6   00:00:30:00  on TRACK (audio only under it): Hold on the performance here
2 not placed (listed, never guessed):
  music-video.notes.txt line 8: no timecode: Overall the colour is great, no notes on the grade
  music-video.notes.txt line 11: after the end of the cut: Fade out sooner
2 unreadable (listed, never dropped):
  music-video.notes.txt line 9: '00:01:75:00' has minutes or seconds past 59: 00:01:75:00 Check the lyric sync
  music-video.notes.txt line 10: a timecode with no note after it: 00:00:13:00
Checked: Valid against FCPXML 1.13 DTD (FCPXMLv1_13.dtd); 6 markers read back on their clips, each within one frame.
Ledger: music-video_notes.fcpxml.cutreview.json

Three formats are read:

  • Plain text, one note per line, timecode first: 00:01:23:12 note, 1:23 note, [00:01:23:12] note, a range 00:01:23:12 - 00:01:25:00 note. An indented line continues the note above it.

  • CSV with a header row. The time column is found by name (timecode, time, tc, in, start...), the note column likewise (note, comment, text, feedback...), and an author column if there is one. A time may be a timecode or plain seconds.

  • Frame.io's comment CSV export, found by its Commenter and Comment columns. Columns are matched by name, so added or reordered columns still read. Replies are folded into the comment they answer, drawn-on comments are flagged, and comments already marked complete are written as completed markers. --source-tc uses the Timecode Source columns. Frame.io publishes no column list for V4; see DECISIONS.md for where the names come from.

Timecodes count from the sequence's start timecode, as Final Cut shows them. If the sequence starts at zero, the cut is under an hour, and every note reads past 01:00:00:00, cutreview reads the file as a review copy with an hour start and says so. --start-tc sets it by hand.

Two checks run on every write, and either one failing leaves no file behind: xmllint against Apple's own FCPXML DTD from the installed Final Cut Pro, and a read-back through fcp-mcp-server's parser that must find each marker on its clip within one frame. Files are written as FCPXML 1.13 (a 1.14 input stays 1.14).

The change door

cutreview diff compares material, not clip names. Each clip is a range of a source file; two cuts are compared source by source:

Reads as

When

removed / added

a clip's material is wholly gone, or wholly new

trimmed

some of a clip's material left or entered at its start, its end or its middle

moved

material now plays out of order on the primary storyline, or a connected clip moved off its anchor or to another lane

retimed

the clip's speed changed

adjusted

an adjust-* or filter-* setting changed, or the clip was disabled

transition

a transition was added, removed or changed length

Clips that only slid with a ripple are counted, not listed. Frames on the page are source frames: effects, titles and grades are not drawn.

cutreview blame reads fcp-mcp-server's journal from FCP_MCP_JOURNAL, the project folder (or its journal/ or .fcp-mcp/journal/), or ~/.fcp-mcp/journal/, and walks it hash by hash from the old file. Each change goes to the last journaled write that changed that material. Work done after the last journaled write reads "not in the journal (by hand in Final Cut, or a tool with no journal)". If a file between two writes is gone, those writes are named together.

As an MCP tool

uvx cutreview mcp

One tool, review, over stdio, with four actions: diff, blame, notes, status. Every file it writes stays inside the folder of the cut it was given.

Claude Code:

claude mcp add cutreview -- uvx cutreview mcp

Claude Desktop and other clients that take a JSON config:

{
  "mcpServers": {
    "cutreview": { "command": "uvx", "args": ["cutreview", "mcp"] }
  }
}

Its name in the official MCP registry is io.github.DareDev256/cutreview. It pairs with fcp-mcp-server, which does the editing.

Work on it

git clone https://github.com/DareDev256/frameio-to-final-cut-pro && cd frameio-to-final-cut-pro
uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest

What "touched" means, exactly

A note is touched when a change lies within one second (--reach) of the note's frames on the earlier cut, or of its marker on the later cut. A change on an audio lane touches only notes that sit on audio, so moving the music bed does not touch a note about the picture. A clip that only slid with a ripple is not a change and touches nothing. That is all. A trim beside a note touches it whether or not it is the trim the reviewer wanted.

Limits in v0.1

  • Final Cut only. Resolve and Premiere projects wait for v0.2.

  • The Final Cut round trip has been run once, on test media with one trim (docs/final-cut-proof.md). A real project with blades, transitions and speed changes made in Final Cut is the next round.

  • No voice notes, no notes without timecodes placed, no undo of a single change.

  • A speed ramp is read as one average speed.

  • Clips inside compound clips are not looked into.

Credits

Built on fcp-mcp-server (MIT), which supplies the FCPXML parser, the writer's element walker, the write journal and the DTD check. The fixtures fixtures/music-video.fcpxml and fixtures/sample.fcpxml come from its examples; its license is in fixtures/LICENSE-fcp-mcp-server.

License

MIT. Copyright (c) 2026 James Olusoga (DareDev256), jamesdare.com.

Available Tools

15 tools
deliverA

Get the edit out: export to other NLEs, CSV, EDL and stems, reformat, relink media, or push straight into a running Final Cut Pro. Exports and push refuse a cut with no rendered preview of its current state (pass confirm_unreviewed=true to ship anyway). Actions: export_csv, export_edl, export_fcp7_xml, export_resolve_xml, export_role_stems, reformat_timeline, relink_media, push_to_fcp, list_fcp_libraries.

Inputs: action (required), args.

diagnoseA

Find problems in a timeline: gaps, flash frames, duplicates, dead air, and beat structure. Read-only. Run before editing. Actions: validate_timeline, detect_gaps, detect_duplicates, detect_flash_frames, detect_silence_candidates, detect_media_silence, detect_beats, find_short_cuts, find_long_clips, diff_timelines.

Inputs: action (required), args.

editB

Change clips on the timeline: insert, delete, trim, split, reorder, retime, remove silence, and attach audio, B-roll or transitions. Writes a new file. Actions: insert_clip, delete_clips, trim_clip, split_clip, reorder_clips, change_speed, rapid_trim, add_transition, add_audio, add_connected_clip, assign_role, fill_gaps, fix_flash_frames, remove_silence_candidates, remove_media_silence, set_keyframes, delete_keyframes, batch_keyframes, set_animation_curve, set_speed_curve, reset_speed.

Inputs: action (required), args.

findA

Natural-language shot search. find_shots (filepath, query, limit=10, visual=false, clip_name?) ranks moments by what was said (transcript), what was logged (names, keywords, notes, markers, audio events) and, when a local vision model is installed, what the frames look like — the first line of every result names which tiers answered and why one could not. find_index (captions=true, backend) warms scenes and captions and reports which clips have no transcript (it never transcribes or goes online). find_to_timeline (min_source_separation=1, output_path?) assembles the hits into a _found selects reel and reports its diversity score. Actions: find_index, find_shots, find_to_timeline.

Inputs: action (required), args.

genA

Generative fill, quote-then-confirm. gen_quote(provider, seconds, prompt, model?) prices a job from a dated table (fal: kling-2.5, wan-2.5; gemini: veo-3.1; runway/luma are honest stubs) and returns a quote id. gen_fill_gap(filepath, prompt, gap_index|at), gen_broll(filepath, clip_name, prompt, seconds=5, at?) and gen_extend_clip(filepath, clip_name, seconds=5) REFUSE without quote_id + confirm=true, a matching job, a key in the environment (FAL_KEY / GEMINI_API_KEY) and a price under FCP_MCP_GEN_MAX_USD (default 5). The result is probed with ffprobe for its real fps and length, saved under generated/ next to the project, attached as a connected clip with role generated and a marker naming prompt and provider, DTD-validated and journaled. Actions: gen_quote, gen_fill_gap, gen_broll, gen_extend_clip.

Inputs: action (required), args.

generateB

Build new timeline structure from source clips: rough cuts, montages, A/B roll, templates and compound clips. Actions: auto_rough_cut, generate_ab_roll, generate_montage, apply_template, create_compound_clip, flatten_compound_clip, import_edl_json.

Inputs: action (required), args.

indexA

The analysis cache under ~/.fcp-mcp/index.db. index_status shows what is cached and how old it is; index_build warms it for every source in a timeline (args: filepath, with_transcript); index_clear drops it. Every other tool works with the index off (FCP_MCP_INDEX=off) — this only makes the second question fast. Actions: index_status, index_build, index_clear.

Inputs: action (required), args.

inspectB

Read a timeline or project without changing it. Use this first to understand what you are working with. Actions: list_projects, analyze_timeline, analyze_pacing, list_clips, list_markers, list_roles, list_keywords, list_effects, list_templates, list_library_clips, list_compound_clips, list_connected_clips, filter_by_role, list_keyframes, list_speed_points.

Inputs: action (required), args.

markB

Add or import markers and chapters, including from SRT/VTT subtitles, transcripts, and beat analysis. Actions: add_marker, batch_add_markers, import_srt_markers, import_transcript_markers, import_beat_markers, snap_to_beats.

Inputs: action (required), args.

organizeA

Bulk library logging and the ledger. organize_auto proposes keywords per clip from cached captions and the transcript (apply=true writes them). Select clips with clip_name (glob), keyword and/or role, then organize_keywords (keywords, mode add|remove|replace), organize_rate (rating favorite|rejected|clear) or organize_roles (audio_role, video_role); each writes a _organized copy. history lists every recorded operation for the file's folder (limit); undo (n) moves the outputs of the last n writes into the journal's undone/ folder — it never deletes and refuses when a file changed since it was written. Actions: organize_auto, organize_keywords, organize_rate, organize_roles, history, undo.

Inputs: action (required), args.

previewB

See the edit without opening Final Cut Pro. Render a proxy video of the timeline, a contact sheet of every cut, a single frame, or a filmstrip-plus-waveform check read from the SOURCE MEDIA rather than from the XML. Run preview_check to confirm a fix actually landed. Actions: preview_render, preview_sheet, preview_frame, preview_check, preview_timeline.

Inputs: action (required), args.

scenesA

Shot boundaries. detect_scenes reads every source in a timeline and reports cuts in timeline time (args: filepath, clip_name?, backend auto|content|adaptive|ffmpeg, threshold?, min_scene_len=0.5); scenes_to_markers writes a marker at each cut; scenes_split cuts the clips there. PySceneDetect via the scenes extra, ffmpeg without it — the result names which one answered. Actions: detect_scenes, scenes_to_markers, scenes_split.

Inputs: action (required), args.

transcriptB

Transcribe source media locally and edit the timeline by what was SAID rather than by timecode. Also removes filler words. Actions: transcribe_media, edit_by_transcript, remove_filler_words, transcript_pack.

Inputs: action (required), args.

viewA

See the cut inline. view_timeline(filepath, thumbnails=true, words=true) returns the timeline — lanes, clips, markers, gaps, cached transcript words and filmstrip thumbnails — as an exact rational-time JSON payload that hosts with MCP Apps render as an interactive timeline (clip details, range selection, inspect / find-similar / marker / delete buttons that call the other tools). view_clip(filepath, clip_name) is the inspect button. Read-only; edits go through edit and mark. Actions: view_timeline, view_clip.

Inputs: action (required), args.

watchA

Close the round-trip. Watch the Final Cut Pro export folder, detect the XML the moment it lands, and diff it against the last one seen. Pair with deliver.push_to_fcp for a full loop: push in, edit, Cmd-E, watch_pull. Actions: watch_start, watch_status, watch_stop, watch_pull.

Inputs: action (required), args.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation3/5

    Most high-level categories are described clearly, but several pairs overlap: generate (timeline generation) vs gen (AI fill), view vs preview vs inspect, and edit vs scenes/mark for splitting and markers. Read-only vs write distinctions help, but an agent can still land in the wrong mega-tool.

    Naming Consistency3/5

    Action names inside tools are consistently snake_case verb_noun, but top-level tool names mix verbs (edit, find, view), nouns (transcript, index, scenes), and the abbreviation gen alongside generate. The all-lowercase style is readable, but the pattern is not predictable.

    Tool Count4/5

    15 top-level tools is within a reasonable range for a complex Final Cut Pro editing/review surface, and each category has a role. However, several are mega-tools with dozens of actions, especially edit, making the set feel heavy despite the nominal count.

    Completeness4/5

    Covers inspection, diagnosis, editing, markers, generation, transcription, delivery, previewing, round-trip watching, indexing, scenes, organization, and generative fill—broad lifecycle coverage. Minor gaps remain around project creation/deletion, audio/color-level operations, and effect application, but core cut-review workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude and other MCP clients to read, edit, and generate real Final Cut Pro timelines from FCPXML, including cut detection, markers, roles, silence removal, transcript-based editing, cross-NLE export, and pushing changes into a running Final Cut Pro. Every write is journaled and undoable, with validation and safety checks for reliable timeline edits.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables an MCP client like Claude to read, edit, and generate real Final Cut Pro timelines from exported FCPXML, covering cut and flash-frame detection, silence and gap removal, markers, keyframes, speed ramps, transcript-based editing, cross-NLE export, and pushing the result into a running Final Cut Pro. Every write is journaled with its sha256 so changes can be undone and unreviewed cuts refused.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users to let an MCP client read, edit, and generate real Final Cut Pro timelines from exported XML or live projects, covering cut detection, markers, roles, transcript-based edits, keyframes, speed ramps, rough cuts, and cross-NLE export.
      -