Skip to content
Rollberry
Docs
Navigation

Debugging

Diagnose bad captures and renders with debug frames, manifests, JSONL logs, and render summary files.

Start with the sidecars#

Rollberry writes structured files on every run. They should be your first stop:

  • <out>.manifest.json
  • <out>.log.jsonl

For render, you also get a project-level *.render-summary.json.

Debug frames#

Use --debug-frames-dir on capture:

npx rollberry capture https://example.com \
  --out ./artifacts/debug.mp4 \
  --debug-frames-dir ./artifacts/debug-frames

Or define debugFramesDir per output in a project file.

The exported PNGs help you answer:

  • Did the page load before capture began?
  • Was the overlay actually hidden?
  • Did the scroll reach the intended area?
  • Did a timeline action land on the right frame?

Reading capture manifests#

Capture manifests currently use schemaVersion: 2 and record:

  • sanitized input URLs
  • viewport, fps, duration, motion, and timeout
  • wait condition and hidden selectors
  • artifact paths
  • result metrics
  • warnings and errors

Warnings are especially useful in automation. For example, scroll_height_truncated means the measured page height exceeded the current capture limit.

Reading render manifests#

Render manifests add output-specific composition details such as:

  • output format (mp4 or webm)
  • audio settings
  • subtitle mode
  • transition settings
  • intermediate and final encoding configuration

The render summary file gives you one place to inspect the status of every named output.

Reading JSONL logs#

Logs are newline-delimited JSON events. They are suitable for grep, jq, and CI artifact collection.

cat ./artifacts/demo.log.jsonl

Useful event families include:

  • capture lifecycle events such as capture.start and capture.complete
  • render lifecycle events such as render.start and render.complete
  • scene and timeline events for project rendering
  • probe warnings when FFprobe-backed metrics are unavailable

Good debugging sequence#

  1. Read the manifest for warnings and the failing option set.
  2. Read the JSONL log for the last successful event.
  3. Export debug frames if the failure is visual or timing-related.
  4. Reduce the scope to one URL or one output if the project is large.

Common signals#

  • Blank first frame: use a stronger --wait-for
  • Overlay still visible: fix --hide-selector
  • Output already exists: rerun with --force
  • Truncation warning: shorten the page, split scenes, or redesign the capture
  • Crossfade render failure with probe warnings: ensure FFmpeg and FFprobe are installed correctly