> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/es/generating-ads/banner-x-responsive/bannerx-video-captions.md).

# Subtítulos de vídeo de Banner X

## Descripción general

La Epsilon Retail Media plataforma admite archivos de subtítulos y transcripciones para Banner X campañas de vídeo. Los anunciantes cargan archivos de subtítulos (`.vtt`, `.srt`) y archivos de transcripciones (`.txt`) junto con sus recursos de vídeo. Su integración consume estas URL de archivos de la respuesta del anuncio y representa los subtítulos en su reproductor de vídeo.

Esta integración le ayuda a cumplir con los requisitos de accesibilidad, como la Ley Europea de Accesibilidad (EAA), que exige subtítulos controlados por el usuario en el contenido de vídeo público.

* Los archivos de subtítulos son pistas de subtítulos sincronizadas en el tiempo para su reproductor de vídeo.
* Los archivos de transcripción son representaciones en texto plano del contenido de audio del vídeo para uso de SEO y lectores de pantalla.

Esta guía cubre:

* Cómo aparecen los archivos de subtítulos y transcripciones en las respuestas de anuncios VAST y JSON
* Estructura del elemento `<ClosedCaptionFile>` VAST 4.3
* Estructura del array `videoTranscriptFiles[]` JSON
* Cómo representar subtítulos utilizando las URL de CDN proporcionadas
* Pruebas y validación

### Modelo de entrega

Las URL de archivos de subtítulos (`.vtt` / `.srt`) se entregan solo a través de VAST, no de JSON.\
Las URL de archivos de transcripción (`.txt`) se entregan solo a través de JSON, no de VAST.\
Los subtítulos los consume su reproductor de vídeo; las transcripciones se consumen a nivel de página.

## Flujo de integración

Los archivos de subtítulos y transcripciones siguen la misma ruta de entrega que los recursos de vídeo. No se requieren llamadas adicionales a la API más allá de su solicitud de anuncio Banner X existente.

1. Un anunciante carga archivos de vídeo, subtítulos y transcripciones a través del asistente de campañas.
2. Los archivos se validan, almacenan y sirven a través de CDN.
3. Su solicitud de anuncio Banner X existente devuelve URL de subtítulos en VAST y URL de transcripciones en JSON.
4. Su reproductor de vídeo lee la URL del archivo de subtítulos y representa los subtítulos.
5. Su página muestra opcionalmente el texto de la transcripción para accesibilidad o SEO.

## Tipos de archivos admitidos

| Recurso       | Formatos                         | Tamaño máximo                                                                  |
| ------------- | -------------------------------- | ------------------------------------------------------------------------------ |
| Subtítulos    | `.vtt` (WebVTT), `.srt` (SubRip) | Configurable según el estándar de contenido del minorista (normalmente 1–4 MB) |
| Transcripción | `.txt` (texto plano)             | Configurable según el estándar de contenido del minorista (normalmente 1–4 MB) |

Los archivos se sirven tal cual; la plataforma no convierte formatos. Su reproductor de vídeo es responsable de representar los subtítulos.

## Requisitos previos

Antes de integrar subtítulos y transcripciones, confirme lo siguiente:

* Integración de vídeo Banner X existente: ya consume `<MediaFiles>` de la etiqueta VAST en el campo adm. Consulte [Anuncios de vídeo](/retail-media-interface/integration/es/generating-ads/banner-x-responsive/video-ads-banner-x.md) para obtener un ejemplo completo de respuesta de anuncio que incluya la entrega de archivos de subtítulos y transcripciones.
* Reproductor de vídeo compatible con subtítulos: pistas de subtítulos WebVTT o SRT (p. ej., elemento HTML5 `<track>` o API de reproductor nativo equivalente).
* Función habilitada para su espacio de nombres: póngase en contacto con su equipo de cuenta para habilitar la carga de subtítulos y transcripciones para su espacio de nombres.
* CORS configurado: permita la obtención de origen cruzado de archivos `.vtt` desde el dominio CDN de Epsilon al utilizar elementos HTML5 `<track>` .

## Autenticación y seguridad

No se requiere autenticación adicional. Los archivos de subtítulos y transcripciones se sirven a través de la misma CDN que los recursos de vídeo. Las URL de archivos devueltas en la respuesta del anuncio son accesibles públicamente, utilizando el mismo modelo de seguridad que las URL de archivos de vídeo.

Si su reproductor de vídeo utiliza elementos HTML5 `<track>` para cargar archivos `.vtt` , asegúrese de que la Política de seguridad de contenido de su página permita la obtención desde el dominio CDN de Epsilon . La CDN establece los encabezados CORS adecuados para la carga de origen `<track>` cruzado.

## Paso 1: Analizar archivos de subtítulos de la respuesta VAST

**Propósito:** Recuperar URL de archivos de subtítulos sincronizados en el tiempo del XML VAST en el campo adm para su representación en su reproductor de vídeo.

### Lo que debe hacer

* En su analizador VAST, busque el elemento `<ClosedCaptionFiles>` dentro de cada `<Linear>` creatividad (dentro de `<MediaFiles>`).
* Cada `<ClosedCaptionFile>` elemento hijo contiene la URL de la CDN como su contenido de texto.
* El `type` atributo indica el tipo MIME (`text/vtt` or `application/x-subrip` para SRT).
* El `language` el atributo indica el idioma de los subtítulos (p. ej., `en`).

### Ejemplo de respuesta VAST

```xml
<Linear>
  <Duration></Duration>
  <MediaFiles>
    <ClosedCaptionFiles>
      <ClosedCaptionFile type="text/vtt" language="en"><![CDATA[https://dev12.flavedo.io./citrus/0f04cbc2-c933-4384-8d37-772e939d8d02]]></ClosedCaptionFile>
    </ClosedCaptionFiles>
    <Mezzanine><![CDATA[https://dev12.flavedo.io./citrus/37bb15a2-fd4d-4eb1-9dd7-7630b5df29d1]]></Mezzanine>
    <MediaFile delivery="progressive" type="video/mp4" width="1280" height="720" bitrate="8700" codec="h264"><![CDATA[https://dev12.flavedo.io./citrus/37bb15a2-fd4d-4eb1-9dd7-7630b5df29d1]]></MediaFile>
  </MediaFiles>
  <VideoClicks>
    <ClickTracking><![CDATA[https://integration.dev12.citrusad.com/v1/resource/second-c/...]]></ClickTracking>
    <ClickThrough></ClickThrough>
  </VideoClicks>
</Linear>
```

### Validación

* Confirme que su analizador VAST extraiga la `<ClosedCaptionFile>` URL cuando esté presente.
* Confirme que su analizador gestione adecuadamente la ausencia de `<ClosedCaptionFiles>` (no todas las campañas incluyen subtítulos).

### Errores comunes

| Error                                | Causa                                                                                                                                                                                         |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` no encontrado | Es posible que la campaña no tenga un archivo de subtítulos aprobado o que la entrega de subtítulos aún no esté habilitada para su entorno. Esto es lo esperado para campañas sin subtítulos. |

## Paso 2: Analizar archivos de transcripción de la respuesta JSON

**Propósito:** Recuperar URLs de archivos de transcripción en texto plano desde la respuesta publicitaria JSON para SEO o accesibilidad de lectores de pantalla.

### Lo que debe hacer

* En la Banner X generar respuesta, busque la `videoTranscriptFiles` matriz en cada objeto de anuncio.
* Cada entrada incluye un `videoFileId` para que pueda hacer coincidir las transcripciones con su vídeo correspondiente.
* Las transcripciones son texto plano (`.txt`) — utilícelas para metadatos SEO, lectores de pantalla o visualización de texto alternativo.

### Ejemplo de respuesta JSON

```json
"videoTranscriptFiles": [
  {
    "videoFileId": "a6f4c4a6-6982-4a8c-9a81-ecdfd4b3fa36",
    "format": "txt",
    "url": "https://dev12.flavedo.io./citrus/03d98ae2-67d5-49d3-9e9b-c8f278520657",
    "language": "en"
  }
]
```

### Validación

* Confirme que su analizador JSON lea la `videoTranscriptFiles` matriz cuando esté presente.
* Confirme una gestión adecuada cuando la matriz esté vacía o ausente.

{% hint style="info" %}
Las URLs de archivos de subtítulos (para `.vtt`/`.srt`) solo se entregan a través de VAST, no de JSON. Los archivos de transcripción (`.txt`) solo se entregan a través de JSON, no de VAST. Esta separación refleja los diferentes patrones de consumo: los subtítulos son para reproductores de vídeo (VAST), las transcripciones son para la accesibilidad a nivel de página (JSON).\*\*
{% endhint %}

## Paso 3: Renderizar subtítulos en su reproductor de vídeo

**Propósito:** Mostrar subtítulos cerrados a los compradores durante la reproducción de vídeo.

### Lo que debe hacer

* Después de analizar la URL del subtítulo desde VAST, añada un `<track>` elemento a su reproductor de vídeo HTML5 (o equivalente en el SDK de su reproductor nativo).
* Establezca `kind="captions"`. Utilice el `default` atributo si desea que los subtítulos estén habilitados por defecto.
* Para archivos .srt, algunos reproductores requieren conversión a WebVTT en tiempo de ejecución (anteponga `WEBVTT\n\n` y reemplace la coma con un punto en las marcas de tiempo).

### Ejemplo de implementación en HTML5

```html
<video controls crossorigin="anonymous">
  <source src="https://cdn.citrusad.com/video/abc123.mp4" type="video/mp4">
  <track
    kind="captions"
    src="https://cdn.citrusad.com/captions/def456.vtt"
    srclang="en"
    label="English"
    default
  >
</video>
```

### Validación

* Reproduzca el vídeo y confirme que los subtítulos aparezcan como una capa superpuesta.
* Confirme que el comprador pueda activar/desactivar los subtítulos mediante los controles del reproductor.
* Confirme que los subtítulos estén sincronizados en tiempo con el audio del vídeo.

### Errores comunes

| Error                                                     | Solución                                                                                                                                                               |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Los subtítulos no se cargan (error de CORS en la consola) | Asegúrese de que su Política de Seguridad de Contenido y la configuración de CORS permitan la extracción del `.vtt` desde el dominio CDN de Epsilon dominio de la CDN. |
| Los subtítulos aparecen ilegibles o vacíos                | Verifique que la URL del archivo devuelva contenido WebVTT válido. Obtenga la URL directamente para inspeccionar el archivo.                                           |

## Paso 4: (Opcional) Mostrar texto de la transcripción

**Propósito:** Proporcionar contenido de texto accesible junto al vídeo o debajo de él para lectores de pantalla y SEO.

### Lo que debe hacer

* Obtenga la URL de la transcripción desde la `videoTranscriptFiles` entrada en la respuesta JSON.
* Utilice el texto de la transcripción para accesibilidad, SEO, lectores de pantalla u otros casos de uso específicos del minorista.

### Ejemplo

```html
<details>
  <summary>Video transcript</summary>
  <p id="transcript-content"></p>
</details>
<script>
  fetch('https://cdn.citrusad.com/transcripts/ghi789.txt')
    .then(r => r.text())
    .then(text => {
      document.getElementById('transcript-content').textContent = text;
    });
</script>
```

## Modelos de datos y definiciones de campos

### VAST: `ClosedCaptionFile` elemento

| Atributo / campo   | Tipo         | Requerido | Descripción                         | Valores aceptados                |
| ------------------ | ------------ | --------- | ----------------------------------- | -------------------------------- |
| `type`             | string       | Sí        | Tipo MIME del archivo de subtítulos | `text/vtt, application/x-subrip` |
| `language`         | string       | No        | Idioma de la pista de subtítulos    | e.g. `en`                        |
| Texto del elemento | string (URL) | Sí        | URL CDN del archivo de subtítulos   | URL HTTPS                        |

### JSON: `videoTranscriptFiles`

| Campo         | Tipo         | Requerido | Descripción                                                 | Valores aceptados |
| ------------- | ------------ | --------- | ----------------------------------------------------------- | ----------------- |
| `videoFileId` | string       | Sí        | ID del archivo de vídeo al que pertenece esta transcripción | UUID              |
| `format`      | string       | Sí        | Formato de archivo de la transcripción                      | `txt`             |
| `url`         | string (URL) | Sí        | URL CDN del archivo de transcripción                        | URL HTTPS         |
| `language`    | string       | Sí        | Idioma de la transcripción                                  | e.g. `en`         |

## Compatibilidad con versiones anteriores

Estas adiciones son totalmente compatibles con versiones anteriores:

* Si no hay archivos de subtítulos adjuntos a una campaña, el `<ClosedCaptionFiles>` elemento se omite por completo de VAST.
* Si no hay archivos de transcripción adjuntos, `videoTranscriptFiles` está ausente o es un array vacío en JSON.
* Las integraciones existentes que no analizan estos nuevos elementos siguen funcionando sin cambios.

## Pruebas, entorno de sandbox y puesta en marcha

### Entorno de prueba / sandbox

* Solicite acceso a un espacio de nombres de prueba con la carga de subtítulos y transcripciones habilitada (póngase en contacto con su equipo de cuenta).
* Cargue una campaña de prueba con un archivo de subtítulos `.vtt` de muestra a través del asistente de campañas.
* Aapruebe la campaña a través del ciclo de revisión.
* Lleme al Banner X endpoint generate e inspeccione la respuesta VAST y JSON.

### Casos de prueba de muestra

| Prueba                                | Pasos                                                                | Resultado esperado                                                           |
| ------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Subtítulo VAST presente               | Solicitar anuncio para la campaña con subtítulo `.vtt` aprobado      | VAST contiene `<ClosedCaptionFiles>` con una URL CDN válida                  |
| Subtítulo VAST ausente                | Solicitar anuncio para campaña sin subtítulos                        | No `<ClosedCaptionFiles>` elemento en VAST                                   |
| Transcripción JSON presente           | Solicitar anuncio para la campaña con subtítulo `.txt` transcripción | JSON contiene `videoTranscriptFiles` array con entrada                       |
| Archivo de subtítulos accesible       | Obtener la URL CDN de la respuesta VAST directamente                 | Devuelve contenido `WebVTT` válido con encabezado WEBVTT                     |
| El reproductor muestra los subtítulos | Cargar vídeo + pista de subtítulos en su reproductor                 | Los subtítulos se muestran sincronizados en el tiempo con el audio del vídeo |
| CORS para el elemento track           | Cargar `.vtt` a través de `<track>` origen cruzado                   | Sin errores de CORS en la consola del navegador; los subtítulos se muestran  |

### Lista de verificación para la puesta en marcha

* [ ] El analizador VAST extrae `<ClosedCaptionFile>` URL cuando están presentes
* [ ] El analizador JSON lee `videoTranscriptFiles[]` cuando están presentes
* [ ] Alternativa degradada elegante cuando no hay subtítulos ni transcripciones
* [ ] El reproductor de vídeo muestra subtítulos desde la URL de la CDN
* [ ] El comprador puede activar o desactivar los subtítulos
* [ ] CORS validado para la recuperación de origen cruzado `.vtt` fetch
* [ ] Texto de transcripción accesible (si se implementa el Paso 4)
* [ ] Probado con ambos formatos de subtítulos `.vtt` y `.srt` formatos de subtítulos

## Preguntas frecuentes y resolución de problemas

### `<ClosedCaptionFiles>` falta el elemento en la respuesta VAST

**Causa probable:** La campaña no tiene un archivo de subtítulos aprobado o la entrega de subtítulos no está habilitada en tu entorno.

**Solución:**

* Confirma que la campaña tenga un archivo de subtítulos aprobado (cargado y revisado).
* Ponte en contacto con tu equipo de cuenta para verificar que la función esté habilitada para tu espacio de nombres.

### Error de CORS al cargar el elemento `.vtt` a través de `<track>` elemento

**Causa probable:** La Política de seguridad de contenido (CSP) o la aplicación de CORS del navegador están bloqueando la recuperación entre orígenes del `.vtt` archivo.

**Solución:**

* Añade el Epsilon dominio de la CDN a las directivas de tu política de seguridad de contenido `connect-src` y `media-src` .
* Establezca `crossorigin="anonymous"` en el elemento primario `<video>` si es necesario.

### Los subtítulos se muestran pero no están sincronizados con el vídeo

**Causa probable:** El archivo de subtítulos se creó con marcas de tiempo incorrectas o el archivo es un SRT que se está cargando como VTT sin conversión.

**Solución:**

* Obtén la URL del archivo de subtítulos e inspecciona las marcas de tiempo en comparación con la reproducción del vídeo.
* Si el archivo es .srt y tu reproductor solo admite .vtt, conviértelo en tiempo de ejecución (antepón `WEBVTT\n\n`, reemplaza `,` por `.` en las marcas de tiempo).

### La URL de la transcripción devuelve un error 404

**Causa probable:** La campaña se actualizó y el archivo de transcripción se eliminó, o hay un retraso en la propagación de la CDN.

**Solución:**

* Vuelve a obtener la respuesta del anuncio para conseguir la URL actual del archivo.
* Si el problema persiste, ponte en contacto con el servicio de soporte.

Al ponerte en contacto con el servicio de soporte, incluye:

* ID de solicitud o ID de correlación de la llamada de generación
* Marca de tiempo (UTC) de la solicitud de anuncio
* El `<ClosedCaptionFile>` or `videoTranscriptFiles` URL que está fallando
* Error de consola del navegador (para problemas de CORS)
* Espacio de nombres e ID de campaña

## Artículos relacionados

* [Anuncios de vídeo](/retail-media-interface/integration/es/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Genera anuncios de banner X para diferentes ubicaciones](/retail-media-interface/integration/es/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Referencia de Banner X](/retail-media-interface/integration/es/references/banner-x-reference-1.md)
* [Visualizador de Banner X](/retail-media-interface/integration/es/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md)

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/integration/es/generating-ads/banner-x-responsive/bannerx-video-captions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.