Ir al contenido
DevLab

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.

En esta página
  1. Para decidir
  2. Adónde va el vídeo
  3. Qué depende del dispositivo
  4. Antes de empezar
  5. Comprobar el equipo
  6. Si no puede llegar la voz
  7. Durante y después
  8. Para la persona medida
¿Cuál elijo?
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 dispositivoEn el dispositivo (tiempo real)
usas móviles modestos, sesiones de varios minutos, o el ritmo de tus sesiones queda bajoDiferido (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 estableDiferido (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 daEn 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 infraestructuraAutoalojado (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 framesAPI HTTP
solo quieres medir, sin interpretaciónMeasurement, en el dispositivo (tiempo real) (en diferido también, desde 0.27.0)
dudasEl camino por defecto: SDK en el dispositivo, empezando por Measurement

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.

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 con transcribe.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.

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.

JavaScript
// 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 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).

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

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.

JavaScript
// 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 startup
const 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.

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.