Recording

import { Aside } from ‘@astrojs/starlight/components’;

Ptah can record the browser viewport as an animated GIF. This is designed for lightweight demo clips and bug reports — not long-form screen capture.

`ptah_browser_record_start`

Begin recording. The call returns immediately; frames are captured in the background until ptah_browser_record_stop is called.

Name	Type	Required	Default	Description
`fps`	number	no	`10`	Frames per second (max 30)
`scale`	number	no	`1`	Multiplier applied to viewport dimensions; use `0.5` for smaller files
`maxDurationMs`	number	no	`60000`	Safety cap; recording auto-stops after this duration

{
  "tool": "ptah_browser_record_start",
  "arguments": {
    "fps": 12,
    "scale": 0.75
  }
}

Stop recording and encode the captured frames into an animated GIF.

Name	Type	Required	Default	Description
`path`	string	no	`.ptah/recordings/{timestamp}.gif`	Custom output path
`loop`	boolean	no	`true`	Whether the GIF should loop forever

{
  "path": "D:/projects/my-app/.ptah/recordings/2026-04-21T10-15-02.gif",
  "frames": 142,
  "durationMs": 14_200,
  "sizeBytes": 2_198_321
}

Keep clips short — 10–20 seconds produces a GIF under 2 MB at default settings.
Lower fps to 8 or use scale: 0.5 for file size-sensitive contexts like GitHub issues.
Run headed for smoother frames; headless capture can stutter on lightly-loaded CPUs.
Record a fresh session: close the browser, navigate fresh, and start recording before the first interaction.