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.
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.
Qué carga Capture, y desde dónde
Sección titulada «Qué carga Capture, y desde dónde»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.
Content Security Policy
Sección titulada «Content Security Policy»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).
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:enscript-srces 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.errorconaudio-start-failed, el avisostt, ytranscriptionesnullen 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:yconnect-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.
Alojar los ficheros tú
Sección titulada «Alojar los ficheros tú»Pasa tus propias URLs al cliente:
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.
Transcripción
Sección titulada «Transcripción»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:
{ "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: nulldetecta 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 avisastt.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 concaptureStream(), como el vídeo de muestra de DevLab), la pista no informa deautoGainControl: 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:
const client = createProtocolClient({ baseUrl: '/engine', tenant, transcribe: { language: 'es' } })Si el idioma no es el que se habla
Sección titulada «Si el idioma no es el que se habla»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: enSessionReport.transcription,vad.utterancespor encima de 0 con pocos o ningúnemittedydiscardedLowConfidenceodiscardedRepetitionLoopaltos apuntan al idioma equivocado (sin ninguno emitido, Capture avisastt.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.languageen la persona.
Qué sale del dispositivo
Sección titulada «Qué sale del dispositivo»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.
Cuando el dispositivo no puede transcribir
Sección titulada «Cuando el dispositivo no puede transcribir»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.
Bundlers
Sección titulada «Bundlers»- 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.transformerssolo ahorra su descarga: el modelo sigue llegando demodelHosty ONNX Runtime dewasmPaths, y sintransformersUrlno hay worker de voz (la voz corre en el hilo principal).