Skip to content

Recording File Format

Recording captures a timeline of everything that happens during a browser session — screenshots, network requests, DOM snapshots, and action groups — and packages it into a single zip file.

All timestamps in the recording are relative monotonic milliseconds — the number of milliseconds elapsed since the recording started. This matches the Playwright trace format and ensures correct rendering in the trace viewer.

  • monotonicTime, startTime, endTime, timestamp, time — relative ms since recording start (small values like 0, 500, 3200)
  • wallTime — absolute Unix ms (only on context-options and frame-snapshot events, for calendar time reference)
  • _monotonicTime (network) — relative ms since recording start (same unit as all other timestamps)

A trace zip contains three kinds of entries:

record.zip
├── trace.trace # Main event timeline (newline-delimited JSON)
├── trace.network # Network events (newline-delimited JSON)
├── resources/
│ ├── page@abc123-1773879004791.jpeg # Screenshot frames (pageId-timestamp.ext)
│ └── page@abc123-1773879004850.jpeg # Other resources (pageId-timestamp.ext)
├── video/<context>.webm # Native video track (when recorded; see below)
├── video/<context>.mp4 # Video of a device, from its stream (see below)
└── video/index.json # Video manifest

For chunked recordings, the first chunk uses trace.trace / trace.network. Subsequent chunks use <N>.trace / <N>.network (e.g., 1.trace, 2.trace).

When the recording carries a video track (recording.start({ video }), Firefox 154+), the engine-encoded WebM is stored under video/ with a manifest. Video entries are additive: existing trace tooling ignores them.

{"version":1,"videos":[{"file":"video/<context>.webm","context":"<browsing context id>","startedAt":1754870000123,"offsetMs":412,"width":1280,"height":720,"mimeType":"video/webm"}]}

offsetMs is the video’s start relative to the recording’s t0 — the wall-clock delta from recording start to the engine’s screencast acknowledgement — and aligns the video timeline with trace event timestamps. If the video pipeline failed, the entry carries an error field and the file may be absent or partial. Chunk artifacts carry no video file; their manifest instead records videoRange: [startMs, endMs], the chunk’s span within the session video.

A session on a Vibium Station or a Roadie drives a device, not a browser that can write a file. Its video is the stream the station or the Roadie serves of the device’s screen. Vibium joins that stream as a viewer and stores the H.264 it receives in an MP4, without re-encoding.

{"version":1,"videos":[{"file":"video/screen.mp4","context":"screen","startedAt":1794285267660,"offsetMs":-120,"durationMs":43557,"width":444,"height":972,"mimeType":"video/mp4"}]}
  • mimeType is video/mp4. The file has one H.264 video track.
  • audio is true when the file also has an audio track. The field is absent when the recording said and heard nothing while the video ran.
    • The track is everything the recording said and heard, mixed into one channel. Each sound is at the time it sounded.
    • The track is AAC-LC, mono, 16 kHz.
    • The same audio stays under audio/, unmixed. A player that reads audio/ SHOULD mute the file.
  • offsetMs MAY be negative. The stream is joined just before the recording starts, so the video covers all of it.
  • startedAt is when the first frame arrived at the machine running Vibium. A frame is on screen a little earlier than it arrives.
  • durationMs is the video’s length.
  • gaps counts the times the stream lost packets. After a loss the video holds its last picture until the next key frame. The field is absent when there were none.
  • error says why the stream ended before the recording did. The file then holds the video up to that point.
  • width and height are the stream’s. A viewer and a recording see the same picture.
  • A key frame arrives about every 2 seconds. A player can seek to any of them.

Resource files use Playwright-compatible naming: <pageId>-<wallTimeMs>.<ext> (e.g., resources/page@abc123-1773879004791.jpeg).

Newline-delimited JSON. Each line is a self-contained event object with a type field. Events appear in chronological order.

context-options — Always the first event. Metadata about the recording session.

{"version":8,"type":"context-options","origin":"library","libraryName":"vibium","libraryVersion":"26.3.18","browserName":"chromium","platform":"darwin","wallTime":1708000000000,"monotonicTime":0,"sdkLanguage":"javascript","title":"my test","contextId":"context@18d5a2b3c00","options":{"viewport":{"width":1280,"height":720}}}
FieldTypeDescription
libraryNamestringAlways "vibium"
libraryVersionstringVersion of the vibium binary (e.g., "26.3.18")
browserNamestringAlways "chromium"
platformstringOS: "darwin", "linux", or "windows"
wallTimenumberAbsolute Unix timestamp in milliseconds (calendar time)
monotonicTimenumberRelative ms since recording start (always 0 for the first event)
titlestringFrom start({ title }) or start({ name })
contextIdstringUnique context ID for this recording session (e.g., "context@18d5a2b3c00")
optionsobjectBrowser context options. Contains viewport ({width, height}) when available.
sdkLanguagestringAlways "javascript"
versionnumberTrace format version (currently 8)
originstringAlways "library"

screencast-frame — A screenshot captured during recording. References an image file in resources/ by name. Default format is JPEG (configurable via format and quality start options).

{"type":"screencast-frame","pageId":"page@abcdef123","sha1":"page@abcdef123-1773879004791.jpeg","width":1280,"height":720,"timestamp":100}
FieldTypeDescription
pageIdstringBrowsing context ID of the captured page
sha1stringResource name in <pageId>-<wallTimeMs>.<ext> format (Playwright-compatible)
widthnumberScreenshot width in pixels (read from image header)
heightnumberScreenshot height in pixels
timestampnumberRelative ms since recording start

Screenshots are captured per-action in dispatch(), with a CAS guard to avoid flooding Chrome with concurrent capture requests.

frame-snapshot — A DOM snapshot. Contains a nested snapshot object with structured HTML as an array tree.

{"type":"frame-snapshot","snapshot":{"callId":"call@3","snapshotName":"before@call@3","pageId":"page@abcdef123","frameId":"page@abcdef123","frameUrl":"https://example.com","doctype":"<!DOCTYPE html>","html":["HTML",{"lang":"en"},["HEAD",{}],["BODY",{},["IMG",{"src":"data:image/jpeg;base64,...","style":"width:100%"}]]],"viewport":{"width":1280,"height":720},"timestamp":200,"wallTime":200,"resourceOverrides":[{"url":"data:image/jpeg;base64,...","sha1":"a1b2c3..."}],"isMainFrame":true}}
FieldTypeDescription
snapshot.callIdstringThe call@N id this snapshot is associated with
snapshot.snapshotNamestring"before@call@N" or "after@call@N"
snapshot.pageIdstringBrowsing context ID
snapshot.frameIdstringFrame ID (same as pageId for main frame)
snapshot.frameUrlstringURL of the frame at snapshot time
snapshot.doctypestringDocument doctype string
snapshot.htmlarrayStructured DOM tree as nested arrays: ["TAG", {attrs}, ...children]
snapshot.viewportobject{width, height} of the viewport
snapshot.resourceOverridesarrayMaps resource URLs to SHA1 hashes in resources/
snapshot.isMainFramebooleanAlways true (sub-frames not yet supported)
snapshot.timestampnumberRelative ms since recording start
snapshot.wallTimenumberRelative ms since recording start

before / after — Paired markers that bracket an operation. There are three kinds: actions, action groups, and BiDi commands. All share a single monotonic counter with call@N format.

Every vibium command emits a before/after pair automatically — both mutations (click, fill, navigate) and read-only queries (text, isVisible, getAttribute).

{"type":"before","callId":"call@1","startTime":300,"class":"Page","method":"vibium:page.navigate","pageId":"page@abcdef123","params":{"url":"https://example.com"},"title":"Page.navigate"}
{"type":"after","callId":"call@1","endTime":400,"afterSnapshot":"after@call@1"}
{"type":"before","callId":"call@2","startTime":500,"class":"Element","method":"vibium:element.click","pageId":"page@abcdef123","params":{"selector":"#login"},"beforeSnapshot":"before@call@2","title":"Element.click"}
{"type":"input","callId":"call@2","point":{"x":640,"y":360},"box":{"x":600,"y":340,"width":80,"height":40}}
{"type":"after","callId":"call@2","endTime":600}
{"type":"before","callId":"call@3","startTime":700,"class":"Element","method":"vibium:element.text","pageId":"page@abcdef123","params":{"selector":".result"},"title":"Element.text"}
{"type":"after","callId":"call@3","endTime":750,"afterSnapshot":"after@call@3"}

before fields:

FieldTypeDescription
callIdstringcall@<N> — same id for both before and after. N is a monotonic counter shared across actions, groups, and BiDi commands.
titlestringHuman-readable name like Element.click, Page.navigate, Element.text. Derived from the vibium method by apiNameFromMethod().
classstringElement, Page, Browser, BrowserContext, Network, Dialog, etc.
methodstringThe raw vibium method (e.g., vibium:element.click, vibium:element.text).
paramsobjectThe command parameters as sent by the client.
startTimenumberRelative ms since recording start.
pageIdstringBrowsing context ID of the page the action targets. Present on actions, absent on groups.
parentIdstringcall@<N> of the enclosing action group, if the action is inside a startGroup()/stopGroup() span. Absent for top-level actions.
beforeSnapshotstring"before@call@<N>" — references the snapshotName of a frame-snapshot event captured before the action ran. Present on interaction actions (click, fill, hover, etc.) that resolve an element — the snapshot is taken after scrolling the element into view. Click-like actions (click, dblclick, hover, tap, set, unset, dragTo) have beforeSnapshot only. Fill-like actions (fill, type, press, clear, selectOption) have both beforeSnapshot and afterSnapshot. Query actions (find, text, navigate, etc.) have afterSnapshot only.

input fields (emitted for element-targeting actions only):

FieldTypeDescription
callIdstringcall@<N> — matches the corresponding before/after pair.
pointobject{x, y} — center of the resolved element’s bounding box (viewport coordinates). Compatible with Playwright’s trace viewer click-dot overlay.
boxobject{x, y, width, height} — full bounding box of the resolved element (viewport coordinates). Used by the record player to draw a highlight rectangle.

Present for actions that resolve an element (click, fill, hover, type, set, etc.). Absent for non-element actions (page.navigate, page.eval, etc.) and action groups.

after fields:

FieldTypeDescription
callIdstringcall@<N> — matches the corresponding before event.
endTimenumberRelative ms since recording start.
afterSnapshotstring"after@call@<N>" — references the snapshotName of a frame-snapshot event captured after the action completed. Present on fill-like actions (fill, type, press, clear, selectOption) and all non-interaction actions (navigate, find, text, etc.). Absent on click-like actions (click, dblclick, hover, tap, set, unset, dragTo) which use beforeSnapshot only, and absent on groups.

The dispatch() wrapper in the router records these markers — every vibium command that goes through dispatch() gets recorded. Recording commands themselves (recording.start, recording.stop, etc.) are excluded since they control recording.

Groups are named spans from startGroup() / stopGroup(). They wrap multiple actions under a single label in the timeline.

{"type":"before","callId":"call@4","startTime":300,"class":"Tracing","method":"tracingGroup","params":{"name":"login flow"},"title":"login flow"}
{"type":"before","callId":"call@5","startTime":350,"class":"Element","method":"vibium:element.fill","pageId":"page@abcdef123","parentId":"call@4","params":{"selector":"#user","value":"admin"},"title":"Element.fill"}
{"type":"after","callId":"call@5","endTime":380,"afterSnapshot":"after@call@5"}
{"type":"after","callId":"call@4","endTime":500}

Groups are nestable. The before and after events share the same call@N id. Actions inside a group have a parentId field pointing to the group’s callId (see parentId in the field table above).

When recording is started with bidi: true, every raw BiDi command sent to the browser via sendInternalCommand is also recorded. This is useful for debugging low-level protocol issues.

{"type":"before","callId":"call@6","title":"browsingContext.navigate","class":"BiDi","method":"browsingContext.navigate","params":{"context":"ABC123","url":"https://example.com"},"startTime":350}
{"type":"after","callId":"call@6","endTime":390}
FieldTypeDescription
callIdstringcall@<N> — same monotonic counter as actions and groups.
titlestringThe BiDi method name (e.g., browsingContext.navigate).
classstringAlways "BiDi".

BiDi markers nest inside action markers — a single vibium command (like Page.navigate) may produce several BiDi commands internally.

event — A BiDi browser event (context creation, dialog, log entry, etc.) recorded as-is.

{"type":"event","method":"browsingContext.contextCreated","params":{...},"time":150,"class":"BrowserContext"}

These are all non-network BiDi events that flow through the router while recording is active.

Newline-delimited JSON. Each line is a resource-snapshot event containing a HAR 1.2 Entry object. This format is compatible with both player.vibium.dev and the standard Playwright trace viewer.

Raw BiDi network events (network.beforeRequestSent, network.responseCompleted, network.fetchError) are automatically correlated by request ID and transformed into HAR entries during recording.

{"type":"resource-snapshot","snapshot":{"startedDateTime":"2024-02-15T10:00:00.000Z","time":45,"request":{"method":"GET","url":"https://example.com/","httpVersion":"HTTP/1.1","cookies":[],"headers":[{"name":"Host","value":"example.com"}],"queryString":[],"headersSize":250,"bodySize":0},"response":{"status":200,"statusText":"OK","httpVersion":"HTTP/1.1","cookies":[],"headers":[{"name":"Content-Type","value":"text/html"}],"content":{"size":1234,"mimeType":"text/html"},"redirectURL":"","headersSize":-1,"bodySize":1234},"cache":{},"timings":{"send":-1,"wait":45,"receive":-1},"_monotonicTime":300,"_frameref":"page@abc123"}}
FieldTypeDescription
typestringAlways "resource-snapshot"
snapshot.startedDateTimestringISO 8601 timestamp of the request
snapshot.timenumberTotal elapsed time in milliseconds
snapshot.requestobjectHAR request with method, url, httpVersion, headers, queryString, etc.
snapshot.responseobjectHAR response with status, statusText, headers, content, etc.
snapshot.cacheobjectAlways {}
snapshot.timingsobject{send, wait, receive} — wait is the request→response delta
snapshot._monotonicTimenumberRelative ms since recording start (same unit as all other timestamps)
snapshot._framerefstringBiDi browsing context ID

For failed requests (network.fetchError), the response has status: 0 and a _failureText field with the error message.

Binary assets referenced by name from the event files. Resource files include their image extension (.jpeg or .png).

ContentSource
Screenshot frames (JPEG by default, or PNG)screencast-frame events
DOM snapshot imagesframe-snapshot resourceOverrides

Resource names use Playwright-compatible format: <pageId>-<wallTimeMs>.<ext> (e.g., resources/page@abc123-1773879004791.jpeg). Each screenshot gets a unique name based on its page and capture time.

Client Proxy Browser
│ │ │
│ recording.start │ │
├───────────────────────────>│ Create Recorder │
│ │ Start screenshot goroutine │
│ │ │
│ page.navigate, click, … │ │
├───────────────────────────>│ dispatch() (see below) │
│ │ │
│ │<─── BiDi events ────────────────│
│ │ RecordBidiEvent() │
│ │ (network → .network, │
│ │ other → .trace) │
│ │ │
│ recording.stop │ │
├───────────────────────────>│ Stop screenshot goroutine │
│ │ Capture final DOM snapshot │
│ │ Build zip │
│<──── zip (base64 or file) ─│ │
dispatch(session, cmd, handler)
│
├── RecordAction(method, params) // before marker
│
│ handler(session, cmd)
│ │
│ ├── sendInternalCommand ────────────────> Browser
│ │ ├── [if bidi: true] RecordBidiCommand()
│ │ │ ···wait for response···
│ │ └── [if bidi: true] RecordBidiCommandEnd()
│ │
│ ├── sendInternalCommand ────────────────> Browser
│ │ └── (same pattern, one per BiDi call)
│ │
│ └── sendSuccess / sendError
│
└── RecordActionEnd() // after marker

The dispatch() wrapper records action markers around every vibium command handler. Inside the handler, sendInternalCommand optionally records BiDi command markers when bidi: true was passed to recording.start. The routeBrowserToClient loop independently records BiDi events (browser-initiated messages like context creation, network activity, log entries) — these are passive observations that require no extra round-trips. Screenshots are captured per-action in dispatch() with a CAS guard.

By default, start() → stop() produces one zip covering the entire session.

Chunks split a recording into segments without stopping the recording:

start() ────────────────────────────────────────────── stop()
│ │ │
events A events B events C
│ │ │
stopChunk() startChunk() (final)
→ zip with A stopChunk()
→ zip with B
→ zip with C

Each chunk gets its own context-options header and chunk index. The monotonic base is reset on each startChunk(), so timestamps within each chunk start from 0. Resources (screenshots, snapshots) are shared across chunks — the resources/ map is not cleared on startChunk(), so a stopChunk zip may contain resources referenced by earlier chunks too.

Open a recording in Record Player:

  1. Go to player.vibium.dev
  2. Drop your record.zip file onto the page

The viewer renders a timeline with screenshots, actions, network waterfall, and DOM snapshots. Every vibium command appears as an individual action in the timeline (e.g., Page.navigate, Element.click, Element.text). Action groups from startGroup()/stopGroup() appear as labeled spans that wrap multiple actions. With bidi: true, raw BiDi commands are also visible as nested entries within their parent actions.