Overview
External agents (such as Claude Code, custom scripts, or any HTTP client) can control the running Masterselects editor via a local HTTP bridge. The bridge exposes 76 tools covering clip management, timeline editing, playback, effects, export, and debugging.
The bridge only accepts loopback connections (127.0.0.1). It never binds to a network interface, so it cannot be reached from other machines on the same network. All requests require a Bearer token generated at startup.
Requirements
Two environments are supported:
| Environment | Endpoint | Requirements |
|---|
| Production | POST http://127.0.0.1:9877/api/ai-tools | Native Helper running, Masterselects open in a browser tab |
| Development | POST http://localhost:5173/api/ai-tools | Vite dev server running, Masterselects open in a browser tab |
Making a request
Endpoint
POST http://127.0.0.1:9877/api/ai-tools
Must be application/json.
Bearer token in the format Bearer <startup-token>. The token is printed to the Native Helper terminal at startup.
Request body
The tool name to execute. Use _list to retrieve all available tools. Use _status to check bridge health.
Arguments for the tool. Shape depends on the tool. Pass {} for tools with no required arguments.
Example: list available tools
curl -X POST http://127.0.0.1:9877/api/ai-tools \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <startup-token>" \
-d '{"tool":"_list","args":{}}'
Example: move the playhead
curl -X POST http://127.0.0.1:9877/api/ai-tools \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <startup-token>" \
-d '{"tool":"setPlayhead","args":{"time":10.5}}'
Example: call from Node.js
const response = await fetch('http://127.0.0.1:9877/api/ai-tools', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <startup-token>',
},
body: JSON.stringify({ tool: 'getStats', args: {} }),
});
const result = await response.json();
Tool call format
{
"tool": "<tool_name>",
"args": { ... }
}
message field.
Available tools (76 total)
Tools are defined in src/services/aiTools/definitions/ across 15 files.
Timeline state
| Tool | Description |
|---|
getTimelineState | Full timeline state (tracks, clips, playhead) |
setPlayhead | Move playhead to a time |
setInOutPoints | Set in/out markers |
Clip info
| Tool | Description |
|---|
getClipDetails | Detailed clip info + analysis + transcript |
getClipsInTimeRange | Find clips within a time range |
Clip editing
| Tool | Description |
|---|
splitClip | Split at a specific time |
splitClipEvenly | Split into N equal parts |
splitClipAtTimes | Split at multiple specific times |
deleteClip | Delete a single clip |
deleteClips | Delete multiple clips |
moveClip | Move to a new position/track |
trimClip | Adjust in/out points |
cutRangesFromClip | Remove multiple sections |
reorderClips | Reorder clips by ID list |
addClipSegment | Add a segment of a source clip to the timeline |
Selection
| Tool | Description |
|---|
selectClips | Select clips by ID |
clearSelection | Clear the current selection |
Track tools
| Tool | Description |
|---|
createTrack | Create a video or audio track |
deleteTrack | Delete a track and its clips |
setTrackVisibility | Show or hide a track |
setTrackMuted | Mute or unmute a track |
Visual capture
| Tool | Description |
|---|
captureFrame | Export a PNG at a specific time |
getCutPreviewQuad | 4 frames before + 4 frames after a cut point |
getFramesAtTimes | Grid image at multiple times |
Analysis and transcript
| Tool | Description |
|---|
getClipAnalysis | Motion/focus/brightness data per frame |
getClipTranscript | Word-level transcript |
findSilentSections | Find silence gaps |
findLowQualitySections | Find blurry sections |
startClipAnalysis | Trigger background analysis |
startClipTranscription | Trigger transcription |
Media panel
| Tool | Description |
|---|
getMediaItems | Files, compositions, folders |
createMediaFolder | Create a folder |
renameMediaItem | Rename an item |
deleteMediaItem | Delete an item |
moveMediaItems | Move items to a folder |
createComposition | Create a new composition |
openComposition | Open/switch to a composition |
importLocalFiles | Import files from the local filesystem |
listLocalFiles | List files in a local directory |
selectMediaItems | Select items in the media panel |
Batch operations
| Tool | Description |
|---|
executeBatch | Execute multiple tool calls as a single undoable action |
YouTube / Downloads
| Tool | Description |
|---|
searchVideos | Search YouTube by keyword |
listVideoFormats | List available formats for a video URL |
downloadAndImportVideo | Download a video and import to the timeline |
getYouTubeVideos | List videos in the Downloads panel |
Transform
| Tool | Description |
|---|
setTransform | Set position, scale, rotation on a clip |
Effects
| Tool | Description |
|---|
listEffects | List available GPU effects |
addEffect | Add an effect to a clip |
removeEffect | Remove an effect from a clip |
updateEffect | Update effect parameters |
Keyframes
| Tool | Description |
|---|
getKeyframes | Get keyframes for a clip property |
addKeyframe | Add a keyframe at a time |
removeKeyframe | Remove a keyframe by ID |
Playback
| Tool | Description |
|---|
play | Start playback |
pause | Pause playback |
setClipSpeed | Set clip playback speed |
undo | Undo the last action |
redo | Redo the last undone action |
addMarker | Add a timeline marker |
getMarkers | Get all markers |
removeMarker | Remove a marker by ID |
Transitions
| Tool | Description |
|---|
addTransition | Add a transition between clips |
removeTransition | Remove a transition |
Masks
| Tool | Description |
|---|
getMasks | Get masks on a clip |
addRectangleMask | Add a rectangle mask |
addEllipseMask | Add an ellipse mask |
addMask | Add a custom polygon mask |
removeMask | Remove a mask |
updateMask | Update mask properties |
addVertex | Add a vertex to a mask path |
removeVertex | Remove a vertex from a mask path |
updateVertex | Update a vertex position |
Stats and debug
| Tool | Description |
|---|
getStats | Current engine performance snapshot (FPS, decoder, drops, audio, GPU) |
getStatsHistory | N snapshots over time with min/max/avg summary |
getLogs | Filter browser logs by level, module, or search text |
getPlaybackTrace | WebCodecs/VF pipeline events + health state for playback debugging |
Bridge architecture
Development (HMR bridge)
In development the Vite dev server proxies HTTP requests to the running app via HMR:
POST /api/ai-tools → Vite server → HMR WebSocket → browser tab → aiTools.execute()
src/services/aiTools/bridge.ts. Uses import.meta.hot.on to receive requests and import.meta.hot.send to return results.
Production (Native Helper bridge)
In production builds the Rust Native Helper proxies HTTP to the browser tab via WebSocket:
POST http://127.0.0.1:9877/api/ai-tools → Native Helper (HTTP :9877) →
WebSocket (:9876) → browser tab → aiTools.execute()
executeToolInternal() in src/services/aiTools/handlers/index.ts.
Undo support
All AI edits are undoable with Ctrl+Z. Batch operations (executeBatch) wrap multiple tool calls in a single history entry:
startBatch('AI: toolName')
// ... execute tools ...
endBatch()
Related