Every feature, scriptable.

List capturable displays, windows, and applications as JSON.

wispframe list-sources

List camera devices — built-in, USB, iPhone Continuity — as JSON.

wispframe list-cameras

Capture 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 --display 1 --duration 10 --fps 60 --bench baseline

--display <id>

Display to probe (default 1).

--duration <s>

Seconds to capture (default 10).

--fps <n>

Target frame rate (default 60).

--bench <label>

Also write memory/benchmarks/<label>-*.{md,csv}.

Record a display, window, or app to a file — the full capture → hardware-encode → mux pipeline.

wispframe record --display 1 --out demo.mp4
wispframe record --app com.apple.Safari --system-audio --mic --out tutorial.mp4
wispframe record --display 1 --record-cursor --out zoomable.mp4

--out <path>

Output file — required. .mp4 (h264/hevc) or .mov (prores).

--display / --window / --app

What to capture (id / window id / bundle id).

--duration <s>

Length in seconds (default 10). Recording is unlimited on Free — processed exports carry a small watermark.

--fps / --width / --height

Capture params (60 / 1920 / 1080).

--codec <c>

h264 (default) · hevc · prores.

--crop "x,y,w,h"

Capture only a sub-rect of the source.

--mask-bg <backend>

Remove the background after recording (vision / onnx).

--system-audio / --mic

Add audio (mixed into one track).

--system-audio-gain / --mic-gain

Balance the mix, 0.0–2.0.

--record-cursor / --record-keys

Write sidecars for Studio zoom / keystrokes.

--hide-cursor / --delay <s>

Cursor-free recording · self-timer countdown before start.

Record the screen with a live webcam picture-in-picture — screen and camera captured in parallel, composited live.

wispframe list-cameras
wispframe record-pip --display 1 --camera <uniqueID> --corner br --out pip.mp4

--camera <uniqueID>

From list-cameras. Defaults to the system camera.

--scale / --corner / --margin

Webcam size & placement (0.3 / br / 24).

--shape <kind>

Webcam bubble shape: rect · rounded · circle · triangle · hexagon — circle = classic bubble.

--system-audio / --mic

Audio into the recording.

Record a camera on its own — webcam, USB capture card, or an iPhone over Continuity Camera — straight to MP4, no screen involved.

wispframe list-cameras
wispframe record-camera --camera <uniqueID> --duration 20 --fps 30 --out cam.mp4

--camera <uniqueID>

From list-cameras. Defaults to the system camera.

--duration <s> / --fps <n>

Capture length and frame rate (10 / 30).

--delay <s>

Self-timer countdown before recording starts.

Record every connected display simultaneously, each to its own file.

wispframe record-all --out-template '/tmp/multi-{n}.mp4' --duration 15

--out-template <tpl>

{n} is replaced with each display id.

Record 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:1,window:42 --layout sbs --canvas 4k --seconds 30 --out live.mp4

--sources <list>

display:<id> / window:<id>, comma-separated.

--layout <l>

sbs · grid · rows · pip-* · speaker.

--canvas <c>

1080p · 1440p · 4k · 8k or WxH.

--shape <IDX:KIND>

LIVE cell shapes: rect · rounded · circle · triangle · hexagon — masked during capture.

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.mp4

--base / --out

Base video and output — required.

--overlay <path>

The PiP source (optional if only redacting).

--rect / --corner / --scale / --margin

Overlay placement.

--redact "x,y,w,h:blur|solid[:S-E]"

Redact a region, baked on top — ':2.5-8' limits it to that time window (seconds).

--shape <kind>

Overlay shape: rect | rounded | circle | triangle | hexagon — circle = webcam bubble.

wispframe run settings.json

Execute a saved app session headless: compose / trim / redact settings files render with one command.

--redact-faces "all|x,y;…[:blur|solid]"

Auto-blur faces, tracked per face.

--text "TEXT:x,y[:size[:#rgb]]"

Burn in a label (CoreText, emoji ok).

Combine 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.8

--sources <a,b,…>

2–9 files — required.

--layout <l>

sbs · grid · rows · pip-* · speaker.

--audio <IDX:GAIN>

Mix a source's audio (repeatable).

--offset / --place / --opacity

Timing, free placement, alpha.

--shape <IDX:KIND>

Cell shape: rect · rounded · circle · triangle · hexagon — circle = webcam bubble. Repeatable.

--layout-key <T:LAYOUT[:TRANS[:DUR]]>

Switch the arrangement at T seconds; TRANS: cut · slide · ease · fade (cross-dissolve). Repeatable.

Execute 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.mp4

<settings.json>

The saved session file (tool tag: compose · trim · redact).

--out <path>

Output file; defaults to the session's own output name.

Remove 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 green

--backend <b>

vision (person, fast) · onnx (general).

--model <m>

u2net (best) · u2netp (lite) — onnx only.

--bg <c>

green · black · white · #rrggbb · image:PATH (15 built-ins pickable in-app, or any file via image:PATH).

Give 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.0

--bg <b>

blur · gradient:NAME · color:#rgb · image:PATH.

--padding / --radius / --shadow

Framing (8% / 16px / 60).

--crop <x,y,w,h>

Keep only a sub-rectangle (source pixels) before framing.

--zoom / --zoom-max / --zoom-follow

Cursor auto-zoom (needs .cursor.json).

--keys

Keystroke pills (needs .keys.json).

Transcribe 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-turbo

--model <m>

Whisper: large-v3-turbo (default) · large-v3 · medium · small · base. Or Qwen3-ASR: qwen3-0.6b · qwen3-1.7b (needs pip install mlx-qwen3-asr).

--lang <l>

Language hint (e.g. hu, en). Omit to auto-detect.

--words

Per-word timestamps (for karaoke/word-highlight).

--out *.json

Write a JSON transcript that keeps word timing (vs cue-level .srt/.vtt).

Burn 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 --export

--preset <p>

22 looks incl. Karaoke, "Word Pop", "Pop Word" (word-by-word popup), "Glow Pop", "Boxed Pop", Aurora / Sunset / Ocean (soft gradient pills), Neon, Serif, Script, Impact, Creator — and more.

--font-size <pct>

Font size as a percent of frame height.

--position <p>

top · middle · bottom.

--font <name>

Font family (Inter, Montserrat, Poppins…).

--style <file.json>

Full per-field style (overrides preset).

--dump-style <file>

Write the resolved style JSON to edit + reuse with --style.

--export

Only convert the caption file (SRT / VTT / JSON).

Upscale 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 3840x2160

--model <m>

general (default, fast) · sharp (full RRDBNet x4plus, fp16/ANE) · apple (built-in VTSuperResolutionScaler, macOS 15.4+).

--scale <n>

Upscale factor 2 or 4.

--max <WxH>

Cap output to fit, preserving aspect.

--denoise <0–1>

Denoise strength (0 = sharpest, higher = cleaner).

Keep 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.mp4

--keep <A-B>

Range to keep (repeatable).

--cut <A-B>

Range to remove — output is the complement.

Change 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.mp4

--factor <0.25–4.0>

Global speed.

--segment <A-B:F>

Per-segment ramp (repeatable).

--audio <pitch|mute>

Audio handling in non-1× regions.

Convert a clip to an animated GIF — pure-Rust encoder, no ffmpeg.

wispframe to-gif --in clip.mp4 --out clip.gif --width 480 --fps 15

--width <px>

Output width, height auto (default 640).

--fps <n>

Frame rate (default 15).

Burn 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-right

--position <p>

top · bottom · bottom-left · bottom-right (default bottom-right).

Render 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.json

--spec <json>

Annotation list; timing fields are ignored for stills.

Bake 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.mp4

--spec <path>

JSON file: an array of { kind, …geometry, start, end }.

kinds

arrow · rect · ellipse · line · pen · highlight · text · step · blur.

coords

Frame pixels; a/b two-point, points[] for pen, pos+text for text.

Capture a still PNG — a full display, a single window, or a dragged region.

wispframe screenshot --display 1 --full --out shot.png
wispframe screenshot --region 100,100,800,600 --out crop.png --clipboard

--full / --region / --window

What to capture.

--clipboard

Also copy the image.

Sample one pixel's colour on a display and print its HEX + RGB.

wispframe pick-color --display 1 --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.

wispframe scroll-capture --region 400,120,900,700 --out tall.png

--region "x,y,w,h" / --out

Scrollable rect and output — required.

--max-frames / --step-frac

Safety cap (60) and scroll step (0.66).

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 license

--action <a>

status (default) · activate · deactivate.

--product <p>

monthly · annual · lifetime (with --action activate).