Install

One ES module from the CDN, a video source, and one call.

Which CDN

One ES module, served per environment. The origin you import from decides which environment you measure against: the library derives the analysis server from that same origin, so there is nothing else to configure.

EnvironmentModule URL
Productionhttps://cdn.saphere.ai/realtime-measure/v1/main.js
Testhttps://cdn.test.saphere.ai/realtime-measure/v1/main.js

The shortest working page

<!doctype html>
<video id="camera" playsinline muted></video>

<script type="module">
    import RealtimeMeasure from "https://cdn.saphere.ai/realtime-measure/v1/main.js"

    const video = document.getElementById("camera")
    video.srcObject = await navigator.mediaDevices.getUserMedia({ video: true, audio: false })
    await video.play()

    const measure = RealtimeMeasure.create({
        video: "#camera",
        retrieveAccessToken: () => fetch("/my-server/realtime-token").then(response => response.text()),
        onEvent: event => {
            if (event.type === "measure:variables")
                console.log(event.variables.heartRate)
        }
    })

    await measure.start()
</script>

The module also registers itself as window.IVirtual.RealtimeMeasure and fires a realtime-measure:ready CustomEvent on window, carrying the class as detail.RealtimeMeasure. That is the way in for a page that cannot write an import: give a module script tag the CDN URL as its src, and listen for the event rather than reading the global, which is not guaranteed to be set when your own inline script runs. The tag has to carry type="module" — the bundle is an ES module, and a classic script tag stops on SyntaxError: Cannot use 'import.meta' outside a module without running at all. The bundle also refuses to be evaluated twice: several measurements come from several create() calls on the one class.

What the browser has to provide

Three requirements, the first two of which rule out some browsers outright, and one recommendation.

  • A secure context. The page must be served over https (or be localhost): both the camera and WebTransport refuse anything else.
  • WebTransport. Chromium-based browsers and Firefox serve it. WebKit does not interoperate with our server today — that is Safari, and every WebView on iOS, which are all WebKit whatever their badge says. On those, the models load and the session never opens: you get realtime:attached, then realtime:error once the ten seconds the handshake is given have passed. If you need those users covered, Saphere Scan measures over a WebSocket they do serve.
  • WebGL2, preferably. The face and body detectors run on the graphics processor, through WebGL2. Where it is unavailable — a driver the browser has blocklisted, a virtual machine — they fall back on the processor: slower, but a measurement rather than none, and still not a configuration to rely on.
  • Room in your Content-Security-Policy, if your page sets one. The CDN origin under script-src and connect-src — the module, the detection models and their WebAssembly come from there; 'wasm-unsafe-eval' under script-src, the detectors and the compression being WebAssembly; the analysis server’s origin (https://api-webtransport. followed by your environment’s host) under connect-src, which is the directive a browser applies to WebTransport; and blob: together with the CDN origin under worker-src, or under the script-src it falls back to. That last pair is the surprising one: a browser refuses a worker script from another origin however permissive its CORS headers are, so the library starts each compression worker from a one-line blob: script of your page’s own origin, which then imports the real worker from the CDN — and a worker-src governs both. With blob: alone, start() fails on Workerpool Worker error; Firefox may report a blocked inline script instead, which points at the wrong thing.

Test on the browser you ship to, early

The WebTransport line above is the one that surprises integrations late. It costs a minute to check: load your page, call start(), and watch for realtime:error.

What start() does, and what it costs

start() attaches the source declared by the video option, loads the detection models and the compression workers, obtains an access token and opens the session. The first call costs seconds and several megabytes; the ones after it do not — what is loaded stays loaded, so stopping and measuring again reloads nothing. realtime:attached marks the passage from one to the other, and carries the dimensions of the source.

Only the models the settings ask for are downloaded, and bodyDetection is on by default: the upper body is what the breathing rate is read from, in the rise and fall of the chest. It costs a second model at start-up and one more compression per frame. Turning it off spares both, and the breathing rate then falls back on the modulation the pulse wave carries, which is the more fragile of the two readings. Turned on again later, the model loads then: the torso is simply missing from getDetection() until it arrives.

The access token is asked for after the loading, at every start(): it is single-use and the handshake consumes it, so nothing is minted until the chain is ready to use it. A failed start() — no source, a token refused, a handshake that does not go through — leaves the instance alive and what it loaded in place, so you can call it again; calling it while a measurement is running rejects.

await measure.start()    // attaches, loads, opens the session
// … later
await measure.stop()     // waits for the session to be closed; the instance stays loaded
measure.destroy()        // releases the models, the workers and the session — for good

Two ways to stop

stop() waits. Its promise resolves once capture has stopped, the frames it had already taken have been sent, the streams are closed and the session is closed — which is also when realtime:stopped reaches your handler, not before. Calling it twice waits for the same closing, and a start() issued meanwhile waits for it rather than opening a session on a chain that is closing.

abort() cuts, and returns in the same turn. Whatever is queued is dropped. Use it where you have nowhere to wait: a component being unmounted, a route change, a beforeunload handler. destroy() uses it for that very reason.

await measure.stop()   // waits: what was captured is sent, then the session closes
measure.abort()        // cuts: what is queued is dropped, the call returns at once

Either way the session is recorded as closed on our side rather than as a dropped link, which is what separates both from simply walking away from the page. A saturated link cannot hang stop(): past five seconds of waiting the session is cut, realtime:stopped then says aborted rather than requested, and the promise resolves all the same — a stop that never ends would be worse than a brutal one.

A destroyed instance stays destroyed: start() rejects on it, and measuring again means another create().

The identifier of the measure

Each session records a measure, and the server announces its identifier as the session opens: realtime:started carries it as measureId, and getMeasureId() returns it. Hand it to your own server, which reads the measure with its API key — its essentials and its outputs — once the measurement is over.

// in your onEvent handler
if (event.type === "realtime:started") send(event.measureId)   // to your server
await measure.stop()
const measureId = measure.getMeasureId()                             // still there after the stop

getMeasureId() returns the identifier of the last session opened, and keeps it after stop(): that is when its results are fetched. It returns null before the first start(), during the next one until its session is open, and when the server did not announce the identifier in time — the measurement then runs all the same, and the console still lists it under Measures › Realtime.

The video source

The source is the video option, in one of three forms:

RealtimeMeasure.create({ video: "#camera" })                        // a CSS selector
RealtimeMeasure.create({ video: document.querySelector("video") })  // the element itself
RealtimeMeasure.create({ video: mediaStream })                      // a bare MediaStream

A selector is only resolved at start(): you can write your options before the page carries the element, and ask for the camera in the meantime.

A <video> element you pass is taken as it is: the library never moves it, mutes it, plays it, mirrors it or hides it — it waits for its metadata, and playing it is yours. If you pass a MediaStream instead, an off-screen video element is created for you, played muted, and removed by destroy(). It is placed off-screen through the script’s style interface rather than a style attribute, so a style-src that forbids inline styles does not affect it.

Handing setOptions() another source swaps it live, during a measurement included: a second realtime:attached then announces the dimensions of the new one, or realtime:error if it designates nothing. A payload that says nothing about video, on the other hand, detaches nothing — start() attaches, destroy() detaches.

Options

Options are validated when you pass them, and a payload that cannot be applied — a field of the wrong type, an empty selector — throws a TypeError without changing anything. setOptions() replaces the payload rather than merging into it: whatever you leave out returns to its default, which is the only way a setting can be taken back. That includes onEvent and retrieveAccessToken, whose default is none: a setOptions() that leaves them out silences your handler, and the next start() fails on no-callback. Pass them again.

OptionDefaultWhat it does
videononeThe source to measure: a CSS selector, a <video> element or a MediaStream. Required by start().
fps30Frames captured and sent per second, rounded and held to 15–60 rather than refused. Below 15 the measurement stops meaning anything; the analysis runs at 30, so a higher rate costs bandwidth without measuring more.
faceDetectiontrueSend the face. It is what carries the pulse, and the vitals are published from it: turning it off leaves no heart rate and no measure:variables at all.
bodyDetectiontrueAlso send the upper body. It is what the breathing rate is read from; turning it off falls back on reading it from the pulse wave.
retrieveAccessTokennoneA function returning the session token, or a promise of it. See Access tokens.
onEventnoneYour handler. Everything the library reports comes through it. See Events.
logsfalseSends what the library does — each step, how long it took, why one failed — to Saphere’s diagnostic log, so that a session that went wrong can be read back. Turning it on is your consent on behalf of your users: a first line announces the browser (user agent and language), and every line carries a random identifier of the instance; never an image, a measured value or a token. It opens a WebSocket to the CDN origin you already allow under connect-src, and costs nothing while it is off: the part of the library that does it is only downloaded when you turn it on.

The capture settings take effect immediately, including during a measurement. getOptions() returns the ones being applied.

Load once, measure many times

stop() leaves the models and the workers loaded, so a second start() only asks for a token and opens a new session, without downloading anything again. Create one instance per page, not one per measurement.

TypeScript

The CDN serves the module alone: no type declarations are published with it today, so an import from its URL is untyped in TypeScript, and the shapes to declare on your side are the tables of this section and of events. What the module does export, besides the class (as the default export and as RealtimeMeasure), is REALTIME_MEASURE_EVENTS, the event names as constants — the one check a JavaScript integration gets on a misspelt type.