X ShellX Docs

docs.theshellx.com / Cut manual

Learn Cut from the interface.

Setup, editing, Generate, delivery, and the Debug API in one manual. Use the tree to find the exact tool, menu item, filter, or panel you need.

Start with setup Open interface map Recording Studio Debug API

Interface map

Click a feature to see where it lives.

ShellX Cut editor with the Assets tab, editing-readiness summary, preview, and timeline tracks visible

Selected item

Assets tab

Use Assets to confirm imported media, read per-clip readiness, filter by type or action needed, and add clips to the base timeline at the playhead.

Where Left sidebar
Requirement Requires a project and at least one imported media file.
Debug/API media.import, library.add_to_project

Recording Studio

Record your screen, and keep the raw streams.

ShellX Cut Record workspace with an explicit desktop-session readiness notice, source and audio settings, raw-stream controls, and a safely disabled Start recording control

Camera capture is parked

Live camera capture is not available in this release. The Record workspace says so directly instead of showing enable, position, size and shape controls that could not work. Screen, microphone and supported system-audio recording are unaffected.

Metadata, not baked pixels

Live Studio changes are saved as timed events so auto-edit can replay background choices and markers into the polished clip.

Raw stream checks

After capture, Cut reports screen, mic, system audio, and Studio event artifacts so the recording can be diagnosed or reused. The camera chip stays dark while camera capture is parked.

Long recording safety

Microphone and Windows system audio are written continuously with bounded memory. Cut exposes the raw WAV only after it finishes cleanly and stops before the WAV format limit could corrupt a long capture.

Windows system audio

On supported Windows 10 and 11 builds, Cut records system audio without opening the physical output driver. Security software may ask once for the new Cut build; if access is denied, screen and microphone recording continue and the missing stream is reported.

macOS system audio

On macOS 14.2 or newer, Cut records system audio through a Core Audio process tap alongside ScreenCaptureKit. The first recording may request Screen Recording and Audio Capture separately; approve both, restart Cut if macOS asks, and retry. A successful take includes system.wav.

Hotkeys

F9 starts or stops recording and F12 adds a marker. The camera bindings (F10, F11, Shift+F11) stay in the keymap but do nothing while camera capture is parked.

First run

Setup is part of the editor.

FFmpeg

Required for clip probe, proxy media, screen recording, preview media, and final export. A fresh PC often needs FFmpeg installed before Cut can work like a video editor. If it is missing, Preview points directly to the Video processing setup card. On macOS, install Homebrew's complete build with brew install ffmpeg-full; Cut detects its keg-only path after restart. The regular Homebrew formula omits filters used by captions, stabilization, and managed color.

Perception and STT

Optional local model setup for transcripts, word cuts, scenes, OCR, diarization inputs, and caption workflows.

CLI agents

Needed for AI planning, Generate prompt and storyboard planning, review assistance, translation workflows, and live agent chat.

Offline work

Basic editing and local renders should remain understandable even when AI models, services, or CLI agents are unavailable.

Workflows

Common Cut tasks.

Import and organize

Create or open a project, import media, check Media Health, filter the asset list, and add clips to the base timeline at the playhead.

Base track and overlays

Use normal Insert or drag from Assets or Library for the story timeline. Imported picture and sound stay linked when moved or trimmed. Use Alt-drag or an overlay lane only when the clip should sit on top, then use track headers to reorder, mute, or solo lanes.

Edit and retime

Split, trim, ripple delete, lift delete, snap, change speed, grade clips, and keep edits reversible. Q ripple-trims from the playhead to the selected clip's start; W trims to its end, closing the gap for linked picture and sound. Add Video Track and Add Audio Track are available in the timeline toolbar.

Caption and translate

Install speech tools, generate transcripts, create captions, style them, and translate captions or transcript text.

Edit for Clarity

Preview the recipe before running it. The pass transcribes, finds pauses and retakes, removes fillers conservatively, and tightens pacing without forcing a render.

Sequence Index

Open Find and choose Sequence Index to search clips and markers across every sequence. Filter by kind, track, offline media, gaps, effects, or hidden, locked, and muted tracks; compact badges expose the matching state. Open a row to switch and seek, or copy the currently shown path-light rows as spreadsheet-safe CSV for QC handoff.

Generated media lifecycle

Use registered project assets as references, label variations, compare takes, choose a result, and insert or replace from verified project history. Cancelled placeholders remain available for an explicit retry.

Edit linked Motion clips

Open a linked package with Edit in Motion, render a verified copy-on-write revision in Canvas, then refresh the same Cut clip. Identity or revision mismatches leave the last good render untouched.

Agent turn review

Attach up to eight registered project assets, use the editable prompt library, then inspect Preview and Diff before Accept, guarded Revert, or Try again. Concurrent edits disable whole-turn revert.

Record and polish

Open Record, choose screen, mic, and system audio, then stop to keep raw streams and build a polished clip on the timeline.

Review and export

Read ops, receipts, QC, scopes, and diffs before rendering previews, final files, or platform-ready exports.

Debug API

Automate and inspect Cut.

Local control surface

Use the local API to inspect project state, dispatch editing verbs, watch events, and connect MCP-capable tools to a running Cut server.

Surface Path or command Purpose
REST verbs POST /api/verb/{name} Dispatch any verb from the live schema.
State GET /api/state Read current project and timeline state.
Verb catalog GET /api/verbs Read the machine-readable contract generated from schema/verbs.json.
Events GET /api/events (WebSocket) Watch operations, job progress, render completion, receipts, and UI state.
Frame inspection GET /api/frame?at_ms=[&h=][&compose=1] Inspect a bounded composed/scrub timeline frame at a specific time (default h=540, maximum 2160; use export.frame for a full-resolution still).
Installed agent docs GET /api/agent and /api/agent-doc/<path> Discover the complete skill and craft guides, verb schema, feature reference, and Debug API contract installed with this exact build.
MCP cutd mcp Expose every Cut verb as an MCP tool for a running Cut server.
Motion render status motion.job.get and motion.job.list Name a blocking Motion render with job_id, then poll it from a second request until pollAfterMs disappears. Cut exposes only jobs owned by the open project.

Local-only security boundary

The supported default is one personal workstation / one trusted interactive environment. The API has no token: loopback is a whole-machine boundary, so any local process or account able to connect can operate the editor. Non-loopback binds are refused; Host and Origin checks mitigate browser cross-origin and DNS rebinding but do not authenticate native callers. The non-local escape does not add Cut authentication and is not a supported remote mode. Remote use requires an independently authenticated and authorized SSH/VPN/ShellX broker or equivalent transport; without it, remote access is refused.