Skip to content

Record Video

Recordings include a video track wherever the engine supports it — no option needed. The browser encodes the viewport to WebM itself, using the WebDriver BiDi browsingContext.startScreencast command, so there is nothing extra to install. The video lands inside the recording zip next to the trace:

record.zip
├── trace.trace
├── trace.network
├── video/<context>.webm
└── video/index.json

With video omitted, vibium records video whenever the engine supports it; otherwise the recording proceeds without it and the stop result reports videoUnavailable with the engine’s reason. video: true requires video: start fails with an explanatory error if the engine can’t deliver. video: false turns it off.

The video films the browsing context that was active at recording.start() and does not follow focus. One camera per context: a second recording cannot film a context that is already being recorded.

This guide covers the video track specifically — engine support, Firefox channels, and video options. For recording in general (screenshots, snapshots, groups, chunks, the viewer), start with the Recording tutorial.

Video requires Firefox 154 or newer, which regular Firefox ships since 2026-08-18. A plain firefox.start() is enough: it installs and launches the release channel.

On macOS and Linux, the clients install Firefox automatically on first use. Windows users must install Firefox themselves and set VIBIUM_ENGINE_PATH. To install it ahead of time on a supported platform:

vibium install --engine firefox

To record against the Firefox beta instead, select the channel with --channel beta, the clients’ channel option, or the VIBIUM_ENGINE_CHANNEL env var; see Using Firefox.

Chrome has not implemented the BiDi screencast command yet. The same code will work on Chrome when it does; today video: true fails there with an error saying so, and an omitted video records the trace without a video track.

A session on a Vibium Station or a Roadie records video with no extra option. The video is the device’s own screen stream.

Terminal window
export VIBIUM_CONNECT_API_KEY=... # the station's API key
vibium start wss://station.example/session
vibium record start -o phone.zip
# Recording "record" started (video: on, screenshots: true, snapshots: false), saving to phone.zip
vibium tap 222 600
vibium record stop -o phone.zip
# Saved phone.zip (3 steps, 12s video)
  • The zip holds video/screen.mp4: H.264, at the stream’s size and frame rate.
  • record start waits for the first picture. That takes under a second on a local network and 2 to 3 seconds through a relay.
  • --video-size and --video-fps do not apply. The stream is stored as it is.
  • With video omitted, a stream that cannot be joined leaves the recording without video, and the stop result says why. --video makes that an error at start.
  • --video=false records no video.
  • Vibium tells the Roadie that it is recording the stream. A Roadie that records its own holds then leaves the video and the sound to Vibium’s recording, so one session is not filmed twice.
  • Expect about 3 MB a minute for a still screen and 8 MB a minute for one that moves.

The video has sound when the recording does. What vibium say sent and what the device played are mixed into the file’s audio track. So video/screen.mp4 plays with its sound in any player, outside the zip.

Terminal window
vibium say "Come here, Watson"
vibium listen
vibium record stop -o phone.zip
# Saved phone.zip (5 steps, 41s video with sound)
unzip phone.zip video/screen.mp4

The same audio is also under audio/ in the zip, one file per clip and one for what was heard.

The Record Player shows the video in place of the screenshots. It keeps the video in step with the timeline and plays the sound with it.

No video is recorded on other remote browser connections (--connect). The engine would write the file on the remote host’s disk, where Vibium cannot reach it — the WebDriver BiDi protocol has no way to retrieve files — so the screencast is never started at all: with video omitted the recording proceeds and the stop result reports videoUnavailable; video: true fails at start. No file is left behind on the remote host, and there is nothing to fetch separately. Every other track — actions, screenshots, snapshots, network — records fully over remote connections; only the video needs a local browser.

For a remote host you control, video: { remote: 'keep' } opts out of the refusal: the screencast records on the remote host and stays there. The stop result and video/index.json carry remotePath — the file’s location on that machine — and vibium never reads, moves, or deletes it; retrieval (scp, a mounted volume) and cleanup are yours. The remote engine must still support the screencast (Firefox 154+). CLI: --video-remote keep; MCP: video_remote: "keep"; Java: .videoRemote("keep").

On Linux, Vibium gives Firefox a private Downloads directory inside the temporary browser profile because Firefox’s native command requires one. It is removed with the profile when the browser closes; Vibium does not create a Downloads folder in your home directory. Recording works in headed and headless modes.

See Using Firefox for installing and selecting Firefox in general.

const { firefox } = require('vibium');
const bro = await firefox.start();
const vibe = await bro.page();
// video: true because this script exists to produce a video -- fail
// rather than quietly write a trace without one.
await vibe.context.recording.start({ video: true, path: 'runs/login.zip' });
await vibe.go('https://example.com');
// ... actions to record ...
await vibe.context.recording.stop();
await bro.stop();

path defaults to a timestamped record-YYYYMMDD-HHMMSS.zip in the working directory, so a rerun never overwrites the previous artifact; stop({ path }) overrides the path declared at start. stop() returns a result — path, steps, durationMs, videos/videoUnavailable. path: null selects bytes-only capture: nothing is written and the result carries the zip itself.

from vibium import firefox
bro = firefox.start()
vibe = bro.page()
# video=True because this script exists to produce a video -- fail
# rather than quietly write a trace without one.
vibe.context.recording.start(video=True, path="runs/login.zip")
vibe.go("https://example.com")
# ... actions to record ...
vibe.context.recording.stop()
bro.stop()
// video(true) because this code exists to produce a video -- fail
// rather than quietly write a trace without one.
recording.start(new RecordingOptions().video(true).path("runs/login.zip"));
// ... actions to record ...
recording.stop();

Setting any video option (videoSize(1280, 720), videoFrameRate(30)) implies video on.

vibium record start --video -o run.zip
# ... actions ...
vibium record stop
# Saved run.zip (23 steps, 14s video)

The MCP tool browser_record_start takes the same options as flat properties: video, video_width, video_height, video_frame_rate, path. Without a path, the recording lands in the MCP server’s working directory when that is a real, writable place (Claude Code launches the server in your project, so it lands next to your code), and in ~/Documents/Vibium otherwise; the stop result names the absolute path either way.

Video dimensions default to the viewport. Explicit dimensions that mismatch the window aspect are letterboxed by the engine. frameRate uses the engine’s default when omitted. Firefox produces WebM; audio is not exposed (Firefox 154 rejects it: “The audio track is not supported”).

Firefox writes the file as a live stream, so the WebM header carries no duration. Every player we tried plays it fine, but some show an unknown or zero duration until playback starts.

While recording, Firefox writes the in-progress file to the system Downloads folder (screencast-<id>.webm); that location is fixed inside Firefox. Vibium moves the file into the recording zip when recording stops and deletes leftovers when the session closes. If the vibium process is force-killed mid-recording, the file can be left behind there.

If the browser session ends with a recording still active, the recording auto-finalizes and delivers to the declared path as if stop() had been called; path: null recordings are lost on close. If the video pipeline dies mid-recording, stop() still delivers the zip — the video is absent or partial and video/index.json records the error.

The video is one more track in the same recording zip that carries per-action screenshots, DOM snapshots, and network events for the Record Player. video/index.json records the video’s offsetMs from the recording’s start so viewers can align the two timelines. See the Recording tutorial for the other tracks and Recording format for the zip layout.