Parse an FCPXML file and return a structure summary.

Args: path: Path to .fcpxml file (absolute or relative to FCP_PROJECTS_DIR)

List all clips in the timeline with timecodes, durations, and roles.

Args: path: Path to .fcpxml file project_name: Optional project name filter (uses first project if empty)

List all markers, chapter markers, and keywords across all clips.

Args: path: Path to .fcpxml file

Analyze shot pacing — average/median shot length, distribution histogram.

Args: path: Path to .fcpxml file

Find all gaps in the timeline.

Args: path: Path to .fcpxml file

Find clips shorter than max_frames (potential flash frames / accidental edits).

Args: path: Path to .fcpxml file max_frames: Maximum frame count to flag (default 2)

Find clips that use the same source media.

Args: path: Path to .fcpxml file

Validate FCPXML structure and report errors/warnings.

Args: path: Path to .fcpxml file

List all effects and transitions applied to clips.

Args: path: Path to .fcpxml file

List all roles and subroles used in the timeline.

Args: path: Path to .fcpxml file

Get comprehensive timeline statistics — duration, clip count, resolution, pacing, etc.

Args: path: Path to .fcpxml file

Compare two FCPXML files and show differences.

Args: path_a: Path to first .fcpxml file path_b: Path to second .fcpxml file

Add a marker to a clip.

Args: path: Path to .fcpxml file clip_name: Name of the clip to add the marker to start: Marker position in FCPXML time (e.g., "60060/30000s") value: Marker title/value note: Optional marker note marker_type: "standard" or "chapter" output_path: Output file path (default: adds _modified suffix)

Add multiple markers at once.

Args: path: Path to .fcpxml file markers_json: JSON array of markers, each: {"clip_name": str, "start": str, "value": str, "note"?: str, "type"?: str} output_path: Output file path (default: adds _modified suffix)

Add a keyword to a clip.

Args: path: Path to .fcpxml file clip_name: Name of the clip value: Keyword text start: Start time in FCPXML format duration: Duration of keyword range (optional) output_path: Output file path

Trim a clip's source in/out points.

Args: path: Path to .fcpxml file clip_name: Name of the clip to trim new_start: New source start time (optional) new_duration: New duration (optional) output_path: Output file path

Split a clip at a given offset within the clip.

Args: path: Path to .fcpxml file clip_name: Name of the clip to split split_at: Offset within the clip to split at (FCPXML time) output_path: Output file path

Remove clips from the timeline by name.

Args: path: Path to .fcpxml file clip_names_json: JSON array of clip names to delete output_path: Output file path

Reorder clips in the primary spine to match the given name order.

Args: path: Path to .fcpxml file clip_names_json: JSON array of clip names in desired order output_path: Output file path

Insert a transition after a clip.

Args: path: Path to .fcpxml file after_clip_name: Name of the clip to add transition after duration: Transition duration (default: 1 second at 29.97) name: Transition name output_path: Output file path

Change clip playback speed.

Args: path: Path to .fcpxml file clip_name: Name of the clip speed_factor: Speed multiplier (2.0 = 2x fast, 0.5 = half speed) output_path: Output file path

Set the role on a clip (e.g., "Dialogue", "Video", "Music", "Effects").

Args: path: Path to .fcpxml file clip_name: Name of the clip role: Role name output_path: Output file path

Add a title clip to the timeline.

Args: path: Path to .fcpxml file text: Title text duration: Title duration in FCPXML time position: "start", "end", or clip name to insert after output_path: Output file path

Add an audio clip to the timeline.

Args: path: Path to .fcpxml file audio_src: Path to audio file name: Clip name (defaults to filename) duration: Duration in FCPXML time (defaults to asset duration) position: "start", "end", or clip name to insert after output_path: Output file path

Create a new empty FCPXML project file.

Args: name: Project name format_name: Video format (e.g., FFVideoFormat1080p2997, FFVideoFormat4Kp24) width: Frame width height: Frame height frame_duration: Frame duration in FCPXML time event_name: Event name output_path: Where to save (default: ~/Movies/.fcpxml)

Build a timeline from a list of clip definitions.

Args: clips_json: JSON array of clips, each: {"src": "/path/to/file.mov", "name"?: str, "duration": "FCPXML_time", "start"?: str, "role"?: str} project_name: Project name format_name: Video format name event_name: Event name output_path: Where to save

Auto-assemble clips into a rough cut timeline.

Args: clips_json: JSON array of clips: [{"src": str, "name"?: str, "duration": str}, ...] target_duration: Target total duration (optional — uses all clips if empty) max_clip_duration: Maximum clip duration (trims longer clips) transition_duration: If set, adds transitions between clips project_name: Project name output_path: Where to save

Generate a montage/highlight reel with uniform clip durations and transitions.

Args: clips_json: JSON array of clips: [{"src": str, "name"?: str, "duration": str}, ...] clip_duration: Duration for each clip in the montage transition_duration: Transition duration between clips project_name: Project name output_path: Where to save

Convert SRT subtitles to title clips and add to timeline.

Args: path: Path to .fcpxml file to add subtitles to srt_path: Path to .srt subtitle file output_path: Output file path

Convert an EDL (Edit Decision List) to FCPXML.

Args: edl_path: Path to .edl file media_dir: Directory containing media files (for resolving reel names) project_name: Project name output_path: Where to save

Reformat a timeline for a different aspect ratio (e.g., 16:9 → 9:16 for vertical).

Args: path: Path to .fcpxml file target_width: Target width target_height: Target height target_format_name: Target format name output_path: Output file path

Auto-fix flash frames by extending very short clips to minimum duration.

Args: path: Path to .fcpxml file min_frames: Minimum frame count (clips shorter than this get extended) frame_duration: Frame duration for calculating frame count output_path: Output file path

Replace all gaps in the timeline with clips from a specified asset.

Args: path: Path to .fcpxml file fill_asset_ref: Asset resource ID to use as fill (e.g., "r3") fill_name: Name for the fill clips output_path: Output file path

Remove gaps longer than the threshold from the timeline.

Args: path: Path to .fcpxml file silence_threshold_seconds: Minimum gap duration to remove (seconds) output_path: Output file path

Rename clips matching a pattern (substring replacement).

Args: path: Path to .fcpxml file pattern: Text to find in clip names replacement: Text to replace with output_path: Output file path

Assign roles to clips based on name matching rules.

Args: path: Path to .fcpxml file rules_json: JSON array of rules: [{"match": "interview", "role": "Dialogue"}, ...] output_path: Output file path

Add transitions between all adjacent clips in the timeline.

Args: path: Path to .fcpxml file duration: Transition duration name: Transition name output_path: Output file path

Generate a comprehensive quality check report for the timeline.

Checks: validation, gaps, flash frames, duplicates, pacing.

Args: path: Path to .fcpxml file

Verify all referenced media files exist on disk.

Args: path: Path to .fcpxml file

Detect mixed frame rate issues in the timeline.

Args: path: Path to .fcpxml file

Flag clips with potential audio issues (volume adjustments, missing audio).

Args: path: Path to .fcpxml file

Check for clips with transforms that might push content outside safe zones.

Args: path: Path to .fcpxml file

Verify the timeline fits a target duration.

Args: path: Path to .fcpxml file target_seconds: Target duration in seconds

List installed Motion templates (titles, transitions, generators, effects).

List configured FCP share destinations.

List available FCP effects and transitions by scanning known locations.

List available FCPXML template files.

Args: templates_dir: Directory to search (default: FCP_PROJECTS_DIR)

Apply an FCPXML template to a set of clips.

Replaces placeholder clips in the template with provided clips.

Args: template_path: Path to template .fcpxml file clips_json: JSON array of clips to insert project_name: New project name output_path: Where to save

Save the current FCPXML structure as a reusable template.

Args: path: Path to .fcpxml file to use as template template_name: Name for the template output_dir: Directory to save template (default: FCP_PROJECTS_DIR)

Check if Final Cut Pro is currently running.

Get all open libraries in Final Cut Pro (requires FCP to be running).

Get events in a library (or all libraries if name not specified).

Args: library_name: Library name to filter (optional)

Get projects in an event (or all events if name not specified).

Args: event_name: Event name to filter (optional)

Get info about the current/first timeline in FCP.

Get FCP application state — version, frontmost status.

Open a FCP library file.

Args: library_path: Path to .fcpbundle file

Import an FCPXML file into Final Cut Pro.

Args: fcpxml_path: Path to .fcpxml file

Trigger XML export in FCP via menu automation (requires Accessibility permissions).

Control FCP playback.

Args: action: "play", "pause", "stop", or "toggle" (space bar)

Navigate to a specific timecode in FCP.

Args: timecode: Timecode to navigate to (e.g., "00:01:30:00"). Opens timecode entry if provided.

Switch FCP editing tool.

Args: tool: "select" (A), "trim" (T), "position" (P), "range" (R), "blade" (B), "zoom" (Z), "hand" (H)

Undo the last action in FCP.

Redo the last undone action in FCP.

Execute any FCP menu command by path.

Args: menu_path: Menu path like "File > Export XML..." or "Edit > Select All"

Send a keyboard shortcut to FCP.

Args: keys: Shortcut description like "cmd+c", "cmd+shift+e", "option+w"

Trigger a share/export from FCP.

Args: destination: Share destination name (opens default if empty)

Encode a file using Compressor CLI.

Args: input_path: Path to input media file setting_path: Path to Compressor preset (.cmprstng) output_dir: Output directory batch_name: Batch name for Compressor

List available Compressor encoding presets.

Convert FCPXML to DaVinci Resolve-compatible format (FCPXML v1.9).

Args: path: Path to .fcpxml file output_path: Output file path

Convert FCPXML to FCP7 XML format (compatible with Premiere Pro and Avid).

Args: path: Path to .fcpxml file output_path: Output file path

Export timeline as EDL (Edit Decision List).

Args: path: Path to .fcpxml file output_path: Output .edl file path

Get detailed media file info (codec, resolution, duration, bitrate, etc.).

Args: path: Path to media file

Detect silent sections in audio/video files.

Args: path: Path to media file noise_threshold: Noise floor threshold (e.g., "-30dB", "-40dB") min_duration: Minimum silence duration in seconds

Detect beat positions in audio/music files.

Returns beat timestamps that can be used for music-synced editing.

Args: path: Path to audio/video file

Analyze audio loudness (EBU R128 / LUFS).

Returns integrated loudness, loudness range, and true peak.

Args: path: Path to audio/video file

Extract a frame thumbnail from video at a specific time.

Args: path: Path to video file time: Time in seconds to extract frame from output_path: Where to save thumbnail (default: auto-generated) width: Thumbnail width in pixels

Extract thumbnails at regular intervals (contact sheet / storyboard).

Args: path: Path to video file interval: Seconds between thumbnails output_dir: Directory to save thumbnails width: Thumbnail width in pixels

List all audio, video, and subtitle streams in a media file.

Args: path: Path to media file

Detect scene changes in video.

Useful for automatic clip segmentation.

Args: path: Path to video file threshold: Scene change sensitivity (0.0-1.0, lower = more sensitive)

Extract audio track from a video file.

Useful for feeding video audio into transcription, analysis, or the sheet-music-maker pipeline (basic-pitch → MIDI → notation).

Args: path: Path to video file output_path: Where to save audio (default: same dir, .wav extension) format: Audio format: wav, mp3, flac (default: wav)

Transcribe audio to MIDI using basic-pitch (ML audio transcription).

Converts audio (from video or standalone) into MIDI note data. Returns the MIDI file path and a summary of detected notes.

Requires basic-pitch: pip install basic-pitch

Args: path: Path to audio file (wav, mp3, flac) or video file output_path: Where to save MIDI (default: same dir, .mid extension)

Define a puppet character rig from body parts.

Each part is a separate image (PNG) that gets positioned and layered to form a character. Parts can be animated independently.

Args: rig_json: JSON object defining the character: { "name": "my_character", "position": [0, 0], "parts": [ { "name": "head", "image": "/absolute/path/to/head.png", "position": [0, 200], "scale": 1.0, "rotation": 0, "anchor": [0, -50], "z_order": 5 }, ... ] } - position: [x, y] offset from character center (y-positive = up) - anchor: pivot point for rotation - z_order: higher = in front

Returns: JSON summary of the rig (use this to verify before building a scene).

Create a standard 6-part humanoid rig from a folder of images.

Expects PNG files named: head.png, body.png, left_arm.png, right_arm.png, left_leg.png, right_leg.png in the image directory.

Parts are auto-positioned for a standard humanoid layout on a 1080p frame.

Args: name: Character name image_dir: Absolute path to folder containing part images position_x: X position on screen (0 = center) position_y: Y position on screen (0 = center) scale: Overall scale multiplier

Build an FCPXML timeline from one or more puppet rigs.

Each rig's parts become layered connected clips with transforms applied. Import the resulting .fcpxml into FCP to see the assembled characters.

Args: rigs_json: JSON array of rig definitions (same format as puppet_create_rig). Each rig: {"name": str, "position": [x, y], "parts": [...]} duration: Scene duration in FCPXML time (default 10 seconds at 29.97fps) project_name: Project name output_path: Where to save (default: ~/Movies/<project_name>.fcpxml)

Build a puppet scene with custom keyframe animations.

Args: rigs_json: JSON array of rig definitions animations_json: JSON array of animations: [ { "part": "head", "property": "position", "keyframes": [ {"time": "0s", "value": [0, 200], "interp": "smooth2"}, {"time": "150150/30000s", "value": [20, 210], "interp": "smooth2"}, {"time": "300300/30000s", "value": [0, 200], "interp": "smooth2"} ] }, { "part": "left_arm", "property": "rotation", "keyframes": [ {"time": "0s", "value": 0}, {"time": "150150/30000s", "value": 45}, {"time": "300300/30000s", "value": 0} ] } ] property: "position" (value=[x,y]), "rotation" (value=degrees), "scale" (value=[sx,sy]) interp: "smooth2" (default, ease), "linear", "hold" duration: Scene duration project_name: Project name output_path: Where to save

Build a puppet scene with a preset motion applied.

Available presets:

• "idle": Subtle breathing/sway (keeps character alive)

• "bounce": Vertical bouncing

• "walk": Full walk cycle (arms, legs, body bob)

• "talk": Mouth movement + head bob

• "wave": Arm waving (applies to left_arm)

Args: rig_json: JSON rig definition preset: Motion preset name duration: Scene duration project_name: Project name output_path: Where to save cycles: Number of motion cycles (more = faster movement) intensity: Scale factor for motion amplitude (0.5 = subtle, 2.0 = exaggerated)

Build a multi-scene puppet animation with different presets per scene.

Generates one FCPXML per scene. Useful for storyboarding a sequence.

Args: rigs_json: JSON array of rig definitions (shared across scenes) scenes_json: JSON array of scene definitions: [ {"name": "intro", "duration": "300300/30000s", "preset": "idle"}, {"name": "greeting", "duration": "150150/30000s", "preset": "wave"}, {"name": "walking", "duration": "600600/30000s", "preset": "walk", "cycles": 4} ] project_name: Base project name (scenes get suffixed) output_path: Output directory (default: ~/Movies/)

List all available puppet animation presets with descriptions.

Returns details on each preset, what body parts it uses, and what parameters it accepts.