Skip to content

WebRTC Client Reference

API reference for @moveris/webrtc — the framework-agnostic WebRTC transport client and its TypeScript types.

In plain terms

WebRTCLivenessClient manages the peer connection, DataChannel, and frame protocol. You call connect(), send frames with sendFrames(), and read the verdict from the returned result or onResult callback.

Import

import { WebRTCLivenessClient, DATACHANNEL_NAME, CHUNK_SIZE_BYTES } from '@moveris/webrtc';

import type {
  WebRTCClientOptions,
  WebRTCLivenessResult,
  WebRTCConnectionState,
  WebRTCFrame,
  WebRTCObserverConfig,
} from '@moveris/webrtc';

WebRTCLivenessClient

Constructor

new WebRTCLivenessClient(options: WebRTCClientOptions)

WebRTCClientOptions

Option Type Default Description
observerConfigUrl string required URL to the observer's /kvs/config endpoint. The client appends ?model=<alias> automatically so the correct model shard responds (3.22.2+)
model string required Model alias (e.g. mixed-30-v3_1)
apiKey string — Moveris API key forwarded to the observer in the start message
deviceIntelligence Record<string, unknown> — Optional device / client metadata included as device_intelligence in the DataChannel start message (3.22.1+)
onResult (result: WebRTCLivenessResult) => void — Called when the observer returns a verdict. Optional — sendFrames() also resolves with the result
onProgress (received: number, required: number) => void — Called as the observer acknowledges frames
onError (error: Error) => void — Connection or protocol errors
onConnectionStateChange (state: RTCPeerConnectionState) => void — Peer connection state changes
channelOpenTimeoutMs number 10000 Max ms to wait for the DataChannel to open
resultTimeoutMs number 30000 Max ms to wait for a verdict after sendFrames()

Methods

Method Description
connect(): Promise<void> Fetch config, establish peer connection and DataChannel. Resolves when the channel is open.
sendFrames(frames: WebRTCFrame[]): Promise<WebRTCLivenessResult> Send frames to the observer. Must be called after connect(). Resolves with the verdict.
disconnect(): void Close the peer connection and signaling channel.
get state Current WebRTCConnectionState.

Types

WebRTCFrame

Field Type Description
index number Frame sequence number (0-based)
timestampMs number Capture timestamp in milliseconds
pixels string Base64-encoded PNG image
landmarks Array<{ x, y, z }> \| null Optional MediaPipe landmarks per frame

WebRTCLivenessResult

Field Type Description
verdict 'live' \| 'fake' \| 'unknown' Liveness verdict
scorePct number Score 0–100
confidence number Confidence 0–1
inferenceMs number Observer-side inference time
captureMs number Total capture duration
sessionId string Session identifier
transport string Transport label returned by the observer
serverMediapipeCalled boolean Whether the observer ran server-side face mesh
physioExtracted boolean \| null Whether physiological signal was extracted

WebRTCConnectionState

Connection lifecycle values exposed on client.state:

Value Description
'idle' Not connected
'connecting' Fetching config or negotiating SDP
'connected' DataChannel open
'sending' Streaming frame chunks to the observer
'awaiting_result' All frames sent; waiting for the verdict
'done' Verdict received
'error' Connection or protocol error
'disconnected' Connection closed

Constants

import { DATACHANNEL_NAME, CHUNK_SIZE_BYTES } from '@moveris/webrtc';

DATACHANNEL_NAME;   // 'liveness'
CHUNK_SIZE_BYTES;   // 16384 (16 KB PNG chunks)