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.
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.
El camino por defecto
Sección titulada «El camino por defecto»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).
Dos preguntas
Sección titulada «Dos preguntas»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)
- Tu página · SDK, cliente en vivo
- Tu backend · proxy (pone el token)
- Engine
Diferido (en servidor)
- Tu página · SDK, cliente de grabación
- Tu backend · receptor de subidas
- Servicio de procesado Preview
- Engine
API HTTP
- Cualquier lenguaje: la API HTTP, directa desde tu backend
- Engine
Cómo integras
Sección titulada «Cómo integras»| Tema | SDK · Recomendado para capturar | API HTTP · Complementaria | SDK + 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 ti | Las 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 resultado | Segundos 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. |
| Esfuerzo | Un 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:
createEngineAdmincrea 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 /resultsocreateEngineAdmin().getResults, la misma API desde Node). Ver Los resultados en tu backend.
Dónde se procesa
Sección titulada «Dónde se procesa»| Tema | En el dispositivo (tiempo real) · Preview 0.45 | Diferido (en servidor) · Preview | Autoalojado (próximamente) |
|---|---|---|---|
| Hoy | Disponible. | Puedes grabar, subir y procesar con el servicio de procesado de Neurologyca: nada que desplegar. | Llegará más adelante. |
| Dónde se procesa | En 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 resultados | Durante 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 dispositivo | Landmarks, 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 limita | El 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óvil | Chrome 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. |
| Measurement | Sí. | Sí, desde 0.27.0: triggerAnalysis: false viaja en el manifiesto y el procesador no llama a /analyze. | Llegará más adelante. |
| Casos típicos | Un 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 otro | createProtocolClient (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?
Sección titulada «¿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 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 |
Para decidir por los dispositivos de tu gente, y comprobar un dispositivo antes de medir: Dispositivos, calidad y modo.
Qué decides tú y qué hace el SDK
Sección titulada «Qué decides tú y qué hace el SDK»| 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 | — | ✔ |