Configuration

Overview#

Rollberry is designed to work with sensible defaults and minimal configuration. Most users will only need the CLI flags documented in the CLI Options reference. However, for advanced use cases — CI/CD pipelines, custom browser configurations, or integration with other tools — Rollberry supports additional configuration through environment variables and internal settings.

Environment variables#

Rollberry respects the following environment variables. These are useful for setting defaults without passing flags on every invocation, or for configuring behavior in CI/CD environments.

Environment variables are overridden by CLI flags. For example, if ROLLBERRY_VIEWPORT is set to 1920x1080 but you pass --viewport 390x844, the CLI flag takes precedence.

Usage example:

# Set defaults for a CI pipeline
export ROLLBERRY_VIEWPORT="1920x1080"
export ROLLBERRY_QUALITY="90"
export ROLLBERRY_TIMEOUT="120000"
 
# These captures use the environment defaults
npx rollberry capture https://example.com
npx rollberry capture https://example.com/about

Browser configuration#

Rollberry uses Playwright to manage the Chromium browser. Under the hood, it configures the browser with settings optimized for page capture.

Default browser arguments#

Rollberry launches Chromium with the following default arguments:

--disable-background-timer-throttling
--disable-backgrounding-occluded-windows
--disable-renderer-backgrounding
--disable-ipc-flooding-protection
--autoplay-policy=no-user-gesture-required

These flags ensure that the browser performs consistently during capture, even in headless mode.

Playwright browser path#

By default, Playwright downloads and manages its own Chromium binary. If you need to use a specific browser installation, you can set the PLAYWRIGHT_BROWSERS_PATH environment variable:

# Use a custom browser installation directory
export PLAYWRIGHT_BROWSERS_PATH=/opt/browsers
npx rollberry capture https://example.com

You can also use the PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH environment variable to point to a specific Chromium or Chrome executable:

# Use system Chrome on macOS
export PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
npx rollberry capture https://example.com

Headless mode#

Rollberry always runs in headless mode. The browser window is never displayed, which makes it suitable for servers, CI/CD pipelines, and headless environments.

Viewport and device emulation#

The --viewport flag sets the browser window size. Rollberry does not perform full device emulation (user agent, touch events, device pixel ratio). If you need to capture a page as it would appear on a specific device, set the viewport to match the device's screen resolution.

Common device viewport sizes for reference:

Video encoding#

Rollberry encodes the captured frames into an MP4 video using the H.264 codec. The encoding settings are determined by the --quality and --fps flags.

Quality mapping:

Higher quality values produce larger files. For most use cases, the default quality of 80 provides a good balance.

Scroll behavior internals#

Rollberry uses JavaScript-based smooth scrolling within the Chromium browser. The scroll algorithm works as follows:

1. Measure the total scrollable height of the page (document.documentElement.scrollHeight)
2. Calculate the scroll distance: totalHeight - viewportHeight
3. Interpolate the scroll position over the configured duration using an easing function
4. Capture a screenshot at each frame interval (determined by --fps)

The --scroll-speed multiplier affects the rate of scroll position change per frame. A speed of 0.5 means the scroll covers half the distance per unit time, while 2.0 covers twice the distance.

If the page height is less than or equal to the viewport height (i.e., the entire page fits in one screen), Rollberry will still produce a video of the specified duration — it will simply show the static page without scrolling.

Timeout behavior#

The --timeout flag sets a global timeout for the entire capture process, including:

• Browser launch
• Page navigation
• Wait conditions (--wait and --wait-for-selector)
• Scroll capture
• Video encoding

If any phase exceeds the remaining timeout, Rollberry aborts the capture and exits with status code 2.

For pages that take a long time to load or have extensive content, increase the timeout:

npx rollberry capture https://slow-site.com --timeout 180000

Network and proxy configuration#

Rollberry uses the system's default network configuration. If you need to route traffic through a proxy, configure it via environment variables that Playwright respects:

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
 
npx rollberry capture https://example.com

To bypass the proxy for specific hosts:

export NO_PROXY=localhost,127.0.0.1,.internal.example.com

Integration with other tools#

Rollberry is designed to work well as part of larger workflows. The manifest.json output and the use of exit codes make it straightforward to integrate with:

• Shell scripts — Parse manifest with jq, check exit codes for error handling
• CI/CD pipelines — Run as a step in GitHub Actions, GitLab CI, or Jenkins
• Node.js scripts — Spawn as a child process, parse manifest output
• Monitoring dashboards — Schedule periodic captures and track visual changes

See the Multi-Page Captures guide for scripting examples.