# CSP y 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

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

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](/docs/es/sdk/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.

## Alojar los ficheros tú

Pasa tus propias URLs al cliente:

```js
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/' } },
})
```

> Los ficheros de voz se pueden alojar tú (`transcribe.selfHost`); los de visión también, con la opción `kodec` del cliente. Las URLs relativas de `modelHost`, `transformersUrl` y `wasmPaths` se resuelven contra la página desde el SDK 0.36.5 (kodec 5.0.0-rc.2). Con un SDK anterior tienen que ser absolutas: con una relativa, kodec corre la voz en el hilo principal, y el SDK avisa `stt.mainThread`.

**`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

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](/docs/es/sdk/on-device/#preparar-antes-de-empezar)).

### Idioma

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:

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

#### 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](/docs/es/sdk/deferred/)).

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.

### 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

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

- 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).
