peach record
Video recording captures the app scene during the take and renders a video after stop in an isolated viewer. The render subcommand exports a saved scene stream at 60 fps by default. Use atomic mode for a fixed duration or start and stop around interactions. GIF and PNG capture use atomic mode. Scene uploads default to recording-only shares; add —live-bundle to include Live. Combined recordings include events and upload automatically. Bundle-bearing live and combined uploads reuse the bundle-derived preview URL when the same app is recorded again. --three films a flow on the 3D device stage: the flow runs at full speed on the flat canvas while the screen is captured, then the capture plays back on the 3D phone under a camera script and the stage is saved as a clip; stage decor takes the same flags as peach mode three configure. Recording needs a signed-in account: peach login or PEACH_API_KEY.
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) |
--capture <kind> | recording plays the full take; run trims the lead-in (default: recording, or run for agents and CI) |
--scene <path> | saved scene stream to render (record render), or upload without a live bundle (record upload) |
--shell-url <url> | Peach shell URL used by the isolated scene renderer (record render) |
--fps <number> | target frame rate for video/gif (default: 30) |
--three | run the flow file given, then film its playback on the 3D device stage (default output ~/Desktop/peach-recordings/<flow>.webm) |
--script <id> | camera script for —three (default: hero-arc) |
--slow <ms> | per-step delay for the —three flow run |
--keep-three | leave 3D mode and the recording editor on after —three |
--background <id> | stage background for —three, with —gradient, —colorway, —environment, —room and —focus as in mode three configure |
--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> | limit the width of rendered video or gif frames |
--scene-only | save the scene stream without rendering a video |
--lockstep | step the live app at exactly 1/fps per frame (record start/stop, mp4 only); this uses live frame capture and virtual time runs slower than wall time, compressing timers and gestures relative to the output timeline |
--no-shell | exclude the simulated iOS chrome (status bar, keyboard, toasts) and 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: https://peachsim.com; also honors PEACH_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 |
--events <path> | for upload: gzipped events .jsonl.gz file to attach |
--video <path> | for upload: mp4/gif recording to attach |
--live-bundle | for upload: include the running app bundle for Live alongside —scene |
--assets-only | for upload: keep assets only; re-issue API calls live |
Examples
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:
- +
webmvia MediaRecorder (default, fastest) - +
mp4via WebCodecs + mp4-muxer (chrome/edge, real h264) - +
gifvia gifenc on sampled frames - +
--frames Ndumps 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.