Événements
Un canal pour ce qui arrive, deux lectures pour ce qui bouge à la cadence de capture.
Un seul canal
Tout ce que la librairie rapporte passe par options.onEvent, appelé avec un seul objet portant un type. realtime:* dit où en est la librairie, token:error pourquoi un jeton n’a pas pu être obtenu, et measure:* porte la mesure — ce que le serveur calcule, et ce qu’en disent le détecteur local et les compteurs. Votre gestionnaire est appelé dans un try : ce qu’il lève est journalisé dans la console et n’arrête rien.
| Événement | Charge | Quand |
|---|---|---|
realtime:attached | width, height | start() a branché la source et chargé ce qu’il lui fallait ; il ne reste que la session à ouvrir. Réémis quand la source change. |
realtime:started | measureId | La session est ouverte et la capture tourne. measureId nomme la mesure qu’elle enregistre — une chaîne, ou null quand le serveur ne l’a pas annoncé à temps ; getMeasureId() le rend aussi. |
realtime:stopped | reason | La mesure s’est arrêtée : requested une fois stop() achevé, aborted après abort(), destroy() ou un stop() qui a dû couper, transport-closed quand le lien est tombé ou que le serveur a fermé la session (y compris une session coupée faute de crédits — voir la FAQ — sans que la librairie transmette le code de fermeture du serveur), capture-failed quand la chaîne de capture elle-même est tombée (un realtime:error qui en porte la cause précède aussitôt). Un seul par session. |
realtime:destroyed | — | Le dernier événement d’une instance : rien ne suit. |
realtime:error | message | Le démarrage a échoué — la source, les modèles, les workers, la session. Aussi, sur une instance en marche, une source remplacée qui ne désigne rien, un modèle activé qui ne se charge pas, ou la chaîne de capture qui tombe — realtime:stopped suit alors avec capture-failed. |
token:error | reason | Le jeton n’a pas pu être obtenu. |
measure:bvp | indexBase, bvp | Un point d’onde de pouls, à la cadence de capture. |
measure:breathing | index, value | Un point d’onde respiratoire, par image de torse mesurée. |
measure:variables | variables | Les grandeurs, une fois par seconde. |
measure:presence | face, body, faceBox, bodyBox | Un sujet est entré dans le champ ou en est sorti. |
measure:stats | stats | Les compteurs, une fois par seconde tant qu’une session tourne. |
RealtimeMeasure.create({
onEvent: event => {
switch (event.type) {
case "measure:bvp": chart.push(event.indexBase, event.bvp); break
case "measure:breathing": breathing.push(event.index, event.value); break
case "measure:variables": panel.show(event.variables); break
case "measure:presence": hint.toggle(event.face); break
case "realtime:error": banner.show(event.message); break
}
}
})
Ce que les grandeurs portent
measure:variables porte la forme même que le serveur calcule : une fréquence cardiaque, une fréquence respiratoire et ce dont elle a été lue, des indices de variabilité, un score de qualité, et deux drapeaux qu’il vaut la peine de lire avant d’afficher quoi que ce soit.
| Champ | Ce qu’il faut en faire |
|---|---|
heartRate, breathingRate | Les deux chiffres qu’un utilisateur attend : battements par minute, et respirations par minute. L’un comme l’autre peut valoir null quand le signal ne permet pas de lecture — testez avant de formater ; heartRateIntervals et breathingSource aussi. |
breathingSource, breathingQuality, breathingWindowS | D’où la fréquence respiratoire a été lue, avec quelle netteté (de 0 à 1), et sur combien de secondes. |
stars, sqi | La qualité du signal, en un nombre entier d’étoiles de 0 à 5 et en indice brut de 0 à 1. |
mature | false tant que dix secondes n’ont pas été mesurées. Dites « mesure en cours », pas un chiffre. |
confident | false quand la qualité ne passe pas la barre, ou quand des images ont manqué — environ 40 % des dix dernières secondes ou davantage — au point que le signal est en grande partie comblé plutôt que mesuré, même si sa qualité paraît correcte. Le champ ne dit pas lequel des deux. Présentez la valeur comme provisoire. |
sdnn, rmssd, pnn50, sd1, sd2, lfHf | La variabilité — en millisecondes, sauf pnn50, un pourcentage, et lfHf, un rapport —, null quand la qualité n’a pas permis de la calculer, ce qui demande un seuil plus haut que celui de confident : confident: true avec sdnn: null est normal. |
heartRateIntervals, beats, rejected | La fréquence par les intervalles, en battements par minute, et combien d’intervalles entre battements ont été retenus et écartés. |
time | Le temps de capture de l’image pour laquelle ces valeurs ont été calculées, en millisecondes depuis l’ouverture de la session. C’est un nombre entier. |
healthIndex | Réservé : il demande l’âge du sujet, qu’une session temps réel n’a aujourd’hui aucun moyen de recevoir, si bien qu’il vaut toujours null. |
Rien n’arrive du tout tant que la fenêtre est trop courte — environ sept secondes après le début de la mesure, les deux premières étant écartées — : un silence au début veut dire pas encore, jamais rien à mesurer. Et un champ de variabilité à null veut dire pas de mesure — jamais zéro, qui serait la lecture d’un cœur parfaitement régulier.
La fréquence respiratoire se lit de deux façons, et breathingSource dit laquelle. motion est le mouvement de la cage thoracique, mesuré sur les images de torse — là où la respiration a lieu. bvp est la lente modulation que porte l’onde de pouls. C’est le repli d’une session qui n’envoie pas de torse, mais aussi ce que rapporte une session qui en envoie un tant que la lecture du torse n’a pas abouti : cette lecture demande un signal à elle, confirmé dans le temps, et repart de zéro quand le torse est resté plus de deux secondes hors du champ. breathingSource peut donc passer de bvp à motion — et inversement — en cours de mesure. Les deux ne valent pas la même chose : un affichage qui montre le chiffre sans lire sa source montre deux choses différentes sous une même étiquette. breathingQuality, entre 0 et 1, dit avec quelle netteté le rythme s’est détaché du signal, et breathingWindowS l’intervalle sur lequel il a été lu — plusieurs sont essayés à chaque publication et celui sur lequel le signal se résout le mieux est retenu, si bien qu’il change en cours de mesure. Les deux valent null quand la source est bvp.
measure:bvp porte indexBase, qui désigne la capture à laquelle le point appartient, comptée à partir de zéro au début de chaque session. Il ne se déduit pas de l’ordre d’arrivée : une image sans visage n’est jamais envoyée, donc la suite saute. Ces trous sont l’image honnête d’une mesure — un visage sorti du champ, un moment de mouvement — et les dessiner comme des trous plutôt que de refermer le trait est ce qui empêche un lecteur de croire le signal continu.
measure:breathing est la même idée sur le torse : un point par image de torse mesurée, index désignant cette image et sautant de la même façon — une capture où aucun torse n’a été trouvé n’envoie rien. Sa value est le déplacement vertical cumulé de la cage thoracique, en cent-vingt-huitièmes de la hauteur du recadrage du torse — une unité qui ne change pas avec la taille du recadrage —, et seule sa variation veut dire quelque chose : son origine est là où se trouvait la première image, et elle dérive lentement. Calez un graphe sur le minimum et le maximum de ce qu’il montre, jamais sur zéro, et lisez-y un rythme plutôt qu’un niveau. La fréquence, elle, est dans les grandeurs.
Rien n’est calculé dans le navigateur
Les points des ondes — pouls comme respiration — arrivent tels que le serveur les a calculés. En tirer votre propre fréquence cardiaque ou respiratoire produirait un second chiffre, différent et sans autorité derrière lui.Lire la détection, plutôt que se la faire annoncer
Ce que le détecteur voit bouge à la cadence de capture. En faire un événement mettrait trente messages par seconde sur un canal qui, en intégration mobile, traverse un pont de WebView — c’est donc une lecture :
function drawOverlay() {
const { source, face, body } = measure.getDetection()
if (face !== null) {
face.box // { left, top, width, height } en pixels de la source — le recadrage envoyé
face.normalizedBox // le même, entre 0 et 1 : à multiplier par votre taille d'affichage
face.landmarks // 478 points, { x, y, z }, normalisés
}
// … dessinez, puis :
requestAnimationFrame(drawOverlay)
}
Appelez-la depuis votre propre boucle de rendu. Le cadre vient dans les deux repères parce qu’il fait huit nombres ; les points ne viennent que normalisés — le visage seul en compte 478, de trois nombres chacun — et source ({ width, height }) suffit à les replacer en pixels. Le cadre du torse n’est pas la boîte de ses points : il est bâti sur les seules épaules et hanches — un poignet levé l’étirerait sinon sur toute l’image —, élargi d’une petite marge, gardé dans l’image, et tenu immobile tant que le sujet ne bouge pas vraiment, un recadrage stable étant ce qui permet de lire le mouvement de la cage thoracique. landmarks vous rend tout de même les trente-trois points.
Le détecteur tourne de l’ouverture de la session, que realtime:started annonce, jusqu’au geste qui met fin à la mesure — stop(), abort() ou destroy(). Hors de cet intervalle — y compris pendant que start() charge ou attend la poignée de main — face et body valent null.
measure:presence vous dit tout de même quand un sujet entre ou sort, ce qui est la partie qu’il faudrait sinon guetter, et il porte faceBox/bodyBox — { box, normalizedBox } comme dans getDetection(), ou null pour une partie sortie du champ — le cadre à cet instant, dans les deux repères. Il n’est pas suivi ensuite : c’est à cela que sert la lecture ci-dessus.
Compteurs
getStats() rend des compteurs cumulés. Le même objet arrive comme measure:stats une fois par seconde tant qu’une session tourne, si bien que vous avez rarement à l’appeler vous-même.
| Champ | Ce qu’il compte |
|---|---|
frames, dropped | Les images capturées, et les fois où la capture a pris du retard sur sa cadence et sauté en avant. |
detections, faceDetected, bodyDetected | Les passes de détection, et combien ont trouvé un visage, un torse. |
faceFrames, faceBytes, bodyFrames, bodyBytes | Les images envoyées et les octets écrits sur le fil, par flux, après compression. |
savedBytes, faceSavedBytes, bodySavedBytes | Les octets que la compression a épargnés, en tout et par flux. |
queued, queuedPeak | Les messages en attente d’écriture, et le plus haut niveau de cette file pendant la session. |
latencyLast, latencyAverage, latencyMax, latencySamples | L’aller-retour d’une image jusqu’à son point d’onde de pouls, en millisecondes — le dernier, la moyenne, le pire — et sur combien d’allers-retours ils reposent. |
Cumulés, jamais une cadence : une cadence demande une fenêtre, et cette fenêtre est une décision d’affichage. Faites la différence de deux relevés si vous voulez un débit. Et cumulés sur l’instance, non sur la session : un second start() reprend là où le premier s’était arrêté — prenez un relevé à realtime:started et soustrayez-le pour obtenir les chiffres d’une session. Seule la file appartient à la session.
Deux d’entre eux se lisent mal. savedBytes est la somme de faceSavedBytes et de bodySavedBytes, si bien que compter les trois compte le gain deux fois. Et latencySamples dit sur combien d’allers-retours les trois valeurs de latence sont assises : zéro veut dire que rien n’est encore revenu, ce qu’un affichage doit distinguer d’une latence nulle.
Une file qui ne redescend pas
queued et queuedPeak sont le signe avancé que la capture produit plus vite que le lien n’absorbe — visible bien avant que la latence ne le montre. Baisser fps est le levier.