SpliceKit CLAUDE.md

SpliceKit - Programmatic Final Cut Pro Control

SpliceKit is an ObjC dylib injected into FCP's process. It exposes all 78,000+ ObjC classes via a JSON-RPC server on TCP 127.0.0.1:9876. Everything is fully programmatic -- no AppleScript, no UI automation, no menu clicks.

NEVER Use Keyboard Simulation or AppleScript

All FCP actions MUST go through direct ObjC calls. Never use any of these:

• SpliceKit_simulateKeyPress() or synthetic NSEvent key events
• CGEvent keyboard/mouse posting
• osascript / NSAppleScript / AppleScript tell application
• Accessibility APIs (AXUIElement) for clicking or typing
• Frame-stepping loops (nextFrame x N) when seekToTime exists

Instead, always use one of these patterns (in priority order):

1. Direct method call on the timeline/sequence/clip object via objc_msgSend
2. Responder chain via [NSApp sendAction:NSSelectorFromString(@"selector:") to:nil from:nil]
3. Batch bridge endpoint (e.g. timeline.addMarkers) for operations on multiple items
4. Menu execute via menu.execute for actions only accessible through menus

If an action doesn't have a direct ObjC selector yet, find one using explore_class / search_methods on the relevant class (FFAnchoredTimelineModule, FFAnchoredSequence, etc.) rather than simulating the keyboard shortcut.

Quick Start

1. bridge_status()                    -- verify connection
2. open_project("My Project")         -- open a project by name
3. get_timeline_clips()               -- see timeline contents
4. timeline_action("blade")           -- edit
5. verify_action("after blade")       -- confirm state changed
6. capture_timeline()                 -- visually verify the timeline
7. capture_viewer()                   -- visually verify the viewer/canvas

CRITICAL: Must Know Before Editing

Opening a Project

Use open_project() to load a project by name:

open_project("My Project")                   # find by name
open_project("Edit v2", event="4-5-26")      # filter by event too