Command line
Every Wispframe feature is a terminal command. The running app is the engine and the permission holder — the wispframe command is a thin client that hands it work, so your terminal never needs a screen-recording or camera grant.
# 1) Install Wispframe from the Mac App Store and launch it once
# (grant Screen Recording when macOS asks — the app keeps the permission)
# 2) In the app header, click "⌘ CLI & MCP" — it installs the wispframe command
# 3) Done. The CLI talks to the app (and starts it if it isn't running):
wispframe record --duration 10 --out demo.mp4Driving Wispframe from an AI agent?
Hand it this one file. It documents every command and MCP tool, the permission model, exit codes and ready-made recipes — enough for a coding agent to work with Wispframe without guessing.
↓ Download wispframe-agent.mdThe App Store build is sandboxed. A relative path, or one starting with ~, is refused before any work — and so is any location outside the app container or the folder you pick as the Agent working folder (⌘ CLI & MCP ▸ Choose). The examples on this page use short names to stay readable; write them out in full, under that folder.
wispframe trim --in /Users/you/Movies/clip.mp4 --out /Users/you/Movies/clip.trimmed.mp4 --keep 0-10Displays, windows, and apps are addressed by id. Enumerate them as JSON, then target one with --display, --window, or --app.
wispframe list-sources
wispframe record --app com.apple.Safari --out out.mp4Same macOS privacy prompts as any recorder — Screen Recording for capture, Microphone for --mic, Camera for record-pip, Accessibility for keystrokes & scrolling. Granted once in System Settings.
Every feature works free with unlimited recording; processed exports carry a small watermark and Pro removes it. The CLI itself is never gated — it reads the same entitlement the app does, so a Pro purchase in the app applies immediately with nothing to activate.
wispframe license # status--codec h264 (default) / hevc write .mp4; prores writes .mov. --system-audio and --mic mix into one AAC track, balanced with per-source gains (0.0–2.0).
--record-cursor writes <out>.cursor.json (for Studio auto-zoom); --record-keys writes <out>.keys.json (for keystroke pills), which needs the Accessibility permission and so records nothing in the sandboxed App Store build. Studio reads them back.
Post-processing writes to <out>.part and renames on success, so a failed run never destroys an existing file. Variable-frame-rate recordings are resampled onto a clean clock — outputs never trip the encoder.
Record displays, windows, apps, webcams, a wired iPhone's screen, and multiple sources at once.
List capturable displays, windows, and applications as JSON. Each display carries both its point size (width/height, what macOS shows in Settings) and its backing pixel size (pixel_width/pixel_height) — every coordinate flag below takes backing pixels, so on a Retina display the two differ by 2×.
wispframe list-sourcesReport where text is on screen, frame by frame, as JSON — on-device OCR, nothing uploaded. The companion to detect-faces: a face and a visible password are the two things that stop a recording being publishable, and both need a rectangle.
wispframe detect-text --in demo.mp4 --out text.json --accurateReport the silent stretches of a video or audio file — and the spans worth keeping, written exactly the way trim --keep wants them, so the two chain without any arithmetic. The app's Trim window does the same thing behind its Cut silence button.
wispframe detect-silence --in talk.mp4 --out silence.jsonReport where the picture changes abruptly — the shot boundaries — as JSON. Always reports the largest difference it saw, so "no cuts" can be told apart from "your threshold was too high".
wispframe detect-cuts --in reel.mp4 --out cuts.jsonReport where faces are in a video, frame by frame, as JSON — Apple Vision on device, nothing uploaded and no model downloaded. Boxes come back in source pixels, the same space the redact flags take, so one can be piped straight into the other.
wispframe detect-faces --in talk.mp4 --out faces.json --stride 3List camera devices — built-in, USB, iPhone Continuity, and a wired iPhone's screen (kind IosScreen) — as JSON.
wispframe list-camerasCapture a display for N seconds and print each frame's PTS — an end-to-end pipeline check, optionally with a CPU/RAM benchmark report.
wispframe probe --duration 10 --fps 60 --bench baselineRecord a display, window, or app to a file — the full capture → hardware-encode → mux pipeline.
wispframe record --out demo.mp4
wispframe record --app com.apple.Safari --system-audio --mic --out tutorial.mp4
wispframe record --record-cursor --out zoomable.mp4Record the screen with a live webcam picture-in-picture — screen and camera captured in parallel, composited live.
wispframe list-cameras
wispframe record-pip --camera <uniqueID> --corner br --out pip.mp4Record a camera on its own — webcam, USB capture card, an iPhone over Continuity Camera, or a wired iPhone's screen at its native portrait resolution — straight to MP4, no screen involved.
wispframe list-cameras
wispframe record-camera --camera <uniqueID> --duration 20 --fps 30 --out cam.mp4Record every connected display simultaneously, each to its own file.
wispframe record-all --out-template '/tmp/multi-{n}.mp4' --duration 15Record 2–9 live sources composited into ONE file during capture — finished the instant you stop, no post-merge wait.
wispframe record-live-grid --sources display:<id>,window:<id> --layout sbs --canvas 4k --seconds 30 --out live.mp4Composite, redact, frame, trim, retime, and export existing recordings.
Overlay a video (picture-in-picture), blur/black out regions or faces, and burn in text labels.
wispframe compose --base screen.mp4 --overlay cam.mp4 --corner br --scale 0.28 --out pip.mp4
wispframe compose --base interview.mp4 --redact-faces all:blur --out safe.mp4Combine 2–9 videos into one scene — side-by-side, grid, rows, picture-in-picture, or speaker — with per-source audio, offsets, free placement, opacity, cell shapes (circle webcam bubbles) and timed layout keyframes that switch the arrangement mid-video.
wispframe compose-grid --sources a.mp4,b.mp4,c.mp4 --layout grid --out grid.mp4
wispframe compose-grid --sources main.mp4,cam.mp4 --layout sbs --shape 1:circle --out talk.mp4 \
--layout-key 0:sbs --layout-key 12:grid:ease:0.6 --layout-key 40:rows:fade:0.8Execute a saved Wispframe settings file headless: the JSON the app's 💾 Save settings writes. Compose, trim, redact, studio, subtitler and annotate sessions all replay headless — compose renders the full composition (sources, offsets, keyframes, shapes), subtitler even re-transcribes when the saved session has no transcript — one command, scriptable and MCP-drivable. The file's tool tag is validated with a clear error on mismatch.
wispframe run compose-settings.json
wispframe run redact-settings.json --out safe.mp4Remove the background from a clip — Apple's Neural Engine for people, or a general U²-Net model.
wispframe remove-bg --in cam.mp4 --out nobg.mp4 --backend vision --bg greenGive a recording that framed, studio-polished look — a backdrop, rounded corners, and a soft shadow — plus optional cursor auto-zoom and keystroke pills.
wispframe studio --in raw.mp4 --out framed.mp4 --bg gradient:Dusk --shadow 70
wispframe studio --in raw.mp4 --out framed.mp4 --zoom --zoom-max 2.0Transcribe a video's speech to captions with an on-device Whisper model (Metal). Writes .srt or .vtt; the model downloads and caches on first use.
wispframe transcribe --in talk.mp4 --out talk.srt --lang en --words
wispframe transcribe --in eloadas.mp4 --out eloadas.vtt --model large-v3-turboBurn styled captions from an .srt/.vtt/.json into a video, or convert a caption file between SRT and VTT. 22 one-click style presets.
wispframe subtitle --in talk.mp4 --captions talk.srt --out talk-sub.mp4 --preset Karaoke
wispframe subtitle --captions talk.srt --out talk.vtt --exportUpscale and sharpen a video with Real-ESRGAN (on-device, ONNX + CoreML). Audio passes through. A heavy pass; the model caches on first use.
wispframe enhance --in small.mp4 --out big.mp4 --scale 2
wispframe enhance --in old.mp4 --out 4k.mp4 --scale 4 --max 3840x2160Keep or cut time ranges, concatenated seamlessly into one shorter clip.
wispframe trim --in demo.mp4 --keep 2-5 --keep 30-45 --out short.mp4
wispframe trim --in demo.mp4 --cut 12-18 --out cleaned.mp4Change playback speed globally, or ramp individual segments up and down.
wispframe speed --in demo.mp4 --factor 2 --out fast.mp4
wispframe speed --in demo.mp4 --segment 10-20:4 --segment 40-42:0.5 --out ramped.mp4Convert a clip to an animated GIF — pure-Rust encoder, no ffmpeg.
wispframe to-gif --in clip.mp4 --out clip.gif --width 480 --fps 15Burn a running MM:SS elapsed-time clock into a video — the GUI's 'Burn elapsed time', headless.
wispframe burn-timer --in take.mp4 --out timed.mp4 --position bottom-rightRender arrows, boxes, text, steps and blur onto a still image — the screenshot Annotate editor, headless. Same JSON spec as annotate-video.
wispframe annotate-image --in shot.png --out shot-annotated.png --spec anns.jsonBake timed annotations — arrows, boxes, ellipses, pen, highlighter, text, numbered steps, blur — onto a video. Each carries a [start, end) band so it shows only when relevant.
wispframe annotate-video --in demo.mp4 --spec annotations.json --out annotated.mp4Screenshots, a scrolling capture, and a screen colour picker.
Capture a still PNG — a full display, a single window, or a dragged region.
wispframe screenshot --full --out shot.png
wispframe screenshot --region 100,100,800,600 --out crop.png --clipboardSample one pixel's colour on a display and print its HEX + RGB.
wispframe pick-color --at 640,360 --clipboard
# → #FAC800 rgb(250, 200, 0)Auto-scroll a region and stitch the frames into one tall PNG — a long page, chat, or document. Not available in the App Store build: it needs the Accessibility permission, which the sandbox forbids. Use screenshot --region.
wispframe scroll-capture --region 400,120,900,700 --out tall.pngInspect and manage the license.
Show the entitlement. Pro is purchased in the app through the App Store; the CLI reads the same entitlement, so there is nothing to activate here.
wispframe licenseEvery command supports -h/--help for the authoritative, always-current option list. Free processed exports carry a small watermark; Pro removes it. The CLI is free on both tiers.