Ir al contenido
DevLab

CSP y transcripción

Los orígenes externos que carga Capture, una Content Security Policy que funciona con ellos, cómo alojarlos tú y cómo configurar la transcripción.

En esta página
  1. Qué carga Capture, y desde dónde
  2. Content Security Policy
  3. Alojar los ficheros tú
  4. Transcripción
  5. Idioma
  6. Qué sale del dispositivo
  7. Cuando el dispositivo no puede transcribir
  8. Bundlers

Tu página carga los modelos de análisis desde CDN públicas; si tu sitio tiene una Content-Security-Policy, tiene que permitirlas, o alojas tú los ficheros.

Capture analiza la cámara (y, con transcripción, el micrófono) en la página. Por defecto carga sus modelos y runtimes desde CDN públicas:

Cuándo Origen Qué Alójalo tú con
Siempre cdn.jsdelivr.net El runtime de visión (MediaPipe Tasks Vision, en una versión fijada) y su WebAssembly kodec.visionUrl, kodec.wasmUrl
Siempre storage.googleapis.com El modelo de la cara kodec.faceModel
Con los modelos de manos o cuerpo storage.googleapis.com Los modelos de manos y de pose kodec.handModel, kodec.poseModel
Con transcripción cdn.jsdelivr.net El runtime de voz (Transformers.js) transcribe.selfHost.transformersUrl
Con transcripción huggingface.co y *.hf.co El modelo de voz (Whisper), unos 136 MB transcribe.selfHost.modelHost
Con transcripción la ruta del propio runtime de voz El WebAssembly de ONNX Runtime transcribe.selfHost.wasmPaths

Esas URLs cargan código: fíjalas en tu build, nunca desde la query ni desde una configuración remota.

Esta política deja que tu página capture con el SDK, transcriba y hable con tu proxy, con todo cargado desde las CDN de arriba. La probamos con el cliente en vivo, con la transcripción encendida y a través del proxy del SDK (Tu backend).

HTTP
Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval' blob: https://cdn.jsdelivr.net; worker-src 'self' blob:; connect-src 'self' https://cdn.jsdelivr.net https://storage.googleapis.com https://huggingface.co https://*.hf.co; style-src 'self'; img-src 'self' data: blob:; media-src 'self' blob:
  • 'wasm-unsafe-eval' basta: no hace falta 'unsafe-eval'.
  • style-src 'self' basta: Capture no necesita estilos en línea ('unsafe-inline').
  • blob: en script-src es imprescindible: el procesado de audio de kodec (su AudioWorklet) se carga desde un Blob. Sin él se pierde la transcripción entera, y se nota: codec.error con audio-start-failed, el aviso stt, y transcription es null en el informe.
  • connect-src 'self' cubre tu proxy cuando vive en tu origen, y la URL del informe de arranque (startup.report.url) cuando es tuya; en otro origen, añádela.
  • Si lo alojas todo tú, sobran los orígenes de las CDN: script-src 'self' 'wasm-unsafe-eval' blob: y connect-src 'self'.

Cuando la política bloquea Capture, la cámara nunca llega a estar lista (se bloquea una descarga), o se pierde la transcripción como arriba. workerBlockedByCsp del informe solo dice si se bloqueó el worker de voz: workerBlockedByCsp no lo cubre si es el AudioWorklet.

Pasa tus propias URLs al cliente:

JavaScript
import { createProtocolClient } from '@neurologyca/capture'
const client = createProtocolClient({
baseUrl: '/engine',
tenant,
kodec: { visionUrl: '/vendor/tasks-vision/', wasmUrl: '/vendor/tasks-vision/wasm', faceModel: '/vendor/face_landmarker.task' },
transcribe: { language: 'es', selfHost: { modelHost: '/vendor/models/', transformersUrl: '/vendor/transformers.js', wasmPaths: '/vendor/ort/' } },
})

wasmPaths desde la 0.42.0 (cambio incompatible). Como cadena es un prefijo que tiene que acabar en /: kodec lo pone delante del nombre del fichero y pide el par de ONNX Runtime del ejecutor en que corre: ort-wasm-simd-threaded.jspi.mjs y ort-wasm-simd-threaded.jspi.wasm en WebGPU con JSPI; ort-wasm-simd-threaded.mjs y ort-wasm-simd-threaded.wasm en WASM y en WebKit (Safari, y todo navegador en iOS). En WebGPU sin JSPI el prefijo pasa a ONNX Runtime como antes. Los cuatro ficheros salen de onnxruntime-web/dist/: sirve los dos pares si tu gente llega con los dos ejecutores. Antes de cargar, kodec comprueba los dos ficheros del par con un HEAD; si uno responde 404 o 410, la voz no arranca y la captura sigue sin ella, con el aviso stt con subStage: 'stt-runtime', reason: 'network' y, en cut, code: 'stt-runtime-missing' con la url que falta (en prepare(), partial con speech-error). Un host que solo sirve el par Asyncify (ort-wasm-simd-threaded.asyncify.*), que antes funcionaba en WebGPU con JSPI, ahora falla así. Como objeto, wasmPaths: { wasm, mjs } apunta a los ficheros exactos y llega a kodec tal cual; en WebKit, apúntalo a la build simple.

La transcripción convierte en texto lo que dice la persona, en el dispositivo. Está apagada hasta que algo la enciende: transcribe: { … } en el cliente, o un objeto transcribe en el kit (tenant), que la enciende aunque tu código no pase transcribe. Solo transcribe: false en el cliente la mantiene apagada diga lo que diga el kit; transcribe: false en el kit la mantiene apagada salvo que el cliente pase un objeto. Con la cámara abre el micrófono; con una fuente <video> transcribe el audio del propio fichero y no abre el micrófono. En Safari, con el <video> en muted, el SDK no añade pista de audio y la transcripción falla con un error explícito.

La primera vez, el navegador descarga unos 160 MB para la voz (136 MB de ellos, los pesos de Whisper, más el motor y la librería) y lo guarda para ese origen; con una conexión móvil lenta son minutos. client.prepare({ models: { speech: true } }) puede descargarlo antes de Empezar, salvo en Safari e iOS (Preparar antes de Empezar).

El idioma se declara, no se detecta: es el idioma en el que hablará la persona, no el de tu página. Fíjalo con un código sin región:

JSON
{ "transcribe": { "language": "es" } }
  • Si pasas un código con región, como es-ES, Capture usa su parte de idioma (es) y lo anota en la consola.
  • Sin language, Capture usa el idioma de la página (<html lang> y, si no, el del navegador).
  • language: null detecta el idioma a partir del audio. No es fiable con respuestas cortas: puede devolver el texto traducido al inglés, sin ningún error. Capture avisa stt.autodetect.
  • Un código que el modelo no conoce pasa a detección, con un aviso.
  • El idioma también puede venir del kit (transcribe.language); los campos del cliente mandan sobre los del kit.
  • Con una fuente que no es un micrófono (un <video> capturado con captureStream(), como el vídeo de muestra de DevLab), la pista no informa de autoGainControl: kodec avisa una vez de que energy y shimmer no son fiables (el mensaje nombra WebKit/iOS, pero lo provoca cualquier pista así). Es lo esperado; esas dos características no son comparables con las de un micrófono.

En el cliente:

JavaScript
const client = createProtocolClient({ baseUrl: '/engine', tenant, transcribe: { language: 'es' } })

kodec obliga al modelo a usar el idioma declarado. Si la persona habla otro, pasa una de dos cosas, según el par de idiomas: el modelo traduce al declarado, con fluidez y buena confianza, así que el texto llega a Engine traducido y sin ningún aviso; o se repite o puntúa bajo, y kodec descarta esas locuciones a propósito, así que los steps de voz llegan a Engine sin texto o con muy poco (solo el aviso stt.silent, si no queda ninguna locución). En una prueba, con inglés declarado sobre voz en español pasó lo primero; con español declarado sobre voz en inglés, lo segundo. Fijar el idioma equivocado es peor que no fijarlo. En diferido pasa lo mismo con el language del trabajo: el transcrito llega con la etiqueta del idioma pedido y su texto no es fiable (Diferido).

Formas de acertar:

  • Guárdalo con la persona o la entrevista en tu backend (el idioma en el que responde el candidato, por ejemplo) y pásalo a cada captura. No lo deduzcas del idioma de la interfaz si pueden ser distintos.
  • Si no lo sabes, pregúntalo antes de capturar, en la pantalla del consentimiento.
  • Un idioma por captura. Quien cambia de idioma a mitad se transcribe en el declarado: divídelo en capturas.
  • Detéctalo después con onReport: en SessionReport.transcription, vad.utterances por encima de 0 con pocos o ningún emitted y discardedLowConfidence o discardedRepetitionLoop altos apuntan al idioma equivocado (sin ninguno emitido, Capture avisa stt.silent). Ofrece repetir la captura en el correcto. Una traducción pasa todos los contadores: solo declarar el idioma correcto la evita.
  • La autodetección no es la salida. En una prueba con language: null, las respuestas más largas en español también volvieron traducidas al inglés. Si conoces el idioma de la persona, decláralo.
  • El idioma de la interpretación va aparte: narrative.language en la persona.

Solo texto. El audio se procesa en el navegador y nunca se envía. La transcripción viaja una vez, en el Final del último step: el texto entero (speech) y el texto de cada step con sus tiempos (sttByStep). Engine lo añade al contexto de la interpretación.

Algunos dispositivos no pueden ejecutar el modelo de voz. Capture te lo dice antes de empezar, con un aviso cuyo code es stt y un blocker, o durante la captura, con stt.cut. Los bloqueos están en STT_BLOCKERS, y sttBlockerOf(error) lee uno de un error:

Bloqueo Qué significa
no-webgpu El navegador no ofrece ningún adaptador WebGPU utilizable (puede tener WebGPU y no ofrecer ninguno)
ladder-exhausted Todas las configuraciones de voz cerraron la pestaña al cargar en este dispositivo, así que no se vuelve a intentar
video-cost-veto Transcribir hizo demasiado lento el análisis de la cámara en este dispositivo
no-memory-to-learn El navegador no guarda nada (modo privado o almacenamiento bloqueado) y ejecutaría la voz sin WebGPU, así que no se arriesga
dtype-required El modelo que elegiste necesita un dtype explícito en este dispositivo

El veto se guarda en el almacenamiento de ese navegador y dura más que la página. Si se midió con el vídeo por debajo de 8 fps, normalmente con la pestaña oculta, se guarda como provisional. Desde el SDK 0.41.0, la primera captura que da vídeo por encima de 8 fps lo borra y transcribe: solo esa captura espera, hasta unos 3 s (en torno a 1 s en un dispositivo sano), y SessionReport.transcriptionSetup.provisionalVetoLifted informa del veto borrado, su único rastro. Una captura que se queda en 8 fps o menos, como una pestaña oculta o un fps de captura de 8 o menos, lo conserva. Hasta 0.40.0 no caducaba nunca dentro de una captura (la transcripción arrancaba antes de medir la cadencia), y 0.40.1 transcribía pero lo conservaba, con la espera en cada captura. Enseña todos los avisos, no solo el último, porque stt es la única señal de que una captura no transcribe.

video-cost-veto es el único que el SDK deja levantar, con forgetTranscriptionVeto detrás de una pulsación de la persona, nunca de forma automática. transcribe.allowWasmWorker: true deja intentarlo en WebAssembly a dispositivos sin un adaptador WebGPU utilizable, más despacio. Desde la 0.43.0 esa vía necesita su Worker de transcripción: si el Worker no arranca (por ejemplo, una Content-Security-Policy que bloquea los workers), no hay voz (un codec.error con wasm-needs-worker, y transcriptionLoad.reason: 'needs-worker' en el informe), en vez de caer al hilo principal, que congelaba el vídeo en cada frase. Con WebGPU no cambia nada. La captura de los indicadores sigue en cualquier caso.

Pasa a las dos funciones el kodec que exporta el propio SDK (kodec, junto a readTranscriptionVeto y forgetTranscriptionVeto, en @neurologyca/capture): kodec no se instala, el SDK lo trae fijado. readTranscriptionVeto(kodec) solo lee y devuelve { veto, learned }: llámala primero para saber si hay un veto que levantar. forgetTranscriptionVeto(kodec) levanta ese veto y nada más; nunca borra el resto de lo que kodec aprendió en el dispositivo, como los límites de memoria (no uses para esto forgetMemoryLimit de kodec). El veto es del navegador, no de la persona: levantarlo solo cambia la próxima captura en este navegador, y si transcribir vuelve a ralentizar el vídeo, el SDK lo veta otra vez.

onReport del cliente recibe el SessionReport al acabar la captura, también cuando acaba con endedBy: 'abort' o 'error'; CaptureOutcome no lo trae. Para la transcripción, lee transcriptionSetup (model, language, languageSource, backend y provisionalVetoLifted) y, por step, transcription.stepsTranscription[] (order, transcribed, emitted, spokenMs): un step con transcribed: false o emitted: 0 no oyó voz, y eso explica un transcript vacío en /results. El playground de DevLab guarda solo esos campos, con provisionalVetoLifted como un sí o un no (nunca su contenido), y los enseña en «Datos técnicos de la respuesta». Cuando una sesión no se transcribe, el playground lo dice bajo el escenario y en la tarjeta del resultado con la frase de su bloqueo de la tabla de arriba y, solo con video-cost-veto y al acabar la sesión, ofrece «Reintentar transcripción», que hace exactamente esto: lee el veto y, si lo hay, lo levanta.

  • El SDK trae kodec 5.0.0-rc.14, fijado: kodec no lo instalas tú. La minificación no rompe la transcripción (arreglado en kodec 4.0.2). Con webpack (Next.js), kodec 4.2.2 o posterior, el que trae el SDK desde 0.34.0; Turbopack no está probado.
  • No instales el runtime de voz ni el de visión «por si acaso»: Capture los carga cuando hacen falta. Pasar el runtime de voz que importas como transcribe.transformers solo ahorra su descarga: el modelo sigue llegando de modelHost y ONNX Runtime de wasmPaths, y sin transformersUrl no hay worker de voz (la voz corre en el hilo principal).