Ir al contenido
DevLab

Vías de integración

Cómo integras (SDK y API HTTP) y dónde se procesa (en el dispositivo o en diferido), con las cifras medidas y una guía corta para elegir.

En esta página
  1. El camino por defecto
  2. Dos preguntas
  3. Cómo integras
  4. Dónde se procesa
  5. ¿Cuál elijo?
  6. Qué decides tú y qué hace el SDK

Recomendamos capturar con el SDK, en el dispositivo (tiempo real), para la mayoría de las integraciones, y usar la API HTTP para lo puntual y tu backend: consultar resultados más tarde, sondear o buscar en el catálogo. Captura en diferido (en servidor) cuando el dispositivo no aguanta la captura en vivo (móviles modestos, sesiones largas) y puedes subir vídeo: hoy puedes grabar, subir y procesar con el servicio de procesado de Neurologyca, sin desplegar nada. Si capturas fuera del navegador (otro lenguaje u otra plataforma, o ya tienes los frames), la API HTTP también captura.

El SDK para capturar; la API para lo puntual y tu backend. Lo habitual es combinar las dos.

Si dudas: el SDK en el dispositivo (tiempo real), con Measurement como primer protocolo (en el entorno de pruebas: el Engine de producción aún no lo ofrece (Tus entornos)); pasa a diferido (en servidor) si tus pruebas en tus móviles lo piden. Empieza por el Quickstart y Measurement.

Sin cuenta: los ejemplos grabados, el código y la doc; medir, con invitación (solicita acceso).

Decides dos cosas, y no dependen una de otra: cómo integras (el SDK, la API HTTP o las dos) y dónde se procesa (en el dispositivo o en un servidor).

En el dispositivo (tiempo real)

  1. Tu página · SDK, cliente en vivo
  2. Tu backend · proxy (pone el token)
  3. Engine

Diferido (en servidor)

  1. Tu página · SDK, cliente de grabación
  2. Tu backend · receptor de subidas
  3. Servicio de procesado Preview
  4. Engine

API HTTP

  1. Cualquier lenguaje: la API HTTP, directa desde tu backend
  2. Engine
Cómo integras
TemaSDK · Recomendado para capturarAPI HTTP · ComplementariaSDK + API · Lo habitual
Para quéPara capturar: protocolo, steps, lotes, baseline y los resultados de la sesión.Para lo puntual y tu backend: resultados más tarde, sondeo, catálogo, participantes, contextos, cualquier lenguaje.Captura en el navegador con el SDK y consulta después desde tu backend con la API: resultados más tarde, sondeo, catálogo. Ver Los resultados en tu backend.
Qué hace por tiLas rutas, el token (lo pone tu proxy), el troceo en lotes, los reintentos, los conflictos y la reserva de la posición.Nada: montas tú las llamadas, los lotes, los reintentos y el flujo de eventos.El SDK hace la captura; tu backend hace lecturas sencillas.
Tu backend@neurologyca/capture-server: el proxy (createEngineProxy) y createEngineAdmin, que es la misma API desde Node.Cualquier lenguaje: POST /token con tu key y después las llamadas de la guía HTTP.createEngineAdmin crea la persona y la inscripción; después, getResults o GET /results.
Tiempo hasta el primer resultadoSegundos después del último step: el CaptureOutcome llega poco después de acabar la sesión, así que un protocolo corto da su primer resultado en menos de un minuto; crear la persona y la inscripción antes de Start lleva un momento más.Segundos después del último lote: el quickstart cURL va de POST /token a los resultados en bastante menos de un minuto.Lo mismo que el SDK; tu backend lee cuando lo necesita.
EsfuerzoUn fichero de backend (proxy, persona e inscripción) y una página: lo que construye el quickstart.La guía HTTP a mano: las llamadas, los lotes, los reintentos y el flujo de eventos.El SDK en la página y unas pocas lecturas en tu backend.

El SDK y la API se combinan en los dos sentidos:

  • Backend primero: createEngineAdmin crea la persona y la inscripción, y la página captura con ese par de ids.
  • Navegador primero: la página captura con el SDK y tu backend lee los resultados después (GET /results o createEngineAdmin().getResults, la misma API desde Node). Ver Los resultados en tu backend.
Dónde se procesa
TemaEn el dispositivo (tiempo real) · Preview 0.45Diferido (en servidor) · PreviewAutoalojado (próximamente)
HoyDisponible.Puedes grabar, subir y procesar con el servicio de procesado de Neurologyca: nada que desplegar.Llegará más adelante.
Dónde se procesaEn el navegador, en el dispositivo de la persona, mientras captura.En nuestro servicio de procesado, poco después de subir. No son horas: simplemente no se procesa en el dispositivo.En tus propios servidores.
Cuándo hay resultadosDurante la sesión y segundos después del último lote en una captura corta. Una captura larga, con miles de frames, tarda minutos. Pasado outcomeDeadlineMs (240 s por defecto), stop() da E_RESULTS_TIMEOUT, que no es una pérdida: lee los resultados después.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.Llegará más adelante.
Qué sale del dispositivoLandmarks, coeficientes de expresión y pose, hacia Engine. Solo si los activas: el transcrito (el reconocimiento de voz corre en el navegador, así que el audio se queda y el texto sale; Engine lo pasa a un LLM para la interpretación) y las señales extra (la voz como números, el pulso, las manos, el cuerpo). Nunca imagen, vídeo ni audio.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.Vídeo y audio, hacia tus propios servidores.
Qué te limitaEl dispositivo: la detección de la cara en la GPU (WebGL 2) y, en móvil, el calor en sesiones largas, que bajan los fps. Un móvil o un portátil reciente suele quedarse cerca de los fps de la cámara; un móvil de gama de entrada captura menos frames por segundo, y un móvil los pierde según se calienta.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.Llegará más adelante.
Navegadores y móvilChrome y Edge 94+, Safari 16.4+ (iOS 16.4+), en escritorio y en móviles capaces.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.Llegará más adelante.
MeasurementSí.Sí, desde 0.27.0: triggerAnalysis: false viaja en el manifiesto y el procesador no llama a /analyze.Llegará más adelante.
Casos típicosUn check-in corto en un portátil; una tarea de dos minutos en un móvil reciente; cualquier captura cuyo vídeo no deba salir del dispositivo.Una entrevista de diez minutos en un móvil modesto; una sesión de campo en un dispositivo flojo, subida después.Vídeo que debe procesarse dentro de tu propia infraestructura.
Pasar de uno a otrocreateProtocolClient (de @neurologyca/capture) ↔ createRecordingClient (de @neurologyca/capture/record, sin kodec). Algunas opciones no pasan: transcribe es solo del vivo; en diferido transcribe el servicio de procesado.Añade el receptor a tu backend (createUploadReceiver); graba desde la cámara, un <video> o un stream.Llegará más adelante.

Firefox no es objetivo: kodec no se ha probado allí (en el dispositivo), y no graba MP4/H.264 (en diferido).

¿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

Para decidir por los dispositivos de tu gente, y comprobar un dispositivo antes de medir: Dispositivos, calidad y modo.

Tema Tú El SDK y capture-server
Tu pantalla: cómo se ve todo, sus textos e idioma; el consentimiento antes de captureProtocol, y solo desde un gesto de la persona ✔ Abrir la cámara y el micrófono en esa llamada
Por protocolo: cuánto dura un step cuando Engine no lo dice, quién lo cierra (un tope, un botón, el final del vídeo) y qué dice un step sin texto ✔, con los datos de describeStep Comprobar cada step con el mínimo y el máximo de Engine (stepDurations)
Por protocolo: si la persona puede repetir una captura y qué pasa con un 409 ✔, con ConflictDetail Convertir cada 409 en una sola forma
Tu backend: autenticar a tus usuarios antes del proxy y del receptor, y qué ids puede tocar cada uno ✔ (authorize con ownsAll, checkManifest) Negarse a construirse sin ellos
Tu backend: dónde se guardan las grabaciones, cuánto se conservan las confirmadas y llamar a sweep() ✔ storage es obligatorio: localDiskStorage o el tuyo; define qué se abandona
Lo que hace el SDK: rutas de Engine, cabeceras, correlación; acuñar, cachear y poner el token — ✔
Lo que hace el SDK: troceo en lotes, reintentos, reanudar una subida, la reserva de la posición y su liberación — ✔