--- name: smoothcapture-cli description: Record the screen, take polished screenshots, apply smart zoom effects, and export demo videos by driving SmoothCapture from the command line. Use when asked to produce a demo/screen recording video, take or beautify a screenshot, automate SmoothCapture, export/edit a .smoothcapture project without the UI, or style/edit an existing video file (mp4/mov/m4v) or image (png/jpg/heic/…) with SmoothCapture. --- # SmoothCapture CLI SmoothCapture (https://www.smoothcapture.app) exposes a CLI control channel: ` cli `. The app binary doubles as the CLI client: ```bash SC="/Applications/SmoothCapture.app/Contents/MacOS/SmoothCapture" # or, after `"$SC" cli install-symlink`: smoothcapture cli ``` Results are one JSON line on stdout (`.data` holds the payload); progress/events stream to stderr, or to stdout as JSON with `--json`. Non-zero exit = failure with a JSON error carrying `code`, `message`, `hint`. ## Core workflow ```bash "$SC" cli ping # reachable? auto-launches the app "$SC" cli devices --json # display/window/camera/mic ids "$SC" cli record start --display 3 # or --window , --area x,y,w,h # … drive the product with real mouse clicks (clicks become zoom anchors) … BUNDLE=$("$SC" cli record stop --json | jq -r '.data.bundlePath') "$SC" cli project autozoom --path "$BUNDLE" # cinematic zooms from click data "$SC" cli export --path "$BUNDLE" --output demo.mp4 --preset 1080p30 ``` Fine-grained effect edits (background, padding, aspect ratio, webcam layout, manual zooms, trims) are made by editing `project.json` inside the bundle, then exporting. Never edit it while the project is open in the editor (or run `cli project reload` immediately after). ## Editing existing video files and images Any plain `mp4`/`mov`/`m4v` or image (`png`/`jpg`/`heic`/`tiff`/`webp`/…) — not just SmoothCapture recordings — can be wrapped into a project and edited: ```bash BUNDLE=$("$SC" cli project import --input screencast.mp4 --json | jq -r '.data.bundlePath') # … edit project.json, or: "$SC" cli project apply-preset --path "$BUNDLE" --preset … "$SC" cli export --path "$BUNDLE" --output polished.mp4 --preset 1080p30 ``` Imported footage has no cursor/click data, so `project autozoom` and cursor effects don't apply — add zooms manually in `project.json` if needed. Everything else (backgrounds, padding, device frames, trims, audio clips, export) works normally. Images become a still clip (`"isStillImage": true`, default 5s) that stretches to **any** duration — set the segment's `endTime` to the length you want; it is not clamped. All effects apply to image clips like video, so an image can be a title card, an intro/outro, or a whole animated-zoom video of its own. Inside the editor UI, `File > Import Media into Project…` adds a video or image to the open project's timeline. ## Screenshots ```bash "$SC" cli screenshot --output shot.png # raw retina capture, cursor hidden "$SC" cli screenshot --window 5533 --pretty --output hero.png # background + padding + rounded corners + shadow "$SC" cli screenshot --window 5533 --device-frame "3D/MacBook_Pro.usdc" \ --environment glasshouse_interior_2k.hdr --output hero.png # 3D hardware mockup "$SC" cli screenshot --input raw.png --device-frame "iPhone-16-Pro/i16pro_Black_Titanium.png" \ --background none --output framed.png # style an existing image, transparent canvas "$SC" cli backgrounds --json # names for --background "$SC" cli device-frames --json # names for --device-frame (2D bezels + 3D models) "$SC" cli environments --json # names for --environment (3D frames only) ``` `--pretty` (implied by any styling flag) renders through the editor's Metal pipeline, so screenshots match video exports exactly. Full control: `--padding`, `--corner-radius`, `--edge-padding`, `--no-shadow`/`--shadow-opacity`, `--aspect 16:9|9:16|…`, `--size WxH`, `--crop x,y,w,h`, `--border` (+ width/color/style/gradient/glow), `--screen-rect`, and `--env-*` (exposure, lighting, rotation, pitch, reflection, DOF). Targets and ids work exactly like `record start` (`--display`, `--window`, `--area x,y,w,h`), or `--input ` to skip capture. Match the capture's aspect to the device frame (portrait for iPhones — check the result's `warnings`). `--keep-project ` additionally saves the styled screenshot as a `.smoothcapture` project (`projectPath` in the result) — reopen it in the editor to tweak the treatment or re-export it later. ## Must-knows - Server is off by default: `"$SC" cli enable` once (or Settings → General → Command-line control). `SERVER_DISABLED` → exit 3. - `PERMISSION_SCREEN_RECORDING` (exit 4) can only be fixed by a human in System Settings → Privacy & Security → Screen Recording. Report it; don't retry. - Smart zoom needs real clicks during recording; zero clicks → zero zoom effects (success with `zoomEffectsGenerated: 0`). - One recording / one headless project op at a time; a project open in the editor blocks headless ops (`PROJECT_OPEN_IN_EDITOR`). - Record defaults: no mic, no camera, no system audio, no countdown — pass flags to opt in. - Recording an iOS Simulator window is auto-detected: the project gets a phone-screen crop, touch cursor, and an iPhone bezel automatically. For sim demos, **drive the app with `xcodebuildmcp ui-automation`** (structured, token-efficient) not cliclick+screenshots — but note injected touches don't trigger autozoom, so add **manual** zooms/camera moves. Do preroll→`record start`→drive→`record stop` in one script (recording keeps running between tool calls). Full fast-path + a ready-to-source helper (`references/sim-demo-helpers.sh`) are in the simulator section of the demo-video-workflow reference. - For 3D device frames: animate with `cameraTransforms`, and add background music via `audioClips` — all in project.json. Subtle screen reflection (~0.05–0.2) is fine since the additive-glass fix (Jul 2026); the screen keeps full brightness. Zoom `manualCenterX/Y` are signed offsets ((0,0) = centered; positive X shifts the device left), not 0–1 coordinates. ## References - [references/cli-reference.md](references/cli-reference.md) — every command, flags, JSON schemas, error/exit codes - [references/project-json-reference.md](references/project-json-reference.md) — bundle layout + project.json field guide for effect edits - [references/demo-video-workflow.md](references/demo-video-workflow.md) — full recipe with polish tips and failure handling