Ir al contenido
DevLab

Trampas conocidas

Las trampas de integración que hemos medido, por vía: el síntoma que ves, su causa y qué hacer. Generadas de una sola fuente.

En esta página
  1. En el dispositivo y el SDK
  2. Diferido (en servidor) · Preview
  3. API HTTP
  4. Cualquier vía

Lo que de verdad se han encontrado quienes integran, con el síntoma que ves primero. Tu agente de código recibe la misma lista en la skill (references/pitfalls.md). Avisa a Neurologyca si encuentras una nueva.

`npm install` responde 404 para `@neurologyca/*`

Síntoma. npm install falla con 404 Not Found (o 401) para @neurologyca/capture o @neurologyca/capture-server.

Causa. Los paquetes están en el registro privado de Neurologyca: sin el .npmrc del proyecto, o sin NODE_AUTH_TOKEN en el entorno, npm los busca en el registro público.

Qué hacer. Añade el .npmrc de la página de instalación (los starters lo traen) y exporta NODE_AUTH_TOKEN con el token del registro que te dio Neurologyca. No es tu API key: no los confundas.

Afecta a: todas las versiones publicadas del SDK.Más: Instalación

Measurement sin `taxonomy.contextId`

Síntoma. Crear el cliente con una configuración de Measurement lanza taxonomy.contextId is required, o buildTenantKit (admin.buildTenantKit) en tu backend rechaza Measurement con E_KIT_NO_CONTEXT y la inscripción que hiciste justo antes queda sin captura.

Causa. La configuración del SDK exige un id de contexto, y Measurement no se interpreta, así que su grupo no tiene contexto de interpretación. buildTenantKit de capture-server 0.19.0 y anteriores solo mira ese id y lanza; desde la 0.20.0 lee interpreted del catálogo de Engine y da a Measurement su propio kit (kind: 'measurement'), pero contra un Engine cuyo catálogo no publica interpreted sigue lanzando.

Qué hacer. Usa taxonomy: { contextId: 'measurement' } (un valor de relleno, MEASUREMENT_CONTEXT_ID en capture-server: desde 0.29.0 el SDK no lo envía cuando Engine dice que el protocolo no se interpreta) y pasa triggerAnalysis: false a la captura. El kit de Measurement de la consola lleva los dos en su neuro.config.json (Tu integración › Protocolos › un protocolo › Kit). En tu backend, usa capture-server 0.20.0 o posterior y ramifica por kit.kind: 'measurement' trae esa configuración y un aviso de capturar con triggerAnalysis: false. Resuelve el kit antes de admin.enrol, así un kit que falle no deja una inscripción huérfana. ProtocolSummary.interpreted (listProtocolLibrary) dice si un protocolo se interpreta. Si buildTenantKit sigue lanzando E_KIT_NO_CONTEXT con Measurement (un capture-server anterior, o un Engine sin interpreted), usa la configuración fija de arriba.

Afecta a: todas las versiones publicadas del SDK (contextId) · capture-server 0.19.0 y anteriores, o un Engine sin interpreted (buildTenantKit).Más: Solo medir · Tu backend

Una fuente `<video>` que no da frames o acaba antes el plan

Síntoma. Con { type: 'video', el } la captura no recibe frames, pierde el principio del fichero, o llega source.ended con steps pendientes y un step posterior falla. Desde la 0.43.0 una segunda captura sobre el mismo fichero puede fallar en el acto con CaptureStartError (stage: 'source', «the capture source has already ended…»).

Causa. El SDK espera los metadatos del vídeo, así que el src va antes de captureProtocol; solo hay frames mientras el vídeo se reproduce; y cuando el fichero acaba no se puede capturar ningún step más. Desde la 0.43.0 (kodec 5.0.0-rc.14), un <video> que ya acabó cuando empieza la captura falla antes de cargar ningún modelo.

Qué hacer. Pon el src antes de captureProtocol, deja el elemento muted y playsInline, y llama a play() en onStarted. Con varios steps sobre un fichero, pon loop mientras dura el plan; con source.ended y steps pendientes, llama a session.abort(). Si el elemento ya llegó al final, rebobínalo (currentTime = 0) antes de captureProtocol.

Afecta a: SDK >=0.27.0.Más: En el dispositivo (tiempo real)

La pestaña quedó oculta durante la captura

Síntoma. La serie tiene huecos reales y onWarning recibe capture.throttled. Ese aviso es relativo a la propia sesión: no es la señal de lo rápido que es el dispositivo.

Causa. Con la pestaña oculta o la ventana tapada, el navegador deja de procesar frames; el SDK solo avisa.

Qué hacer. Pide a la persona que deje la pestaña a la vista mientras captura y enseña el aviso.

Afecta a: todas las versiones publicadas del SDK.Más: Errores, avisos y reintentos · Cómo capturar para la máxima precisión

La cámara no se abre fuera de un contexto seguro

Síntoma. En un móvil u otra máquina de tu red la cámara no se abre nunca; classifyMediaError dice insecure-context.

Causa. Los navegadores solo dan la cámara a contextos seguros: HTTPS, o localhost en la misma máquina. Una dirección http:// de tu red no lo es.

Qué hacer. Sirve la página por HTTPS (un túnel a tu máquina de desarrollo o un certificado para tu red local) y traduce los errores de medios con classifyMediaError para decirle a la persona qué hacer.

Afecta a: todas las versiones publicadas del SDK.Más: En el dispositivo (tiempo real)

Funciona en local y falla en producción: la CSP

Síntoma. En producción la cámara no llega a estar lista, o se pierde la transcripción entera: codec.error con audio-start-failed, el aviso stt y transcription: null en el informe (workerBlockedByCsp no dice nada aquí: va dentro de transcription, que es null, y solo cubre el worker de voz).

Causa. Por defecto, Capture carga su motor de visión y sus modelos de CDN públicos, y su procesado de audio desde un blob:. Una Content Security Policy que no los permite los bloquea.

Qué hacer. Usa la política probada de la guía de CSP: 'wasm-unsafe-eval' y blob: en script-src, blob: en worker-src y los orígenes de los CDN en connect-src; o aloja tú los ficheros (kodec.* y transcribe.selfHost).

Afecta a: todas las versiones publicadas del SDK.Más: CSP y transcripción

El transcrito vuelve en inglés

Síntoma. El texto es fluido y bien puntuado, pero traducido al inglés; onWarning recibe stt.autodetect.

Causa. Con language: null el idioma se detecta del audio, lo que no es fiable con respuestas cortas: el modelo puede devolver una traducción sin ningún error.

Qué hacer. Fija el idioma con un código sin región: transcribe: { language: 'es' }. Sin language, el SDK usa el idioma de la página (<html lang>, y si no, el del navegador): una plantilla con <html lang="en"> transcribe en inglés sin ningún aviso, así que fíjalo.

Afecta a: todas las versiones publicadas del SDK.Más: CSP y transcripción

Levantar el veto de transcripción de forma automática

Síntoma. La transcripción no arranca (un aviso stt con blocker: 'video-cost-veto') o, tras levantarlo por código, el vídeo se sigue congelando en ese dispositivo.

Causa. El veto es una medida real: transcribir hizo demasiado lenta la cámara en ese dispositivo, o su latencia demasiado alta (reason: 'latency', con el vídeo intacto). forgetTranscriptionVeto la borra; llamarlo al arrancar o en un reintento convierte el veto en un bucle que pierde vídeo.

Qué hacer. Llama a forgetTranscriptionVeto(kodec) solo detrás de un botón que pulse la persona. Los indicadores se capturan igual.

Afecta a: todas las versiones publicadas del SDK.Más: CSP y transcripción · Errores, avisos y reintentos

Una opción que el SDK no tiene

Síntoma. createProtocolClient, captureProtocol, un step o createRecordingClient lanzan E_UNKNOWN_OPTION antes de tocar la cámara; tras subir a la 0.42.0, un cliente que antes se creaba ahora lanza al crearse.

Causa. El SDK rechaza cualquier opción que no conoce. Desde la 0.42.0 eso incluye createProtocolClient (y cada clave dentro de startup), que antes ignoraba en silencio una clave desconocida; una opción de cada captura (como signal o captureId) pasada al cliente también se rechaza, y el mensaje dice que va en captureProtocol.

Qué hacer. Toma los nombres de las opciones solo de la referencia, nunca de memoria ni de ejemplos antiguos, y quita de la configuración cualquier clave de más. triggerAnalysis, signal y captureId van por captura, en captureProtocol.

Afecta a: todas las versiones publicadas del SDK.Más: Errores, avisos y reintentos · Referencia del SDK

Preparaste, y la captura lo vuelve a descargar todo

Síntoma. prepare() resolvió ready, pero al pulsar Empezar la cara (y la voz) se cargan otra vez: las etapas del arranque dicen source: 'network', la espera es la misma y la página tiene los modelos dos veces.

Causa. Solo la siguiente captura del mismo cliente adopta lo que cargó prepare(). Un segundo cliente (uno creado en cada render o en cada componente, o uno para preparar y otro para capturar) no tiene nada que adoptar; prepareCapture() y level: 'cache' solo calientan la caché del navegador, y solo si la captura pide los mismos ficheros. Dos pestañas de tu app son dos páginas: cada una carga sus propios modelos, y solo comparten la caché del navegador.

Qué hacer. Crea un cliente por página y mantenlo toda la visita: prepara con él al montar la página, captura con él y llama a client.release() cuando la página o la vista se van. Con prepareCapture() en una página anterior, comparte el mismo objeto de configuración con la página de la captura. Con keepPrepared: true (0.43.0) usa ese mismo cliente en todas las capturas: cada una adopta lo que dejó la anterior, sin ningún prepare() entre medias, y llama a client.release() entre una persona y la siguiente en un dispositivo compartido. Sin la opción, la voz se libera tras cada sesión, así que prepara otra vez antes de la siguiente captura.

Afecta a: SDK 0.42.0 y posteriores.Más: En el dispositivo (tiempo real)

Con `keepPrepared`, la siguiente persona hereda el modelo de la cara

Síntoma. En un dispositivo que pasa de una persona a otra (un quiosco, una tableta compartida), las capturas siguen usando los mismos modelos cargados de una persona a la siguiente, sin prepare() ni descarga nueva.

Causa. Con keepPrepared: true el cliente guarda los modelos de una captura a la siguiente hasta client.release() o hasta que la página se va. Son modelos, no lo capturado, pero el modelo de la cara puede arrastrar estado del último frame de una captura a la siguiente.

Qué hacer. Llama a client.release() entre una persona y la siguiente, o no enciendas la opción donde un dispositivo sirve a varias personas.

Afecta a: SDK 0.43.0 y posteriores.Más: En el dispositivo (tiempo real) · Cargar los modelos

Sin WebGPU, preparar la voz entre capturas recarga la cara cada vez

Síntoma. Con keepPrepared, cada captura arranca tan despacio como la primera, y cada prepare() entre capturas da el aviso prepare.released con 'replaced'.

Causa. Donde se rechaza la transcripción (sin WebGPU y sin allowWasmWorker) el modelo de voz nunca se guarda, así que un prepare({ models: { face: true, speech: true } }) entre capturas pide algo que no está guardado: suelta la cara guardada y la vuelve a cargar.

Qué hacer. Prepara una vez antes de la primera captura y no prepares entre capturas, o pide solo la cara.

Afecta a: SDK 0.43.0 y posteriores.Más: Cargar los modelos · En el dispositivo (tiempo real)

La transcripción deja de funcionar tras la 0.42.0 con ONNX Runtime alojado por ti

Síntoma. Con transcribe.selfHost.wasmPaths como cadena, la captura sigue sin voz: el aviso stt con subStage: 'stt-runtime', reason: 'network' y, en cut, code: 'stt-runtime-missing' con la url que falta; en prepare(), partial con speech-error.

Causa. Desde la 0.42.0, wasmPaths como cadena es un prefijo que tiene que acabar en /: kodec lo pone delante del nombre del fichero y comprueba, con un HEAD, el par de ONNX Runtime del ejecutor en que corre (ort-wasm-simd-threaded.jspi.{mjs,wasm} en WebGPU con JSPI, ort-wasm-simd-threaded.{mjs,wasm} en WASM y en Safari e iOS). Un 404 o 410 de cualquiera de los dos para la voz en el acto. Un host que solo sirve el par Asyncify antes funcionaba y ahora falla así.

Qué hacer. Acaba el prefijo en / y sirve bajo él los dos pares de onnxruntime-web/dist/, o pasa wasmPaths como objeto, { wasm, mjs }, apuntando a los ficheros exactos (en Safari e iOS, la build simple).

Afecta a: SDK 0.42.0 y posteriores.Más: CSP y transcripción

Una webcam pasada como `stream` le dice a la persona que revise el vídeo

Síntoma. Abres tú la cámara y la pasas como stream; si no se ve ninguna cara a tiempo, el arranque falla y userMessage dice «No se ve ninguna cara en el vídeo…» en vez de pedir a la persona que se ponga frente a la cámara.

Causa. Desde la 0.42.1 el SDK elige el mensaje del primer frame por la fuente: first-frame.timeout solo con la webcam que abre él, first-frame.timeout-media con cualquier stream o <video> tuyo. No distingue una cámara en directo de un stream grabado.

Qué hacer. Sustituye first-frame.timeout-media en startup.messages por la frase de la webcam (o por tu propio texto), o deja que el SDK abra la cámara.

Afecta a: SDK 0.42.1 y posteriores.Más: En el dispositivo (tiempo real) · Errores, avisos y reintentos

Reintentar `/analyze` como regla general

Síntoma. Un manejador de reintentos vuelve a llamar a /analyze tras cualquier fallo de la interpretación, y los fallos se acumulan en vez de resolverse.

Causa. E_AXES_MISSING es el único caso en que reintentar es correcto: el análisis no llegó a generarse porque faltaba un eje (casi siempre frames sin featuresMeta de una fuente propia). Otros fallos, como una generación que se quedó sin tiempo, empeoran con más carga. Con el SDK 0.40.0 ese caso llega como E_TAXONOMY_REJECTED: Engine ya no manda el detalle por el que el SDK lo clasificaba.

Qué hacer. Decide por code, nunca con una regla común. Con E_AXES_MISSING (hoy, E_TAXONOMY_REJECTED con una fuente propia), corrige featuresMeta y pide la interpretación otra vez sin volver a capturar; los demás, no los reintentes en bucle.

Afecta a: todas las versiones publicadas del SDK.Más: Errores, avisos y reintentos

Avisos de duración que no pediste

Síntoma. Llegan step.duration-below-min o step.duration-above-max a onWarning aunque no cambiaste nada.

Causa. stepDurations vale 'warn' por defecto: un step duró fuera del mínimo o del máximo que declara el catálogo. Engine no impone las duraciones.

Qué hacer. Enséñalos o fíltralos por code en onWarning; usa stepDurations: 'enforce' para rechazar ese step (E_STEP_DURATION) u 'off' para apagar la comprobación.

Afecta a: todas las versiones publicadas del SDK.Más: Steps y marcado

Abortar después de `stop()` destruye una captura buena

Síntoma. Tras stop(), onError trae E_RESULTS_TIMEOUT o E_INTERPRETATION_TIMEOUT con recoverable: false, tu código llama a abort() y la captura se pierde.

Causa. Un recoverable distinto de true significa que la captura se perdió solo durante los steps. Tras stop(), Engine ya tiene la captura y la sigue procesando.

Qué hacer. Llama a abort() ante un error no recuperable solo mientras corren los steps. Tras stop(), guarda userProtocolId y protocolMechanicId fuera de la pestaña y lee los resultados más tarde (client.retrieveResults o tu backend).

Afecta a: todas las versiones publicadas del SDK.Más: Errores, avisos y reintentos

El cliente apunta directamente a Engine

Síntoma. Todas las peticiones responden 401 y onWarning recibe token.missing.

Causa. baseUrl es una dirección absoluta de otro origen y no hay getToken: ninguna petición lleva token.

Qué hacer. Apunta baseUrl al proxy de tu backend (por ejemplo /engine), que pone el token; pasa getToken solo si usas un proxy sin capture-server.

Afecta a: todas las versiones publicadas del SDK.Más: Tu backend · Proxy a mano

Un proxy hecho a mano al que le falta una ruta

Síntoma. Un 404 a mitad de captura, o en el baseline o la interpretación, mientras el resto funciona.

Causa. El SDK llama a 13 rutas, y algunas solo en algunos casos (baseline, cancelar, interpretación). Un proxy propio que no reenvía alguna responde 404.

Qué hacer. Reenvía exactamente las 13 rutas de la página del proxy, o usa createEngineProxy de capture-server, que lleva la lista.

Afecta a: todas las versiones publicadas del SDK.Más: Proxy a mano · Tu backend

`E_UPLOAD_FAILED` en una captura en vivo, leído como «sin reintentos»

Síntoma. Una captura en vivo termina con E_UPLOAD_FAILED enseguida, no tras los reintentos habituales; a menudo con un 413 de tu proxy.

Causa. E_UPLOAD_FAILED es un error del flujo en vivo (un lote parcial), no del diferido. Un 4xx (por ejemplo un 413 porque el lote supera el tope de cuerpo del proxy) es terminal al primer intento; solo un 5xx o un error de red se reintenta (3 intentos, 30 s).

Qué hacer. No lo leas como «sin reintentos» para reenviar a ciegas. Si es un 413, sube el tope de cuerpo de tu proxy (al menos 4,5 MB con el SDK 0.34.0 o posterior, al menos 10 MB antes); una función serverless solo vale si su tope llega a eso (una función de Vercel, 4,5 MB, sí; una API route del Pages Router de Next.js (pages/api), 1 MB por defecto, no hasta que lo subas); si no, corrige la credencial o el receptor y vuelve a capturar cuando el par esté libre.

Afecta a: todas las versiones publicadas del SDK.Más: En el dispositivo (tiempo real) · Errores, avisos y reintentos

El proxy detrás de un rewrite de Firebase Hosting (Cloud Run o Cloud Functions)

Síntoma. Con el proxy servido a través de Firebase Hosting, el flujo de eventos (/stream) o un /analyze largo se corta a los 60 s con un 504; o el proxy rechaza todas las peticiones con 403 porque tu authorize no encuentra la cookie de sesión.

Causa. Firebase Hosting tiene un tiempo máximo de 60 segundos por petición, también cuando reescribe a Cloud Run o Cloud Functions con uno mayor, y el proxy mantiene abierto el flujo de eventos durante toda la captura. Hosting además quita las cookies de las peticiones que reenvía: solo llega a tu app la que se llama __session.

Qué hacer. Deja /engine fuera del rewrite de Hosting, para que nada corte el flujo a los 60 s, y sirve la página y el proxy en el mismo origen desde el runtime de larga vida (Cloud Run en su dominio, o detrás de un balanceador). Las peticiones que no pasan por Hosting conservan sus cookies, así que ahí tu cookie de sesión puede mantener su nombre: __session solo importa para lo que siga pasando por Hosting. Lo mejor, el proxy en el origen de la página. Si tiene que vivir en otro origen, desde @neurologyca/capture 0.45.0 hacen falta dos mitades: credentials: 'include' en el cliente (createProtocolClient, createRecordingClient, y urlTokenProvider si tu endpoint de token está ahí) y cors: { origins: ['https://app.ejemplo.com'], credentials: true } en createEngineProxy (capture-server 0.20.1 o posterior, que además expone Retry-After); sin la del cliente, tu cookie de sesión no llega a authorize y el proxy responde 403. El navegador solo envía las cookies válidas para el host del proxy: en un subdominio del mismo sitio (la página en app.ejemplo.com, el proxy en api.ejemplo.com) dale a la cookie Domain=ejemplo.com (basta con SameSite=Lax); en otro sitio (por ejemplo, una dirección *.run.app) es una cookie de terceros (SameSite=None; Secure) que Safari bloquea por defecto, así que ahí sirve el proxy bajo tu propio dominio. Sin getToken detrás del proxy. Nunca te saltes la guarda: cors.origins admite orígenes exactos, nunca "*".

Afecta a: todas las versiones publicadas del SDK, con Firebase Hosting.Más: Proxy a mano · Tu backend

La consola se llena de mensajes de la librería de visión

Síntoma. Al arrancar la captura, la consola del navegador imprime líneas como INFO: Created TensorFlow Lite XNNPACK delegate for CPU, algunas como errores o avisos.

Causa. Vienen de MediaPipe (TensorFlow Lite), la librería de visión que carga el SDK. Escribe sus registros en la consola por el flujo de errores y el navegador los pinta en rojo. No son fallos de tu integración ni del SDK.

Qué hacer. Ignóralos. Decide que una captura falló por lo que informa el SDK (onError, onWarning y el CaptureOutcome), no por la consola. No ocultes esos mensajes con un filtro en el código de producción.

Afecta a: todas las versiones publicadas del SDK.Más: Errores, avisos y reintentos

Sin voz en un dispositivo sin WebGPU

Síntoma. En algunos móviles y ordenadores la captura mide la cara pero no transcribe nada: llega el aviso stt con blocker: 'no-webgpu' y la comprobación webgpu-adapter del diagnóstico del dispositivo (solo sale cuando se pide la voz) no pasa.

Causa. Transcribir en el dispositivo necesita un adaptador WebGPU utilizable (un navegador puede tener WebGPU y no ofrecer ninguno). Sin él, el SDK rechaza la transcripción salvo que pongas transcribe.allowWasmWorker: true, que deja al dispositivo probar el modelo de voz en WebAssembly, más despacio y solo en su propio Worker. La captura de los indicadores sigue igual.

Qué hacer. Si habrá voz solo se sabe al preparar la voz o al empezar a transcribir: una comprobación sin modelos no lo dice. Para saberlo antes de medir, pide la voz: sin adaptador WebGPU, prepare({ models: { speech: true } }) da webgpu-adapter fail y no descarga la voz (con él, descarga los modelos). Enseña cada aviso stt y sigue sin voz; o pon transcribe.allowWasmWorker: true y acepta que el texto llega más tarde y que la primera carga de los pesos puede cerrar la pestaña en un dispositivo con poca memoria (si una Content-Security-Policy bloquea los workers, por esa vía tampoco hay voz). Si necesitas la voz en todos los dispositivos, el diferido (Preview, si tu organización lo tiene activado) la transcribe en el servidor.

Afecta a: todas las versiones publicadas del SDK.Más: Dispositivos, calidad y modo · CSP y transcripción · En el dispositivo (tiempo real)

Las sesiones con el delegado de CPU pueden no compararse con las de GPU

Síntoma. SessionReport.captureQuality.delegate dice 'CPU' en unos dispositivos y 'GPU' en otros, y comparas sus sesiones como si fueran la misma medida.

Causa. La detección de la cara corre en la GPU (WebGL 2) y cae a la CPU cuando no se puede crear el delegado de GPU. Los dos delegados ejecutan los modelos con distinta precisión y distinto preprocesado de la imagen, así que los puntos de la cara no son idénticos entre uno y otro, y los resultados de sesiones con delegados distintos pueden no ser comparables. Lo que limita al dispositivo es esa detección en GPU, no la CPU: con solo la cara, el delegado de CPU no es necesariamente más lento.

Qué hacer. Guarda el delegate de cada sesión y compara sesiones con el mismo delegado. Comprueba que WebGL 2 funciona en los dispositivos a los que te diriges. No fijes kodec: { delegate: 'CPU' } salvo para diagnosticar un driver gráfico: fijar un delegado desactiva la caída, así que la captura falla en vez de degradarse.

Afecta a: todas las versiones publicadas del SDK.Más: Dispositivos, calidad y modo · En el dispositivo (tiempo real)

En iOS el micrófono mantiene su ganancia automática

Síntoma. En iPhone y iPad, los rasgos de la voz que dependen de la intensidad absoluta (energía, shimmer y la activación que sale de ellos) no cuadran con los de otros dispositivos, y la calidad de audio de kodec dice agc: 'unknown' y trust: false.

Causa. El SDK pide al micrófono autoGainControl: false, con la supresión de ruido y la cancelación de eco apagadas, para que la voz conserve su dinámica real. WebKit, que usan todos los navegadores de iOS, no implementa esa restricción: allí la ganancia automática no se puede apagar y el navegador no puede decir si está encendida ('unknown' no es «apagada»). El vídeo y los puntos de la cara no se ven afectados.

Qué hacer. No compares los rasgos de la voz basados en la intensidad entre iOS y otros dispositivos, ni entre sesiones con trust en false; guarda la plataforma con cada sesión. El navegador tampoco ve otras ganancias: los auriculares Bluetooth, las mejoras de micrófono de Windows o el aislamiento de voz de macOS e iOS.

Afecta a: todas las versiones publicadas del SDK.Más: Dispositivos, calidad y modo · En el dispositivo (tiempo real)

Ventanas privadas y almacenamiento bloqueado

Síntoma. En una ventana privada, o con el almacenamiento del sitio bloqueado: donde la voz correría en WebAssembly (sin WebGPU, o Safari e iOS) la transcripción se rechaza con blocker: 'no-memory-to-learn'; o, al grabar (diferido, Preview), llega el aviso recording.storage-memory.

Causa. Cuando el SDK no encuentra almacenamiento persistente (no distingue toda ventana privada: algunas guardan hasta cerrarse). En vivo, kodec no puede recordar lo que aprende en el dispositivo, como una configuración que cerró la pestaña, así que una carga que la mata se repetiría en cada sesión; ahí no arriesga la voz en WebAssembly (donde la voz corre en WebGPU sigue transcribiendo; no en Safari e iOS, donde corre en WebAssembly). Al grabar, no hay IndexedDB y la grabación vive solo en la memoria de la pestaña: si la pestaña se cierra antes de que acabe la subida, se pierde y no se puede reanudar.

Qué hacer. Pide una ventana normal cuando puedas. En vivo, sigue sin voz cuando se rechace. Al grabar con recording.storage-memory (y upload.not-persistent al empezar la subida), dile a la persona que no cierre la pestaña hasta que acabe la subida.

Afecta a: todas las versiones publicadas del SDK.Más: Dispositivos, calidad y modo · CSP y transcripción · Diferido (en servidor)

Las sesiones largas en un móvil se ralentizan al calentarse

Síntoma. El ritmo de una sesión en un móvil baja según avanza, y la misma configuración da menos ritmo cuanto más tiempo lleva el móvil capturando.

Causa. El ritmo lo marca la detección de la cara en la GPU (WebGL 2), y un móvil se ralentiza cuando se calienta. Los primeros segundos tras el arranque tampoco son representativos: los modelos aún se están calentando.

Qué hacer. Trata una sesión larga en un móvil modesto como degradada, no estable, y plantea allí sesiones más cortas. Lee el ritmo que entrega el códec en ese dispositivo y en ese momento (el evento capture-quality y captureQuality del SessionReport) en vez de suponerlo por el modelo, y deja fuera los primeros segundos al describirlo.

Afecta a: todas las versiones publicadas del SDK.Más: Dispositivos, calidad y modo

`minFps` no es el ritmo de la sesión

Síntoma. Lees captureQuality.minFps del SessionReport como el ritmo de la sesión, concluyes que el dispositivo no puede medir o comparas dispositivos por él.

Causa. minFps es la más baja de las ventanas de alrededor de un segundo que kodec mide en toda la sesión, arranque incluido (los modelos aún se están calentando) y cualquier momento con la pestaña oculta o la ventana tapada. La dispersión dentro de una sesión es mayor que casi cualquier diferencia que quieras leer en un solo número. 8 fps es el único suelo que publica el SDK. Por debajo, no estima el pulso (un canal opcional, apagado por defecto) y deja un veto de transcripción como provisional. No hay un umbral publicado de cómo afecta el ritmo a los indicadores: compara tus sesiones.

Qué hacer. Describe el ritmo con el evento capture-quality: la mediana de las ventanas tras el arranque, cuántas quedan bajo ese suelo y la más baja, sin la pestaña oculta (la página enlazada tiene el código). delegate es un dato para comparar y droppedTotal por encima de cero, un aviso aparte. Tampoco son el ritmo capture.throttled, relativo al ritmo de la propia sesión, ni quality.warning, de Engine.

Afecta a: todas las versiones publicadas del SDK.Más: Dispositivos, calidad y modo · En el dispositivo (tiempo real)

No decidas por el user-agent

Síntoma. Enciendes o apagas la voz, o eliges entre vivo y diferido, leyendo navigator.userAgent, y las versiones recientes de iOS pasan por otras más antiguas.

Causa. El user-agent no dice la versión de iOS: Safari en un iOS reciente se anuncia como una anterior y solo el token Version/ dice la real. Por eso el informe de arranque lleva uaVersionToken junto a userAgent. El SDK no decide nada por el user-agent: su diagnóstico del dispositivo comprueba capacidades (el contexto seguro, el acceso a la cámara, la ruta de captura, WebGPU, WASM SIMD, el almacenamiento persistente).

Qué hacer. Decide por capacidades: llama a prepare() antes de medir y lee PrepareResult.capture y sus comprobaciones device (la página enlazada tiene el código). Usa uaVersionToken, no el user-agent, solo para agrupar informes al analizarlos; con startup: { includeUserAgent: false } los dos salen null.

Afecta a: @neurologyca/capture 0.42.0 y posteriores.Más: Dispositivos, calidad y modo · Cargar los modelos

La transcripción ya no arranca en un navegador

Síntoma. La transcripción está encendida y el vídeo va bien, pero /results trae speech sin transcript en todas las capturas de ese navegador; onWarning recibe stt con blocker: 'video-cost-veto', fácil de perder si tu UI solo guarda el último aviso.

Causa. Una captura anterior midió el vídeo por debajo de 8 fps (normalmente con la pestaña oculta) y guardó en el navegador un veto provisional. Debería caducar en cuanto una captura mida más de 8 fps, pero hasta 0.40.0 la transcripción arranca justo tras el primer frame, antes de que se mida la cadencia, así que el veto se respeta siempre.

Qué hacer. Actualiza @neurologyca/capture a 0.41.0 o posterior (fija kodec 5.0.0-rc.3): la primera captura que da vídeo por encima de 8 fps borra el veto provisional y transcribe; solo esa captura espera, hasta unos 3 s. 0.40.1 ya transcribía, pero conservaba el veto y esperaba en cada captura. El veto borrado se informa una vez, en SessionReport.transcriptionSetup.provisionalVetoLifted. Una captura que se queda en 8 fps o menos (una pestaña oculta, o un fps de captura de 8 o menos) lo conserva: mantén la pestaña a la vista y enseña todos los avisos.

Resuelta en 0.40.1: actualiza a esa versión.Más: CSP y transcripción · Errores, avisos y reintentos

`createEngineAdmin` falla al cargarlo con `require()`

Síntoma. En un backend CommonJS (require('@neurologyca/capture-server'), o TypeScript compilado a CommonJS), cada llamada de administración que necesita un token de Engine falla con ReferenceError: return_nullishCoalesce is not defined.

Causa. De la 0.12.0 a la 0.17.0, la entrada CommonJS del paquete se generaba mal: la petición del token de createEngineAdmin (y de un createHttp usado directamente) llamaba a una función que no existe. La entrada de módulos ES (import) no estaba afectada.

Qué hacer. Actualiza tu backend a capture-server 0.17.1 o posterior. Sin cambios de código.

Resuelta en capture-server 0.17.1: actualiza a esa versión.Más: Instalación

Un `413` de un proxy en una función de Vercel (u otro host con tope de 4,5 MB)

Síntoma. Una captura en vivo termina con E_UPLOAD_FAILED en su primer lote, y el proxy, alojado en una función de Vercel o en un host parecido, responde 413.

Causa. Antes de 0.34.0 el SDK cortaba los lotes solo por número: hasta 300 frames, unos 9,3 MB con cámara. Eso supera el tope de cuerpo de una función de Vercel (4,5 MB) y el de una API route del Pages Router de Next.js (pages/api) por defecto (1 MB), y un 4xx termina la sesión al primer intento.

Qué hacer. Actualiza al SDK 0.34.0 o posterior: cada lote en vivo lleva como mucho 3 MB de frames, así que un proxy con un tope de cuerpo de al menos 4,5 MB lo admite. Esto no cubre una API route del Pages Router de Next.js (pages/api): su tope de 1 MB por defecto queda por debajo de un lote con cualquier versión del SDK, así que responde 413 hasta que subas su límite. Ese caso, y cómo leer el E_UPLOAD_FAILED, está en la trampa upload-failed-4xx-terminal (E_UPLOAD_FAILED leído como «sin reintentos»).

Resuelta en 0.34.0: actualiza a esa versión.Más: Proxy a mano · Tu backend

`createEngineProxy` responde `413 E_BODY_TOO_LARGE` con su límite por defecto

Síntoma. Una captura en vivo termina con E_UPLOAD_FAILED, y el proxy de tu backend respondió 413 E_BODY_TOO_LARGE a un POST /process-kpn-emo.

Causa. Hasta capture-server 0.11.0, createEngineProxy leía cuerpos de hasta 8 MiB por defecto (maxBodyBytes), y un SDK anterior a 0.34.0 envía lotes de hasta unos 9,3 MB con cámara.

Qué hacer. Actualiza tu backend a capture-server 0.12.0 o posterior (por defecto 16 MiB) y el SDK a 0.34.0 o posterior, o pasa un maxBodyBytes mayor. Una petición puede tener ahora ese cuerpo en memoria, así que limita la concurrencia de tu servidor.

Resuelta en capture-server 0.12.0: actualiza a esa versión.Más: Tu backend · Errores, avisos y reintentos

Con webpack (Next.js), `init()` falla antes de abrir la cámara

Síntoma. La build pasa con el aviso «Critical dependency: the request of a dependency is an expression» y, en ejecución, la captura falla antes de abrir la cámara con «Cannot find module» para el bundle de MediaPipe.

Causa. kodec 4.2.1, el que traía el SDK antes de 0.34.0, carga MediaPipe con un import() dinámico que webpack sustituía por un módulo vacío. Vite y Rollup lo dejan tal cual, así que no les afectaba.

Qué hacer. Actualiza @neurologyca/capture a 0.34.0 o posterior: fija kodec 4.2.2 o posterior (0.36.5 fija kodec 5.0.0-rc.2), cuyo import() lleva webpackIgnore. kodec no es una dependencia que instales tú. Turbopack no está probado.

Resuelta en kodec 4.2.2: actualiza a esa versión.Más: Instalación

Dos interpretaciones, y pagas las dos

Síntoma. Con el SDK en tiempo real y triggerAnalysis activo, la persona ve una interpretación en la página y POST /analyze desde tu backend devuelve otra, con from_cache: true.

Causa. El Final con triggerAnalysis hace que Engine genere y guarde una interpretación (la que avisa constellation.complete). Hasta el SDK 0.37, cuando stop() tenía los resultados y ese aviso aún no había llegado, el SDK abría además /analyze/stream, que siempre genera una nueva, no lee ninguna caché y no guarda nada. Dos generaciones del modelo de lenguaje, dos textos, las dos se cobraban. La válida es la guardada.

Qué hacer. Desde 0.38.0, stop() espera el aviso de Engine hasta analyzeTimeoutMs y, si no llega, llama una vez a POST /analyze, que sirve la guardada: una interpretación por sesión, el mismo texto que lee tu backend. Desde la 0.44.0, si ese /analyze responde 202 ANALYSIS_IN_PROGRESS, el SDK espera y vuelve a pedirla dentro de analyzeTimeoutMs contado desde el primer 202, y acaba con E_ANALYSIS_IN_PROGRESS si se agota. stop() puede tardar más (unos 13 minutos en el peor caso con los valores por defecto). SessionReport.interpretationSource dice de dónde salió; el aviso analysis.regenerated (from_cache: false) significa que /analyze tuvo que generarla. No pidas interpretation: 'stream' salvo que necesites progreso por fases: genera una que Engine no guarda. No llames tú además a /analyze/stream: cada llamada genera de nuevo.

Resuelta en 0.38.0: actualiza a esa versión.Más: HCIs y resultados · Los resultados en tu backend

Llamar a `/analyze` una y otra vez tras un trabajo diferido

Síntoma. Cada lectura de la interpretación de un trabajo diferido tarda decenas de segundos (hasta unos dos minutos) y cuesta, o vuelve distinta.

Causa. Con interpretation: 'ready', el análisis guardado sale de la caché. Con 'degraded' o 'failed' ninguna llamada lee el guardado: cada /analyze lo regenera (con sus tokens de LLM). Pedirlo antes del succeeded del trabajo también puede generar otro.

Qué hacer. Espera succeeded y lee su interpretation. Con ready, léela; con degraded o failed, pídela una vez si la necesitas, nunca en bucle. timeout no es un fallo: los indicadores están bien.

Afecta a: capture-server >=0.11.0.Más: Servicio de procesado

Tratar el aviso `interpreting` como un fallo

Síntoma. Con interimWebhook: true, los trabajos diferidos acaban en un timeout falso y sus vídeos no se borran nunca.

Causa. interpreting es un aviso, no un final: el trabajo sigue esperando la interpretación. Un onEvent que trata todo estado distinto de succeeded como fallo cierra el trabajo, y se deniega la renovación del token.

Qué hacer. Trata primero interpreting. Borra el vídeo en interpreting o en succeeded, lo que llegue antes; deja el trabajo abierto hasta succeeded y que un interpreting tardío no reabra nada. Actualiza el manejador antes de encender interimWebhook.

Afecta a: capture-server >=0.11.0.Más: Servicio de procesado

La subida está completa, pero el servicio de procesado no la recibe

Síntoma. Todos los bytes se suben, pero uploadRecording sigue reintentando complete (503 E_NOTIFY_FAILED, Retry-After: 30) durante minutos y luego rechaza con E_UPLOAD_NOT_NOTIFIED. Tu backend registra E_UNAUTHORIZED (o un error de red) de submit.

Causa. La grabación está guardada en tu backend; lo que falla es tu onComplete, que se la entrega al servicio de procesado: el servicio está caído, o no acepta tu key de servicio o el cliente dado de alta.

Qué hacer. No lo enseñes como una subida fallida: di que está subida y pendiente de entregar. Reintenta desde tu backend (receiver.pendingNotifications() y receiver.notify() cada minuto), registra el código del ProcessorError sin el cuerpo y revisa la key de servicio (E_UNAUTHORIZED es un error de configuración: reintentar no lo arregla).

Afecta a: capture 0.29.2 o posterior y capture-server 0.11.0 o posterior.Más: Diferido (en servidor) · Servicio de procesado

Cancelar desde la página con la subida ya completa

Síntoma. Con la subida completa, abandonUpload (un DELETE a tu receptor) responde 409 E_ALREADY_COMPLETE; tu página dice que la grabación se descartó, pero tu backend conserva el trabajo, lo sigue reintentando y aún puede procesarlo.

Causa. Una subida completa es de tu backend: su dueño solo puede abandonar una sin terminar.

Qué hacer. Dale a tu página su propia ruta de cancelar en tu backend (con la sesión del usuario y solo su captura): cierra el trabajo como cancelado, deja de dar tokens para él, borra el vídeo con receiver.remove() (lanza UploadBusyError mientras corre el onComplete de esa captura: reinténtalo después) y haz que onComplete salte una captura ya cerrada. Di «descartada» solo cuando tu backend lo confirme.

Afecta a: capture-server 0.11.0 o posterior.Más: Diferido (en servidor) · Servicio de procesado

Apuntar el servicio de procesado a localhost

Síntoma. Probando en tu máquina, los trabajos fallan con E_DESTINATION_NOT_ALLOWED, o el servicio nunca descarga el vídeo ni llama a tu webhook.

Causa. El servicio de procesado de Neurologyca solo llama a un origen https: público: rechaza http:, localhost, las direcciones privadas y de loopback, las redirecciones y las URLs con credenciales.

Qué hacer. Pon en PUBLIC_BASE_URL el origen HTTPS público de tu backend y construye con él la URL del vídeo, tokenUrl y webhookUrl. En tu máquina, abre un túnel HTTPS público (cloudflared o ngrok), pon su origen en PUBLIC_BASE_URL y ciérralo al terminar; o despliega. Después, retry de los trabajos fallidos: no es un reintento a ciegas.

Afecta a: El servicio de procesado de Neurologyca.Más: Servicio de procesado

Fiarse de la IP del servicio en vez de la firma

Síntoma. Tu URL del token o tu webhook se saltan la comprobación de la firma porque las tres rutas están limitadas a la IP de salida del servicio.

Causa. Esa IP es la misma para todas las organizaciones: otra puede hacer que el servicio llame a tus rutas desde ella. Limitar por IP es defensa en profundidad, no autenticación.

Qué hacer. Deja que createWebhookHandler y createProcessorTokenHandler verifiquen el HMAC con tu PROCESSOR_SECRET, y el receptor la firma de la URL del vídeo, limites por IP o no.

Afecta a: El servicio de procesado de Neurologyca.Más: Servicio de procesado

Mandar un trabajo sin sus parámetros

Síntoma. submit se rechaza con 400 E_BAD_REQUEST, o con 400 E_JOB_PARAMS_CONFLICT.

Causa. El servicio de Neurologyca tiene una credencial por organización para todos los protocolos, así que cada trabajo dice su contexto y su idioma: sin taxonomy.contextId o sin language responde E_BAD_REQUEST. Un procesador autoalojado cuyo cliente los fija rechaza otro valor con E_JOB_PARAMS_CONFLICT.

Qué hacer. Manda taxonomy (el taxonomy.contextId de la página), language (el de la sesión) y transcribeSteps en cada submit, con capture-server 0.13.0 o posterior. Con E_JOB_PARAMS_CONFLICT, manda los valores del cliente, o ninguno. No repitas la misma llamada.

Afecta a: capture-server >=0.13.0.Más: Servicio de procesado

El navegador no puede grabar MP4/H.264

Síntoma. La grabación se rechaza con E_RECORDER_UNSUPPORTED (classifyMediaError dice recorder-unsupported).

Causa. El modo diferido graba MP4 con vídeo H.264; algunos navegadores, como Firefox de escritorio, no pueden. Firefox no es objetivo: kodec no se ha probado allí.

Qué hacer. No hay reintento: ofrece otro navegador o el modo en el dispositivo.

Afecta a: todas las versiones publicadas del SDK.Más: Diferido (en servidor) · Errores, avisos y reintentos

Un `capture-server` más antiguo que el servicio que espera

Síntoma. Mientras un trabajo espera su interpretación, cada submit y getJob falla con E_PROCESSOR_PROTOCOL, y el móvil sigue reintentando complete contra un 503.

Causa. Un capture-server anterior a 0.11.0 no conoce el estado interpreting que el servicio de procesado comunica ahora, aunque interimWebhook esté apagado.

Qué hacer. Actualiza tu backend a capture-server 0.11.0 o posterior.

Resuelta en capture-server 0.11.0: actualiza a esa versión.Más: Servicio de procesado · Instalación

Grabar un `<video>` con un SDK anterior a 0.27.2

Síntoma. El servicio de procesado rechaza una grabación de un <video> o de un stream (E_MANIFEST_INVALID), o Engine tarda varias veces más en procesarla.

Causa. 0.27.0 cerraba el último step después del final del fichero grabado, y 0.27.0 y 0.27.1 grababan un <video> a la frecuencia de la pantalla en vez de a 30 fps.

Qué hacer. Usa 0.27.2 o posterior, y vuelve a grabar lo que se grabó de un <video> con 0.27.0 o 0.27.1.

Resuelta en 0.27.2: actualiza a esa versión.Más: Diferido (en servidor)

Sin interpretación por HTTP: falta `triggerAnalysis`

Síntoma. Todos los lotes responden 202 y llegan los indicadores, pero constellation.complete nunca llega.

Causa. Por HTTP, un triggerAnalysis omitido significa que no se pide interpretación; el SDK hace lo contrario.

Qué hacer. En un protocolo interpretado, envía triggerAnalysis: true en el Final del último step, o llama a POST /analyze cuando los resultados estén listos.

Afecta a: API.Más: Guía de la API HTTP · Límites declarados y modos de fallo

Un `Final` enviado justo después del lote anterior

Síntoma. El agregado del step no incluye los últimos lotes antes del Final.

Causa. Engine agrega el step cuando llega el Final, y el lote justo anterior puede seguir procesándose.

Qué hacer. Antes de cada Final, espera 2,5 s desde el lote anterior aceptado, como hace el SDK.

Afecta a: API.Más: Guía de la API HTTP

Lotes que rompen el contrato del step

Síntoma. Los lotes responden 202 pero la posición no se completa, o no se pide la interpretación, o el Final responde 400.

Causa. Cada step se numera por separado: kpnfile.order empieza en 1 en cada step, y cada step necesita su propio Final. triggerAnalysis solo cuenta en el Final del último step, y un lote necesita al menos un frame.

Qué hacer. Reinicia kpnfile.order en 1 en cada step, cierra cada step con un Final con frames, envía triggerAnalysis solo en el Final del último step y no pases de 300 frames o 3 MB de frames por lote como mucho, lo que llegue antes, como el SDK (en una mecánica de flujo libre, añade también ahí mechanicComplete: true).

Afecta a: API.Más: Guía de la API HTTP · Límites declarados y modos de fallo

Un `Final` con lotes que faltan

Síntoma. El Final de un step responde 400 con qualityCode: "KPN-EMO-MISSING-PACKETS" y una lista missingOrders.

Causa. No llegaron lotes anteriores de ese step. Ese Final no guardó nada.

Qué hacer. Reenvía los lotes de missingOrders y después vuelve a enviar el Final.

Afecta a: API.Más: Límites declarados y modos de fallo · Referencia de la API

Leer un `400` de lote sin su `qualityCode`

Síntoma. Un lote responde 400 y reintentarlo no cambia nada.

Causa. Cuando un lote rompe el contrato, el cuerpo dice por qué en qualityCode (KPN-EMO-…). Solo algunos motivos se arreglan reenviando.

Qué hacer. Decide por qualityCode con la tabla de Límites: corrige el step con KPN-EMO-STEP, reenvía con KPN-EMO-MISSING-PACKETS y no reintentes el resto.

Afecta a: API.Más: Límites declarados y modos de fallo

Esperar `results.ready` tras cada step

Síntoma. Tu código espera un results.ready tras cada step, o uno con un stepOrder concreto, y se queda colgado o lee antes de tiempo.

Causa. results.ready llega una vez por posición, cuando su captura está completa, y no en todos los casos: en una posición que pidió la interpretación normalmente no llega (llega constellation.complete), y en casos raros llega dos veces. Su stepOrder no siempre es el del último step.

Qué hacer. Tómalo como señal, no como la verdad: sigue sondeando GET /results/{userProtocolId}/{protocolMechanicId} como respaldo hasta que tenga datos, e ignora su stepOrder.

Afecta a: API.Más: Guía de la API HTTP · HCIs y resultados

Culpar a los `taxonomyWarnings` de un fallo

Síntoma. POST …/context responde 201 con taxonomyWarnings (UNKNOWN_CONTEXT, UNKNOWN_HCI) justo con los ids que te da tu kit.

Causa. Engine comprueba los ids contra su copia local de la taxonomía. En el Engine del entorno de pruebas esa copia se refresca al arrancar y cada 6 horas, así que un aviso justo después de un cambio de taxonomía puede ser esa espera. Esos avisos no detienen el análisis.

Qué hacer. Lee la lista y regístrala, pero lo que confirma que el contexto funciona es que POST /analyze responda. La causa de un 422 está en otra parte.

Afecta a: API.Más: Guía de la API HTTP

Filtros de bloquear o desbloquear enviados en el cuerpo

Síntoma. POST /users/block o /users/unblock actúa sobre todos los usuarios al alcance de la key en vez de sobre el que querías (antes del cambio de Engine del 2026-11-02 en el Engine de pruebas, que responde 400 a una llamada sin filtro o con cuerpo; el Engine de producción todavía lo hace).

Causa. Sus filtros (externalId, role, developer) se leen de la query. En el Engine de producción un cuerpo no se lee, y sin filtro la llamada se aplica a todos los usuarios a tu alcance; el Engine del entorno de pruebas responde 400 en su lugar, salvo que la llamada lleve all=true.

Qué hacer. Pon los filtros en la query (?externalId=…) y, en tu propio código, no envíes la llamada sin ninguno. Usa all=true solo a propósito, para actuar sobre todos los que alcanzas.

Afecta a: API.Más: Referencia de la API

Un proxy a mano que reenvía cualquier cosa, o deja pasar `reAnalyze`

Síntoma. El proxy funciona, pero una petición manipulada desde el navegador puede alcanzar rutas más allá de las 13 que el SDK necesita, o forzar una interpretación nueva.

Causa. El proxy es un pass-through con tu key de Engine en vez de una lista blanca. Todo lo que el navegador pueda enviar llega a Engine con tu key.

Qué hacer. Reenvía solo las 13 rutas y responde 404 a todo lo demás; quita reAnalyze de los cuerpos de /analyze y /analyze/stream para que una página no pueda forzar una reinterpretación de pago. createEngineProxy con ownsAll hace las dos cosas.

Afecta a: todas las versiones publicadas del SDK.Más: Proxy a mano · HCIs y resultados

La API key llegó al navegador

Síntoma. Tu key kop_… aparece en un bundle, en neuro.config.json, en una variable de entorno pública o en una petición que hace la página.

Causa. Quien tenga la key puede acuñar tokens para toda tu organización. La key es solo de tu backend.

Qué hacer. Deja la key en el entorno de tu backend (ENGINE_API_KEY, nunca en git). Con el SDK, el proxy de tu backend pone el token y la página crea el cliente sin getToken; por HTTP, tu backend acuña el token. Si la key se filtró, pide rotarla.

Afecta a: todas las versiones publicadas del SDK · API.Más: Tu backend · Proxy a mano

Un id de contexto que no sale de tu kit

Síntoma. POST …/context responde 201 (con taxonomyWarnings), la captura acaba bien y luego la interpretación se rechaza con un 422 (E_TAXONOMY_REJECTED en el SDK).

Causa. Engine no rechaza un id que no reconoce al fijar el contexto; la taxonomía queda fijada al capturar y solo la interpretación la comprueba.

Qué hacer. Toma el contexto, el subcontexto y las audiencias de tu kit (neuro.config.json y KIT.md), nunca los adivines. Si en KIT.md queda algo por resolver, pídeselo a Neurologyca antes de grabar a nadie.

Afecta a: todas las versiones publicadas del SDK · API.Más: Instalación · Protocolos y su jerarquía

La lectura está escrita para otra persona de la que la lee

Síntoma. POST /analyze responde 200 y la interpretación está completa, pero le habla a otro lector: una lectura escrita para la persona que enseñas a otra, o al revés. Sin audience, audience_applied llega null.

Causa. Sin audience (en la petición o en la persona), Engine aplica la lectura por defecto. Un contexto con varias audiencias puede tener una de por defecto, y no siempre es el lector que tienes en mente.

Qué hacer. Mira en KIT.md, en Audiencias, cuál va marcada como la de por defecto, si hay una. Si tu lector es otro, fíjala en la persona (POST /users, o después PATCH /users/{externalId}) o envíala en POST /analyze.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Tu kit

Pedir una interpretación a Measurement

Síntoma. Con Measurement, POST /analyze responde 409 con PROTOCOL_NOT_ANALYSED, o client.analyze() lo lanza, o tu página espera una interpretación que nunca llega.

Causa. Measurement no se interpreta nunca. Un triggerAnalysis omitido vale true en el SDK y false por HTTP. Desde el SDK 0.29.0 el SDK se salta el análisis solo cuando Engine devuelve interpreted: false (y avisa protocol.not-interpreted), pero no todo Engine devuelve aún ese campo.

Qué hacer. Pasa triggerAnalysis: false a captureProtocol con Measurement (el neuro.config.json del kit lo lleva para que tu código lo pase), no llames a /analyze para él y lee los indicadores con GET /results/{userProtocolId}/{protocolMechanicId}.

Afecta a: todas las versiones publicadas del SDK · API.Más: Solo medir · Errores, avisos y reintentos

Un baseline de otra persona o de otro origen

Síntoma. Los indicadores de una persona salen desplazados, aunque la captura fue bien.

Causa. El baseline es la expresión de reposo de una persona, y Engine lo aplica siempre que existe, aunque sea inválido. Un baseline capturado con otra persona o con otro origen (un vídeo de prueba, una muestra sintética) descuenta la expresión equivocada.

Qué hacer. Captura el baseline de la misma persona, con el mismo tipo de origen con el que vas a medir, con el externalId de esa persona. No reutilices una identidad de prueba para todos.

Afecta a: todas las versiones publicadas del SDK · API.Más: Baseline

El baseline no está justo después de su Final

Síntoma. Justo después de aceptarse el último lote del baseline, GET /users/{externalId}/baseline responde 404 (o getBaselineInfo devuelve null).

Causa. Engine calcula el baseline en segundo plano tras el Final; tarda unos segundos. Para una persona sin ninguna captura previa, un 404 antes de eso es la respuesta esperada: aún no hay baseline. La consola del navegador lo pinta como un error en rojo; no lo es.

Qué hacer. Reléelo varias veces, con unos segundos entre lecturas, antes de dar por fallida la captura. Mira missingOrders en el último 202: si faltan lotes, no se calcula ningún baseline.

Afecta a: todas las versiones publicadas del SDK · API.Más: Baseline

Esperar la interpretación nada más acabar la captura

Síntoma. Los indicadores están pero la interpretación no; un timeout HTTP corto corta un /analyze bloqueante (504), o el SDK acaba con E_INTERPRETATION_TIMEOUT.

Causa. La interpretación se genera cuando la posición se completa y tarda de decenas de segundos hasta unos dos minutos (constellation.complete se midió unos 82 s después del primer lote).

Qué hacer. Enseña antes los indicadores y la interpretación cuando llegue. Espera constellation.complete y llama después a POST /analyze; si lo llamas bloqueante, dale un timeout largo. No abortes la captura por E_INTERPRETATION_TIMEOUT: pide la interpretación otra vez más tarde.

Afecta a: todas las versiones publicadas del SDK · API.Más: Timeouts · Timeouts · Límites declarados y modos de fallo

Leer un `202` de `/analyze` como «sin interpretación»

Síntoma. POST /analyze responde 202 con ANALYSIS_IN_PROGRESS y sin interpretación, y tu app enseña «sin interpretación»: por HTTP, o porque client.analyze() en la página o admin.analyze en tu backend devuelven interpretation: null; con un SDK anterior a la 0.44.0, la captura además acababa con E_INTERPRETATION_TIMEOUT.

Causa. Engine aún está analizando esa sesión (el análisis que lanza tras la captura, o un reAnalyze) y no arranca otro. Desde @neurologyca/capture 0.44.0 y capture-server 0.20.0 el SDK lo dice: client.analyze() y admin.analyze devuelven inProgress: true y retryAfterMs junto a interpretation: null, y al cerrar una captura el SDK espera y vuelve a pedirla (analysis.in-progress), y acaba con E_ANALYSIS_IN_PROGRESS (recuperable) si se agota la espera. El código que solo lee interpretation, un SDK anterior o un cliente de la API HTTP lo siguen confundiendo con «sin interpretación».

Qué hacer. Un 202 cuenta como «interpretando», nunca como «sin interpretación». Con el SDK, mira inProgress antes de dar por definitivo un interpretation: null, espera retryAfterMs (unos 30 s si es null) y vuelve a pedirla unas pocas veces como mucho; tras E_ANALYSIS_IN_PROGRESS, enseña los resultados y lee la interpretación más tarde. Por HTTP, mira reason === 'ANALYSIS_IN_PROGRESS' y espera retryAfterSeconds (también la cabecera Retry-After). Si sigue en curso, enséñala como «interpretando» y pídela más tarde, o espera constellation.complete en el stream. El patrón, para la página y para tu backend, es askInterpretation en Errores (El 202 de la interpretación).

Afecta a: todas las versiones publicadas del SDK (antes de la 0.44.0 el SDK no lo distingue; desde la 0.44.0, el código que ignora inProgress) · API.Más: HCIs y resultados · Errores, avisos y reintentos · Límites declarados y modos de fallo

Enseñar como resultado una interpretación fallida

Síntoma. La persona ve una interpretación genérica o vacía, aunque /analyze respondió 200.

Causa. Una interpretación con metadata.status: "failed" es un marcador (el SDK da E_ANALYSIS_FAILED); con "degraded" se hizo con datos parciales (el SDK avisa analysis.degraded). El porqué está en los warnings de la raíz de la respuesta.

Qué hacer. No enseñes nunca una interpretación failed; enseña los indicadores, que siguen valiendo. Una degraded, enséñala con un aviso.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Errores, avisos y reintentos

Dar por ausente Effective Active Attention en la primera lectura tras el Final

Síntoma. session.effective_active_attention vuelve null en la lectura de /results justo tras el Final, aunque la sesión se midió y tu contexto lo incluye.

Causa. Engine puede estar calculando todavía el valor de la sesión cuando los resultados por frame y por step ya están (visto en el Engine de pruebas, por la vía del SDK). Es Preview.

Qué hacer. No lo des por ausente en la primera lectura: vuelve a leer /results un poco después y enséñalo cuando llegue v; null definitivo es que no se midió o que no está en tu contexto.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Mostrar y aprovechar los resultados

Leer la interpretación por título o por `insight`

Síntoma. Tu página enseña un resumen vacío o confunde dos secciones de la interpretación.

Causa. structured_data.insight puede llegar null, y los títulos de las secciones se escriben para la audiencia y pueden repetirse. structured_data.headline también puede faltar (por diseño en las interpretaciones de selección).

Qué hacer. Si insight es null, enseña structured_data.headline. Si headline también falta, enseña la primera entrada de sections[], y mira metadata.status. Identifica las secciones por sections[].key, nunca por title.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados

Un subcontexto mal escrito cae al de por defecto sin error

Síntoma. La interpretación no sigue el subcontexto que fijaste y nada dio error.

Causa. El subcontexto es opcional: sin él, Engine aplica el de la mecánica (constellationSubcontextId) o, si la mecánica no declara ninguno, el de por defecto del contexto; un subcontextId que no conoce cae a ese de por defecto en silencio.

Qué hacer. Mejor omitirlo que adivinarlo. Si lo fijas, tómalo de tu kit y compruébalo contra taxonomy.subcontexts de GET /catalog/contexts.

Afecta a: todas las versiones publicadas del SDK · API.Más: Protocolos y su jerarquía · Guía de la API HTTP

Una etiqueta de audiencia que Engine no conoce

Síntoma. La interpretación no encaja con la audiencia que pediste y no hubo error.

Causa. Engine no valida la etiqueta de audiencia: una desconocida se acepta sin error.

Qué hacer. Usa solo las audiencias que tu kit lista para el contexto del protocolo (KIT.md, Audiencias); nunca compongas la etiqueta a partir de texto libre.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Guía de la API HTTP

Una sola audiencia para todas las personas y todos los contextos

Síntoma. Tu app fija la misma audiencia en todas las personas (por ejemplo, desde un ajuste de entorno), y las lecturas de algunos contextos salen para un lector para el que no se escribieron, o audience_applied no es la que fijaste.

Causa. Una audiencia es de un contexto: cada contexto tiene su lista (algunos ninguna, y una puede ser la de por defecto), y una etiqueta solo significa algo en su contexto. Vive en la persona (POST /users, PATCH /users/{externalId}) o en cada POST /analyze, y la de la persona vale para todos los contextos en que se la mide. Engine no la valida: una que el contexto no tiene cae en la lectura por defecto sin error.

Qué hacer. Elige la audiencia por protocolo, solo entre las que KIT.md lista para él (Audiencias); déjala vacía para la lectura por defecto del contexto. Si a una persona se la mide en contextos con audiencias distintas, fija la suya antes de cada captura (PATCH /users/{externalId}, admin.updateUser), como hace el playground, o vuelve a leer desde tu backend con admin.analyze(pair, { audience }); y compara audience_applied con la que querías.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Tu kit

Comparar interpretaciones que salieron de la caché, o forzarlas en bucle

Síntoma. Volver a pedir POST /analyze devuelve exactamente la misma interpretación, aunque algo haya cambiado; o la factura crece con cada lectura.

Causa. Engine guarda una interpretación por sesión y audiencia y la devuelve con from_cache: true. reAnalyze: true se salta eso y genera una nueva, que se paga cada vez.

Qué hacer. Mira from_cache antes de comparar dos lecturas. Para una nueva, envía reAnalyze: true (con ese nombre exacto) desde tu backend por una decisión deliberada, nunca en bucle ni en cada lectura; la siguiente petición normal devuelve la nueva.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Proxy a mano

Reconectar el stream con el mismo token tras un cambio de credencial

Síntoma. El stream de eventos se cierra con stream.end y un reason que empieza por credential_, y reconectar con el mismo token falla.

Causa. La credencial que acuñó el token se rotó, se revocó, se borró, caducó o cambió de alcance: ese token ya no se acepta.

Qué hacer. Acuña un token nuevo con una key válida (la nueva tras una rotación; la misma tras un cambio de alcance) y reconecta. Con una key revocada, borrada o caducada, consigue antes una válida.

Afecta a: todas las versiones publicadas del SDK · API.Más: Autenticación

Toda interpretación se rechaza para tu organización

Síntoma. Las capturas y los indicadores van bien, pero toda interpretación responde 422. Hoy el cuerpo solo trae code y un message genérico, y el SDK lo da como E_TAXONOMY_REJECTED (E_TENANT_UNKNOWN no se emite con el SDK 0.40.0).

Causa. Tu organización aún no está activa en el servicio de interpretación. No es tu captura ni tu taxonomía, pero la respuesta ya no distingue los dos casos.

Qué hacer. No vuelvas a capturar: los indicadores están guardados. Compara los ids de la taxonomía con los del protocolo; si coinciden y falla toda interpretación, avisa a Neurologyca y, cuando esté resuelto, pide de nuevo la interpretación sobre el mismo par.

Afecta a: todas las versiones publicadas del SDK · API.Más: Errores, avisos y reintentos · HCIs y resultados

Transcribir en un idioma que la persona no habla

Síntoma. En el dispositivo, los steps de voz llegan a Engine sin texto o con muy poco (solo el aviso stt.silent, si no queda ninguna locución), o con un texto fluido traducido al idioma declarado y sin ningún aviso. En diferido, el transcrito llega con la etiqueta del idioma que pediste (speech.language) sea cual sea el idioma hablado, y su texto no es fiable.

Causa. El idioma se declara, nunca se detecta: en el dispositivo kodec, y en diferido el servicio de procesado, obligan al modelo a usarlo. Si se habla otro, el modelo o bien traduce al declarado, con fluidez y buena confianza, así que nada lo filtra, o bien se repite o puntúa bajo, y en el dispositivo kodec descarta a propósito esas locuciones (low-confidence, repetition-loop). Depende del par de idiomas: en una prueba, inglés declarado sobre voz en español volvió traducido; español declarado sobre voz en inglés se descartó casi todo. Fijar el idioma equivocado es peor que no fijarlo. Por defecto (<html lang>, y si no, el del navegador) es el idioma de la página, que no siempre es el de la persona. El playground lo hace explícito: su mando «Idioma hablado» es el idioma que se habla en la sesión, y el Vídeo de muestra queda fijo en inglés porque es lo que dice.

Qué hacer. Declara, en cada captura, el idioma en el que hablará la persona: transcribe: { language } en el dispositivo, el language del trabajo en diferido. Formas de acertar: guárdalo con la persona o la entrevista en tu backend (el idioma en el que responde el candidato, por ejemplo) y pásalo a cada captura; si no lo sabes, pregúntalo antes de capturar, en la pantalla del consentimiento; un idioma por captura (quien cambia de idioma a mitad se transcribe en el declarado: divídelo en capturas). Para detectarlo después, lee SessionReport.transcription (onReport): vad.utterances por encima de 0 con pocos o ningún emitted y discardedLowConfidence o discardedRepetitionLoop altos apuntan al idioma equivocado (sin ninguno emitido, el SDK avisa stt.silent); ofrece repetir la captura en el correcto. Una traducción pasa todos los contadores: solo declarar el idioma correcto la evita. No pases a language: null para esquivarlo: en una prueba, la autodetección también tradujo al inglés las respuestas más largas en español. El idioma de la interpretación va aparte: narrative.language en la persona. En el playground, elige «Idioma» según lo que se hable (con la cámara empieza en el idioma de la página).

Afecta a: todas las versiones publicadas del SDK.Más: CSP y transcripción · Diferido (en servidor)

Un step con varias preguntas y ninguna declarada

Síntoma. La interpretación no menciona la pregunta que respondió la persona: metadata.missing_inputs incluye question_text y el status no es degraded, así que nada parece fallar. Con el SDK, onWarning recibe step.media-undeclared. En /results, el mismo questionText en varios steps de speech (solo en el Engine del entorno de pruebas) es el mismo síntoma: la pregunta no se eligió por step.

Causa. El step ofrece varias medias (preguntas alternativas) y la captura no dijo cuál vio la persona: sin mediaPid en start() o run() (SDK), sin mediaId en los lotes del step (API HTTP). text de describeStep(step) es solo el primer texto que casa con el idioma, así que tomarlo es adivinar. Por HTTP, Engine no comprueba que el mediaId sea del step, así que una media de otro step pasa sin error. El aviso del SDK no salta en steps con fases, porque ahí las medias de texto son las pautas de cada fase, no preguntas alternativas (no hay nada que elegir). Un mediaPid que no es del step lanza E_MEDIA_UNKNOWN.

Qué hacer. En cada step con más de una pregunta, enseña una y declárala: elígela de describeStep(step).texts (cada entrada trae su mediaPid y su body) o de plan.steps[].media, y pásala como mediaPid (SDK) o como mediaId en todos los lotes del step (HTTP). No repitas la misma pregunta en varios steps de un protocolo. El kit y los starters guardan esta elección en neuro.config.json (media, por step), con un valor por defecto; el mando «Preguntas» del playground deja elegir antes de medir.

Afecta a: todas las versiones publicadas del SDK · API.Más: Steps y marcado · Errores, avisos y reintentos

Un step de pregunta enseñado como step de respuesta

Síntoma. Tu página marca como «responde ahora» el step que hace la pregunta (o abre ahí el tiempo de respuesta), así que la persona responde antes de leer u oír la pregunta; o el step de respuesta enseña su propia línea y la pregunta desaparece de la pantalla.

Causa. El papel del step se dedujo del nombre de su tipo, de responseClock o de que no tuviera reloj. Lo dice el catálogo: un step de respuesta es category: 'answer' o expectsSpeech: 'yes'. Con el SDK, describeStep (StepFacts) da expectsSpeech pero hoy no category ni delivery.media_from: están en el step del plan (PlanStep).

Qué hacer. Lee category, expectsSpeech y delivery.media_from de los steps del plan (session.plan.steps con el SDK). Cada step enseña su media; sin ella, la pregunta del step anterior (media_from: 'previous_step') o el texto del siguiente ('next_step', un step de lectura en silencio: no declara mediaPid). Un step de respuesta mantiene en pantalla la pregunta anterior, con su propia media como la línea de debajo. Nunca enseñes delivery.instructions ni delivery.prompt.

Afecta a: todas las versiones publicadas del SDK · API.Más: Steps y marcado

La pregunta de `speech` vuelve en otro idioma, o no vuelve

Síntoma. En /results, speech da el questionText de un step en un idioma distinto del que se mostró o se habló, o no da questionText, aunque transcript sí esté.

Causa. Engine escribe questionText en el idioma de la narrativa de la persona (narrative.language), no en el que se mostró ni en el que se habló. Una persona creada sin ese idioma no recibe questionText.

Qué hacer. Fija narrative: { language } al crear a la persona (createUser/updateUser), el idioma en que quieres leer. Para enseñar la pregunta tal como salió en pantalla, guarda el mediaPid que elegiste y lee su body. Relacionadas: «La interpretación vuelve en el idioma equivocado», «El transcrito vuelve en inglés» y «Transcribir en un idioma que la persona no habla».

Afecta a: API · todas las versiones publicadas del SDK.Más: HCIs y resultados · Tu backend

Unir los `transcript` de cada step para tener el texto entero

Síntoma. Unir los transcript de speech da menos de lo que dijo la persona: faltan palabras del principio o del final, o un step no tiene ninguno.

Causa. transcript es lo dicho que tu app situó en ese step (sttByStep). El SDK reparte la voz por los límites de los steps; lo dicho fuera de un step (antes del primero, entre dos, después del último) no tiene step y no aparece.

Qué hacer. Lee speech por step, para lo dicho en cada uno. Para el texto entero, guárdalo en el dispositivo según llega, con onTranscript en la captura, o guarda el speech.text que tu backend mandó en el Final.

Afecta a: API · todas las versiones publicadas del SDK.Más: HCIs y resultados · Guía de la API HTTP

Buscar en `/results` los indicadores que necesitan sesiones previas

Síntoma. Mental Fatigue Load, Facial Muscle Tension, Disengagement o Emotional Mental Control nunca aparecen en /results, ni siquiera tras varias sesiones de la misma persona.

Causa. Estos cuatro necesitan el historial de la persona: 5 sesiones previas completadas en el mismo contexto (el baseline no cuenta), así que tienen valor desde la 6.ª; Facial Muscle Tension, desde la 1.ª si el contexto tiene datos de calibración de Neurologyca. Aun así, Engine solo los usa dentro de la interpretación (/analyze): ninguna ruta devuelve su valor, y aún no están en la producción de Engine.

Qué hacer. No los esperes en /results ni construyas sobre sus valores. Mantén la misma persona (externalId) y el mismo contexto entre sesiones para que la interpretación pueda usarlos, y lee los indicadores por frame que sí llegan.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados

Attention pintada en un eje de 0 a 100

Síntoma. La barra o la línea de Attention queda plana abajo en un gráfico compartido con los demás indicadores, o una media como 0.83 se enseña como «0,83» o «1 %».

Causa. Attention no está en la escala de 0 a 100: vale 0 o 1 por frame, y su media en /results es la fracción de frames con atención, de 0 a 1. Los demás indicadores van de 0 a 100, salvo Valence y Motivation, de −100 a 100.

Qué hacer. Pinta Attention por frame como una banda de sí/no, no en el eje de 0 a 100, y enseña su media como porcentaje de frames (× 100: «83 % de los frames con atención»). Effective Active Attention (session.effective_active_attention.v, Preview) ya es un porcentaje de 0 a 100: no lo multipliques.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Mostrar y aprovechar los resultados

Un indicador que llega en el ejemplo y no en tu captura

Síntoma. Un indicador que ves en el ejemplo grabado del playground, en esta documentación o en otro protocolo falta en tus rawResults y aggResults, session llega en null o un Relevante de la interpretación no está en tu /results; la captura acaba con normalidad.

Causa. Qué indicadores recibes depende del contexto y del acuerdo de tu organización. Todo contexto interpretado incluye los que su interpretación necesita; el resto del catálogo público llega bajo acuerdo, y la lista puede cambiar con él. Los ejemplos grabados llevan todo el catálogo público. No es el caso de los cuatro que necesitan sesiones previas, que no llegan en /results para nadie.

Qué hacer. Mira los indicadores de cada protocolo en Tu integración › Protocolos («Indicadores que recibes en este contexto»); cuando tu contexto no los incluye todos, Resultados del playground dice cuántos (tras una sesión). Trata como opcional todo indicador: una clave que falta no se ha recibido, nunca es un cero. Para recibir más, pídeselo a Neurologyca.

Afecta a: todas las versiones publicadas del SDK · API.Más: HCIs y resultados · Tu cuenta de DevLab

La interpretación vuelve en el idioma equivocado

Síntoma. El transcrito está en el idioma correcto (fijaste transcribe: { language }), pero la interpretación que devuelve Engine sale en inglés para una captura en español.

Causa. El idioma de la interpretación se fija en la persona, con narrative.language (default en), no con transcribe.language (eso es el transcrito) ni en /analyze (que no lleva idioma). El backend del SDK envía narrativeLanguage: 'en' si no fijas narrative.language.

Qué hacer. Crea o actualiza la persona con narrative: { language } (createUser/updateUser) y vuelve a pedir la interpretación. /analyze/stream recalcula siempre; /analyze necesita reAnalyze: true desde tu backend.

Afecta a: todas las versiones publicadas del SDK.Más: Tu backend · HCIs y resultados