# Dispositivos, calidad y modo

## 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

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](/docs/es/start/paths/#dónde-se-procesa).

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

## 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

```js
// 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

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

```js
// 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

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

```js
// 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.

## 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](/docs/es/concepts/capture/).
