Installation

Un module ES depuis le CDN, une source vidéo, et un appel.

Quel CDN

Un module ES, servi par environnement. L’origine depuis laquelle vous l’importez décide de l’environnement que vous mesurez : la librairie en déduit le serveur d’analyse, il n’y a donc rien d’autre à configurer.

EnvironnementURL du module
Productionhttps://cdn.saphere.ai/realtime-measure/v1/main.js
Testhttps://cdn.test.saphere.ai/realtime-measure/v1/main.js

La page qui marche en le moins de lignes

<!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("/mon-serveur/realtime-token").then(response => response.text()),
        onEvent: event => {
            if (event.type === "measure:variables")
                console.log(event.variables.heartRate)
        }
    })

    await measure.start()
</script>

Le module se pose aussi comme window.IVirtual.RealtimeMeasure et émet sur window un CustomEvent realtime-measure:ready qui porte la classe sous detail.RealtimeMeasure. C’est la porte d’une page qui ne peut pas écrire d’import : donnez l’URL du CDN comme src d’une balise de script de type module, et écoutez l’événement plutôt que de lire la globale, qui n’est pas garantie posée quand votre propre script en ligne s’exécute. La balise doit porter type="module" — le paquet est un module ES, et une balise ordinaire s’arrête sur SyntaxError: Cannot use 'import.meta' outside a module sans rien exécuter. Le paquet refuse par ailleurs d’être évalué deux fois : plusieurs mesures s’obtiennent par plusieurs create() sur la même classe.

Ce que le navigateur doit fournir

Trois exigences, dont les deux premières écartent d’emblée certains navigateurs, et une recommandation.

  • Un contexte sécurisé. La page doit être servie en https (ou être localhost) : la caméra comme WebTransport refusent le reste.
  • WebTransport. Les navigateurs fondés sur Chromium et Firefox le prennent en charge. WebKit n’interopère pas avec notre serveur aujourd’hui — c’est-à-dire Safari, et toutes les WebViews d’iOS, qui sont toutes WebKit quelle que soit leur étiquette. Là, les modèles se chargent et la session ne s’ouvre jamais : vous recevez realtime:attached, puis realtime:error une fois écoulées les dix secondes que la poignée de main a pour aboutir. S’il vous faut couvrir ces utilisateurs, Saphere Scan mesure par un websocket qu’ils prennent en charge, eux.
  • WebGL2, de préférence. Les détecteurs du visage et du torse tournent sur le processeur graphique, par WebGL2. Là où il n’est pas disponible — un pilote écarté par le navigateur, une machine virtuelle —, ils se rabattent sur le processeur : plus lent, mais une mesure plutôt qu’aucune, et toujours pas une configuration sur laquelle compter.
  • De la place dans votre Content-Security-Policy, si votre page en pose une. L’origine du CDN sous script-src et connect-src — le module, les modèles de détection et leur WebAssembly en viennent ; 'wasm-unsafe-eval' sous script-src, les détecteurs et la compression étant du WebAssembly ; l’origine du serveur d’analyse (https://api-webtransport. suivi de l’hôte de votre environnement) sous connect-src, qui est la directive qu’un navigateur applique à WebTransport ; et blob: avec l’origine du CDN sous worker-src, ou sous le script-src sur lequel il retombe. Cette dernière paire est celle qui surprend : un navigateur refuse un script de worker d’une autre origine si permissifs que soient ses en-têtes CORS, si bien que la librairie démarre chaque worker de compression par un script blob: d’une ligne, de l’origine de votre page, qui importe ensuite le vrai worker depuis le CDN — et un worker-src régit les deux. Avec blob: seul, start() échoue sur Workerpool Worker error ; Firefox peut rapporter à la place un script en ligne bloqué, ce qui désigne la mauvaise cause.

Éprouvez tôt le navigateur que vous visez

La ligne sur WebTransport est celle qui surprend tard les intégrations. Elle coûte une minute à vérifier : chargez votre page, appelez start(), et guettez realtime:error.

Ce que fait start(), et ce qu’il coûte

start() branche la source déclarée par l’option video, charge les modèles de détection et les workers de compression, obtient un jeton d’accès et ouvre la session. Le premier appel coûte des secondes et plusieurs mégaoctets ; les suivants non — ce qui est chargé le reste, si bien qu’arrêter puis remesurer ne recharge rien. realtime:attached marque le passage de l’un à l’autre, et porte les dimensions de la source.

Seuls les modèles que vos réglages demandent sont téléchargés, et bodyDetection est actif par défaut : c’est du torse que se lit la fréquence respiratoire, dans le mouvement de la cage thoracique. Il en coûte un second modèle au démarrage et une compression de plus par image. Le couper épargne les deux, et la fréquence respiratoire retombe alors sur la modulation que porte l’onde de pouls, qui est la plus fragile des deux lectures. Réactivé plus tard, le modèle se charge à ce moment-là : le torse manque simplement à getDetection() jusqu’à son arrivée.

Le jeton d’accès est demandé après le chargement, à chaque start() : il est à usage unique et la poignée de main le consomme, donc rien n’est frappé tant que la chaîne n’est pas prête à s’en servir. Un start() en échec — pas de source, un jeton refusé, une poignée de main qui n’aboutit pas — laisse l’instance vivante et ce qu’elle a chargé en place, si bien que vous pouvez le rappeler ; l’appeler pendant qu’une mesure tourne le fait rejeter.

await measure.start()    // branche, charge, ouvre la session
// … plus tard
await measure.stop()     // attend que la session soit fermée ; l'instance reste chargée
measure.destroy()        // rend les modèles, les workers et la session — pour de bon

Deux façons d’arrêter

stop() attend. Sa promesse ne rend la main qu’une fois la capture arrêtée, les images déjà prises envoyées, les streams fermés et la session fermée — et c’est à ce moment-là que realtime:stopped arrive à votre gestionnaire, pas avant. L’appeler deux fois attend la même fermeture, et un start() lancé entre-temps l’attend au lieu d’ouvrir une session sur une chaîne qui se ferme.

abort() coupe, et rend la main dans le même tour. Ce qui est en file est jeté. Employez-le là où vous n’avez nulle part où attendre : un composant qu’on démonte, un changement de route, un gestionnaire beforeunload. C’est pour cette raison même que destroy() l’emploie.

await measure.stop()   // attend : ce qui a été capturé part, puis la session se ferme
measure.abort()        // coupe : ce qui est en file est jeté, l'appel rend la main aussitôt

Dans les deux cas la session est enregistrée fermée chez nous, et non comme un lien tombé : c’est ce qui les sépare l’un comme l’autre du fait de quitter la page sans rien dire. Un lien saturé ne peut pas faire pendre stop() : passé cinq secondes d’attente la session est coupée, realtime:stopped dit alors aborted et non requested, et la promesse rend tout de même la main — un arrêt qui ne finit jamais serait pire qu’un arrêt brutal.

Une instance détruite le reste : start() y est rejeté, et mesurer de nouveau demande un autre create().

L’identifiant de la mesure

Chaque session enregistre une mesure, et le serveur en annonce l’identifiant à l’ouverture : realtime:started le porte sous measureId, et getMeasureId() le rend. Transmettez-le à votre serveur, qui lit la mesure avec sa clé d’API — l’essentiel et ses sorties — une fois la mesure finie.

// dans votre gestionnaire onEvent
if (event.type === "realtime:started") send(event.measureId)   // à votre serveur
await measure.stop()
const measureId = measure.getMeasureId()                             // toujours là après l'arrêt

getMeasureId() rend l’identifiant de la dernière session ouverte, et le garde après stop() : c’est alors qu’on va chercher ses résultats. Il rend null avant le premier start(), pendant le suivant tant que sa session n’est pas ouverte, et quand le serveur n’a pas annoncé l’identifiant à temps — la mesure tourne alors tout de même, et la console la liste toujours sous Measures › Realtime.

La source vidéo

La source est l’option video, sous l’une des trois formes :

RealtimeMeasure.create({ video: "#camera" })                        // un sélecteur CSS
RealtimeMeasure.create({ video: document.querySelector("video") })  // l'élément lui-même
RealtimeMeasure.create({ video: mediaStream })                      // un MediaStream nu

Un sélecteur n’est résolu qu’à start() : vous pouvez écrire vos options avant que la page ne porte l’élément, et demander la caméra entre-temps.

Un élément <video> que vous passez est pris tel quel : la librairie ne le déplace pas, ne le met pas en sourdine, ne le lance pas, ne le retourne pas et ne le masque pas — elle attend ses métadonnées, et le lire vous revient. Si vous passez un MediaStream à la place, un élément vidéo hors du champ est fabriqué pour vous, lu en muet, et destroy() le retire. Sa mise hors du champ passe par l’interface de style du script et non par un attribut de style, si bien qu’un style-src qui interdit les styles en ligne ne l’affecte pas.

Remettre une autre source à setOptions() la rebranche à chaud, mesure en cours comprise : un second realtime:attached annonce alors les dimensions de la nouvelle, ou realtime:error si elle ne désigne rien. Une charge qui ne dit rien de video, en revanche, ne débranche rien — start() branche, destroy() débranche.

Options

Les options sont validées au moment où vous les passez, et une charge qui ne peut pas s’appliquer — un champ du mauvais type, un sélecteur vide — lève une TypeError sans rien changer. setOptions() remplace la charge au lieu de s’y fondre : ce que vous omettez revient à son défaut, ce qui est la seule façon de reprendre un réglage. Cela vaut pour onEvent et retrieveAccessToken, dont le défaut est aucun : un setOptions() qui les omet fait taire votre gestionnaire, et le start() suivant échoue sur no-callback. Passez-les de nouveau.

OptionDéfautCe qu’elle fait
videoaucunLa source à mesurer : un sélecteur CSS, un élément <video> ou un MediaStream. Exigée par start().
fps30Images capturées et envoyées par seconde, arrondie et ramenée à 15–60 plutôt que refusée. Sous 15, la mesure ne veut plus rien dire ; l’analyse tourne à 30, si bien qu’une cadence plus haute coûte du débit sans rien mesurer de plus.
faceDetectiontrueEnvoyer le visage. C’est lui qui porte le pouls, et les grandeurs sont publiées à partir de lui : le couper ne laisse ni fréquence cardiaque ni aucun measure:variables.
bodyDetectiontrueEnvoyer aussi le torse. C’est de lui que se lit la fréquence respiratoire ; le couper fait retomber celle-ci sur l’onde de pouls.
retrieveAccessTokenaucunUne fonction rendant le jeton de session, ou une promesse de jeton. Voir Jetons d’accès.
onEventaucunVotre gestionnaire. Tout ce que la librairie rapporte passe par lui. Voir Événements.
logsfalseEnvoie ce que la librairie fait — chaque étape, sa durée, pourquoi l’une a échoué — au journal de diagnostic de Saphere, pour qu’une session qui s’est mal passée se relise. L’activer vaut votre consentement au nom de vos utilisateurs : une première ligne annonce le navigateur (agent utilisateur et langue), et chaque ligne porte un identifiant aléatoire de l’instance ; jamais une image, une valeur mesurée ni un jeton. Elle ouvre un websocket vers l’origine du CDN que vous autorisez déjà sous connect-src, et ne coûte rien tant qu’elle est éteinte : la partie de la librairie qui le fait ne se télécharge que lorsque vous l’activez.

Les réglages de capture prennent effet immédiatement, mesure en cours comprise. getOptions() rend ceux qui s’appliquent.

Charger une fois, mesurer plusieurs

stop() laisse les modèles et les workers chargés, si bien qu’un second start() ne fait que demander un jeton et ouvrir une nouvelle session, sans rien retélécharger. Créez une instance par page, pas une par mesure.

TypeScript

Le CDN sert le module seul : aucune déclaration de types n’est publiée avec lui aujourd’hui, si bien qu’un import depuis son URL n’est pas typé en TypeScript, et les formes à déclarer de votre côté sont les tableaux de cette section et des événements. Ce que le module exporte, outre la classe (en export par défaut et sous le nom RealtimeMeasure), est REALTIME_MEASURE_EVENTS, les noms d’événements en constantes — le seul contrôle qu’une intégration en JavaScript obtienne sur un type mal orthographié.