Start Recording

start_recording

Start a background screen recording. Returns a session id; finalize it with stop_recording. Never auto-starts.

capturewritesdestructivesince v0.2.0

00:00PARAMETERS

Name	Type	Description
`target` required	`string`	full \| monitor:<i> (0 = primary) \| window:<title> (or window:exe=<app.exe> / window:hwnd=<n>) \| region:<x>,<y>,<w>,<h>. With gdigrab a window's rectangle is resolved once at start (visible, on top); it does not follow the window.
`exactTitle`	`boolean`	window: targets match the whole title only, never a substring (default false).
`fps`	`integer`	Frames per second (default 30). ≥ 1, ≤ 120
`quality`	`"draft" \| "standard" \| "high"`	Encoder preset (default standard).
`audio`	`object`	Audio (default none). No microphone capture.
`audio.source` required	`"system" \| "none"`	system = what the machine plays (needs a loopback device); none = video only.
`audio.device`	`string`	dshow loopback device (from list_audio_devices); auto-detected if omitted.
`output`	`string`	Output .mp4 path (default under SCREENCAST_HOME/recordings).
`overwrite`	`boolean`	Allow replacing an existing file at the output path (default false).
`maxDurationSec`	`integer`	Auto-stop after this many seconds (default 3600 or SCREENCAST_MAX_RECORDING_SEC; max 7 days; 0 = no cap). ≥ 0, ≤ 604800
`events`	`boolean`	Also log clicks, scroll, cursor, and typing (video-timed, video pixels) for read_events (default false; ~1 s slower start).
`keys`	`"masked" \| "shortcuts"`	With events: masked (default) logs typing only as 0.5 s-grid bursts, never keys; shortcuts also names Ctrl/Alt/Win chords. Typed text is never logged.
`cursor`	`"os" \| "events"`	events: leave the OS cursor out and log it (implies events) for the cursor tool to redraw.
`backend`	`"gdigrab" \| "wgc" \| "ddagrab"`	gdigrab (default): the screen rectangle. wgc (window: targets, FFmpeg 8+): the window's own surface, even when covered or moved; client area only, no audio. ddagrab: one display on the GPU, low CPU.
`encoder`	`"auto" \| "x264" \| "nvenc" \| "qsv" \| "amf"`	auto = first working GPU encoder, else x264 (default with ddagrab; else x264).
`webcam`	`object`	Also record a camera to <output>.webcam.mp4, aligned for overlay.
`webcam.device`	`string`	list_video_devices name (default: first).
`webcam.corner`	`"top_left" \| "top_right" \| "bottom_left" \| "bottom_right"`
`webcam.size`	`number`	Share of width (0.25). ≥ 0.1, ≤ 0.5
`webcam.shape`	`"rect" \| "circle"`
`replayBufferSec`	`integer`	Instant replay: keep only the last N s (bounded disk) for save_replay. gdigrab only. ≥ 4, ≤ 3600

00:05A MINIMAL CALL

start_recording { "target": "window:Notepad" }

The required arguments only, with placeholder values. Everything else takes its default.

00:10WHAT COMES BACK

Structured content (structuredContent), alongside a text summary:

Field	Type
`sessionId` always	`string`
`status` always	`string`
`backend` always	`string`
`outputPath` always	`string`

00:15SEEN IN

REC 01Bug-repro clip for a PRstart_recording → find_text → redact_region → trim → callout → export_gif
REC 02README demo GIFstart_recording → contact_sheet → export_gif (webp)
REC 06Zoom toward every clickstart_recording (events) → stop_recording → read_events → zoom (follow clicks, highlightClicks) → export_gif
REC 07The whole edit in one callstart_recording → find_text → pipeline (redact → trim → callout → export_gif)