# Cargar los modelos

Por defecto no hay nada que hacer: la captura carga los modelos al empezar. Preparar solo adelanta esa espera a un momento en que la persona hace otra cosa. Es el modo en el dispositivo; grabar para el diferido no descarga ningún modelo.

## En resumen

- Sin preparar, la espera se ve entre Empezar y el primer frame; para una sola sesión vale.
- Preparar carga antes el modelo de la cara, en el **mismo cliente** que va a capturar, y nunca llama a Engine ni pide permisos.
- La voz es una descarga grande: pídela solo cuando la persona haya aceptado.
- En Safari e iOS solo se adelanta la cara; la voz carga al empezar la captura.
- Con varias sesiones, `keepPrepared` guarda los modelos de una a la siguiente hasta que los sueltas.

## Qué manera elegir

| Tu caso | Manera | Por qué |
| --- | --- | --- |
| Una sesión | A o B | A no pide nada; B esconde la espera tras una pantalla tuya |
| Con transcripción | C | La voz, solo cuando la persona acepta |
| Varias sesiones | E | Desde la segunda sesión se reutilizan los modelos: ni descarga ni carga de los modelos de nuevo (la cámara y el primer frame sí arrancan) |
| Con baseline | E | El baseline adopta la cara preparada y deja la voz para la medición |
| Un móvil, o el ahorro de datos | B | La cara antes; la voz al pulsar Empezar, no antes |
| Safari o iOS | cualquiera | Solo la cara queda lista antes; la voz carga al empezar la captura |
| Sin WebGPU | B o E, solo la cara | La transcripción se rechaza salvo que permitas `transcribe.allowWasmWorker` (más lenta); donde se rechaza, con E, no prepares entre sesiones |
| Un dispositivo para varias personas | E | `client.release()` entre una persona y la siguiente (un quiosco, una tableta compartida) |
| Dos pestañas de tu app | un cliente por página | Cada pestaña es una página que carga sus modelos; solo comparten la caché del navegador |
| Una página antes, del mismo origen | D | Calienta la caché del navegador; nada queda en memoria |

## Las cinco maneras

De menos a más trabajo. En cada bloque, `/engine` es el proxy de tu backend (el navegador nunca ve la key) y `your_context_id` es el `contextId` de tu kit.

### A · Sin preparar

**Cuándo:** una sesión, sin prisa por el arranque. **Qué gana:** ninguna llamada. **Qué cuesta:** la espera, visible, hasta el primer frame.

```js
// A · Without preparing: the capture loads the models when it starts, and the person waits until the first frame.
import { createProtocolClient } from '@neurologyca/capture'

// /engine is your backend's proxy: the browser never sees the key. Replace your_context_id with the contextId of your kit.
const client = createProtocolClient({ baseUrl: '/engine', taxonomy: { contextId: 'your_context_id' } })

/** @param {{ userProtocolId: string, protocolMechanicId: string }} pair from your backend */
export async function measure(pair) {
  const session = await client.captureProtocol({ ...pair, source: { type: 'webcam' } })
  // … the session's steps …
  return session.stop() // CaptureOutcome
}
```

### B · Preparar en la pantalla anterior

**Cuándo:** un formulario o unas instrucciones antes de medir. **Qué gana:** la cara está lista al pulsar Empezar; la captura la adopta sin opción. **Qué cuesta:** el modelo baja de un CDN de terceros, que ve la IP antes de medir nada, aunque la persona no llegue a medir. Si se va sin medir, `client.release()`.

```js
// B · Prepare on the previous screen: the face model loads while the person fills in a form or reads the instructions.
import { createProtocolClient } from '@neurologyca/capture'

const client = createProtocolClient({ baseUrl: '/engine', taxonomy: { contextId: 'your_context_id' } })

// When the form or the instructions show. The face only: no permission and no call to Engine.
// Note: the model comes from a third-party CDN, which sees the IP, even if the person never measures.
export function onInstructionsShown() {
  void client.prepare({ models: { face: true } })
}

/** On Measure, the capture adopts the face model already loaded, with no option. @param {{ userProtocolId: string, protocolMechanicId: string }} pair */
export async function onMeasure(pair) {
  const session = await client.captureProtocol({ ...pair, source: { type: 'webcam' } })
  // … the session's steps …
  return session.stop()
}

// If the person leaves this view without measuring: what was prepared stays in memory until you release it.
export function onLeave() {
  client.release()
}
```

### C · La voz tras el consentimiento

**Cuándo:** con transcripción. **Qué gana:** la voz carga tras tu pantalla de consentimiento, mientras la persona lee lo siguiente. **Qué cuesta:** unos 160 MB la primera vez; después, de la caché. `prepare()` no pide el micrófono, así que el navegador no avisa de esa descarga: tu sí es el único. En Safari e iOS la voz no se prepara y carga al empezar: `estimatedSpeechMs` (una guía que tiende a salir alta) te deja avisar de esa espera; donde el dispositivo no va a transcribir (`'unavailable'`), no la hay.

```js
// C · Speech after consent: a large download on the person's data plan, only once they have said yes.
import { createProtocolClient } from '@neurologyca/capture'

// Speech needs transcription configured on the client.
const client = createProtocolClient({
  baseUrl: '/engine', taxonomy: { contextId: 'your_context_id' }, transcribe: { language: 'en' },
})

/**
 * Called by the «I agree» of your consent screen, never before. prepare() does not ask for the microphone: the capture
 * does, when it starts.
 * @param {(ms: number) => void} showWaitingNote your screen: a note that speech will still take a while at the start
 */
export async function onConsentAccepted(showWaitingNote) {
  const prepared = await client.prepare({ models: { face: true, speech: true } })
  // Not ready ahead, but the capture will load it at the start (Safari and iOS, a slow network); never with 'unavailable'.
  // The estimate tends to come out high; null when it cannot be estimated.
  const speechLater = prepared.transcription === 'not-prepared' || prepared.transcription === 'failed'
  if (speechLater && prepared.estimatedSpeechMs !== null) showWaitingNote(prepared.estimatedSpeechMs)
  return prepared
}
```

### D · Calentar la caché en otra página

**Cuándo:** una landing o una sala de espera del mismo origen. **Qué gana:** los ficheros llegan a la caché del navegador antes de la página de captura; compensa sobre todo con la voz. **Qué cuesta:** nada queda en memoria, así que la captura aún crea los modelos al empezar. Las dos páginas leen la misma configuración, o la captura vuelve a descargar lo que no case.

```js
// D · Warm the cache on an earlier page of the same origin: the files reach the browser's cache, nothing stays in memory.
import { captureCacheStatus, prepareCapture } from '@neurologyca/capture'

// capture-config: one module both pages import, so the files warmed are the ones the capture asks for.
// No baseUrl or taxonomy: there is no client on this page (they would throw E_UNKNOWN_OPTION).
/** @type {import('@neurologyca/capture').CaptureCacheStatusOptions} */
export const captureConfig = { transcribe: { language: 'en' } }

// On the landing page or the waiting room.
export async function warmTheCache() {
  const status = await captureCacheStatus(captureConfig)
  if (status.speechWeights !== 'cached') {
    await prepareCapture({ ...captureConfig, level: 'cache', prepare: { face: true, speech: true } })
  }
}

// On the capture page: the same config, plus what only a client has.
// createProtocolClient({ ...captureConfig, baseUrl: '/engine', taxonomy: { contextId: 'your_context_id' } })
```

### E · Varias sesiones

**Cuándo:** baseline, medir, medir. **Qué gana:** desde la segunda sesión se reutilizan los modelos: ni descarga ni carga de los modelos de nuevo (en Safari e iOS, solo la cara); la cámara y el primer frame sí arrancan. Un `prepare()` antes de la primera sesión y ninguno entre sesiones. **Qué cuesta:** ocupan memoria hasta que los sueltas. El modelo de la cara puede llevar estado del último frame a la sesión siguiente: llama a `client.release()` entre una persona y la siguiente, y antes de soltar el cliente (una vista que se desmonta). Si la persona ya aceptó la voz, pídela en esa misma llamada (`prepare({ models: { face: true, speech: true } })`); si no, la carga la primera medición.

```js
// E · Several sessions (baseline, measure, measure): what each session loads stays for the next one.
import { createProtocolClient } from '@neurologyca/capture'

const client = createProtocolClient({
  baseUrl: '/engine', taxonomy: { contextId: 'your_context_id' }, transcribe: { language: 'en' },
  keepPrepared: true, // what each session loads stays for the next one
})
/** @type {import('@neurologyca/capture').CaptureSource} */
const source = { type: 'webcam' }

/** The same person: a baseline and two measurements, with the ids from your backend.
 * @param {string} userId @param {string} userProtocolId @param {string} firstPm @param {string} secondPm */
export async function baselineAndTwoSessions(userId, userProtocolId, firstPm, secondPm) {
  // Once, before the baseline.
  await client.prepare()
  await client.captureBaseline({ userId, source })

  // No prepare() between sessions: each one adopts what the previous one left.
  const first = await client.captureProtocol({ userProtocolId, protocolMechanicId: firstPm, source })
  await first.stop()
  const second = await client.captureProtocol({ userProtocolId, protocolMechanicId: secondPm, source })
  await second.stop()
}

// Between one person and the next, and before you drop the client (a view that unmounts): what is kept stays in
// memory until then. When the page goes away, the SDK releases it on its own.
export function releaseModels() {
  client.release()
}
```

## Qué se descarga

| Qué | Cuánto | De dónde | Cuánto dura en la caché |
| --- | --- | --- | --- |
| La cara: el runtime de visión y el modelo de la cara | unos 13,5 MB | `cdn.jsdelivr.net`, `storage.googleapis.com` | La caché HTTP del navegador; el modelo de la cara se revalida pasada una hora |
| La voz, solo con transcripción | unos 160 MB la primera vez | `cdn.jsdelivr.net`, `huggingface.co`, `*.hf.co` | El Cache Storage del navegador, hasta que el navegador o la persona borran los datos del sitio |

La caché es del navegador: puede vaciarla cuando quiera, así que no hay un plazo con el que contar. Esos servidores ven la IP del dispositivo y no reciben nada capturado; puedes alojar tú los ficheros ([CSP y transcripción](/docs/es/guides/csp-transcription/)). Lo que la persona debe saber: [Privacidad y datos](/docs/es/resources/privacy/).

## Qué ve la persona

El SDK no pinta nada. `onStartupStage` da cada etapa con `userMessage`, un texto listo (`STARTUP_MESSAGES`); los eventos de una preparación llevan `kind: 'prepare'`, y la pantalla de la captura pinta los suyos. Más: [La pantalla de arranque](/docs/es/sdk/on-device/#la-pantalla-de-arranque) y [Timeouts](/docs/es/guides/timeouts/#el-arranque).

## Compruébalo en tu app

Aquí no hay una cifra de referencia: compruébalo con tus sesiones en tus dispositivos. En `onReport`, `report.startup.prepared` dice qué hizo cada sesión: `face` y `speech` valen `'adopted'` si usaron lo preparado o guardado, `prepared.origin` dice de dónde venía (`'prepare'` o `'previous-session'`; ausente la primera vez que se presta una preparación; aparece desde la segunda sesión), y `faceReloaded` solo aparece, `true`, si tuvo que volver a cargar la cara. `startup.totalMs` es lo que tardó ese arranque; compáralo entre tu primera y tu segunda sesión. Sin nada preparado, `prepared` es `null`.

## Qué puede salir mal

- **La captura lo vuelve a descargar todo:** preparaste en otro cliente. Solo adopta la siguiente captura del mismo cliente ([trampa](/docs/es/resources/pitfalls/#pf-prepare-other-client)).
- **`prepare()` durante una sesión** rechaza con `PrepareError` y `reason: 'capture-in-progress'`: prepara antes, o cuando acabe.
- **Una llamada más estrecha suelta:** `prepare()` solo con la cara tras pedir la voz suelta la voz. Decide una vez qué preparar; en un componente que se monta dos veces, pasa el mismo `signal`, o ninguno.
- **Donde se rechaza la transcripción (sin WebGPU y sin `allowWasmWorker`), preparar la voz entre sesiones** suelta la cara guardada y la vuelve a cargar cada vez: con E, prepara una vez, o solo la cara.
- **La voz no llega a tiempo:** `prepare()` resuelve `partial` con `speech-timeout` o `speech-error`. Empieza igual (la captura vuelve a intentar la voz), sigue sin ella con `captureProtocol({ …, transcribe: false })`, que conserva la cara preparada, u ofrece la captura en diferido.
- **Sin WebGPU** (muchos móviles Android): `transcription: 'unavailable'` y `transcriptionGate.blocker: 'no-webgpu'`; no se descargó nada. Sigue sin voz u ofrece la captura en diferido ([trampa](/docs/es/resources/pitfalls/#pf-no-webgpu-no-speech)).
- **Falla la cara y la voz cargó** (`failed`, `face: 'failed'`, `transcription: 'ready'`): empieza igual; la captura carga la cara y adopta la voz. Si nadie va a empezar, llama a `client.release()`, o se quedan cargados unos 160 MB.
- **La pestaña se cierra en un móvil modesto mientras carga la voz** (memoria): la página se recarga. Prepara la voz justo antes de empezar, o solo la cara.

Más: [Preparar antes de Empezar](/docs/es/sdk/on-device/#preparar-antes-de-empezar) y [Guardar los modelos entre capturas](/docs/es/sdk/on-device/#guardar-los-modelos-entre-capturas). Si este dispositivo puede medir y transcribir: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/).
