Ir al contenido
DevLab

Servicio de procesado

Qué hace nuestro servicio de procesado con una grabación, qué le expones, la URL del token, el webhook, sus códigos de error y Measurement en diferido.

En esta página
  1. Qué hace el servicio
  2. Con nuestro servicio, o autoalojado
  3. Mandar una grabación
  4. La URL del token
  5. El webhook
  6. La interpretación
  7. Códigos de error
  8. Measurement en diferido
Preview

Descarga el vídeo de tu backend, repite la captura contra Engine con el mismo SDK (replayRecording, de @neurologyca/capture/replay), transcribe el audio de la grabación (entero, si el trabajo pide algún step) y solo pasa a Engine el texto de los steps que pide cada trabajo (transcribeSteps) y avisa a tu backend con un webhook firmado. No calcula indicadores: los calcula Engine. Tú nunca ejecutas /replay: lo ejecuta el servicio.

Aspecto Con nuestro servicio (disponible hoy) Autoalojado (más adelante)
Qué recibes Nada que desplegar. Una credencial por organización: la URL del servicio (PROCESSOR_URL) y su IP de salida, en tu kit; la clave del procesador (PROCESSOR_API_KEY) y el secreto del webhook (PROCESSOR_SECRET), una sola pareja que la comparten todos los equipos: cualquier equipo activo la recibe en el zip de su starter de grabación con Incluir mi key y las credenciales del procesador, y el equipo admin de tu organización la revela y la rota en Tu cuenta El procesador (una imagen de contenedor) y su guía de alojamiento, para ejecutarlo en tus servidores. Más adelante, sin fechas
Qué expones Tres rutas HTTPS públicas bajo PUBLIC_BASE_URL: el vídeo firmado, la URL del token y el webhook Nada público: un listener interno, alcanzable solo desde la red del procesador
Qué guardas Secretos distintos para las URLs firmadas y el webhook, un almacén de nonces por propósito y una tabla de trabajos Lo mismo
Contexto, idioma, transcripción Por trabajo: cada submit lleva el taxonomy, el language y los transcribeSteps de esa captura Lo mismo; un procesador cuyo cliente los fija acepta los mismos valores o ninguno
  • Limitar las tres rutas a la IP de salida del servicio es defensa en profundidad, no autenticación. Esa IP es la misma para todas las organizaciones: otra puede hacer que el servicio llame a tus rutas desde ella. Lo que te protege es la firma HMAC con tu PROCESSOR_SECRET, que verifican createWebhookHandler y createProcessorTokenHandler, y la firma de la URL del vídeo. No te saltes ninguna, limites por IP o no.
  • PUBLIC_BASE_URL es el origen HTTPS público de tu backend. El servicio acepta cualquier origen https: público y rechaza http:, localhost, las direcciones privadas y de loopback, las redirecciones y las URLs con credenciales (E_DESTINATION_NOT_ALLOWED). Para probar en tu máquina, el servicio no puede llamar a localhost: abre un túnel HTTPS público (por ejemplo cloudflared o ngrok), pon su origen en PUBLIC_BASE_URL y ciérralo al terminar; o despliega. El starter de grabación explica las dos cosas.
  • Si se filtra una credencial, Neurologyca desactiva el acceso de tu organización al servicio (E_CLIENT_DISABLED; los trabajos en curso terminan), tu equipo admin rota en dos pasos —los valores nuevos quedan pendientes hasta que los despliegas y los activas— y el acceso se reactiva. Ningún webhook en curso se firma con un secreto que tu backend aún no tiene: Si se filtra una credencial del procesador.

Desde el onComplete de tu receptor, firma una URL para el vídeo y manda el trabajo con los parámetros de esa captura. Guarda el jobId.

JavaScript
// Your backend, handing a recording to Neurologyca's processing service (Node 20.3+). `url`, `apiKey` and the webhook
// secret come from your DevLab account; `publicBase` is your backend's public HTTPS origin (PUBLIC_BASE_URL), where the
// service calls the video, the token URL and the webhook. Never localhost: to test on your machine, use a public tunnel.
import { createProcessorClient } from '@neurologyca/capture-server'
/**
* @param {object} o
* @param {string} o.url the processing service's URL (PROCESSOR_URL, from your kit)
* @param {string} o.apiKey your key for the service (PROCESSOR_API_KEY; never the Engine key)
* @param {Pick<import('@neurologyca/capture-server').UploadReceiver, 'signedUrl' | 'manifest'>} o.receiver your upload receiver
* @param {string} o.publicBase your backend's public origin for the service (PUBLIC_BASE_URL, HTTPS)
* @param {string} o.engineBase your environment's Engine URL (ENGINE_BASE)
*/
export function processing(o) {
const processor = createProcessorClient({ url: o.url, apiKey: o.apiKey })
return {
// Call it from your receiver's onComplete. Idempotent per captureId: the service answers with the same job.
// `params` are THIS capture's: taxonomy.contextId (your page's) and language (the session's) are required by the
// service; with a non-empty transcribeSteps the service transcribes the whole audio of the recording and passes to Engine only
// the text of the listed step types (absent or [] = nothing is transcribed).
async submit(
/** @type {string} */ captureId,
/** @type {{ taxonomy: import('@neurologyca/capture-server').ProcessorJobTaxonomy, language: string, transcribeSteps?: string[] }} */ params,
) {
const videoUrl = await o.receiver.signedUrl(captureId, { baseUrl: `${o.publicBase}/media` }) // valid 24 h by default
const manifest = /** @type {{ userProtocolId: string, protocolMechanicId: string }} */ (await o.receiver.manifest(captureId))
const { jobId, status } = await processor.submit({
videoUrl, manifest, engineBaseUrl: o.engineBase,
tokenUrl: `${o.publicBase}/processor/token`, webhookUrl: `${o.publicBase}/processor/webhook`,
taxonomy: params.taxonomy, language: params.language, transcribeSteps: params.transcribeSteps ?? [],
})
// Save all of it next to the captureId: the token URL compares the pair with the JOB's, because the upload
// (manifest included) is deleted at `interpreting` while the job still runs.
return { jobId, status, userProtocolId: manifest.userProtocolId, protocolMechanicId: manifest.protocolMechanicId }
},
job: (/** @type {string} */ jobId) => processor.getJob(jobId), // poll when a webhook does not arrive
}
}

Con nuestro servicio, engineBaseUrl tiene que ser un Engine que el servicio admite (el de tu cuenta): cualquier otro se rechaza en el submit. Cada submit lleva los parámetros de ESA captura: taxonomy (contextId obligatorio, hciId y subcontextId opcionales; el mismo taxonomy.contextId que la configuración de tu página), language (el idioma de la sesión, por ejemplo 'es'), transcribeSteps (los tipos de step que se transcriben; [] es siempre ninguno; ausente es ninguno con el servicio alojado; con un servicio propio, los steps que su propia configuración fija para tu cliente) y, si quieres, interimWebhook. El servicio exige taxonomy.contextId y language: sin ellos, 400 E_BAD_REQUEST. createProcessorClient los valida antes de enviar (un valor mal formado es un TypeError en la llamada) y solo envía los que pasas. Hacen falta capture-server 0.13.0 o posterior.

El servicio solo acepta MP4 con H.264, que es lo que produce el cliente de grabación. Si rechaza la llamada, submit rechaza con un ProcessorError (code, status, retryAfterMs); cada llamada se rinde a los 30 s.

Monta la URL del token y el webhook antes de cualquier body parser: los dos verifican la firma sobre el cuerpo tal cual llega. El servicio le pide a tu backend un token de Engine, firmado, con el par de la captura y su jobId. createProcessorTokenHandler verifica la firma; tu authorize decide si entregar un token: solo si el jobId es el que devolvió submit, el trabajo sigue en curso (interpreting incluido) y el par es el que guardaste de ese trabajo en el submit. Nunca lo compares con receiver.manifest(): tras el aviso interpreting la subida, manifiesto incluido, ya está borrada, el servicio sigue renovando su token mientras espera la interpretación, y una negativa acaba esa espera en un timeout falso. Por defecto, el token es el token de developer de la organización, no uno limitado a esa captura: authorize limita cuándo se emite, nunca qué puede hacer. Es una condición para producción.

Desde capture-server 0.10.0 puedes entregar en su lugar un token limitado a la captura: captureToken: { baseUrl } en createProcessorTokenHandler, con baseUrl la URL de Engine de tu entorno (ENGINE_BASE). El handler se lo pide a Engine con POST /token/capture, para exactamente el par y el captureId firmados, autenticado con tus tokens (el token de developer nunca sale de tu backend), y entrega solo ese token. Dura 30 minutos (el servicio lo vuelve a pedir cuando caduca) y solo llega a la ingesta de esa captura, a su plan y a su stream. Está apagado por defecto: hoy solo el Engine del entorno de pruebas tiene esa ruta; contra un Engine que no la tiene, el handler responde un 502 que ve tu onError, nunca un fallo silencioso. Con él encendido, el replay no llama a ningún /analyze* (el token no puede, y el servicio repite con awaitInterpretation: false), así que nunca avisa analysis.out-of-token-scope: Engine hace la interpretación que pidió el Final de cierre, y tú la lees después con tu propia credencial. Engine limita además las peticiones de ese token por captura y por minuto; desde @neurologyca/capture 0.37.0 el replay espera el Retry-After y sigue, más lento, con el aviso transport.rate-limited (un procesador con una versión anterior hace fallar el trabajo). Qué puede y qué no puede hacer ese token: Un token para una sola captura. El modo diferido de DevLab también puede entregarlo: una opción de su servidor, apagada por defecto, solo contra el Engine del entorno de pruebas.

El servicio avisa a tu backend cuando termina el trabajo (succeeded o failed). El contrato (campos firmados, nonces, al menos una vez, idempotencia, getJob como respaldo): Resultados en tu backend.

Desde capture-server 0.11.0 hay además un aviso intermedio, status: 'interpreting', firmado como los demás, con report y processor a null y sin campos de fallo. El servicio lo manda mientras interimWebhook está encendido: con nuestro servicio, por defecto (apágalo por trabajo con interimWebhook: false en submit). Un receptor 0.10.0 le responde 400. No es terminal:

  • Borra el vídeo en interpreting o en succeeded, lo que llegue antes, y no cierres el trabajo hasta el succeeded. Sin el aviso (apagado, o perdido) el vídeo se queda en tu receptor toda la espera, hasta 300 s más.
  • Mira interpreting lo primero. Un onEvent que trata como fallo todo lo que no es succeeded cierra el trabajo: se deniega la renovación del token, la espera acaba en un timeout falso y el vídeo no se borra nunca. Actualiza el manejador antes de desplegar contra nuestro servicio, donde interimWebhook está encendido por defecto.
  • Un interpreting que llega después del terminal (una entrega reintentada) no vuelve a abrir nada.

Desde capture-server 0.11.0 el trabajo espera la interpretación de Engine. Si el protocolo se interpreta, el último Final la pide y Engine la hace por su cuenta (la guarda y la anuncia con constellation.complete); entretanto el trabajo está en interpreting, hasta 300 s por defecto. Cuenta como en curso, getJob lo devuelve así y nunca acaba en failed. succeeded llega cuando la interpretación está lista o cuando consta que no llegará, y su interpretation (en el webhook y en getJob) dice cómo acabó el análisis. El trabajo acaba succeeded valga lo que valga: los indicadores están en /results. El texto nunca viaja en el webhook: léelo con tu credencial (client.analyze() o POST /analyze).

interpretation Qué significa Qué hacer
ready El análisis salió completo Léela ya: sale de la caché (from_cache: true) y no vuelve a costar tokens. Medido el 2026-10-13: 726 ms
degraded Llegó, pero el análisis salió degradado No hay llamada que lea el análisis guardado sin rehacerlo: cada /analyze lo regenera (decenas de segundos, hasta unos dos minutos, y tokens de LLM) y devuelve el nuevo o, si sale peor, el guardado. Pídela una vez si la necesitas, nunca en bucle
failed Llegó, pero el análisis falló Lo mismo que degraded
timeout No llegó el evento dentro de la espera No es un fallo. Se puede pedir, a costa de tokens del LLM si no está guardada: Engine la genera en ese momento
unknown Se pidió y no se sabe cómo acabó Se puede pedir, a costa de tokens del LLM. Si processor.interpretation.reconnects es un número y el outcome no es already-processed, el evento llegó sin un estado legible: el análisis está guardado y /analyze lo sirve de la caché, como con ready. reconnects: null es un reinicio del servicio durante la espera; outcome: 'already-processed', una sesión procesada por un trabajo anterior
not-requested No se pidió (triggerAnalysis: false, un protocolo que no se interpreta), o Engine se la saltó porque le faltó una entrada (por ejemplo, la transcripción de una respuesta que acabó sin voz) No hay nada que pedir; en el segundo caso, graba otra vez con voz en cada respuesta

El trabajo trae la espera en processor.interpretation (e.processor en el webhook, job.processor en getJob; no en report): { outcome, waitedMs, reconnects, lastClose }. Por qué importa esperar, medido por DevLab el 2026-10-13: pedida al terminar la repetición, from_cache: false (se generó otra y se pagó dos veces); pedida 300 s después, from_cache: true las dos veces.

Con el token de captura (captureToken) aquí no cambia nada: el servicio repite con awaitInterpretation: false y no llama a ningún /analyze* (fuera del alcance de ese token), así que analysis.out-of-token-scope no aparece. La sesión acaba complete, y la interpretación es la que Engine hace por su cuenta.

Del catálogo de errores del servicio. «/retry» dice si el trabajo se puede reintentar; «Reserva», si el servicio libera la reserva de la persona en Engine.

Código Cuándo /retry Reserva Qué hace tu backend
Errores al llamar (ProcessorError; submit o retry rechazan con ellos) E_UNAUTHORIZED (401): sin credencial o errónea. E_CLIENT_DISABLED (403): el acceso de tu organización al servicio está desactivado; submit y retry se rechazan, getJob sigue respondiendo y los trabajos en curso terminan. E_BAD_REQUEST (400; 413 si pasa de 4 MiB; con nuestro servicio, también un trabajo sin taxonomy.contextId o sin language), E_DESTINATION_NOT_ALLOWED (400, las URLs del trabajo quedan fuera de las reglas del servicio, por ejemplo un PUBLIC_BASE_URL en http:), E_JOB_PARAMS_CONFLICT (400, autoalojado: el cliente del procesador fija taxonomy, language, transcribeSteps o interimWebhook y el trabajo trae otro valor), E_CAPTURE_ID_CONFLICT (409, el captureId es de otro cliente), E_NOT_RETRYABLE (409, retry sobre un trabajo que no está failed o no es reintentable). E_STARTING y E_STOPPING (503). E_PURGE_PENDING (503, Retry-After: 5, retry mientras se borran los ficheros del trabajo). E_PROCESSOR_HTTP (una respuesta de error sin code) y E_PROCESSOR_PROTOCOL (un 2xx que el cliente no entiende), del cliente No aplica No aplica Revisa la key del servicio (E_UNAUTHORIZED). Tras una filtración, rota en dos pasos y espera a que se reactive; si no, habla con Neurologyca (E_CLIENT_DISABLED). Defecto tuyo, no reintentes (E_BAD_REQUEST: manda taxonomy y language en cada submit; E_JOB_PARAMS_CONFLICT: manda los valores del cliente, o ninguno; E_DESTINATION_NOT_ALLOWED: corrige la configuración y vuelve a llamar a submit; E_CAPTURE_ID_CONFLICT, E_NOT_RETRYABLE). Reintenta más tarde (E_STARTING, E_STOPPING, E_PROCESSOR_HTTP, E_PROCESSOR_PROTOCOL); reintenta tras 5 s (E_PURGE_PENDING)
E_REDIRECT_REFUSED, E_DESTINATION_NOT_ALLOWED, E_VIDEO_TOO_LARGE Se rechazó la descarga o la URL del token: una redirección, una dirección fuera de las reglas del servicio (con nuestro servicio, todo lo que no sea un origen HTTPS público), o un vídeo por encima del tope de tamaño del servicio Sí, cuando falla la descarga o la URL del token (al llamar, E_DESTINATION_NOT_ALLOWED es un error de la llamada: corrígelo y vuelve a llamar a submit) No Corrige la configuración (un origen HTTPS público en PUBLIC_BASE_URL, nunca localhost) o manda una videoUrl nueva, y luego reintenta. No es un reintento a ciegas
E_VIDEO_URL_EXPIRED La descarga respondió 401 o 403 Sí, con una videoUrl nueva No Reintenta con una URL nueva
E_DOWNLOAD_FAILED Red, 5xx, 408 o 429 tras 3 intentos Sí No Reintenta más tarde
E_DOWNLOAD_FAILED (otro 4xx) Tu ruta del vídeo respondió otro 4xx, por ejemplo un 404 porque receiver.mediaHandler no está montado en /media/<captureId>/video No Sí Corrige la ruta del vídeo para las siguientes grabaciones; esta captura no se recupera (volver a enviarla devuelve el mismo trabajo fallido)
E_QUEUE_FULL Más de 50 trabajos sin terminar del cliente No aplica (se rechaza la llamada) No Reintenta submit más tarde con una espera creciente: retryAfterMs llega vacío (el servicio no manda Retry-After)
E_MANIFEST_INVALID El manifiesto está mal formado o no cuadra con el vídeo No Sí No reintentes
E_MEDIA_UNSUPPORTED El vídeo no es MP4/H.264 No Sí No reintentes
E_MEDIA_INVALID, E_ROTATION_UNRESOLVED El fichero no se puede leer como vídeo, o no se resuelve su rotación No Sí No reintentes
E_NO_FACE_PREROLL, E_EMPTY_STEP Sin cara en los primeros segundos, o un step sin frames con cara No Sí No reintentes; graba de nuevo con la persona
E_TOKEN_FAILED La URL del token no respondió bien tras 3 intentos, o al primer intento si responde un 4xx Sí No Revisa tu URL del token; reintenta
E_POSITION_BUSY, E_OWN_ATTEMPT_PROCESSING La posición está ocupada, o el intento propio de la persona sigue procesándose, tras las esperas del propio servicio Sí No Reintenta más tarde
E_ALREADY_PROCESSED No es un fallo: el intento ya estaba completado en Engine y el trabajo acaba succeeded No aplica No No es un fallo: trátalo como éxito
E_CAPTURE_DISCARDED, E_CAPTURE_OUT_OF_ORDER La persona descartó la grabación, o ya hay una sesión posterior calculada No Sí No reintentes; borra el vídeo
E_USER_BLOCKED, E_USER_GONE Engine respondió 403 o 404 para el usuario o la posición No Sí No reintentes
E_POSITION_COMPLETED, E_CONFLICT Otra captura completó la posición, u otro conflicto de ventana No Sí No reintentes
E_SESSION_ABANDONED, E_KODEC, E_STT_FAILED Engine abandonó la sesión, o falló el análisis o la transcripción del servicio Sí No Reintenta
E_GPU_UNAVAILABLE, E_CHROME_SANDBOX El anfitrión del servicio no puede ejecutar el trabajo Sí No Reintenta más tarde; es cosa del servicio
E_PROCESSOR_HANG, E_JOB_TIMEOUT, E_PROCESSOR_RESTARTED 60 s sin latido, 120 minutos en marcha, o el servicio se reinició Sí No Reintenta
E_INTERNAL Un fallo inesperado Sí No Reintenta; repórtalo si se repite
Cualquier otro código El servicio tiene más códigos que esta tabla (errorCode es un texto) El retryable del trabajo Reintenta solo si el trabajo dice retryable: true; si no, ciérralo

Si ves E_PROCESSOR_AUTH, E_PROCESSOR_UNAVAILABLE o E_PROCESSOR_REJECTED en el playground de DevLab, son la forma propia de DevLab de mostrar «subido pero no entregado al servicio»: del lado de la subida es E_UPLOAD_NOT_NOTIFIED (Diferido), y del lado del submit, uno de los códigos ProcessorError de arriba.

Un fallo que no vas a reintentar cierra el trabajo: deja de dar tokens por él en tu URL del token, y conserva o borra la grabación según tu retención. Un trabajo que falla con E_REDIRECT_REFUSED, E_DESTINATION_NOT_ALLOWED o E_VIDEO_TOO_LARGE (los tres errores de configuración) conserva la reserva de la persona hasta que Engine la caduca (72 horas después del aviso de fin).

Funciona desde 0.27.0: triggerAnalysis: false viaja en el manifiesto y el servicio no llama a /analyze. De punta a punta, el trabajo acaba succeeded y Engine guarda todos los frames que manda la repetición. Que transcriba depende del trabajo: con la transcripción apagada (transcribeSteps: []) el servicio no transcribe nada; con la transcripción activada, pide measurement_free en transcribeSteps (el único step de Measurement no es de habla, así que ninguna otra lista lo incluye) y su texto llega a Engine. Desde la 0.29.0, cuando Engine dice interpreted: false, el cliente de grabación reserva sin taxonomía y escribe interpreted: false en el manifiesto, y el replay del servicio no envía taxonomía ni pide análisis sin que pases nada. Producción aún no devuelve interpreted: allí, mantén triggerAnalysis: false en la captura.