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.
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
Sección titulada «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,
keepPreparedguarda los modelos de una a la siguiente hasta que los sueltas.
Qué manera elegir
Sección titulada «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
Sección titulada «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
Sección titulada «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.
// 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
Sección titulada «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().
// 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
Sección titulada «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.
// 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
Sección titulada «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.
// 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
Sección titulada «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.
// 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
Sección titulada «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). Lo que la persona debe saber: Privacidad y datos.
Qué ve la persona
Sección titulada «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 y Timeouts.
Compruébalo en tu app
Sección titulada «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
Sección titulada «Qué puede salir mal»- 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 conPrepareErroryreason: '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 mismosignal, 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()resuelvepartialconspeech-timeoutospeech-error. Empieza igual (la captura vuelve a intentar la voz), sigue sin ella concaptureProtocol({ …, transcribe: false }), que conserva la cara preparada, u ofrece la captura en diferido. - Sin WebGPU (muchos móviles Android):
transcription: 'unavailable'ytranscriptionGate.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 aclient.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.