Skip to content

Capture Files

Jump to bottom
alsi-lawr edited this page Jul 18, 2026 · 1 revision

Capture files

A capture is one .lua file. Its first non-whitespace content is a strict, versioned TOML header; the rest is trusted top-level Lua.

--[[
# viset
version = 1
output = "output/{device}-{theme}.png"

[devices.desktop]

[devices.desktop.viewport]
width = 1280
height = 720

[matrix]
theme = ["light", "dark"]

[data]
url = "https://example.com"
]]

viset.page.navigate(viset.context.data.url)
viset.page.wait_for("document.readyState === 'complete'", "10s")
viset.snapshot()

This produces desktop-light.png and desktop-dark.png beneath output/.

Required structure

  • # viset is the exact header marker.
  • version = 1 is the current format.
  • output ends in .png or .webp.
  • At least one [devices.<name>.viewport] provides positive width and height values.
  • Every declared device expands automatically in declaration order.
  • Every [matrix] value is a non-empty array. Matrix axes expand in declaration order after devices.
  • [data] holds arbitrary TOML values exposed through viset.context.data.

Unknown fields in the fixed schema are errors. matrix and data are the open tables.

Outputs

{device} and matrix-axis names are available as output placeholders. Expanded paths must be unique, relative, and safe. output_root changes the base directory; --output DIR overrides it for one command.

Viset refuses existing output before browser work unless --force is supplied. Outputs are ordinary user-owned files: no manifest, ownership marker, history, or rollback data is created.

Devices and framing

Devices may set mobile, touch, device_scale, viewport dimensions, and optional frame dimensions. mobile and touch default to false, and device_scale defaults to 1.0.

The top-level frame accepts builtin:auto, builtin:phone, builtin:laptop, or a capture-relative custom HTML path. builtin:auto uses the phone frame for mobile devices and the laptop frame otherwise. Custom frame HTML requires explicit frame dimensions.

PNG and WebP

  • A .png capture calls viset.snapshot() exactly once.
  • A .webp capture creates exactly one viset.record() and records at least two visible frames.
  • frames_per_second is WebP-only, ranges from 1 through 60, and defaults to 30.

See Trusted Lua API for page and recording control, and WebP and performance for media options.

Clone this wiki locally