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.

terminal
peach record [options]
peach record start [options]
peach record render --scene <path> --shell-url <url> --output <video.mp4>
peach record prelude-start [--origin <url>]
peach record stop [--output <path>]
peach record status # reports the record-start session; also probes the engine
peach record cancel # cancels a record-start session
peach record upload (--events <path> | --video <path> | --scene <path>) [--live-bundle] [--open]
peach record --three <flow.yaml> [--script <id>] [--output <path>]

Options

flagdescription
--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)
--threerun 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-threeleave 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-onlysave the scene stream without rendering a video
--lockstepstep 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-shellexclude the simulated iOS chrome (status bar, keyboard, toasts) and record the tenant surfaces only
--shell-onlyrecord only the shell chrome
--openopen 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-bundlefor upload: include the running app bundle for Live alongside —scene
--assets-onlyfor upload: keep assets only; re-issue API calls live

Examples

terminal
peach record --duration 5
peach record --format mp4 --output demo.mp4 --duration 8
peach record --output demo.gif --duration 3
peach record --frames 10 --output ./frames/
peach record --mode combined --duration 8 --open --owner my-org --repo my-app
peach record start --format mp4
peach record start --mode combined
peach record prelude-start
peach record stop --output flow.mp4
peach record cancel
peach record upload --events ./my-run.jsonl.gz --open
peach record upload --video /tmp/peach-flow.mp4
peach record --three flows/feed-scroll.yaml
peach record --three flows/swap.yaml --script hero-arc --background gradient-tide --output ~/Desktop/swap-3d.mp4

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.