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.jsonWith 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.
Browser support
Section titled “Browser support”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 firefoxTo 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.
Record a device on a station or a Roadie
Section titled “Record a device on a station or a Roadie”A session on a Vibium Station or a Roadie records video with no extra option. The video is the device’s own screen stream.
export VIBIUM_CONNECT_API_KEY=... # the station's API keyvibium start wss://station.example/sessionvibium record start -o phone.zip# Recording "record" started (video: on, screenshots: true, snapshots: false), saving to phone.zipvibium tap 222 600vibium 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 startwaits for the first picture. That takes under a second on a local network and 2 to 3 seconds through a relay.--video-sizeand--video-fpsdo not apply. The stream is stored as it is.- With
videoomitted, a stream that cannot be joined leaves the recording without video, and the stop result says why.--videomakes that an error at start. --video=falserecords 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.
vibium say "Come here, Watson"vibium listenvibium record stop -o phone.zip# Saved phone.zip (5 steps, 41s video with sound)unzip phone.zip video/screen.mp4The 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.
Remote browsers
Section titled “Remote browsers”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.
JavaScript
Section titled “JavaScript”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.
Python
Section titled “Python”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.
Options
Section titled “Options”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.
Video vs. trace tracks
Section titled “Video vs. trace tracks”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.