Debugging

Overview#

When a capture does not produce the expected result — a blank video, missing content, or incorrect scroll behavior — Rollberry provides several tools to help you diagnose the problem: debug frames, JSONL logs, and sidecar manifests.

Debug frames#

Use the --debug-frames-dir flag to save every captured frame as an individual PNG file. This is the most powerful way to see exactly what the browser was "seeing" during the capture:

rollberry capture https://example.com --debug-frames-dir ./debug-output

The specified directory will be created if it does not exist and will contain:

debug-output/
├── 00000.png
├── 00001.png
├── 00002.png
├── ...
└── 00300.png

The frames are numbered sequentially across the entire capture. At the default 60 FPS with a 5-second duration, this produces 300 frames.

Examining individual frames#

The saved frames let you pinpoint exactly where something went wrong:

Check the first frame — Open 00000.png to see what the page looked like before scrolling started. This helps identify:

• Whether the page loaded correctly.
• Whether overlay elements were hidden (if using --hide-selector).
• Whether the --wait-for condition was sufficient for the page to render.

Check the last frame — Open the last frame to confirm the scroll reached the bottom of the page.

Compare frames in sequence — Look for sudden jumps or blank sections that might indicate lazy-loading failures or scroll interruptions.

# On macOS, open all frames in Preview for quick review
open ./debug-output/*.png
 
# On Linux, use an image viewer
feh ./debug-output/

Structured JSONL logs#

By default, Rollberry writes a sidecar log file in JSONL format (one JSON object per line) named after your output file (e.g., rollberry.log.jsonl). You can specify a custom path using --log-file.

# View the raw log
cat rollberry.log.jsonl

Each log entry has a consistent structure:

{"timestamp":"2026-03-20T04:30:00.000Z","level":"info","event":"browser.open","details":{"url":"https://example.com","viewport":{"width":1440,"height":900}}}
{"timestamp":"2026-03-20T04:30:00.500Z","level":"info","event":"render.start","details":{"frameCount":300,"fps":60,"durationSeconds":5}}
{"timestamp":"2026-03-20T04:30:05.600Z","level":"info","event":"encode.complete","details":{"outPath":"/path/to/rollberry.mp4"}}

Sidecar manifest#

Rollberry also generates a .manifest.json file (e.g., rollberry.manifest.json) containing technical metadata about the capture. This is useful for verifying the results of an automated capture process.

{
  "outPath": "/path/to/rollberry.mp4",
  "frameCount": 300,
  "durationSeconds": 5.0,
  "pages": [
    {
      "url": "https://example.com",
      "frameCount": 300,
      "durationSeconds": 5.0,
      "scrollHeight": 4200,
      "truncated": false
    }
  ],
  "truncated": false
}

Troubleshooting with debug output#

Blank or white video#

Check 00000.png. If it is blank, the page did not load before capture started. Try using --wait-for with a selector or a fixed delay:

rollberry capture https://example.com --wait-for ms:5000 --debug-frames-dir ./debug

Content missing from the video#

If certain sections appear blank in the frames, the content may be lazy-loaded and not triggering during the scroll. Try a slower fixed duration:

# Force a slow 20-second scroll
rollberry capture https://example.com --duration 20

Scroll does not reach the bottom#

Check the .manifest.json or JSONL logs for the scrollHeight value. Rollberry has a default limit of 30,000 pixels. If your page is longer than this, it will be truncated (indicated by truncated: true in the manifest).

Overlay elements still visible#

Open 00000.png and check if the overlay is present. If it is, your CSS selector may not be matching the element. Use browser DevTools to verify the correct selector, then retry:

rollberry capture https://example.com \
  --hide-selector ".correct-selector" \
  --debug-frames-dir ./debug

Performance considerations#

Saving debug frames significantly increases disk usage and slightly slows down the capture because every frame must be written to disk as a PNG file. For a 5-second capture at 60 FPS:

• Standard capture: ~1 MP4 file (a few MB)
• With debug frames: ~300 PNG files (can be 200+ MB)

Only use --debug-frames-dir when actively troubleshooting.