En el dispositivo (tiempo real)
El cliente en vivo: créalo sin token, captura step a step y lee el resultado, los avisos, el baseline, la transcripción y el flujo de eventos.
Se procesa en el navegador mientras capturas. Pruébalo en el playground: allí es la vía por defecto.
El modo, de un vistazo
Sección titulada «El modo, de un vistazo»| Tema | En el dispositivo (tiempo real) · Preview 0.45 |
|---|---|
| Hoy | Disponible. |
| Dónde se procesa | En el navegador, en el dispositivo de la persona, mientras captura. |
| Cuándo hay resultados | Durante la sesión y segundos después del último lote en una captura corta. Una captura larga, con miles de frames, tarda minutos. Pasado outcomeDeadlineMs (240 s por defecto), stop() da E_RESULTS_TIMEOUT, que no es una pérdida: lee los resultados después. |
| Qué sale del dispositivo | Landmarks, coeficientes de expresión y pose, hacia Engine. Solo si los activas: el transcrito (el reconocimiento de voz corre en el navegador, así que el audio se queda y el texto sale; Engine lo pasa a un LLM para la interpretación) y las señales extra (la voz como números, el pulso, las manos, el cuerpo). Nunca imagen, vídeo ni audio. |
| Qué te limita | El dispositivo: la detección de la cara en la GPU (WebGL 2) y, en móvil, el calor en sesiones largas, que bajan los fps. Un móvil o un portátil reciente suele quedarse cerca de los fps de la cámara; un móvil de gama de entrada captura menos frames por segundo, y un móvil los pierde según se calienta. |
| Navegadores y móvil | Chrome y Edge 94+, Safari 16.4+ (iOS 16.4+), en escritorio y en móviles capaces. |
| Measurement | Sí. |
| Casos típicos | Un check-in corto en un portátil; una tarea de dos minutos en un móvil reciente; cualquier captura cuyo vídeo no deba salir del dispositivo. |
| Pasar de uno a otro | createProtocolClient (de @neurologyca/capture) ↔ createRecordingClient (de @neurologyca/capture/record, sin kodec). Algunas opciones no pasan: transcribe es solo del vivo; en diferido transcribe el servicio de procesado. |
Crea el cliente
Sección titulada «Crea el cliente»Un cliente por contexto de protocolo. Tu página habla con el proxy de tu backend: sin getToken, sin key, sin token en la página (Tu backend).
import { createProtocolClient, defineTenantConfig } from '@neurologyca/capture'import kit from './neuro.config.json' // la configuración de tu contexto, de tu kit
const client = createProtocolClient({ baseUrl: '/engine', // tu proxy tenant: defineTenantConfig(kit), onStatus: (s) => ui.status(s.status), onResult: (r) => ui.result(r), // r.raw es todo el cuerpo de GET /results onWarning: (w) => ui.warning(w.code, w.message), onError: (e) => ui.error(e.code, e.recoverable),})Captura
Sección titulada «Captura»Recoge el consentimiento antes de captureProtocol, y llámalo solo desde un gesto de la persona (un clic): abre la cámara.
import { describeStep } from '@neurologyca/capture'
const session = await client.captureProtocol({ userProtocolId, protocolMechanicId, source: { type: 'webcam' } })for (const step of session.plan.steps) { const facts = describeStep(step, { lang: 'es' }) ui.step(step.order, facts.text?.value ?? null) await session.step(step.order).run({ durationMs: (facts.maxSeconds ?? 30) * 1000, mediaPid: facts.text?.mediaPid ?? null })}const outcome = await session.stop()Este bucle enseña facts.text, la media del propio step. Un step puede no llevar texto propio (una respuesta que mantiene la pregunta anterior, o una lectura que toma el del step siguiente): para elegir qué enseñar en cada step, usa stepPrompt de el mismo bucle, en vivo y grabado.
Con un fichero corto, source.ended llega por onWarning antes de acabar el plan y un run() posterior falla: trátalo llamando a session.abort(), o termina el bucle tras el aviso.
La interpretación se pide por defecto: captureProtocol la pide salvo que pases triggerAnalysis: false. Recíbela con onInterpretation (la narrativa, con structured y metadata) y onInterpretationDetails (el mismo detalle estructurado, justo después), ambas opciones de createProtocolClient.
Engine genera la interpretación una vez y la guarda, y stop() la espera (desde 0.38.0): escucha el aviso de Engine en el flujo de eventos hasta analyzeTimeoutMs (280 s por defecto; 120 s si el flujo nunca conectó) y, si el aviso no llega, lee la guardada con un solo POST /analyze. Así que stop() puede tardar minutos: unos 13 en el peor caso con los valores por defecto (Timeouts). Enseña los indicadores mientras espera. Si quieres progreso por fases, pasa interpretation: 'stream' a captureProtocol y onProgress al cliente: onProgress({ phase, route }) recibe las fases de /analyze/stream, que hace una generación que Engine no guarda, así que tu backend no leerá después ese mismo texto. interpretation: 'stream' es por captura: el cliente la rechaza, y también una captura con triggerAnalysis: false o en modo grabación; con un token de captura no produce interpretación.
El par (userProtocolId, protocolMechanicId) viene de tu backend, que inscribió a la persona. Quién cierra cada step (un tope, un botón, el final de un vídeo) y cómo funciona el reloj: Steps y marcado.
Un <video> también sirve de fuente ({ type: 'video', el }): dale su src antes de llamar a captureProtocol (el SDK espera a sus metadatos), mantenlo muted y playsInline, y reprodúcelo en onStarted. Cuando el fichero acaba, el SDK avisa source.ended una vez: un step conducido con run() se cierra en ese instante con los frames que tenía, y con start() y end() llamas tú a end(). Ya no se puede capturar ningún step posterior, así que llama a session.abort(). Con varios steps sobre un mismo fichero, pon loop en el vídeo mientras corre el plan. session.abort() cancela cualquier captura.
La pantalla de arranque
Sección titulada «La pantalla de arranque»Entre el clic de la persona y el primer step están las lecturas de Engine, el permiso de la cámara, el modelo de la cara (unos 13,5 MB la primera vez) y, con transcripción, el modelo de voz (unos 160 MB: 136 MB de pesos, más el motor y la librería). En una red móvil lenta son minutos. Desde la 0.42.0 el SDK pone tope a lo que no depende de la persona, te deja cancelar y te cuenta cada etapa con un mensaje listo para enseñar; no pinta nada.
import { createProtocolClient, defineTenantConfig, CaptureAbortedError, CaptureStartError } from '@neurologyca/capture'import kit from './neuro.config.json'
const client = createProtocolClient({ baseUrl: '/engine', tenant: defineTenantConfig(kit), startup: { timeouts: { speech: { totalMs: 300_000 } } }, // 5 min para la voz en vez de 10; null quita un tope transcribe: { language: 'es', progress: true }, // progress: bytes de la voz y su aviso de atasco también donde kodec no la pre-descarga // Una preparación en segundo plano tiene sus propios eventos (kind 'prepare'): la pantalla pinta los de la captura. onStartupStage: (e) => { if (e.kind !== 'prepare' && e.userMessage !== null) ui.status(e.userMessage) }, onWarning: (w) => { if (w.code === 'startup.stalled') ui.offer(w.stage === 'speech' ? ['wait', 'cancel', 'without-voice'] : ['wait', 'cancel', 'reload']) },})
let cancel = null // el botón Cancelar llama a cancel?.abort()async function start(pair, voice = true) { cancel = new AbortController() try { // Sin voz: esta captura no abre el micrófono ni transcribe nada, con el mismo cliente. return await client.captureProtocol({ ...pair, source: { type: 'webcam' }, signal: cancel.signal, ...(voice ? {} : { transcribe: false }) }) } catch (e) { if (e instanceof CaptureAbortedError || e instanceof CaptureStartError) { ui.status(e.userMessage ?? e.message); return null } throw e }}- Las etapas.
onStartupStagese llama en cada cambio de etapa (STARTUP_STAGES):engine-setup,device,camera,face-model,first-frame,speechyengine-session, con unstatus(pending,running,stalled,done,failed,skipped). PintauserMessagey tienes la pantalla; va enstartup.locale('es'o'en'; por defecto el idioma de la transcripción, después el del kit, después el del navegador), ystartup.messagessustituye cualquier texto por su clave (STARTUP_MESSAGE_KEYS; los textos hechos sonSTARTUP_MESSAGES). Llegan también las subetapas de kodec (STARTUP_SUB_STAGES, conparent: 'face-model'o'speech'), sin mensaje y conbytes,totalybytesPerSec: para una barra de progreso más fina o tu telemetría. Los mismos eventos llegan encaptureBaseliney en modo grabación. - Los bytes de la voz y su atasco. kodec siempre cuenta los bytes de
face-model, pero los despeech(y con ellos su avisostartup.stalled) solo donde él pre-descarga la voz: no en Safari ni en iOS, ni con unmodelexplícito, untransformersinyectado, WebGPU sin JSPI o WASM sinselfHost.wasmPaths. En los demás casos solo los datranscribe: { progress: true }.speech.runningdice «Descargando el reconocimiento de voz… (X de Y MB)» solo con los bytes y el total, y por esa vía el total no llega (total: null, también con el SDK 0.43.0 y kodec 5.0.0-rc.14): el texto va sin la cifra. Su coste: con un origen sinContent-Length, la librería copia el búfer entero en cada trozo, y en un móvil eso sube la memoria justo en la fase que ya cierra pestañas. Los pesos por defecto llegan conContent-Length; si los sirves tú, mándalo también (CSP y transcripción). - Textos según la fuente (desde la 0.42.1). Los textos
face-model.*hablan de preparar el análisis facial, no de la cámara: el modelo de la cara se carga igual con una webcam, unstream, un<video>o una preparación sin fuente. Un tope del primer frame usafirst-frame.timeout-media(«No se ve ninguna cara en el vídeo…») cuando la fuente es tu propiostreamo<video>, y en la reproducción de una grabación; con la webcam sigue siendofirst-frame.timeout(«No se te ve…»). El SDK lo elige por la fuente, en el evento de la etapa y enCaptureStartError.messageKeyyuserMessage. Una cámara en directo que pasas comostreamtambién recibe la frase del vídeo: sustituyefirst-frame.timeout-mediaenstartup.messagessi quieres la de la webcam. Un texto que sustituiste constartup.messagesse mantiene, y un juego completo de textos propios tipado comoRecord<StartupMessageKey, string>tiene que añadir cada clave nueva (STARTUP_MESSAGE_KEYSlista veinte desde la 0.43.0, confirst-frame.face-reload-failed). - Los topes (por defecto; Plazos): el modelo de la cara falla con
CaptureStartError(stage: 'face-model',reason: 'timeout') 120 s después de conceder la cámara; la voz se rinde a los 600 s con el avisosttconreason: 'timeout', y la captura sigue sin ella; 20 s sin un byte nuevo lanzanstartup.stalled(uno por atasco), que no corta nada.nullquita un tope. El permiso de la cámara y la espera a que se ponga el móvil en vertical no tienen tope:signallos cancela. - Esperar, cancelar o seguir sin voz. Con
startup.stalleddespeech, la persona puede esperar (los bytes pueden volver), cancelar (abort()de tuAbortController) o seguir sin voz: aborta el arranque y vuelve a llamar acaptureProtocol({ …, transcribe: false })con el mismo cliente. En un plan con steps de voz, esos steps llegan entonces a Engine sin transcrito. Unface-modelatascado no tiene «sin voz»: esperar, cancelar o recargar. - Cancelar.
signal(unAbortSignal) encaptureProtocolycaptureBaselineactúa hasta que la llamada resuelve: el SDK suelta la cámara, el micrófono y el hueco del par, cancela la sesión de Engine si llegó a abrirse y rechaza conCaptureAbortedError(E_CAPTURE_ABORTED). Una vez resuelta, la captura se acaba consession.abort()osession.stop(). - Si
face-modelse agota, ofrece recargar. ConCaptureStartError.subStage'vision-runtime', un reintento en la misma página vuelve a esperar al módulo colgado y se agota otra vez; con'face-asset'o'vision-create'sí merece la pena reintentar. Recargar funciona en todos los casos, y el mensajeface-model.timeoutlo sugiere. - El informe. Cada arranque deja un
StartupReport(etapas y tiempos, las comprobaciones del dispositivo,outcomeready,partial,failed,abortedounfinished). En vivo y encaptureBaselinellega enSessionReport.startupporonReport, ySessionReport.transcriptionLoaddice cómo acabó la carga de la voz. Para recibirlo también en tu servidor (la única vía en modo grabación, y la única que ve un arranque abandonado cerrando la pestaña), pasastartup.report: { url, on, context }:on: 'failures'solo envía lo que no fue bien, ycontextadmite hasta 8 pares tuyos, con valores de hasta 128 caracteres, sin datos personales. Sinreport.urlno sale nada de la página. El informe lleva el user agent salvo que pasesstartup.includeUserAgent: false. Sudevicelista las comprobaciones (DeviceCheck, ids enDeviceCheckId: el contexto seguro,getUserMedia, el adaptador de WebGPU, JSPI, WASM SIMD y otras), cada unapass,warn,failounknown, decididas por capacidad y nunca por el user agent; y, en una captura a la que se prestó una preparación,prepared(PreparedBlock) dice qué hizo con la cara y con la voz (adopted,stale,unusedonot-prepared) y, enprepareId, elstartupIddel informe de la propia preparación. El receptor: Tu backend.
Los textos ya hechos de STARTUP_MESSAGES (las veinte claves, en el idioma de startup.locale; {loadedMb} y {totalMb} son megabytes enteros, y el tramo entre [ y ] desaparece si falta uno). Este es el juego en español:
| Clave | Cuándo | Texto |
|---|---|---|
startup.preparing |
Cualquier momento sin mensaje propio | Preparando la captura… |
face-model.running |
Carga el modelo de la cara | Preparando el análisis facial… |
face-model.cached |
Ya estaba en el dispositivo | Preparando el análisis facial (ya estaba en este dispositivo)… |
speech.running |
Se descarga el reconocimiento de voz (con los MB cuando se conocen) | Descargando el reconocimiento de voz…[ ({loadedMb} de {totalMb} MB)] |
speech.stalled |
La descarga de voz no avanza | Tu conexión va lenta y la descarga de voz no avanza. Puedes esperar o seguir sin reconocimiento de voz. |
speech.timeout |
La voz no llegó a tiempo | El reconocimiento de voz no llegó a tiempo. La captura sigue sin él. |
speech.unavailable |
Este dispositivo no puede transcribir | Este dispositivo no puede transcribir la voz. La captura sigue sin ella. |
face-model.stalled |
La carga del modelo de la cara no avanza | Tu conexión va lenta y la preparación del análisis facial no avanza. Puedes esperar o recargar la página. |
face-model.timeout |
El modelo de la cara no cargó a tiempo | No se pudo preparar el análisis facial a tiempo. Recarga la página para intentarlo de nuevo. |
face-model.error |
Falló la carga del modelo de la cara | No se pudo preparar el análisis facial. Recarga la página o prueba con otra red. |
first-frame.timeout |
La webcam no muestra ninguna cara | No se te ve. Ponte frente a la cámara, con la cara iluminada, e inténtalo de nuevo. |
first-frame.timeout-media |
Tu stream o <video> (y un replay) no muestra ninguna cara |
No se ve ninguna cara en el vídeo. Comprueba que se vea una cara de frente y bien iluminada, e inténtalo de nuevo. |
first-frame.face-reload-failed |
El análisis facial se paró al empezar la captura y volver a cargarlo falló (desde la 0.43.0) | El análisis facial dejó de funcionar al empezar y no se pudo volver a preparar. Recarga la página para intentarlo de nuevo. |
camera.timeout |
La cámara no respondió (reservado) | La cámara no respondió a tiempo. Recarga la página para intentarlo de nuevo. |
capture.aborted |
Se canceló la captura | Se canceló la captura. |
startup.ready |
El arranque terminó | Todo listo. |
prepare.speech-timeout |
En una preparación, la voz no terminó de descargarse | El reconocimiento de voz no terminó de descargarse. Puedes empezar igualmente: se intentará de nuevo al empezar. |
prepare.speech-error |
En una preparación, no se pudo descargar la voz | No se pudo descargar el reconocimiento de voz. Puedes empezar igualmente: se intentará de nuevo al empezar. |
prepare.aborted |
Se canceló la preparación | Se canceló la preparación. |
prepare.record-unsupported |
En la preparación de una grabación, el dispositivo no puede grabar | Este dispositivo no puede grabar la sesión. Prueba con otro navegador o dispositivo. |
Preparar antes de Empezar
Sección titulada «Preparar antes de Empezar»No es obligatorio: sin ello, la captura carga lo que necesita al pulsar Empezar. client.prepare() lleva esa espera a un momento en que la persona hace otra cosa (un formulario, las instrucciones), y la siguiente captureProtocol del mismo cliente adopta lo cargado, sin ninguna opción. Nunca llama a Engine ni abre la cámara. El patrón recomendado: un cliente por página, el mismo durante toda la visita; preparar al montar la página y liberar al salir. Cuál de las cinco maneras de cargar los modelos encaja en tu flujo, con un bloque para cada una: Cargar los modelos.
import { createProtocolClient, defineTenantConfig } from '@neurologyca/capture'import kit from './neuro.config.json'
// Un cliente para la página: una captura solo adopta lo que preparó este mismo cliente.const client = createProtocolClient({ baseUrl: '/engine', tenant: defineTenantConfig(kit) })
// Al montar la página. En React: useEffect(() => { void client.prepare(); return () => client.release() }, [client])const preparing = client.prepare() // solo la cara; también la voz con { models: { face: true, speech: true } }, tras el consentimiento
// El botón Empezar, desde el clic de la persona: adopta lo preparado y espera, con sus propios topes, lo que falte.function onStart(pair) { return client.captureProtocol({ ...pair, source: { type: 'webcam' } })}
// Cuando la persona sale de la página, o tu vista se desmonta.function onLeave() { client.release()}- Qué prepara. Por defecto, la cara (unos 13,5 MB). La voz (unos 160 MB), solo con
models: { speech: true }, que necesita la transcripción del propio SDK (transcribeencendido). Su descarga no pide el permiso del micrófono, así que pídela cuando la persona haya aceptado. En Safari e iOS solo se prepara la cara: la voz se carga al empezar la captura (transcription: 'not-prepared',partialReason: 'speech-not-prepared'; no es un fallo). level.'memory'(por defecto) carga los modelos en la página, para la siguiente captura de este cliente.'cache'solo los descarga a la caché del navegador y no deja nada que adoptar: no lo mezcles con Empezar en la misma página.- El resultado.
prepare()resuelve unPrepareResult:outcome('ready','partial','failed'o'aborted'),partialReason,face,transcription,estimatedSpeechMs(una guía de la descarga de la voz, que suele salir alta),cache,report,messageKeyyuserMessage. No rechaza por cómo fue la carga, salvo conthrowOnFailure: true, y entonces solo con'failed'o'aborted':PrepareError(E_PREPARE), con elPrepareResultentero enresult.timeoutscambia los topes del cliente solo para esa llamada, ysignalla aborta. - Una preparación por cliente, y la adopta una captura. Solo adopta la captura del cliente que preparó: un segundo cliente en la página vuelve a cargarlo todo, y ocupa el doble de memoria. Sin
keepPrepared(abajo), la voz se libera tras cada sesión, así que cada captura necesita su propia preparación, y sin la opción el baseline no adopta: prepara antes decaptureBaselineo cuando acabe. Mientras corre una captura o un baseline de este cliente,prepare()rechaza conPrepareErroryreason: 'capture-in-progress'; prepara la siguiente cuando acabe la actual. - Repetir y liberar. Las mismas opciones devuelven la misma promesa; cualquier diferencia sustituye lo preparado (el aviso
prepare.released,reason: 'replaced'; sus otros motivos son'release','abort','pagehide'y, conkeepPrepared,'unusable'), y una llamada más estrecha libera lo que ya no pide: decide una vez qué preparar.client.release()es síncrona e idempotente: libera lo que no tiene ninguna captura y resuelve'aborted'una preparación en curso (una conlevel: 'cache'solo acaba por susignal). Llámala antes de soltar un cliente (un componente que se desmonta); si no, los modelos siguen cargados hasta que la página se va. El cliente también libera enpagehide. El avisoprepare.staledice que una captura no pudo usar una parte preparada (la carga ella); con un solo cliente y su propia configuración no debería salir. - Si falla la cara preparada. Con o sin
keepPrepared(desde la 0.43.0), una cara preparada que rechaza sus primeros frames o pierde su contexto de GPU la vuelve a cargar kodec una vez: el avisoprepare.face-lost, y la cara sigue'adopted'en el informe, confaceReloaded: true. Si esa recarga falla antes del primer frame, el arranque falla en el acto conCaptureStartError(stage: 'first-frame',reason: 'error', clavefirst-frame.face-reload-failed). Una cara que cargó la propia captura avisaface.context-losten el mismo caso (Errores).
Guardar los modelos entre capturas
Sección titulada «Guardar los modelos entre capturas»Desde la 0.43.0, keepPrepared (apagada por defecto, solo en vivo) guarda lo que cargaron prepare(), cada captura y cada baseline: al parar una sesión, los modelos de la cara, y la voz cargada o aún cargándose, vuelven al cliente, y la siguiente captura los adopta. No hay prepare() entre capturas, y una captura que cargó sus modelos sin ningún prepare() también los guarda. Con keepPrepared el baseline adopta la cara preparada (o la que guardó una sesión anterior) y deja la voz para la captura.
import { createProtocolClient, defineTenantConfig } from '@neurologyca/capture'import kit from './neuro.config.json'
const client = createProtocolClient({ baseUrl: '/engine', tenant: defineTenantConfig(kit), keepPrepared: true })
// Una vez, antes del primer baseline o captura (la voz, tras el consentimiento). Después no hay nada que preparar.const preparing = client.prepare({ models: { face: true, speech: true } })// captureBaseline(…) adopta la cara; captureProtocol(…) y su stop(), y después la siguiente captureProtocol(…): cada una// adopta lo que dejó la anterior.
// Entre una persona y la siguiente en el mismo dispositivo, y antes de soltar el cliente (haya preparado o no).function onNextPerson() { client.release()}- Lo que cuesta. La memoria sigue ocupada mientras la persona hace otra cosa, hasta
client.release(), la salida de la página (pagehide, también al entrar en la caché de páginas del navegador) o que kodec deje inservible una parte guardada (prepare.releasedconreason: 'unusable'y supart: solo se suelta esa parte). Por eso, con la opción, todo cliente necesitaclient.release()antes de soltarlo, haya preparado o no. Dos clientes en la página guardan cada uno lo suyo, y ocupan el doble.client.cacheStatus()no ve lo guardado: lee la caché del navegador, no la memoria. - Prepara una vez. Un
client.prepare({ models: { face: true, speech: true } })antes de la primera captura o baseline; sin él, la primera captura carga las dos cosas ella misma, y las guarda. Unprepare()que pide solo lo guardado resuelve sin cargar nada (su informe llevakept: true); uno que pide una parte que no está guardada suelta lo guardado y vuelve a cargarlo todo (prepare.released,'replaced'). - Sin WebGPU, no prepares entre capturas. Donde se rechaza la transcripción (sin WebGPU y sin
allowWasmWorker) la voz nunca se guarda, así que unprepare()que pide la voz entre capturas suelta la cara guardada ('replaced') y la vuelve a cargar cada vez. Ahí, prepara una vez antes de la primera captura y no prepares entre capturas, o pide solo la cara (prepare({ models: { face: true } })). - En Safari e iOS solo se guarda la cara: la voz se vuelve a cargar con cada captura, y un baseline no toma una preparación cuya voz está cargada o cargándose.
- Entre personas. Lo guardado son modelos, no lo capturado: el transcrito de cada sesión se libera al cerrarla, y nada va a disco. Pero el modelo de la cara puede arrastrar estado del último frame de una captura a la siguiente. Si un dispositivo pasa de una persona a otra, llama a
client.release()entre una persona y la siguiente, o deja la opción apagada (Privacidad). - En los informes. Una captura o un baseline al que se prestaron modelos guardados lo dice en su
StartupReport:prepared.origin('prepare','previous-session'onullpor parte;null: esa parte no estaba entre los modelos guardados) yprepared.prepareId, que esnullcuando ninguna parte vino de unprepare(). Esos informes sonschema: 2, y un receptor los valida concapture-server0.19.0 o posterior (Tu backend). En modo grabación la opción se ignora, con el avisorecording.option-ignored.
La caché, desde otra página
Sección titulada «La caché, desde otra página»- La caché.
client.cacheStatus()dice qué está ya en la caché del navegador: solospeechWeightsysttRuntimedicen algo ('cached','not-cached'o'unknown');faceModel,sttLibraryyvisionRuntimeson siempre'unknown'. En una página anterior sin cliente (una portada),prepareCapture({ level: 'cache' })calienta la caché ycaptureCacheStatus()la lee, con la misma configuración que la página de la captura pasa acreateProtocolClient:
import { captureCacheStatus, prepareCapture } from '@neurologyca/capture'
// Un módulo que importan las dos páginas, para que lo calentado sea lo que pedirá la captura.const captureConfig = { transcribe: { language: 'es' } }
const cached = await captureCacheStatus(captureConfig)if (cached.speechWeights !== 'cached') await prepareCapture({ ...captureConfig, level: 'cache', prepare: { face: true, speech: true } })Lo que cuesta: los datos de la persona se gastan aunque no llegue a empezar (unos 175 MB en frío, la cara y la voz), y el navegador puede vaciar su caché cuando quiera. Un cliente de grabación también tiene prepare(), que no carga ningún modelo: solo comprueba, antes de pedir ningún permiso, si el dispositivo puede grabar (Diferido (en servidor)).
El resultado
Sección titulada «El resultado»stop() resuelve con un CaptureOutcome: status ('complete', 'timeout', 'invalidated' o 'cancelled'), hcis (las medias), hcisByStep, frameCount, interpretation (la narrativa, o null) y, desde 0.39.0, structured (los datos estructurados de la interpretación, o null; de ahí lee un índice de 0 a 100 con readScoreIndex, ver Un índice de 0 a 100). Los campos y las escalas: HCIs y resultados.
Si pediste interpretación, onInterpretationDetails salta justo después de onInterpretation (desde 0.38.0), así que puedes guardar las dos juntas. Con interpretation: 'stream' el detalle llega después, normalmente cuando stop() ya ha resuelto: espéralo con un plazo propio, y guarda sin él si se agota. Un processing.error de Engine mientras stop() espera la interpretación acaba la sesión 'invalidated': no va a llegar ninguna interpretación.
Pasado outcomeDeadlineMs (240 s por defecto), E_RESULTS_TIMEOUT: no es una pérdida. Engine tiene la captura; guarda el par y lee los resultados más tarde (Resultados en tu backend).
Errores y avisos
Sección titulada «Errores y avisos»Tres familias: fallos del pipeline por onError ({ code, recoverable, stepOrder? }), errores de uso que se lanzan hacia ti, y avisos. La regla: un recoverable distinto de true durante los steps da la captura por perdida, así que llama a abort(); después de stop(), no: códigos como E_RESULTS_TIMEOUT llegan con recoverable: false pero Engine ya tiene la captura.
Los avisos que conviene enseñar (los códigos son strings, no una unión publicada):
source.ended: tu fichero o tu stream acabó. Un step conducido conrun()se cierra; constart()yend()lo cierras tú conend(). Ya no se puede capturar ningún step posterior.step.duration-below-minystep.duration-above-max: un step se cerró fuera de su ventana.step.media-undeclared: el step tiene varias medias y no dijiste cuál enseñaste.capture.throttledes relativo a la propia sesión: salta cuando los fps caen a una cuarta parte de los propios de esa sesión durante tres ventanas seguidas, con un step abierto (una vez por step), normalmente una pestaña oculta. Un dispositivo lento desde la primera ventana nunca lo dispara, así que no es la señal de lo rápido que es el dispositivo (léelo como en Probar en tu móvil).quality.warning: Engine dice que la calidad de lo que le llega no es suficiente.stream.unavailable: el flujo de eventos no conectó; la captura sigue.interpretation.sse-timeoutyanalysis.regenerated(desde 0.38.0): el aviso de Engine no llegó a tiempo y la interpretación se leyó conPOST /analyze; conanalysis.regenerated,/analyzetuvo que generar una nueva, y la sesión pudo cobrarse dos veces. Los dos dicen la causa; si el flujo se cortó durante la espera, comprueba que tu proxy reenvía/stream/{userProtocolId}.transcription.off-on-voice-stepytranscribeSteps.excludes-voice-step(desde 0.38.0, antes de abrir la cámara): un step en el que se espera que la persona hable (expectsSpeech: 'yes'en el plan) no se transcribirá, porquetranscribeestá apagado otranscribeStepslo deja fuera.expectsSpeechvale'yes','no','any'(la persona puede hablar o no),null(sin declarar) u otro valor que declare el catálogo, y el SDK solo avisa con'yes'.transcribeSteps.noMatch: ningún tipo detranscribeStepsexiste en el plan, así que no se transcribe ningún step.protocol.not-interpreted(desde 0.29.0): Engine dice que el protocolo no se interpreta (Measurement): no se envía taxonomía ni se pide análisis, aunque pasestriggerAnalysis: true.interpretationseránull.
E_CONFLICT llega con reason y conflict.<campo>. Todos los códigos, por capa: Errores, avisos y reintentos.
Baseline
Sección titulada «Baseline»Léelo con client.getBaselineInfo(userId) (null = aún no hay) y captúralo con client.captureBaseline({ userId, source, onStarted, onProgress }); con keepPrepared adopta la cara preparada (Guardar los modelos entre capturas). Engine lo calcula en segundo plano: vuelve a leerlo hasta que esté. Con un <video>, la captura se detiene cuando el fichero acaba. El baseline pasa siempre por el cliente en vivo: el cliente de grabación no tiene captureBaseline. Ver Baseline.
const info = await client.getBaselineInfo(userId) // null: aún no hay baselineif (!info) await client.captureBaseline({ userId, source: { type: 'webcam' }, onProgress: (p) => ui.progress(p) })Transcripción
Sección titulada «Transcripción»Apagada hasta que algo la enciende. Enciéndela con transcribe en el cliente, y di qué steps con transcribeSteps (los steps de habla de tu protocolo). Un objeto transcribe en el kit (tenant) también enciende la transcripción, aunque tu código no pase transcribe; el kit de DevLab de todo protocolo de contexto lleva uno por defecto (un idioma sin región), así que, con la cámara como fuente, la captura abre el micrófono salvo que tu código pase transcribe: false. Está apagada por defecto en Measurement, que no tiene steps de habla; si la enciendes ahí, Engine guarda el texto y /results lo devuelve como transcript del step 1 (speech, solo en el Engine del entorno de pruebas).
El reconocimiento de voz corre en el navegador: el audio no sale del navegador; el texto va a Engine, que se lo pasa a un LLM para la interpretación. La primera vez descarga unos 160 MB (136 MB de ellos, los pesos del modelo, de un CDN de terceros; CSP y transcripción); puedes descargarlo antes de Empezar (Preparar antes de Empezar). Con un <video> como fuente, el SDK transcribe el audio del propio fichero, sin abrir el micrófono.
const client = createProtocolClient({ baseUrl: '/engine', tenant, transcribe: { language: 'es' }, transcribeSteps: ['free_speech'] })La sesión y su flujo de eventos
Sección titulada «La sesión y su flujo de eventos»| Cuándo | Qué pasa |
|---|---|
captureProtocol resuelve |
El SDK abre GET /stream/{userProtocolId} a través de tu proxy. |
| Mientras capturas | Eventos: connected, hci.warning, results.ready (una vez por posición, y no en todos los casos: el SDK sigue conciliando por HTTP; desde 0.29.0 es un evento conocido, antes daba stream.unknown-event) y los eventos de la interpretación cuando la pediste. |
| El stream se cae | El SDK lo reabre, esperando de 0,5 a 10 s; tras tres intentos fallidos avisa stream.unavailable y la captura continúa. |
stop() |
Con una interpretación en camino, el SDK espera en el stream el aviso de Engine (solo el de esta mecánica) y después lo cierra. |
abort() |
El stream se cierra. |
| La persona cierra sesión en tu app | Un stream abierto la sobrevive (el authorize de tu proxy corre una vez, al abrirlo): cierra la captura cuando la persona se vaya, y limita los streams por usuario en tu backend. |
| La pestaña se cierra | La captura se detiene; Engine conserva lo que recibió, y la posición abierta sigue las reglas de sesión de Engine (Sesiones). |
Probar en tu móvil
Sección titulada «Probar en tu móvil»Sirve tu página por HTTPS al móvil (un contexto seguro: un túnel a tu máquina de desarrollo o un certificado para tu red local, el que uses), permite la cámara y lee el ritmo en ejecución con onCodecEvent('capture-quality'): kodec da más o menos una ventana por segundo con los frames por segundo que midió. Descarta las dos primeras ventanas (el arranque) y las de la pestaña oculta (document.visibilityState), y lee la mediana del resto, cuántas ventanas quedan por debajo de 8 fps y la más baja. 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. La regla con su código, y la comprobación del dispositivo antes de medir: Dispositivos, calidad y modo. SessionReport.captureQuality resume esas mismas ventanas pero incluye el arranque y las ocultas, así que no juzgues solo por él; y capture.throttled es relativo al ritmo de la propia sesión, así que un móvil lento desde el principio nunca lo dispara. Lo que limita el ritmo es la detección de la cara en la GPU (WebGL 2) y, en móvil, el calor en sesiones largas (Navegadores y frecuencia de frames). La frecuencia de frames depende del dispositivo, no de la plataforma: un móvil reciente suele quedarse cerca de la de la cámara, un móvil de gama de entrada captura menos frames por segundo y un móvil la pierde según se calienta en una sesión larga. Léelo en ejecución, no del modelo de teléfono. Los ayudantes (keepScreenOn, guardUnload, classifyMediaError) están en Steps y marcado; guardUnload depende del navegador: en Chrome para Android, al cerrar la pestaña no sale el diálogo; una pestaña cerrada acaba la captura, así que vuelve a capturar (al grabar en diferido, listPendingRecordings() encuentra en la visita siguiente lo que no se subió: súbelo con uploadRecording o descártalo con su release()). La prueba más barata: abre el playground en tu móvil.
Opciones
Sección titulada «Opciones»batchMs (5000 por defecto), fps, stepDurations ('warn' por defecto; 'enforce'; 'off'), requestTimeoutMs, outcomeDeadlineMs (240 s), analyzeTimeoutMs (280 s: la espera de la interpretación, y después el POST /analyze; desde la 0.44.0, tras un 202 ANALYSIS_IN_PROGRESS el SDK espera y vuelve a pedirla dentro de ese plazo, contado desde el primer 202, y acaba con E_ANALYSIS_IN_PROGRESS si se agota), credentials (desde la 0.45.0: 'omit', 'same-origin' o 'include', el modo credentials de las peticiones del cliente a tu proxy, incluidos el flujo de eventos y la interpretación en stream; sin ella, el 'same-origin' del navegador; 'include' para un proxy en otro origen que decide por tu cookie de sesión, El proxy en otro origen), onProgress (solo con interpretation: 'stream'), correlationId (un prefijo para X-Correlation-Id), channels, kodec (ver CSP y transcripción), startup (timeouts, locale, messages, report, includeUserAgent; una clave desconocida lanza UnknownOptionError) y onStartupStage (La pantalla de arranque). Desde la 0.42.0, createProtocolClient lanza UnknownOptionError (E_UNKNOWN_OPTION) con cualquier opción que no tiene; antes la ignoraba. Los plazos están en Plazos. Las demás opciones de la referencia son de ajuste avanzado; déjalas con sus valores por defecto salvo que Neurologyca te diga otra cosa.