sootsim record

capture the live sim as webm/mp4/gif, or sample N png frames (--frames)

sootsim record

Drives the engine’s built-in canvas recorder over the WS bridge — no second browser, no ffmpeg. Encoding happens in the running page (MediaRecorder for webm, WebCodecs for mp4, gifenc for gif). Two modes: atomic (duration-bounded) or stateful (start → interact → stop). Stateful mode is webm/mp4 only; for gif/png use atomic mode. Use —frames to sample N evenly-spaced png snapshots instead of a video. NOTE on live/combined: the /preview/<id> id is derived from the app’s bundle identity, not the recording — so re-recording the same app reuses the same URL and overwrites the previous preview. This is intentional (re-record replaces in place); keep a recording you want to preserve by copying its /preview/<id> page elsewhere before recording the same app again.

terminal

sootsim record [options]
sootsim record start [options]
sootsim record prelude-start [--origin <url>]
sootsim record stop [--output <path>]
sootsim record status   # reports the record-start session; also probes the engine
sootsim record cancel   # cancels a record-start session

Options

flag	description
`--format <type>`	webm \| mp4 \| gif \| png (inferred from —output extension; stateful mode is webm/mp4 only)
`--mode <kind>`	video \| live \| combined (default: video). live captures the event stream; combined captures both and uploads automatically. NOTE: live/combined upload to /preview/<id> whose id is bundle-derived, so re-recording the same app overwrites the previous preview
`--duration <seconds>`	recording duration (default: 10, atomic mode only)
`--fps <number>`	target frame rate for video/gif (default: 30)
`--output <path>`	output file, or directory when —frames is set
`--frames <n>`	sample N evenly-spaced png frames instead of a video
`--max-width <px>`	downscale gif frames to this width
`--no-shell`	exclude the simulated iOS chrome (status bar, keyboard, toasts) — record the tenant surfaces only
`--shell-only`	record only the shell chrome
`--open`	open the uploaded preview URL in the browser after stop (live/combined)
`--sim <sim>`	target a specific sim
`--origin <url>`	billing/upload origin for live/combined (default: auto — probes a local :3000 stack, else https://sootbean.com; also honors SOOTSIM_UPLOAD_ORIGIN)
`--owner <org>`	associate live/combined preview uploads with a linked org repo; pass with —repo
`--repo <repo>`	repo name for —owner; the signed-in user must belong to the owning org team

Examples

terminal

sootsim record --duration 5
sootsim record --format mp4 --output demo.mp4 --duration 8
sootsim record --output demo.gif --duration 3
sootsim record --frames 10 --output ./frames/
sootsim record --mode combined --duration 8 --open --owner lightstrikelabs --repo three-punch-convo-app
sootsim record start --format mp4
sootsim record start --mode combined
sootsim record prelude-start
sootsim record stop --output flow.mp4
sootsim record cancel

Recording Notes

record drives the engine’s built-in canvas recorder over the WS bridge — no second browser, no ffmpeg. Encoding happens in the running page:

webm via MediaRecorder (default, fastest)
mp4 via WebCodecs + mp4-muxer (chrome/edge — real h264)
gif via gifenc on sampled frames
--frames N dumps N evenly spaced png frames to a directory — handy when you only need a few snapshots from a sim (e.g. for handoff, regression reports, or diffing)

Format is inferred from --output’s extension, or pass --format. For step-by-step evidence around a bug, pair it with debug snapshot rather than trying to infer state from the video alone.

detox

profile

sootsim record

sootsim record

#Options

#Examples

#Recording Notes

#Related

Ready to build?

Options

Examples

Recording Notes

Related