Dispositivos, calidad y modo
Qué modo encaja con los dispositivos de tu gente, qué depende del dispositivo, cómo comprobarlo antes de medir y cómo leer después el ritmo de la sesión.
Para decidir
Sección titulada «Para decidir»| Si… | Elige |
|---|---|
| tu gente usa escritorio o móviles recientes y quieres resultados durante la sesión (en capturas cortas; las largas tardan minutos en cerrarse) | En el dispositivo (tiempo real) |
| el vídeo no puede salir del dispositivo | En el dispositivo (tiempo real) |
| usas móviles modestos, sesiones de varios minutos, o el ritmo de tus sesiones queda bajo | Diferido (en servidor): hoy puedes grabar, subir y procesar con el servicio de procesado de Neurologyca, sin desplegar nada. |
| no sabes qué dispositivos usará tu gente, o sus móviles son muy distintos, y quieres la calidad más estable | Diferido (en servidor) (Preview): el vídeo sale del dispositivo, se sube y se procesa en el servidor, así que esperas el resultado tras la subida. Tu organización tiene que tenerlo activado. |
| quieres tiempo real por defecto y una salida cuando el dispositivo no da | En el dispositivo (tiempo real) por defecto, y Diferido (en servidor) (Preview), con permiso de la persona, cuando la comprobación del dispositivo dice que no puede medir o no puede transcribir. Tu organización tiene que tenerlo activado. |
| el vídeo debe procesarse fuera del dispositivo pero dentro de tu infraestructura | Autoalojado (próximamente); hasta entonces, diferido con nuestro servicio. |
| capturas en el navegador y luego consultas desde tu backend (resultados, sondeo, catálogo) | SDK + API (lo habitual) |
| capturas desde otro lenguaje u otra plataforma, o ya tienes los frames | API HTTP |
| solo quieres medir, sin interpretación | Measurement, en el dispositivo (tiempo real) (en diferido también, desde 0.27.0) |
| dudas | El camino por defecto: SDK en el dispositivo, empezando por Measurement |
Adónde va el vídeo
Sección titulada «Adónde va el vídeo»En el dispositivo, vídeo y audio no salen del equipo. El diferido (en servidor) es Preview y solo funciona si tu organización lo tiene activado: sube el vídeo. Qué envía cada modo: Dónde se procesa.
Qué depende del dispositivo
Sección titulada «Qué depende del dispositivo»Decide por capacidades, nunca por el navegador ni el modelo de móvil:
| Nivel | Veredicto | Qué hacer |
|---|---|---|
| Puede medir | 'ok' |
Mide |
| Puede medir con límites | 'degraded' (en vivo: wasm-simd) |
Mide; el ritmo lo dirá |
| No puede medir | 'unsupported' |
El remedio del check que falla; si es capture-route, ofrece el diferido |
- El ritmo depende de la detección facial de MediaPipe en la GPU (WebGL 2). Con solo la cara, la CPU no es necesariamente más lenta, pero sus landmarks difieren: compara sesiones con el mismo
delegate. - Sin WebGPU, el equipo no puede transcribir (
blocker: 'no-webgpu') salvo contranscribe.allowWasmWorker, más lento, o ofrece el diferido en su lugar. Transcribir cuesta ritmo. - Manos y cuerpo vienen apagados: cuestan ritmo y Engine los descarta.
- Los móviles se frenan al calentarse; los primeros segundos no cuentan.
- iOS no deja apagar la ganancia automática del micrófono; Safari e iOS guardan solo la cara entre sesiones.
- Modo privado: sin caché persistente; la grabación vive en memoria (
recording.storage-memory). - Diferido: la calidad depende del bitrate y de la luz, no de la potencia del dispositivo; los móviles graban en vertical (
recording.handheld). - Guía de kodec: GPU con WebGL 2, 8 GB de memoria, cámara 720p.
Antes de empezar
Sección titulada «Antes de empezar»Es capacidad, no calidad: el ritmo solo se sabe al medir. Un prepare() sin modelos no carga nada: comprueba este navegador y equipo, sin cámara ni permisos, y da capture ('ok', 'degraded', 'unsupported' o null) y un DeviceCheck por check. captureCacheStatus() dice si los pesos de la voz están en caché; recorder.prepare() añade indexeddb y storage-quota.
Comprobar el equipo
Sección titulada «Comprobar el equipo»// Before measuring: no permission, no call to Engine. Without `keepPrepared`, call it before// preparing: a prepare() with other options releases the current one.
/** @typedef {import('@neurologyca/capture').DeviceCheck} DeviceCheck *//** @typedef {'live' | 'record'} Mode */
// A `fail` blocks the capture. Recording also needs MP4 and IndexedDB.const BLOCKS = { live: new Set(['secure-context', 'get-user-media', 'capture-route']), record: new Set(['secure-context', 'get-user-media', 'capture-route', 'media-recorder-mp4', 'indexeddb']),}// `warn` or `fail` limits it; storage only when recording. Speech checks never limit it.const LIMITS = { live: new Set(['wasm-simd']), record: new Set(['wasm-simd', 'storage-persisted', 'storage-quota']),}
/** * Reads a device diagnosis: the SDK's verdict, what blocks, what limits and whether speech can come. * @param {{ capture: 'ok' | 'degraded' | 'unsupported' | null, device: readonly DeviceCheck[] }} r what prepare() settled with * @param {Mode} mode `'live'` or `'record'` (deferred mode, Preview) * @returns {{ verdict: 'ok' | 'degraded' | 'unsupported' | null, blocking: DeviceCheck[], limiting: DeviceCheck[], speech: 'possible' | 'impossible' | 'unknown' }} */export function readDiagnosis(r, mode) { const blocking = r.device.filter((c) => BLOCKS[mode].has(c.id) && c.status === 'fail') const limiting = r.device.filter((c) => LIMITS[mode].has(c.id) && (c.status === 'warn' || c.status === 'fail')) // The WebGPU adapter: only checked when speech is asked for (with no model, 'unknown'). const gpu = r.device.find((c) => c.id === 'webgpu-adapter')?.status const speech = gpu === 'fail' ? 'impossible' : gpu === 'pass' ? 'possible' : 'unknown' // null: a deciding check did not answer; the capture checks again. return { verdict: r.capture, blocking, limiting, speech }}
/** @typedef {import('@neurologyca/capture').ProtocolClientHandle} ProtocolClientHandle *//** @typedef {import('@neurologyca/capture/record').RecordingClientHandle} RecordingClientHandle *//** @typedef {ReturnType<typeof readDiagnosis>} Diagnosis */
/** * Diagnoses the device with no model. `'live'` (default) with a live client, `'record'` with a recording client. * @overload * @param {ProtocolClientHandle} client * @param {'live'} [mode] * @returns {Promise<Diagnosis>} *//** * @overload * @param {RecordingClientHandle} client * @param {'record'} mode * @returns {Promise<Diagnosis>} *//** * @param {ProtocolClientHandle | RecordingClientHandle} client * @param {Mode} [mode] * @returns {Promise<Diagnosis>} */export async function checkDevice(client, mode = 'live') { const result = mode === 'record' ? await client.prepare() : await client.prepare({ models: { face: false, speech: false } }) return readDiagnosis(result, mode)}Si no puede llegar la voz
Sección titulada «Si no puede llegar la voz»Si habrá voz solo se sabe al preparar la voz o al empezar a transcribir: una comprobación sin modelos no lo dice. Si se rechaza la voz (transcription: 'unavailable'), ofrece grabar, con permiso (diferido, Preview, si tu organización lo tiene activado): transcribe en el servidor. Con WebGPU, pedirla descarga la cara (unos 13,5 MB) y la voz (unos 160 MB).
// Speech is only known by asking for it; deferred is Preview, only if your organization has it turned on.import { checkDevice, readDiagnosis } from './check-device.mjs'
/** * @param {object} o * @param {import('@neurologyca/capture').ProtocolClientHandle} o.client your live client, with `transcribe` * @param {import('@neurologyca/capture/record').RecordingClientHandle} o.recorder your recording client * @param {() => Promise<boolean>} o.askToRecord your UI: asks consent to upload the video and process it on the server * @returns {Promise<{ mode: 'live', speech: boolean } | { mode: 'record' } | { mode: 'none', blocking: import('@neurologyca/capture').DeviceCheck[] }>} */export async function chooseMode({ client, recorder, askToRecord }) { const live = await checkDevice(client, 'live') const canLive = live.verdict !== 'unsupported' if (canLive) { // Downloads the face and speech models and waits. The next capture adopts them; with keepPrepared, // later ones too, and asking for another part releases them. const prepared = await client.prepare({ models: { face: true, speech: true } }) if (prepared.transcription !== 'unavailable' && readDiagnosis(prepared, 'live').speech !== 'impossible') return { mode: 'live', speech: true } }
// Only diagnoses: no load, no camera. const rec = await checkDevice(recorder, 'record') const canRecord = rec.verdict === 'ok' || rec.verdict === 'degraded' if (canRecord && (await askToRecord())) { client.release() // the recording takes over return { mode: 'record' } } // Not recording: live without speech, or what blocks. return canLive ? { mode: 'live', speech: false } : { mode: 'none', blocking: live.blocking }}Durante y después
Sección titulada «Durante y después»onCodecEvent('capture-quality') da cerca de una ventana por segundo, un kodec.CaptureQuality. Describe el ritmo, sin calificarlo: sin las dos primeras ventanas, las ocultas ni las de fps: null, da la mediana (si es par, la media de las dos centrales), las ventanas bajo 8 fps y la más baja; redondea solo al pintar.
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.
// After measuring: the session rate, described, never graded. Feed it the 'capture-quality' windows.
/** @typedef {{ fps: number | null, hidden: boolean }} RateWindow *//** @typedef {'counted' | 'low' | 'skipped' | 'hidden'} WindowState *//** * @typedef {object} SessionRate * @property {number} counted the windows that count (low ones included) * @property {number | null} median the median fps of those windows; null without any * @property {number} lowWindows how many of them fall below the floor * @property {number | null} lowest the lowest fps of them; null without any * @property {'steady' | 'low' | 'none'} verdict `'none'` without a counted window, `'low'` with a low one, `'steady'` otherwise * @property {readonly { fps: number | null, state: WindowState }[]} windows every window in order, at most 600 */
const STARTUP = 2 // the first two windows are the startupconst MAX_WINDOWS = 600 // the strip keeps 600 (ten minutes); the counts cover all
/** * @param {readonly RateWindow[]} windows * @param {number} floor the floor, kodec.PULSE_MIN_FPS * @returns {SessionRate} */export function sessionRate(windows, floor) { /** @type {{ fps: number | null, state: WindowState }[]} */ const strip = [] /** @type {number[]} */ const fps = [] windows.forEach((w, i) => { /** @type {WindowState} */ let state if (i < STARTUP || w.fps === null || !Number.isFinite(w.fps)) state = 'skipped' else if (w.hidden) state = 'hidden' // a hidden tab is throttled: it says nothing of the device else { state = w.fps < floor ? 'low' : 'counted'; fps.push(w.fps) } if (strip.length < MAX_WINDOWS) strip.push({ fps: w.fps, state }) }) const lowWindows = fps.filter((x) => x < floor).length return { counted: fps.length, median: median(fps), lowWindows, lowest: fps.length ? Math.min(...fps) : null, verdict: fps.length === 0 ? 'none' : lowWindows > 0 ? 'low' : 'steady', windows: strip, }}
/** @param {number[]} xs @returns {number | null} */function median(xs) { if (!xs.length) return null const a = [...xs].sort((x, y) => x - y) const mid = a.length >> 1 return a.length % 2 ? a[mid] : (a[mid - 1] + a[mid]) / 2}Un droppedTotal mayor que cero es un aviso aparte; delegate, un dato para comparar. minFps y maxFps incluyen el arranque y la pestaña oculta. Tampoco son el ritmo capture.throttled, relativo al ritmo de la propia sesión, ni quality.warning, de Engine.
Para la persona medida
Sección titulada «Para la persona medida»Léeselo a la persona antes de medir, o ponlo en tu pantalla de captura:
- Ponte de cara a la luz: que te ilumine de frente, sin una ventana detrás.
- Siéntate a la distancia de un brazo de la cámara, con toda la cara a la vista.
- Mira a la pantalla y muévete poco; no hace falta estar inmóvil.
- Deja esta pestaña delante y a la vista hasta el final: una pestaña oculta frena la captura.
- Cierra las otras apps y pestañas que usan la cámara o la tarjeta gráfica (videollamadas, juegos, editores).
Y, por cada aviso que el SDK ya da (onWarning), la frase para la persona:
| Aviso | Qué decirle |
|---|---|
quality.warning |
La imagen no es lo bastante buena. Ponte de cara a la luz, con la cara a la vista, y muévete poco. |
source.ended |
El vídeo terminó, así que esta parte ha acabado. |
capture.throttled |
La captura se ha frenado. Deja esta pestaña delante y a la vista, y cierra lo que no necesites. |
recording.rotate-to-portrait |
Pon el móvil en vertical: la grabación solo empieza así. |
El resto de las condiciones de la persona, y lo que comprueba Engine: Cómo capturar para la máxima precisión.