# Diferido (en servidor)

**Preview**

> Preview: el procesado en servidor es el servicio de procesado de Neurologyca, lo único disponible hoy; alojarlo tú mismo llegará más adelante. El manifiesto puede cambiar. Úsalo solo con personas que hayan dado su consentimiento informado; lo cubre el Anexo de tratamiento de datos (DPA) que tu organización acepta con los Términos de DevLab.

El SDK graba el vídeo y un manifiesto de steps y los sube; nuestro servicio de procesado lo procesa poco después. No son horas: simplemente no se procesa en el dispositivo. [Mira el ejemplo en el playground](/playground#deferred).

## El bucle, de un vistazo

Navegador (createRecordingClient → uploadRecording) → Tu receptor (createUploadReceiver.onComplete) → Tu backend (lo encarga al servicio (submit)) → Servicio de procesado (Preview) → De vuelta a tu backend (URL del token mientras corre · webhook / getJob) → interpreting → succeeded (lees /results + interpretación)

El procesado es Preview. Responde el webhook 2xx rápido y trabaja después; deja de sondear en succeeded o failed.

1. **Página** — `createRecordingClient`, el mismo bucle de steps que en el dispositivo; `session.stop()` da la grabación.
2. **Página** — `uploadRecording(recording, { url })` la sube en trozos y borra la copia local solo cuando tu receptor confirma.
3. **Tu backend** — el `onComplete` de tu receptor firma una URL para el vídeo y encarga el trabajo al servicio de procesado.
4. **Tu backend** — el servicio reproduce la captura contra Engine (transcribiendo la grabación y pasando a Engine solo el texto de los steps que pide el trabajo) y avisa a tu webhook; sondea `getJob` si no llega. Responde el webhook `2xx` rápido y trabaja después, y **deja de sondear cuando el trabajo sea `succeeded` o `failed`**.

## El modo, de un vistazo

| Tema | Diferido (en servidor) · Preview |
| --- | --- |
| Hoy | Puedes grabar, subir y procesar con el servicio de procesado de Neurologyca: nada que desplegar. |
| Dónde se procesa | En nuestro servicio de procesado, poco después de subir. No son horas: simplemente no se procesa en el dispositivo. |
| Cuándo hay resultados | Unos minutos después de subir, sumando tres tramos: la subida (unos 7 min para 3 min de vídeo a 1,75 Mbps, un cálculo), la cola (un trabajo cada vez) y el procesado, algo más largo que el propio vídeo. |
| Qué sale del dispositivo | Vídeo y audio (con la cámara, el micrófono va siempre) hacia tu receptor y, de ahí, al servicio de procesado, que, con la transcripción activada, transcribe todo el audio de la grabación y solo pasa a Engine el texto de los steps que pide el trabajo (`transcribeSteps`). El audio crudo identifica a una persona más que los números, y el manifiesto que viaja con el vídeo lleva el `userAgent` completo del navegador. |
| Qué te limita | El ancho de banda de subida. A 4 Mbps, 3 min de vídeo son unos 93 MB (unos 310 MB por 10 min). La subida se reanuda tras un corte. La calidad depende del bitrate de la grabación y de la luz, no de la potencia del dispositivo: el procesado corre en el servidor. |
| Navegadores y móvil | Graba MP4/H.264: Chrome y Edge de escritorio, Chrome en Android y Safari en iOS. Un iPhone también graba MP4: su fichero puede acabar unos 1,1 s antes del stop, por eso el SDK sigue grabando 2 s más. En móvil o tableta graba en vertical: espera a que el dispositivo esté derecho. |
| Measurement | Sí, desde 0.27.0: `triggerAnalysis: false` viaja en el manifiesto y el procesador no llama a `/analyze`. |
| Casos típicos | Una entrevista de diez minutos en un móvil modesto; una sesión de campo en un dispositivo flojo, subida después. |
| Pasar de uno a otro | Añade el receptor a tu backend (`createUploadReceiver`); graba desde la cámara, un `<video>` o un stream. |

## Grabar

El cliente de grabación viene de `@neurologyca/capture/record`, que no descarga kodec. Su bucle es el del modo en vivo, con los steps marcados en el vídeo ([Steps y marcado](/docs/es/sdk/steps/)). Los bloques de esta página se publican tal cual se ejecutan, así que sus comentarios están en inglés.

```js
import { createRecordingClient } from '@neurologyca/capture/record'
import { keepScreenOn, guardUnload } from '@neurologyca/capture/helpers'

const recorder = createRecordingClient({ baseUrl: '/engine', tenant })
const session = await recorder.captureProtocol({ userProtocolId, protocolMechanicId, source: { type: 'webcam' } })
```

Antes de grabar en un móvil: pide almacenamiento persistente (`navigator.storage.persist()`), mantén la pantalla encendida (`keepScreenOn`) y protege la pestaña (`guardUnload`) hasta que termine la subida; con el móvil en vertical, `waitForPortraitOrientation`. También puedes grabar un `<video>` (`{ type: 'video', el }`, con su `src` puesto antes) o un `MediaStream` (`{ type: 'stream', stream }`): cuando termina, el SDK avisa `source.ended`.

Desde la 0.42.0, antes de pedir ningún permiso, `recorder.prepare()` te dice si este dispositivo puede grabar: no carga ningún modelo, no abre la cámara y nunca llama a Engine. Además de las comprobaciones de la grabación añade `indexeddb` (sin ella no se puede grabar nada) y `storage-quota` (avisa por debajo de 150 MB libres), y resuelve `ready`, `failed` (con el mensaje `prepare.record-unsupported`; `device` y `capture` dicen qué comprobación falló) o `aborted` (por su `signal`). El cliente de grabación también admite `startup` (`timeouts.gateMs`, `locale`, `messages`, `report`) y `onStartupStage`, y avisa `recording.option-ignored` para `startup.timeouts.vision` y `startup.timeouts.speech`, que una grabación no tiene. `keepPrepared` (desde la 0.43.0) es solo en vivo: `createProtocolClient({ mode: 'record', keepPrepared })` la ignora con el mismo aviso `recording.option-ignored` (una grabación no carga ningún modelo, y `captureBaseline` no guarda nada en modo grabación), y `createRecordingClient` lanza `E_UNKNOWN_OPTION` con ella. En modo grabación no se emite `SessionReport`, así que el informe de arranque solo te llega con `startup.report.url` ([Tu backend](/docs/es/sdk/backend/#los-informes-de-arranque-opcional)). El `signal` de `captureProtocol` actúa hasta que resuelve.

> Usa 0.27.2 o posterior para grabar un `<video>` o un stream: con 0.27.0, el servicio de procesado rechaza uno que termina (`E_MANIFEST_INVALID`), y 0.27.0 y 0.27.1 lo graban a la frecuencia de refresco de la pantalla, así que Engine tarda varias veces más.

## Qué se graba

MP4 con vídeo H.264 y audio AAC, a unos 4 Mbps por defecto (`recording.videoBitsPerSecond`). A la cámara se le piden 1280×720 (`ideal`: una preferencia, no una garantía), y `RecordingManifest.recorder` dice el tamaño que obtuvo. Con la cámara, el micrófono se graba siempre. Una grabación lleva como mucho 30 fotogramas por segundo, sea cual sea la fuente (`recording.maxFps`, de 1 a 120): el servicio de procesado reproduce cada fotograma a Engine, y su tiempo crece con ellos. Si un stream no se puede limitar, la grabación sigue tal cual y el SDK avisa una vez con `recording.fps-high`. La grabación se guarda en este navegador (IndexedDB) hasta que se sube.

La calidad de una captura en diferido depende del bitrate de la grabación y de la luz, no de la potencia del dispositivo: el procesado corre en el servidor. En un móvil o una tableta se graba en vertical: si el dispositivo está en horizontal, la cámara no se abre y sale `recording.rotate-to-portrait` hasta que se pone derecho (`waitForPortraitOrientation` lo espera antes de empezar); `recording.handheld` corrige un dispositivo mal detectado (`false` graba en horizontal, para un quiosco tomado por un móvil). Elegir el modo por dispositivo: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/).

## Subir

`session.stop()` entrega un `RecordingResult` (`blob`, `manifest`, `release()`, `storage`). `uploadRecording(recording, { url })` la sube por trozos a tu receptor, continúa donde se quedó y reintenta los errores de red (6 veces por defecto, respetando `Retry-After`); solo borra la copia local cuando tu receptor confirma (el `200` de `complete`) o contesta `410`. Si no puede, rechaza con `UploadRecordingError` (`code`, `status`, `retryable`):

| Código | Cuándo | Reintentable | Qué haces |
| --- | --- | --- | --- |
| `E_UPLOAD_NETWORK` | Red, 5xx, 408 o 429 tras los reintentos | Sí | Llama más tarde: la copia local sigue |
| `E_UPLOAD_NOT_NOTIFIED` | Tu receptor la guardó pero su `onComplete` falló (por ejemplo, el servicio de procesado está caído o no acepta tu key) | Sí | Dile al usuario que está subida; tu backend reintenta `onComplete` por su cuenta (`receiver.notify()`), o llama más tarde |
| `E_UPLOAD_AUTH` | 401: sin sesión | Sí, tras iniciar sesión | Inicia la sesión del usuario y llama otra vez |
| `E_UPLOAD_REJECTED` | 403, 400, 413, 415 o demasiadas subidas abiertas | No | No es de este usuario o está mal formada |
| `E_UPLOAD_CONFLICT` | 409 sin forma de resincronizar | No | Avisa al usuario |
| `E_UPLOAD_TOO_LARGE` | Pasa de `maxBytes` | No | Graba más corto o con menos bitrate |
| `E_UPLOAD_LOCAL_UNREADABLE` | La copia local ya no se puede leer | No | `abandonUpload` |
| `E_UPLOAD_PROTOCOL` | Tu receptor contesta algo imposible | No | Revisa el receptor |
| `E_UPLOAD_ABORTED` | Tu propio `signal` | Sí | Llama otra vez cuando quieras continuar |

## Grabaciones pendientes y dispositivos compartidos

`listPendingRecordings()` devuelve lo que se grabó y no se subió en este navegador: fíltralo por el usuario con sesión antes de ofrecerlo. `abandonUpload(captureId, { url })` renuncia a una; `recording.release()` borra la copia local.

`abandonUpload` solo renuncia a una subida sin terminar: cuando `complete` ya la guardó, tu receptor responde 409 `E_ALREADY_COMPLETE`, porque una subida completa es de tu backend. Para cancelarla entonces, llama a una ruta de tu propio backend que cierre su trabajo, deje de dar tokens para él y borre el vídeo (`receiver.remove()`), y di al usuario que se descartó solo cuando tu backend lo confirme.

## Si algo falla a mitad

La cámara se para o se cierra la pestaña: `E_RECORDING_LOST`, no se guarda nada; graba de nuevo. Sin espacio: `E_STORAGE_FULL`. El navegador no sabe grabar MP4/H.264: `E_RECORDER_UNSUPPORTED` (Firefox no es objetivo: kodec no se ha probado allí, y Firefox de escritorio no graba MP4/H.264). Un `captureId` que ya tiene una grabación aquí: `E_CAPTURE_ID_IN_USE`. Una subida cortada por la red continúa en la siguiente llamada.

## Tu receptor

Tu backend recibe los trozos con `createUploadReceiver`, de `@neurologyca/capture-server`: autentica a tu usuario, comprueba que la inscripción es suya antes del primer byte (`checkManifest`) y llama a `onComplete` una vez por grabación. Cómo encaja con el proxy y la retención: [Tu backend](/docs/es/sdk/backend/#el-receptor-de-subidas).

```js
// Your backend for the deferred mode (Node 20.3+): the upload receiver. Mount both BEFORE any body parser:
//   if (req.url.startsWith('/uploads/')) return listener(req, res)
//   /media/<captureId>/video, the signed video the processing service downloads: return media(req, res)
import { createUploadReceiver } from '@neurologyca/capture-server'
import { localDiskStorage, toNodeListener } from '@neurologyca/capture-server/node'

/**
 * @param {object} o
 * @param {string} o.dir a private directory for the recordings
 * @param {string} o.urlSecret 32+ characters, for the signed URLs of the videos
 * @param {(req: Request) => Promise<string | null>} o.signedIn your session: a subject (your user id) or null
 * @param {(subject: string, userProtocolId: string, protocolMechanicId: string) => Promise<boolean>} o.ownsPair is this enrolment the user's?
 * @param {(captureId: string) => Promise<void>} o.onRecording a recording is complete: submit it to the processing service (or keep it, if you process it yourself)
 */
export function uploadsHandler(o) {
  const receiver = createUploadReceiver({
    mountPath: '/uploads',
    storage: localDiskStorage({ dir: o.dir }),
    urlSecret: o.urlSecret,
    authorize: (req) => o.signedIn(req), // null answers 401; never throw here
    checkManifest: (subject, m) => o.ownsPair(subject, m.userProtocolId, m.protocolMechanicId), // refused before the first byte
    onComplete: ({ captureId }) => o.onRecording(captureId), // must be idempotent per captureId
    onError: (_error, ctx) => console.error(`upload receiver: ${ctx.piece} ${ctx.route ?? ''} ${ctx.captureId ?? ''}`), // never the body or a URL
  })
  return { receiver, listener: toNodeListener(receiver.handler), media: toNodeListener(receiver.mediaHandler) }
}
```

## Transcripción

El cliente de grabación no tiene opción `transcribe`: en diferido transcribe el servicio de procesado. Qué steps llegan a Engine con su texto se decide por trabajo: cada `submit` de tu backend lleva los `transcribeSteps` y el `language` de esa captura ([Mandar una grabación](/docs/es/sdk/processing/#mandar-una-grabación)); `[]` es siempre nada; ausente es nada con el servicio alojado. Ten en cuenta que el audio sale hacia el servicio, que transcribe todo el audio en el servidor, también lo que se dice entre steps; en el dispositivo, el audio nunca sale del navegador ([En el dispositivo (tiempo real)](/docs/es/sdk/on-device/#transcripción)).

El idioma del transcrito es el `language` del trabajo; el de la **interpretación** es el de la persona, `narrative.language`, fijado al crearla o actualizarla ([Tu backend](/docs/es/sdk/backend/#personas-e-inscripciones-createengineadmin)). Si el usuario cambia de idioma entre crear la persona y grabar, el transcrito sigue el idioma nuevo y la interpretación se queda en el anterior: actualiza antes la persona (`updateUser` con `narrative`). En el playground de DevLab, la persona de prueba se crea con el idioma de la interfaz la primera vez que mides, grabas o capturas el baseline; si después cambias el idioma de la interfaz, cambia el transcrito y la interpretación mantiene el idioma de la persona hasta que uses una persona nueva.

## El trabajo: webhook y sondeo

Cuando tu receptor entrega una grabación, el servicio de procesado contesta con un `jobId`. El webhook firmado es el aviso; `processor.getJob(jobId)` es la forma de sondear el trabajo (`status`, `outcome`, `errorCode`, `retryable`, `attempt` y, desde `capture-server` 0.11.0, `interpretation`). El trabajo espera la interpretación en `interpreting`, que cuenta como en curso, y acaba `succeeded` aunque la interpretación salga mal: qué hacer con cada valor, en [La interpretación](/docs/es/sdk/processing/#la-interpretación). El contrato del webhook: [Resultados en tu backend](/docs/es/sdk/results-backend/#el-webhook-del-diferido-como-contrato); el servicio: [Servicio de procesado](/docs/es/sdk/processing/).

```js
const job = await processor.getJob(jobId) // status: queued, downloading, preparing, transcribing, replaying, waiting, interpreting, succeeded or failed; interpretation on a succeeded
```

**Cada cuánto sondear.** El SDK no fija un intervalo para `getJob` ni sondea por su cuenta: lo eliges tú. Un trabajo tarda minutos (la reproducción y, por defecto, hasta 300 s más en `interpreting`), y más si se reintenta. Cada pocos segundos basta mientras alguien espera en pantalla, menos a menudo si nadie espera, y para en `succeeded` o `failed`. Si `getJob` rechaza con un `ProcessorError` que trae `retryAfterMs`, espera al menos eso. Como referencia, el playground de DevLab pregunta a su servidor cada 3 s, su servidor llama a `getJob` como mucho una vez cada 2 s por grabación y la página espera hasta 40 minutos.

## Qué puedes hacer hoy

Grabar, subir y procesar con el servicio de procesado de Neurologyca, lo único disponible hoy y activado para tu organización: la URL del servicio y su IP de salida están en tu kit, y la clave del procesador y el secreto del webhook, una sola pareja que la comparten todos los equipos, llegan en el zip de tu starter de grabación con **Incluir mi key y las credenciales del procesador** (el equipo admin de tu organización los rota en [Tu cuenta](/account)). Tu backend expone tres rutas HTTPS públicas bajo `PUBLIC_BASE_URL` ([Servicio de procesado](/docs/es/sdk/processing/)). Sin esos valores, graba y sube contra tu propio receptor sin procesado: `onComplete` guarda la grabación y no la entrega, que es como corre el ejemplo de grabación del propio SDK con el procesado apagado. Alojar el procesador tú mismo llegará más adelante. Measurement en diferido se midió de punta a punta el 2026-10-12.

## Probar en tu móvil

HTTPS hasta el móvil, como en el dispositivo ([Probar en tu móvil](/docs/es/sdk/on-device/#probar-en-tu-móvil)), y además: sujeta el móvil en vertical, mantén la pantalla encendida y la pestaña delante hasta que termine la subida (Chrome en Android no muestra el aviso de salida). Un iPhone también graba MP4: su fichero puede acabar unos 1,1 s antes del stop, por eso el SDK sigue grabando 2 s más tras el último step. El tiempo de subida depende de tu red: a 4 Mbps, 3 minutos de vídeo son unos 93 MB.
