# En el dispositivo (tiempo real)

Se procesa en el navegador mientras capturas. [Pruébalo en el playground](/playground#measure): allí es la vía por defecto.

## 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

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](/docs/es/sdk/backend/)).

```js
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),
})
```

> Con Measurement, el `neuro.config.json` de tu kit ya lo dice: `taxonomy: { contextId: 'measurement' }`, y `triggerAnalysis: false` en `captureProtocol`. Desde la 0.29.0 el SDK se salta solo la taxonomía y el análisis cuando Engine dice `interpreted: false`; mantén `triggerAnalysis: false` de tu kit, que lo mantiene funcionando con un Engine que no lo diga. El `contextId` sigue siendo obligatorio ([Measurement](/docs/es/guides/measurement/)).

## Captura

Recoge el consentimiento **antes** de `captureProtocol`, y llámalo solo desde un gesto de la persona (un clic): abre la cámara.

```js
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](/docs/es/sdk/steps/#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](/docs/es/guides/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](/docs/es/sdk/steps/).

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

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.

```js
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.** `onStartupStage` se llama en cada cambio de etapa (`STARTUP_STAGES`): `engine-setup`, `device`, `camera`, `face-model`, `first-frame`, `speech` y `engine-session`, con un `status` (`pending`, `running`, `stalled`, `done`, `failed`, `skipped`). Pinta `userMessage` y tienes la pantalla; va en `startup.locale` (`'es'` o `'en'`; por defecto el idioma de la transcripción, después el del kit, después el del navegador), y `startup.messages` sustituye cualquier texto por su clave (`STARTUP_MESSAGE_KEYS`; los textos hechos son `STARTUP_MESSAGES`). Llegan también las subetapas de kodec (`STARTUP_SUB_STAGES`, con `parent: 'face-model'` o `'speech'`), sin mensaje y con `bytes`, `total` y `bytesPerSec`: para una barra de progreso más fina o tu telemetría. Los mismos eventos llegan en `captureBaseline` y en modo grabación.
- **Los bytes de la voz y su atasco.** kodec siempre cuenta los bytes de `face-model`, pero los de `speech` (y con ellos su aviso `startup.stalled`) solo donde él pre-descarga la voz: no en Safari ni en iOS, ni con un `model` explícito, un `transformers` inyectado, WebGPU sin JSPI o WASM sin `selfHost.wasmPaths`. En los demás casos solo los da `transcribe: { progress: true }`. `speech.running` dice «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 sin `Content-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 con `Content-Length`; si los sirves tú, mándalo también ([CSP y transcripción](/docs/es/guides/csp-transcription/)).
- **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, un `stream`, un `<video>` o una preparación sin fuente. Un tope del primer frame usa `first-frame.timeout-media` («No se ve ninguna cara en el vídeo…») cuando la fuente es tu propio `stream` o `<video>`, y en la reproducción de una grabación; con la webcam sigue siendo `first-frame.timeout` («No se te ve…»). El SDK lo elige por la fuente, en el evento de la etapa y en `CaptureStartError.messageKey` y `userMessage`. Una cámara en directo que pasas como `stream` también recibe la frase del vídeo: sustituye `first-frame.timeout-media` en `startup.messages` si quieres la de la webcam. Un texto que sustituiste con `startup.messages` se mantiene, y un juego completo de textos propios tipado como `Record<StartupMessageKey, string>` tiene que añadir cada clave nueva (`STARTUP_MESSAGE_KEYS` lista veinte desde la 0.43.0, con `first-frame.face-reload-failed`).
- **Los topes** (por defecto; [Plazos](/docs/es/guides/timeouts/#el-arranque)): 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 aviso `stt` con `reason: 'timeout'`, y la captura sigue sin ella; 20 s sin un byte nuevo lanzan `startup.stalled` (uno por atasco), que no corta nada. `null` quita un tope. El permiso de la cámara y la espera a que se ponga el móvil en vertical no tienen tope: `signal` los cancela.
- **Esperar, cancelar o seguir sin voz.** Con `startup.stalled` de `speech`, la persona puede esperar (los bytes pueden volver), cancelar (`abort()` de tu `AbortController`) o seguir sin voz: aborta el arranque y vuelve a llamar a `captureProtocol({ …, transcribe: false })` **con el mismo cliente**. En un plan con steps de voz, esos steps llegan entonces a Engine sin transcrito. Un `face-model` atascado no tiene «sin voz»: esperar, cancelar o recargar.
- **Cancelar.** `signal` (un `AbortSignal`) en `captureProtocol` y `captureBaseline` actú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 con `CaptureAbortedError` (`E_CAPTURE_ABORTED`). Una vez resuelta, la captura se acaba con `session.abort()` o `session.stop()`.
- **Si `face-model` se agota, ofrece recargar.** Con `CaptureStartError.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 mensaje `face-model.timeout` lo sugiere.
- **El informe.** Cada arranque deja un `StartupReport` (etapas y tiempos, las comprobaciones del dispositivo, `outcome` `ready`, `partial`, `failed`, `aborted` o `unfinished`). En vivo y en `captureBaseline` llega en `SessionReport.startup` por `onReport`, y `SessionReport.transcriptionLoad` dice 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), pasa `startup.report: { url, on, context }`: `on: 'failures'` solo envía lo que no fue bien, y `context` admite hasta 8 pares tuyos, con valores de hasta 128 caracteres, sin datos personales. **Sin `report.url` no sale nada de la página.** El informe lleva el user agent salvo que pases `startup.includeUserAgent: false`. Su `device` lista las comprobaciones (`DeviceCheck`, ids en `DeviceCheckId`: el contexto seguro, `getUserMedia`, el adaptador de WebGPU, JSPI, WASM SIMD y otras), cada una `pass`, `warn`, `fail` o `unknown`, 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`, `unused` o `not-prepared`) y, en `prepareId`, el `startupId` del informe de la propia preparación. El receptor: [Tu backend](/docs/es/sdk/backend/#los-informes-de-arranque-opcional).

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

**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](/docs/es/guides/load-models/).

```js
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 (`transcribe` encendido). 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 un `PrepareResult`: `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`, `messageKey` y `userMessage`. No rechaza por cómo fue la carga, salvo con `throwOnFailure: true`, y entonces solo con `'failed'` o `'aborted'`: `PrepareError` (`E_PREPARE`), con el `PrepareResult` entero en `result`. `timeouts` cambia los topes del cliente solo para esa llamada, y `signal` la 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](#guardar-los-modelos-entre-capturas)), 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 de `captureBaseline` o cuando acabe. Mientras corre una captura o un baseline de este cliente, `prepare()` rechaza con `PrepareError` y `reason: '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, con `keepPrepared`, `'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 con `level: 'cache'` solo acaba por su `signal`). 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 en `pagehide`. El aviso `prepare.stale` dice 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 aviso `prepare.face-lost`, y la cara sigue `'adopted'` en el informe, con `faceReloaded: true`. Si esa recarga falla antes del primer frame, el arranque falla en el acto con `CaptureStartError` (`stage: 'first-frame'`, `reason: 'error'`, clave `first-frame.face-reload-failed`). Una cara que cargó la propia captura avisa `face.context-lost` en el mismo caso ([Errores](/docs/es/sdk/errors/#avisos-que-conviene-mostrar)).

### 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.

```js
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.released` con `reason: 'unusable'` y su `part`: solo se suelta esa parte). Por eso, con la opción, todo cliente necesita `client.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. Un `prepare()` que pide solo lo guardado resuelve sin cargar nada (su informe lleva `kept: 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 un `prepare()` 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](/docs/es/resources/privacy/#qué-guarda-el-sdk-en-tu-navegador)).
- **En los informes.** Una captura o un baseline al que se prestaron modelos guardados lo dice en su `StartupReport`: `prepared.origin` (`'prepare'`, `'previous-session'` o `null` por parte; `null`: esa parte no estaba entre los modelos guardados) y `prepared.prepareId`, que es `null` cuando ninguna parte vino de un `prepare()`. Esos informes son `schema: 2`, y un receptor los valida con `capture-server` 0.19.0 o posterior ([Tu backend](/docs/es/sdk/backend/#los-informes-de-arranque-opcional)). En modo grabación la opción se ignora, con el aviso `recording.option-ignored`.

### La caché, desde otra página

- **La caché.** `client.cacheStatus()` dice qué está ya en la caché del navegador: solo `speechWeights` y `sttRuntime` dicen algo (`'cached'`, `'not-cached'` o `'unknown'`); `faceModel`, `sttLibrary` y `visionRuntime` son siempre `'unknown'`. En una página anterior sin cliente (una portada), `prepareCapture({ level: 'cache' })` calienta la caché y `captureCacheStatus()` la lee, con **la misma configuración** que la página de la captura pasa a `createProtocolClient`:

```js
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)](/docs/es/sdk/deferred/)).

## 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](/docs/es/concepts/results/#un-índice-de-0-a-100)). Los campos y las escalas: [HCIs y resultados](/docs/es/concepts/results/#en-el-sdk).

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](/docs/es/sdk/results-backend/)).

## 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 con `run()` se cierra; con `start()` y `end()` lo cierras tú con `end()`. Ya no se puede capturar ningún step posterior.
- `step.duration-below-min` y `step.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.throttled` es 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](#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-timeout` y `analysis.regenerated` (desde 0.38.0): el aviso de Engine no llegó a tiempo y la interpretación se leyó con `POST /analyze`; con `analysis.regenerated`, `/analyze` tuvo 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-step` y `transcribeSteps.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á, porque `transcribe` está apagado o `transcribeSteps` lo deja fuera. `expectsSpeech` vale `'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 de `transcribeSteps` existe 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 pases `triggerAnalysis: true`. `interpretation` será `null`.

`E_CONFLICT` llega con `reason` y `conflict.<campo>`. Todos los códigos, por capa: [Errores, avisos y reintentos](/docs/es/sdk/errors/).

## 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](#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](/docs/es/concepts/baseline/).

```js
const info = await client.getBaselineInfo(userId) // null: aún no hay baseline
if (!info) await client.captureBaseline({ userId, source: { type: 'webcam' }, onProgress: (p) => ui.progress(p) })
```

## 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`](/docs/es/concepts/results/#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](/docs/es/guides/csp-transcription/)); puedes descargarlo antes de Empezar ([Preparar 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.

```js
const client = createProtocolClient({ baseUrl: '/engine', tenant, transcribe: { language: 'es' }, transcribeSteps: ['free_speech'] })
```

## 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](/docs/es/concepts/sessions/)). |

## 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](/docs/es/start/devices-and-modes/). `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](/docs/es/concepts/capture/#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](/docs/es/sdk/steps/#ayudantes); `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](/docs/es/sdk/deferred/), `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](/playground) en tu móvil.

## 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](/docs/es/api/proxy/#un-proxy-en-otro-origen)), `onProgress` (solo con `interpretation: 'stream'`), `correlationId` (un prefijo para `X-Correlation-Id`), `channels`, `kodec` (ver [CSP y transcripción](/docs/es/guides/csp-transcription/)), `startup` (`timeouts`, `locale`, `messages`, `report`, `includeUserAgent`; una clave desconocida lanza `UnknownOptionError`) y `onStartupStage` ([La pantalla de arranque](#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](/docs/es/guides/timeouts/). 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.
