Ir al contenido
DevLab

Cargar los modelos

Las cinco maneras de cargar en el navegador los modelos de la cara y de la voz, cuál elegir, qué se descarga y de dónde, y cómo comprobarlo en tu app.

En esta página
  1. En resumen
  2. Qué manera elegir
  3. Las cinco maneras
  4. A · Sin preparar
  5. B · Preparar en la pantalla anterior
  6. C · La voz tras el consentimiento
  7. D · Calentar la caché en otra página
  8. E · Varias sesiones
  9. Qué se descarga
  10. Qué ve la persona
  11. Compruébalo en tu app
  12. Qué puede salir mal

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.

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

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.

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

JavaScript
// 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
}

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().

JavaScript
// 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()
}

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.

JavaScript
// 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
}

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.

JavaScript
// 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' } })

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.

JavaScript
// 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é 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). Lo que la persona debe saber: Privacidad y datos.

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 y Timeouts.

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.

  • La captura lo vuelve a descargar todo: preparaste en otro cliente. Solo adopta la siguiente captura del mismo cliente (trampa).
  • 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).
  • 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 y Guardar los modelos entre capturas. Si este dispositivo puede medir y transcribir: Dispositivos, calidad y modo.