Ir al contenido
DevLab

Diferido (en servidor)

El cliente de grabación: graba el vídeo y un manifiesto de steps, súbelos a tu receptor y sigue el trabajo del servicio de procesado.

En esta página
  1. El bucle, de un vistazo
  2. El modo, de un vistazo
  3. Grabar
  4. Qué se graba
  5. Subir
  6. Grabaciones pendientes y dispositivos compartidos
  7. Si algo falla a mitad
  8. Tu receptor
  9. Transcripción
  10. El trabajo: webhook y sondeo
  11. Qué puedes hacer hoy
  12. Probar en tu móvil
Preview

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.

  1. NavegadorcreateRecordingClient → uploadRecording
  2. Tu receptorcreateUploadReceiver.onComplete
  3. Tu backendlo encarga al servicio (submit)
  4. Servicio de procesadoPreview
  5. De vuelta a tu backendURL del token mientras corre · webhook / getJob
  6. interpreting → succeededlees /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.
Diferido (en servidor)
TemaDiferido (en servidor) · Preview
HoyPuedes grabar, subir y procesar con el servicio de procesado de Neurologyca: nada que desplegar.
Dónde se procesaEn nuestro servicio de procesado, poco después de subir. No son horas: simplemente no se procesa en el dispositivo.
Cuándo hay resultadosUnos 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 dispositivoVí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 limitaEl 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óvilGraba 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.
MeasurementSí, desde 0.27.0: triggerAnalysis: false viaja en el manifiesto y el procesador no llama a /analyze.
Casos típicosUna 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 otroAñade el receptor a tu backend (createUploadReceiver); graba desde la cámara, un <video> o un stream.

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). Los bloques de esta página se publican tal cual se ejecutan, así que sus comentarios están en inglés.

JavaScript
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). El signal de captureProtocol actúa hasta que resuelve.

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.

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

Sección titulada «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.

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

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

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); [] 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)).

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

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. El contrato del webhook: Resultados en tu backend; el servicio: Servicio de procesado.

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

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). Tu backend expone tres rutas HTTPS públicas bajo PUBLIC_BASE_URL (Servicio de procesado). 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.

HTTPS hasta el móvil, como en el dispositivo (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.