Quick Start

Your first capture#

The simplest Rollberry command takes just a URL:

rollberry capture https://example.com

This will:

1. Launch a headless Chromium browser.
2. Navigate to https://example.com.
3. Wait for the page to load.
4. Automatically calculate the scroll duration based on page height (approx. 800px per second).
5. Scroll from top to bottom at 60 FPS.
6. Save an MP4 video to ./rollberry.mp4.

Rollberry also generates sidecar files: rollberry.manifest.json (metadata) and rollberry.log.jsonl (detailed logs).

Viewing the output#

After the capture completes, you will see your video file in the current directory:

ls rollberry.*

You will see:

rollberry.mp4
rollberry.manifest.json
rollberry.log.jsonl

Open the MP4 file with any video player, or drag it into a browser window to preview.

Customizing the viewport#

By default, Rollberry captures at 1440x900 pixels. To capture at a different resolution, use the --viewport flag:

# Desktop full HD
rollberry capture https://example.com --viewport 1920x1080
 
# Mobile viewport (iPhone-like)
rollberry capture https://example.com --viewport 390x844
 
# Tablet viewport (iPad-like)
rollberry capture https://example.com --viewport 768x1024

The viewport format is WIDTHxHEIGHT in pixels.

Adjusting scroll duration#

By default, Rollberry uses auto duration. You can force a fixed duration (in seconds) using the --duration flag:

# Quick 3-second scroll
rollberry capture https://example.com --duration 3
 
# Slow, detailed 15-second scroll
rollberry capture https://example.com --duration 15

Specifying the output path#

Use --out to change the output file path:

rollberry capture https://example.com --out ./captures/homepage.mp4

Practical examples#

Here are a few real-world usage patterns:

Capture a landing page at full HD:

rollberry capture https://your-site.com \
  --viewport 1920x1080 \
  --duration 8

Capture a mobile view with cookie banner hidden:

rollberry capture https://your-site.com \
  --viewport 390x844 \
  --hide-selector ".cookie-banner" \
  --hide-selector ".consent-dialog"

Capture a local development server:

rollberry capture http://localhost:3000 \
  --wait-for ms:2000 \
  --duration 10

Wait for a specific element before capturing:

rollberry capture https://your-site.com \
  --wait-for "selector:#hero-image" \
  --duration 6

Terminal output#

When you run a capture, Rollberry provides progress output in your terminal:

rollberry capture https://example.com

[1/3] Launching browser...
[2/3] Navigating to page...
[3/3] Scrolling and capturing...
[########################################] 100%

/Users/you/project/rollberry.mp4

Capture complete: rollberry.mp4
  Duration:  5.2s (312 frames at 60fps)
  File size: 1.4 MB
  Manifest:  rollberry.manifest.json

If anything goes wrong, Rollberry will display a clear error message. For help debugging issues, see the Debugging guide.