Quickstart
De tu API key a tus primeros indicadores: con el SDK en una página tuya, con cURL o con Python.
Preview 0.45 Disponible · Preview 0.45. La API puede cambiar antes de la 1.0: ver Fases de lanzamiento.
Antes de empezar
Sección titulada «Antes de empezar»- Una cuenta de DevLab con equipo (organización
tu organización , equipotu equipo ). La API key de tu equipo está en Tu cuenta:Inicia sesión para verla . En los ejemplos aparece como<your-api-key>. - La URL de Engine de tu entorno está en el kit de un protocolo, en Tu integración (un protocolo → Kit →
.env.example→ la líneaENGINE_BASE; dónde exactamente): el kit reúne la configuración del cliente de ese protocolo, el entorno de tu backend y un starter listo para ejecutar por modo (Tu kit). Los ejemplos la llaman$ENGINE. - Para la vía cURL,
curlyjqinstalados. - Para el SDK, Node.js 20.3 o posterior (
@neurologyca/capture-serversolo corre en el servidor). - Guarda la API key en tu servidor. Nunca la pongas en una página ni en una app.
- Para el SDK, el token del registro (
NODE_AUTH_TOKEN): lo entrega Neurologyca con tu invitación, por el mismo canal que la key; no está en DevLab.
En qué puedes inscribir a las personas depende de los contextos de tu organización (ver Qué es Engine 2). Este quickstart usa Measurement: una posición, un step e indicadores sin interpretación. Engine recomienda un baseline antes de cualquier protocolo; la inscripción responde con baselineWarning, pero no bloquea, así que este quickstart se lo salta.
Qué consigues: una persona medida con la cámara o un vídeo, y los indicadores que devuelve Engine, en tu propia página.
Elige tu camino
Sección titulada «Elige tu camino»1. Configura el registro
Sección titulada «1. Configura el registro»En una carpeta nueva para el quickstart, crea .npmrc con:
@neurologyca:registry=https://npm.pkg.github.com//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}Después define el token del registro en tu shell, antes de instalar:
export NODE_AUTH_TOKEN="<your-registry-token>"En PowerShell:
$env:NODE_AUTH_TOKEN = "<your-registry-token>"2. Instala
Sección titulada «2. Instala»npm init -y && npm pkg set type=modulenpm install @neurologyca/capture@0.45.0 @neurologyca/capture-server@0.20.1 esbuild3. Tu backend
Sección titulada «3. Tu backend»Crea a una persona, la inscribe en Measurement y hace de proxy de las llamadas del navegador con tu key. El navegador nunca lleva un token. No lo despliegues: no tiene sesión, así que cualquiera que lo abra capturaría con tu key a través de su proxy.
Guarda server.mjs, index.html y page.js en esa carpeta. server.mjs sirve index.html desde ahí y el bundle desde public/page.js, que crea el paso 5. Los tres ficheros se publican tal cual se ejecutan, así que sus comentarios y mensajes están en inglés.
// Your backend for the quickstart (Node 20.3+). It creates one person, enrols them in Measurement and proxies the// browser's calls to Engine with your key, which only lives here.// ENGINE_BASE=<your Engine URL> ENGINE_API_KEY=<your key> node server.mjsimport http from 'node:http'import { readFile } from 'node:fs/promises'import { createEngineAdmin, createTokenSource, createEngineProxy, ownsAll } from '@neurologyca/capture-server'import { toNodeListener } from '@neurologyca/capture-server/node'
const { ENGINE_BASE, ENGINE_API_KEY, PORT = '3000' } = process.envif (!ENGINE_BASE || !ENGINE_API_KEY) throw new Error('Set ENGINE_BASE (your environment\'s Engine URL, in your kit) and ENGINE_API_KEY')
// 1. One person and their enrolment. In your app: your signed-in user, and the pair saved in your database.const admin = createEngineAdmin({ baseUrl: ENGINE_BASE, apiKey: ENGINE_API_KEY })const measurement = (await admin.listProtocolLibrary()).find((p) => p.name === 'Measurement' && p.status === 'published')if (!measurement) { console.error('Your environment does not offer the Measurement protocol yet. Ask Neurologyca, or use the cURL tab with another protocol.') process.exit(1)}const { externalId } = await admin.createUser({ name: 'quickstart-user' }) // the package generates an opaque UUIDconst { userProtocolId } = await admin.enrol(externalId, measurement.pid)const next = await admin.getNextPosition(userProtocolId)if (!next) throw new Error('The enrolment has no position to capture')const pair = { userProtocolId, protocolMechanicId: next.protocolMechanicId }console.log(`Person ${externalId} enrolled in Measurement. Each start creates one: delete it when you are done (irreversible), with ENGINE_BASE and ENGINE_API_KEY set as for server.mjs: node --input-type=module -e "import { createEngineAdmin } from '@neurologyca/capture-server'; await createEngineAdmin({ baseUrl: process.env.ENGINE_BASE, apiKey: process.env.ENGINE_API_KEY }).deleteUser('${externalId}')"`)
// 2. The proxy: the browser calls /engine/* with no token and the proxy adds yours. ownsAll checks every id a route// carries: here, only this person's enrolment.const tokens = createTokenSource({ baseUrl: ENGINE_BASE, apiKey: ENGINE_API_KEY })const engine = toNodeListener(createEngineProxy({ baseUrl: ENGINE_BASE, tokens, mountPath: '/engine', authorize: async (_req, route) => ownsAll(route, { userProtocol: async (up) => up === pair.userProtocolId, user: async (userId) => userId === externalId, }),}))
// 3. The page, its bundle and the pair.const files = new Map([['/', ['index.html', 'text/html']], ['/page.js', ['public/page.js', 'text/javascript']]])const server = http.createServer(async (req, res) => { const url = req.url ?? '/' if (url.startsWith('/engine/')) return engine(req, res) // before any body parser if (url === '/pair') { res.writeHead(200, { 'content-type': 'application/json' }) return res.end(JSON.stringify(pair)) } const file = files.get(url) if (!file) { res.writeHead(404); return res.end() } res.writeHead(200, { 'content-type': file[1] }) res.end(await readFile(new URL(file[0], import.meta.url)))})server.listen(Number(PORT), () => { const { port } = /** @type {import('node:net').AddressInfo} */ (server.address()) console.log(`Open http://localhost:${port}`)})4. Tu página
Sección titulada «4. Tu página»<!doctype html><html lang="en"><meta charset="utf-8"><title>Quickstart: Measurement with the SDK</title><p><label>Optional, a video of yours with a face: <input id="file" type="file" accept="video/*"></label></p><video id="video" muted playsinline width="320"></video><p><button id="start">Start</button> <button id="cancel" disabled>Cancel</button></p><pre id="out"></pre><script type="module" src="/page.js"></script></html>// Your page: a short Measurement capture with the SDK, from the camera or from a video file of yours.// Bundle it for the browser: npx esbuild page.js --bundle --format=esm --outfile=public/page.jsimport { createProtocolClient, classifyMediaError } from '@neurologyca/capture'
const out = /** @type {HTMLPreElement} */ (document.querySelector('#out'))const video = /** @type {HTMLVideoElement} */ (document.querySelector('#video'))const picker = /** @type {HTMLInputElement} */ (document.querySelector('#file'))const cancel = /** @type {HTMLButtonElement} */ (document.querySelector('#cancel'))
// One client for the whole page, created when it loads and reused for every capture.const client = createProtocolClient({ baseUrl: '/engine', // your backend's proxy: the browser carries no token keepPrepared: true, // what prepare() loaded survives a capture: measure again without preparing in between taxonomy: { contextId: 'measurement' }, // Measurement: any value; required by the SDK, though Measurement does not send it (0.29.0) startup: { includeUserAgent: false }, // the startup report stays in the SDK: no user agent, and nothing is sent anywhere // The SDK's own words for each startup stage of a capture (userMessage), ready to show. onStartupStage: (e) => { if (e.kind === 'capture' && e.userMessage) out.textContent = e.userMessage }, onWarning: (w) => console.warn(w.code, w.message), onError: (e) => { out.textContent = `${e.code}: ${e.message}` }, // a failure mid-capture (a 409, a lost session): its cause})// Prepare once, before the first click, so Start does not wait for the face model. It never calls Engine and asks for no// permission. With keepPrepared the models stay between captures: no prepare() after one. It does not reject on a failed// load (the capture then loads it itself). The SDK releases what it kept when the page goes away (pagehide): you do not// listen for it. Call client.release() only when you drop the client, or between one person and the next.const prepare = () => { client.prepare().catch((e) => console.warn(e.code, e.message)) }prepare()
document.querySelector('#start')?.addEventListener('click', async () => { out.textContent = 'Capturing…' // Cancel: before the capture starts, the signal cuts the start; once it runs, session.abort() ends it. const stopper = new AbortController() /** @type {Awaited<ReturnType<typeof client.captureProtocol>> | null} */ let session = null cancel.disabled = false cancel.onclick = () => { stopper.abort(); void session?.abort().catch(() => { /* already over */ }) } try { // The pair comes from your backend (it enrolled the person), never from the browser. const { userProtocolId, protocolMechanicId } = await (await fetch('/pair')).json() const file = picker.files?.[0] video.srcObject = null // an earlier camera run left its stream here, and it would hide your video if (file) video.src = URL.createObjectURL(file) // a video of yours: give it its src BEFORE capturing session = await client.captureProtocol({ captureId: crypto.randomUUID(), // yours: it joins this capture's warnings and startup report userProtocolId, protocolMechanicId, source: file ? { type: 'video', el: video } : { type: 'webcam' }, signal: stopper.signal, // Your video: play it now (muted, so it plays on its own). The camera: show the SDK's preview in your <video>. onStarted: (preview) => { if (!file) video.srcObject = preview.srcObject; video.play().catch((e) => { out.textContent = String(e) }) }, triggerAnalysis: false, // Measurement: nothing to interpret. SDK 0.29.0 skips it when Engine returns interpreted: false; keep it until yours does }) const [step] = session.plan.steps // Measurement has one step, of 6 s or more if (file) video.currentTime = 0 // the SDK loaded its model meanwhile: rewind so no second of your file is lost await session.step(step.order).run({ durationMs: 15_000 }) // a shorter video ends it earlier const outcome = await session.stop() console.log(outcome) out.textContent = JSON.stringify(outcome, null, 2) } catch (e) { // classifyMediaError names the cause: insecure-context (not HTTPS or localhost), denied, no-device, in-use, no-frames… const err = /** @type {Error & { code?: string }} */ (e) out.textContent = stopper.signal.aborted ? 'Cancelled.' : `${classifyMediaError(e) ?? err.code ?? err.name}: ${err.message}` await session?.abort().catch(() => { /* already over */ }) } finally { cancel.onclick = null cancel.disabled = true }})taxonomy: { contextId: 'measurement' } y triggerAnalysis: false: el contextId sigue siendo obligatorio, aunque Measurement no lo envía. Desde la 0.29.0 el SDK se salta solo el análisis cuando Engine dice interpreted: false; producción aún no lo devuelve, así que mantén triggerAnalysis: false (Solo medir).
El cliente se crea una sola vez, al cargar la página, y client.prepare() corre enseguida: carga el modelo de la cara mientras la persona lee la página, así que Start no lo espera. prepare() nunca llama a Engine, no pide ningún permiso y no rechaza si falla una descarga (la captura carga entonces lo que necesita). Con keepPrepared: true lo cargado se queda para la siguiente captura del mismo cliente, así que no hay ningún prepare() entre capturas: cada una adopta lo que dejó la anterior (en Safari e iOS, solo la cara). El SDK lo suelta solo al salir de la página; llama a client.release() solo al soltar el cliente, o entre una persona y la siguiente en el mismo dispositivo. signal es lo que usa Cancel: corta el arranque y, con la captura en marcha, session.abort() la termina. captureId es tuyo y une los avisos de la captura con su informe de arranque. startup: { includeUserAgent: false } deja el user agent del navegador fuera de ese informe, que se queda en el SDK: nada lo envía a ningún sitio. onStartupStage da el texto propio del SDK para cada etapa (userMessage), listo para mostrar. Más en Preparar antes de Empezar y La pantalla de arranque; para que el arranque no se note en tu flujo, Cargar los modelos.
5. Ejecútalo
Sección titulada «5. Ejecútalo»npx esbuild page.js --bundle --format=esm --outfile=public/page.jsENGINE_BASE="<engine base URL>" ENGINE_API_KEY="<your-api-key>" node server.mjsEn PowerShell, la segunda línea es:
$env:ENGINE_BASE = "<engine base URL>"; $env:ENGINE_API_KEY = "<your-api-key>"; node server.mjsENGINE_BASE es el mismo valor que $ENGINE: la URL de Engine de tu entorno, que está en tu kit (dónde).
Abre http://localhost:3000 en Chrome, Edge o Safari (16.4+): la cámara solo se abre en HTTPS o en localhost. Pulsa Start y permite la cámara, o elige antes un vídeo tuyo con una cara. Pulsa Start una vez, y para medir otra vez vuelve a arrancar server.mjs: el par es una posición, Engine lo rechaza una vez capturada, y cada arranque crea e inscribe a una persona nueva. Con la cámara, la página enseña la vista previa de la cámara (la del SDK, en tu <video>); con un vídeo, lo reproduce cuando empieza la captura y lo rebobina antes del step, para no perder ni un segundo. Para probarlo en el móvil, mira Pruébalo en tu móvil.
Salida esperada, en la página y en la consola:
{ "status": "complete", "hcis": { "valence": "<number>", "arousal": "<number>", "Confusion": "<number>", "Stress_intens": "<number>" }, "hcisByStep": { "1": { "valence": "<number>", "arousal": "<number>", "Confusion": "<number>", "Stress_intens": "<number>" } }, "frameCount": 450, "interpretation": null, "structured": null}Los valores salen de la cara de una persona, así que aquí van sin ellos; los nombres son los indicadores públicos que recibes. El ejemplo enseña 4 de las 65 señales en total, de una captura de prueba con Measurement, que recibe todos los indicadores públicos; otro contexto puede recibir menos (cuáles). El resultado llega segundos después de que acabe el step de 15 segundos: bastante menos de un minuto desde que se pulsa Start.
¿Sin cámara ni vídeo? Mira el ejemplo en el playground.
1. Pide un token
Sección titulada «1. Pide un token»export ENGINE="<engine base URL>"export ENGINE_API_KEY="<your-api-key>"
TOKEN=$(curl -s -X POST "$ENGINE/token" \ -H "Content-Type: application/json" \ -d "{\"apiKey\":\"$ENGINE_API_KEY\"}" | jq -r .token)Respuesta esperada:
{ "token": "<jwt>", "expiresIn": 3600 }2. Crea un usuario
Sección titulada «2. Crea un usuario»Engine identifica a las personas con un id que eliges tú (externalId). Usa un id opaco, nunca un email ni un nombre. Cada ejecución crea una persona nueva: EXT lleva la hora, así que repetir los pasos crea otra. El paso 8 la borra.
EXT="quickstart-$(date +%s)"curl -s -X POST "$ENGINE/users" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "{\"externalId\":\"$EXT\",\"name\":\"quickstart-user\"}"Respuesta esperada (recortada):
{ "externalId": "quickstart-1767225600", "name": "quickstart-user", "createdBy": "<your-credential-name>", "lastAccessAt": null}3. Mira qué puede usar tu organización e inscribe al usuario
Sección titulada «3. Mira qué puede usar tu organización e inscribe al usuario»El catálogo es el de tu organización: Neurologyca asigna contextos a cada organización, y estas listas solo contienen protocolos de esos contextos. Lista primero tus contextos y tus protocolos:
curl -s "$ENGINE/catalog/contexts" \ -H "Authorization: Bearer $TOKEN" | jq '.[] | {name, taxonomy}'curl -s "$ENGINE/catalog/protocols" \ -H "Authorization: Bearer $TOKEN" | jq '.[] | {pid, name, status}'Tus listas serán distintas. En el entorno de pruebas todas las organizaciones ven Baseline y Measurement, que allí es universal; por ejemplo:
[ { "pid": "00000000-0000-4000-8000-0147b17fe72c", "name": "Measurement", "status": "published" }, { "pid": "00000000-0000-4000-8000-53ac3da6df87", "name": "Baseline", "status": "published" }]Filtra por status: published: el catálogo trae también versiones archivadas con el mismo nombre, y una archivada se puede inscribir con un aviso, así que sin el filtro podrías inscribirte en la antigua.
Cada entrada trae el pid con el que se inscribe. Toma el protocolo Measurement e inscribe al usuario:
# Measurement by default. To use another protocol, set PROTOCOL to its pid before running this block.PROTOCOL=${PROTOCOL:-$(curl -s "$ENGINE/catalog/protocols" \ -H "Authorization: Bearer $TOKEN" \ | jq -r '.[] | select(.name=="Measurement" and .status=="published") | .pid')}
if [ -z "$PROTOCOL" ]; then echo "Your environment does not offer the Measurement protocol yet. Set PROTOCOL to a pid from the list above (except Baseline) and run this block again." >&2 falseelse UP=$(curl -s -X POST "$ENGINE/user-protocols" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "{\"user\":\"$EXT\",\"protocol\":\"$PROTOCOL\"}" | jq -r .userProtocolId) echo "UP=$UP"fiSi tu entorno aún no ofrece el protocolo Measurement, el bloque se para con un mensaje en inglés que dice eso: fija PROTOCOL al pid de un protocolo de la lista de arriba (salvo Baseline) y vuelve a ejecutar el bloque.
Engine responde así (recortado); el bloque solo se queda con userProtocolId. El baselineWarning es el recordatorio del baseline:
{ "status": "active", "protocol": { "name": "Measurement" }, "baselineWarning": { "missing": true, "expired": false, "invalid": false, "message": "No baseline found for this user." }}Si Measurement no está en tu lista (tu entorno aún no lo ofrece), este quickstart funciona igual con cualquier protocolo cuya siguiente posición tenga un solo step (lo compruebas en el paso 4), salvo Baseline, en el que no se inscribe a nadie (ver Baseline): envía la muestra como ese step. Si la mecánica tiene varios steps, la sesión sigue abierta hasta que cada step recibe sus propios lotes y su propio Final (step: N); los steps que declaran media esperan el mediaId que mostraste.
4. Busca la posición que hay que capturar
Sección titulada «4. Busca la posición que hay que capturar»PM=$(curl -s "$ENGINE/user-protocols/$UP" -H "Authorization: Bearer $TOKEN" \ | jq -r .nextProtocolMechanic.protocolMechanicId)
curl -s "$ENGINE/user-protocols/$UP/mechanics/$PM" \ -H "Authorization: Bearer $TOKEN" | jq '.mechanic.steps'La muestra cubre un step, así que comprueba que la posición tiene exactamente uno:
[ { "order": 1, "type": "measurement_free", "minTimeSeconds": 6 }]5. Envía la captura
Sección titulada «5. Envía la captura»En producción, Capture produce estos frames en el navegador. Aquí envías una muestra: descarga la captura de ejemplo (unos 3 MB) en la carpeta donde ejecutas estos comandos. Es sintética: una malla facial genérica, no es la cara de nadie, así que sus indicadores no describen a nadie. Contiene diez lotes de 30 frames del step 1, numerados del 1 al 10, y el último lleva Final.
# The last batch is the Final. Engine aggregates the step when the Final arrives,# so give the previous batch a few seconds to be processed.LAST=$(jq 'length' sample-capture.json); i=0jq -c '.[]' sample-capture.json | while read -r packet; do i=$((i + 1)); [ "$i" -eq "$LAST" ] && sleep 3 echo "$packet" | jq --arg up "$UP" --arg pm "$PM" '. + {userProtocolId:$up, protocolMechanicId:$pm}' \ | curl -s -X POST "$ENGINE/process-kpn-emo" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ --data-binary @- echodoneCada lote responde 202. Envía los diez en orden, con una pausa breve antes del Final: un hueco o un Final que falta dejan el step abierto.
{ "code": 202, "message": "KPN-EMO enqueued successfully, processing...", "status": "accepted", "framesReceived": 30, "framesWithoutFeaturesMeta": 0, "framesWithoutMediaTime": 30, "step": 1}6. Lee los resultados
Sección titulada «6. Lee los resultados»Los resultados están listos cuando la sesión se completa (unos segundos con esta muestra). Hasta entonces la respuesta viene vacía, así que consulta en bucle, durante tres minutos como mucho:
for _ in $(seq 1 60); do curl -s "$ENGINE/results/$UP/$PM" -H "Authorization: Bearer $TOKEN" \ | jq -e '(.rawResults["1"] // {}) | del(.stepType) | length > 0' >/dev/null 2>&1 && break sleep 3donecurl -s "$ENGINE/results/$UP/$PM" -H "Authorization: Bearer $TOKEN" | jq '{aggResults}'Respuesta esperada, recortada a cuatro indicadores (la real trae muchas más señales):
{ "aggResults": { "1": { "mean": { "valence": 6.751, "arousal": 69.775, "Confusion": 14.618, "Stress_intens": 54.195 } } }}rawResults trae los mismos indicadores para cada frame.
7. Opcional: una interpretación
Sección titulada «7. Opcional: una interpretación»Measurement devuelve indicadores, no una interpretación: pedir POST /analyze sobre una captura de Measurement devuelve 409 (PROTOCOL_NOT_ANALYSED), porque Measurement nunca se interpreta. Una interpretación necesita un protocolo de un contexto con taxonomía: envías su taxonomía con POST /user-protocols/{userProtocolId}/{protocolMechanicId}/context antes de los frames, y pones triggerAnalysis: true en el lote Final o llamas a POST /analyze después. Las vías de integración y la guía de tu contexto lo cuentan.
8. Limpia
Sección titulada «8. Limpia»Cada ejecución deja en tu organización una persona, su inscripción y sus resultados. Bórralos al terminar: DELETE /users/{externalId} elimina a la persona y todos sus datos (capturas, sesiones, inscripciones, baseline y consentimientos). Es irreversible y el cuerpo debe repetir el externalId en confirm.
curl -s -X DELETE "$ENGINE/users/$EXT" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "{\"confirm\":\"$EXT\"}"Respuesta esperada (los recuentos dependen de lo que capturaste):
{ "deleted": "quickstart-1767225600", "counts": { "frames": 120, "sessions": 1, "userProtocols": 1, "subjectStates": 1, "consents": 1, "thresholds": 0, "policies": 0 }}Para medir a la misma persona otra vez, no la crees de nuevo: un POST /users con el mismo externalId responde 409. Conserva a la persona y abre una inscripción nueva con POST /user-protocols (una posición se captura una vez, así que una medición nueva necesita una inscripción nueva). Una credencial read_all solo puede borrar a las personas que creó.
Este código corre en tu servidor: la API key nunca llega al navegador. Necesita Python 3.8+ y requests (pip install requests), elegido frente a urllib de la biblioteca estándar porque envía JSON y cabeceras en una sola llamada. Los siete bloques son un solo script, quickstart.py, que se ejecuta en la carpeta donde descargas la captura de ejemplo:
ENGINE_BASE="<engine base URL>" ENGINE_API_KEY="<your-api-key>" python quickstart.py1. Pide un token
Sección titulada «1. Pide un token»import json, os, sys, timeimport requests
# La URL de Engine de tu entorno está en tu kit (ENGINE_BASE: la pestaña cURL la llama $ENGINE). La API key, solo en tu servidor.ENGINE = os.environ["ENGINE_BASE"]API_KEY = os.environ["ENGINE_API_KEY"]
r = requests.post(f"{ENGINE}/token", json={"apiKey": API_KEY})r.raise_for_status()token = r.json()["token"]auth = {"Authorization": f"Bearer {token}"}La respuesta es la misma que en la pestaña cURL: token y expiresIn (segundos).
2. Crea un usuario
Sección titulada «2. Crea un usuario»Usa un id opaco (externalId), nunca un email ni un nombre. Cada ejecución crea una persona nueva: ext lleva la hora, así que repetir el script crea otra. El paso 7 la borra.
ext = f"quickstart-{int(time.time())}"r = requests.post(f"{ENGINE}/users", headers=auth, json={"externalId": ext, "name": "quickstart-user"})r.raise_for_status()print(r.status_code, r.json())3. Mira qué puede usar tu organización e inscribe al usuario
Sección titulada «3. Mira qué puede usar tu organización e inscribe al usuario»El catálogo es el de tu organización, como en la pestaña cURL. Si Measurement no está, pon en PROTOCOL el pid de un protocolo cuya siguiente posición tenga un solo step (nunca Baseline).
# El catálogo de tu organización. Measurement por defecto; para usar otro protocolo, pon su pid en PROTOCOL.protocols = requests.get(f"{ENGINE}/catalog/protocols", headers=auth).json()for p in protocols: print(p["pid"], p["name"], p["status"])protocol = os.environ.get("PROTOCOL") or next( (p["pid"] for p in protocols if p["name"] == "Measurement" and p["status"] == "published"), None)if not protocol: sys.exit("Your environment does not offer the Measurement protocol yet. Set PROTOCOL to a pid from the list above (except Baseline).")r = requests.post(f"{ENGINE}/user-protocols", headers=auth, json={"user": ext, "protocol": protocol})r.raise_for_status()up = r.json()["userProtocolId"]4. Busca la posición que vas a capturar
Sección titulada «4. Busca la posición que vas a capturar»La muestra cubre un step, así que el script comprueba que la posición tenga exactamente uno.
pm = requests.get(f"{ENGINE}/user-protocols/{up}", headers=auth).json()["nextProtocolMechanic"]["protocolMechanicId"]steps = requests.get(f"{ENGINE}/user-protocols/{up}/mechanics/{pm}", headers=auth).json()["mechanic"]["steps"]if len(steps) != 1: sys.exit(f"This position has {len(steps)} steps and the sample covers one: use a position with a single step.")5. Envía la captura
Sección titulada «5. Envía la captura»Diez lotes en orden, con una pausa breve antes del Final: cada uno responde 202.
# La captura de ejemplo, descargada junto a este script: diez lotes del step 1, el último Final.with open("sample-capture.json") as f: packets = json.load(f)for i, packet in enumerate(packets): if i == len(packets) - 1: time.sleep(3) # Engine agrega el step cuando llega el Final: dale unos segundos al lote anterior r = requests.post(f"{ENGINE}/process-kpn-emo", headers=auth, json={**packet, "userProtocolId": up, "protocolMechanicId": pm}) r.raise_for_status() print(r.status_code, r.json()["framesReceived"])6. Lee los resultados
Sección titulada «6. Lee los resultados»# Listos cuando la sesión se completa; hasta entonces la respuesta está vacía, así que sondea hasta tres minutos.for _ in range(60): results = requests.get(f"{ENGINE}/results/{up}/{pm}", headers=auth).json() step1 = (results.get("rawResults") or {}).get("1") or {} if any(k != "stepType" for k in step1): break time.sleep(3)print(json.dumps({"aggResults": results.get("aggResults")}, indent=2))La respuesta es la misma que en la pestaña cURL: aggResults por step, y rawResults con los mismos indicadores para cada frame. Measurement no se interpreta: para una interpretación, mira el paso 7 de la pestaña cURL.
7. Limpia
Sección titulada «7. Limpia»Borra a la persona y todos sus datos (irreversible; confirm repite el externalId).
# Limpia: borra a la persona y todos sus datos (irreversible; "confirm" repite el externalId).r = requests.delete(f"{ENGINE}/users/{ext}", headers=auth, json={"confirm": ext})r.raise_for_status()print(r.status_code, r.json()["counts"])Para medir a la misma persona otra vez, no llames a POST /users por segunda vez con el mismo externalId (responde 409): conserva a la persona y abre una inscripción nueva con POST /user-protocols.
Qué puede salir mal
Sección titulada «Qué puede salir mal»Algunos fallos responden con un error; otros responden 2xx y solo se notan después.
- Un error de la cámara o del vídeo en la página:
classifyMediaErrordice su causa.insecure-context: no estás en HTTPS ni enlocalhost.denied: se denegó el permiso de la cámara.no-deviceoin-use: no hay cámara, u otra aplicación la tiene.no-frames(CaptureStartError): la cámara se abrió pero no dio ningún frame útil, o tu vídeo estaba en pausa o ya había terminado. E_RESULTS_TIMEOUT: no es una pérdida; lee los resultados más tarde con el mismo par (ver Los resultados en tu backend).- Un
403desde/engine/…: elownsAlldel proxy rechazó un id que no es de esta persona.
| Qué ves | Por qué |
|---|---|
npm install responde 401/404 para @neurologyca/… |
Falta NODE_AUTH_TOKEN en esta terminal o es incorrecto (Instalación) |
La captura se para en el modelo de la cara (CaptureStartError, stage: 'face-model') |
Tu red bloquea cdn.jsdelivr.net o storage.googleapis.com: permítelos o aloja tú los modelos (Cargar los modelos) |
401 con el cuerpo vacío (y WWW-Authenticate: Bearer) |
Falta el token o ha caducado. Pide otro con POST /token |
401 { "code": 401, "message": "Invalid credentials." } en /token |
La API key es incorrecta, está revocada o ha caducado, o tu organización está suspendida (la misma respuesta en todos los casos) |
404 { "code": 404, "message": "Not found." } |
Un id que no existe o no es tuyo; Engine no dice cuál de las dos |
409 POSITION_ALREADY_COMPLETED |
Esa posición ya tiene una captura completada. Para medir otra vez, vuelve a inscribir |
202 con framesWithoutFeaturesMeta mayor que 0 |
Los frames sin featuresMeta no dan valence ni arousal |
202 con framesWithoutMediaTime igual al total del lote |
Normal si no envías mediaTimeMs (dónde estaba un reproductor de estímulo, opcional por frame). Es información, no un error |
202 en todos los lotes, pero los resultados siguen vacíos |
Un hueco en la numeración de los lotes, un Final que falta o una mecánica con más steps de los que enviaste |
Más en Límites declarados.