> 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/fr/generating-ads/banner-x-responsive/bannerx-video-captions.md).

# Légendes vidéo Banner X

## Présentation

La Epsilon Retail Media plateforme prend en charge les fichiers de sous-titres et de transcriptions pour les Banner X campagnes vidéo. Les annonceurs téléversent des fichiers de sous-titres (`.vtt`, `.srt`) et des fichiers de transcription (`.txt`) aux côtés de leurs ressources vidéo. Votre intégration consomme ces URL de fichiers à partir de la réponse publicitaire et affiche les sous-titres dans votre lecteur vidéo.

Cette intégration vous aide à respecter les exigences d'accessibilité telles que l'Acte européen sur l'accessibilité (EAA), qui impose des sous-titres contrôlés par l'utilisateur sur le contenu vidéo destiné au public.

* Les fichiers de sous-titres sont des pistes de sous-titres synchronisées dans le temps pour votre lecteur vidéo.
* Les fichiers de transcription sont des représentations en texte brut du contenu audio de la vidéo, utilisées pour le référencement (SEO) et les lecteurs d'écran.

Ce guide couvre :

* Comment les fichiers de sous-titres et de transcription apparaissent dans les réponses publicitaires VAST et JSON
* VAST 4.3 `<ClosedCaptionFile>` structure de l'élément
* JSON `videoTranscriptFiles[]` structure du tableau
* Comment afficher les sous-titres à l'aide des URL CDN fournies
* Test et validation

### Modèle de diffusion

Les URL des fichiers de sous-titres (`.vtt` / `.srt`) sont diffusées uniquement via VAST, pas JSON.\
Les URL des fichiers de transcription (`.txt`) sont diffusées uniquement via JSON, pas VAST.\
Les sous-titres sont consommés par votre lecteur vidéo ; les transcriptions sont consommées au niveau de la page.

## Flux d'intégration

Les fichiers de sous-titres et de transcription suivent le même parcours de diffusion que les ressources vidéo. Aucune appel d'API supplémentaire n'est requis au-delà de votre Banner X demande publicitaire existante.

1. Un annonceur téléverse des fichiers vidéo, de sous-titres et de transcription via l'assistant de campagne.
2. Les fichiers sont validés, stockés et servis via CDN.
3. Votre Banner X demande publicitaire existante renvoie les URL de sous-titres dans VAST et les URL de transcription dans JSON.
4. Votre lecteur vidéo lit l'URL du fichier de sous-titres et affiche les sous-titres.
5. Votre page affiche facultativement le texte de transcription pour l'accessibilité ou le référencement (SEO).

## Types de fichiers pris en charge

| Ressource          | Formats                          | Taille maximale                                                                |
| ------------------ | -------------------------------- | ------------------------------------------------------------------------------ |
| Sous-titres fermés | `.vtt` (WebVTT), `.srt` (SubRip) | Configurable selon la norme de contenu du distributeur (généralement 1 à 4 Mo) |
| Transcription      | `.txt` (texte brut)              | Configurable selon la norme de contenu du distributeur (généralement 1 à 4 Mo) |

Les fichiers sont servis tels quels ; la plateforme ne convertit pas les formats. Votre lecteur vidéo est responsable de l'affichage des sous-titres.

## Conditions préalables

Avant d'intégrer les sous-titres et les transcriptions, confirmez ce qui suit :

* Existante Banner X intégration vidéo — vous consommez déjà `<MediaFiles>` à partir de la balise VAST dans le champ adm. Voir [Annonces vidéo](/retail-media-interface/integration/fr/generating-ads/banner-x-responsive/video-ads-banner-x.md) pour un exemple complet de réponse publicitaire incluant la diffusion de fichiers de sous-titres et de transcription.
* Lecteur vidéo avec prise en charge des sous-titres — pistes de sous-titres WebVTT ou SRT (par ex. HTML5 `<track>` élément, ou API de lecteur natif équivalente).
* Fonctionnalité activée pour votre espace de noms — contactez votre équipe de compte pour activer le téléversement de sous-titres et de transcriptions pour votre espace de noms.
* CORS configuré — autorisez la récupération inter-origine des `.vtt` fichiers à partir du domaine CDN Epsilon lors de l'utilisation d'éléments HTML5 `<track>` .

## Authentification et sécurité

Aucune authentification supplémentaire n'est requise. Les fichiers de sous-titres et de transcription sont servis via le même CDN que les ressources vidéo. Les URL de fichiers renvoyées dans la réponse publicitaire sont accessibles publiquement, en utilisant le même modèle de sécurité que les URL de fichiers vidéo.

Si votre lecteur vidéo utilise des éléments HTML5 `<track>` pour charger des fichiers `.vtt` , assurez-vous que la politique de sécurité du contenu (CSP) de votre page autorise la récupération à partir du domaine CDN Epsilon . Le CDN définit les en-têtes CORS appropriés pour le chargement `<track>` inter-origine.

## Étape 1 : Analyser les fichiers de sous-titres à partir de la réponse VAST

**Objectif :** Récupérer les URL des fichiers de sous-titres synchronisés à partir du XML VAST dans le champ adm pour les afficher dans votre lecteur vidéo.

### Ce que vous devez faire

* Dans votre analyseur VAST, recherchez l'élément `<ClosedCaptionFiles>` au sein de chaque `<Linear>` création (à l'intérieur de `<MediaFiles>`).
* Chaque `<ClosedCaptionFile>` élément enfant contient l'URL du CDN dans son contenu textuel.
* L' `type` attribut indique le type MIME (`text/vtt` or `application/x-subrip` pour SRT).
* L' `language` attribut indique la langue des sous-titres (par ex. `en`).

### Exemple de réponse 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>
```

### Validation

* Confirmez que votre parseur VAST extrait l' `<ClosedCaptionFile>` URL lorsqu'elle est présente.
* Confirmez que votre parseur gère correctement l'absence de `<ClosedCaptionFiles>` (toutes les campagnes n'incluent pas de sous-titres).

### Erreurs courantes

| Erreur                            | Cause                                                                                                                                                                                                               |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` non trouvé | La campagne ne dispose peut-être pas d'un fichier de sous-titres approuvé, ou la diffusion des sous-titres n'est pas encore activée pour votre environnement. Cela est attendu pour les campagnes sans sous-titres. |

## Étape 2 : Analyser les fichiers de transcription à partir de la réponse JSON

**Objectif :** Récupérer les URL des fichiers de transcription en texte brut à partir de la réponse publicitaire JSON pour le référencement naturel (SEO) ou l'accessibilité des lecteurs d'écran.

### Ce que vous devez faire

* Dans la Banner X réponse générée, recherchez le `videoTranscriptFiles` tableau sur chaque objet publicitaire.
* Chaque entrée comprend un `videoFileId` afin que vous puissiez faire correspondre les transcriptions avec leur vidéo correspondante.
* Les transcriptions sont au format texte brut (`.txt`) — utilisez-les pour les métadonnées SEO, les lecteurs d'écran ou l'affichage de texte alternatif.

### Exemple de réponse JSON

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

### Validation

* Confirmez que votre parseur JSON lit le `videoTranscriptFiles` tableau lorsqu'il est présent.
* Confirmez la gestion fluide lorsque le tableau est vide ou absent.

{% hint style="info" %}
Les URL des fichiers de sous-titres (pour `.vtt`/`.srt`) ne sont livrées que via VAST, pas JSON. Les fichiers de transcription (`.txt`) ne sont livrés que via JSON, pas VAST. Cette séparation reflète les différents modes de consommation : les sous-titres sont destinés aux lecteurs vidéo (VAST), les transcriptions sont destinées à l'accessibilité au niveau de la page (JSON).\*\*
{% endhint %}

## Étape 3 : Afficher les sous-titres dans votre lecteur vidéo

**Objectif :** Afficher les sous-titres fermés aux acheteurs pendant la lecture de la vidéo.

### Ce que vous devez faire

* Après avoir analysé l'URL des sous-titres à partir de VAST, ajoutez un `<track>` élément à votre lecteur vidéo HTML5 (ou équivalent dans le SDK de votre lecteur natif).
* Définissez `kind="captions"`. Utilisez l' `default` attribut si vous souhaitez que les sous-titres soient activés par défaut.
* Pour les fichiers .srt, certains lecteurs nécessitent une conversion en WebVTT au moment de l'exécution (ajoutez `WEBVTT\n\n` et remplacez la virgule par un point dans les horodatages).

### Exemple d'implémentation 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>
```

### Validation

* Lancez la vidéo et confirmez que les sous-titres apparaissent en superposition.
* Confirmez que l'acheteur peut activer/désactiver les sous-titres via les commandes du lecteur.
* Confirmez que les sous-titres sont synchronisés dans le temps avec l'audio de la vidéo.

### Erreurs courantes

| Erreur                                                           | Solution                                                                                                                                                                                    |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Les sous-titres ne se chargent pas (erreur CORS dans la console) | Assurez-vous que votre stratégie de sécurité du contenu (CSP) et votre configuration CORS autorisent la récupération depuis `.vtt` fichiers à partir du domaine CDN Epsilon domaine du CDN. |
| Les sous-titres apparaissent déformés ou vides                   | Vérifiez que l'URL du fichier renvoie un contenu WebVTT valide. Récupérez directement l'URL pour inspecter le fichier.                                                                      |

## Étape 4 : (Facultatif) Afficher le texte de la transcription

**Objectif :** Fournir un contenu textuel accessible à côté ou en dessous de la vidéo pour les lecteurs d'écran et le SEO.

### Ce que vous devez faire

* Récupérez l'URL de la transcription à partir de la `videoTranscriptFiles` entrée dans la réponse JSON.
* Utilisez le texte de la transcription pour l'accessibilité, le SEO, les lecteurs d'écran ou d'autres cas d'utilisation spécifiques au détaillant.

### Exemple

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

## Modèles de données et définitions de champs

### VAST : `ClosedCaptionFile` élément

| Attribut / champ   | Type                       | Obligatoire | Description                         | Valeurs acceptées                |
| ------------------ | -------------------------- | ----------- | ----------------------------------- | -------------------------------- |
| `type`             | chaîne de caractères       | Oui         | Type MIME du fichier de sous-titres | `text/vtt, application/x-subrip` |
| `language`         | chaîne de caractères       | No          | Langue de la piste de sous-titres   | e.g. `en`                        |
| Texte de l'élément | chaîne de caractères (URL) | Oui         | URL CDN du fichier de sous-titres   | URL HTTPS                        |

### JSON : `videoTranscriptFiles`

| Champ         | Type                       | Obligatoire | Description                                               | Valeurs acceptées |
| ------------- | -------------------------- | ----------- | --------------------------------------------------------- | ----------------- |
| `videoFileId` | chaîne de caractères       | Oui         | ID du fichier vidéo auquel appartient cette transcription | UUID              |
| `format`      | chaîne de caractères       | Oui         | Format de fichier de la transcription                     | `txt`             |
| `url`         | chaîne de caractères (URL) | Oui         | URL CDN du fichier de transcription                       | URL HTTPS         |
| `language`    | chaîne de caractères       | Oui         | Langue de la transcription                                | e.g. `en`         |

## Compatibilité ascendante

Ces ajouts sont entièrement rétrocompatibles :

* Si aucun fichier de sous-titres n'est associé à une campagne, l'élément `<ClosedCaptionFiles>` est totalement omis du VAST.
* Si aucun fichier de transcription n'est associé, `videoTranscriptFiles` est absent ou prend la forme d'un tableau vide dans le JSON.
* Les intégrations existantes qui ne analysent pas ces nouveaux éléments continuent de fonctionner sans modification.

## Tests, sandbox et mise en production

### Environnement de test / sandbox

* Demandez l'accès à un espace de noms de test avec l'importation de sous-titres et de transcriptions activée (contactez votre équipe de compte).
* Importez une campagne de test avec un exemple de `.vtt` fichier de sous-titres via le assistant de campagne.
* Approuver la campagne tout au long du cycle de révision.
* Appelez le Banner X générez l'endpoint et inspectez la réponse VAST et JSON.

### Exemples de cas de test

| Test                            | Étapes                                                                      | Résultat attendu                                                               |
| ------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Légende VAST présente           | Demander une annonce pour la campagne avec approbation `.vtt` légende       | Le VAST contient `<ClosedCaptionFiles>` avec une URL CDN valide                |
| Légende VAST absente            | Demander une annonce pour une campagne sans légendes                        | No `<ClosedCaptionFiles>` élément dans VAST                                    |
| Transcription JSON présente     | Demander une annonce pour la campagne avec approbation `.txt` transcription | Le JSON contient `videoTranscriptFiles` tableau avec entrée                    |
| Fichier de légende accessible   | Récupérer l'URL CDN directement à partir de la réponse VAST                 | Renvoie un valide `WebVTT` contenu avec en-tête WEBVTT                         |
| Le lecteur affiche les légendes | Charger la vidéo et la piste de légende dans votre lecteur                  | Les légendes s'affichent de manière synchronisée avec l'audio de la vidéo      |
| CORS pour l'élément track       | Charger `.vtt` via `<track>` cross-origin                                   | Aucune erreur CORS dans la console du navigateur ; les sous-titres s'affichent |

### Liste de contrôle de mise en ligne

* [ ] Le parseur VAST extrait `<ClosedCaptionFile>` Les URL lorsqu'elles sont présentes
* [ ] Le parseur JSON lit `videoTranscriptFiles[]` lorsqu'ils sont présents
* [ ] Repli fluide lorsque les sous-titres ou les transcriptions sont absents
* [ ] Le lecteur vidéo affiche les sous-titres à partir de l'URL du CDN
* [ ] L'acheteur peut activer/désactiver les sous-titres
* [ ] CORS validé pour la récupération `.vtt` fetch inter-origines
* [ ] Texte de la transcription accessible (si l'étape 4 est mise en œuvre)
* [ ] Testé avec les deux `.vtt` et `.srt` formats de sous-titres

## Dépannage et FAQ

### `<ClosedCaptionFiles>` élément manquant dans la réponse VAST

**Cause probable :** La campagne ne dispose pas d'un fichier de sous-titres approuvé, ou la diffusion des sous-titres n'est pas activée dans votre environnement.

**Solution :**

* Confirmez que la campagne dispose d'un fichier de sous-titres approuvé (téléchargé et validé par l'examen).
* Contactez votre équipe compte pour vérifier que la fonctionnalité est activée pour votre espace de noms.

### Erreur CORS lors du chargement de l'élément `.vtt` via `<track>` élément

**Cause probable :** la politique de sécurité du contenu (CSP) ou l'application du CORS par le navigateur bloque la récupération inter-origine de la `.vtt` fichier.

**Solution :**

* Ajoutez le Epsilon domaine CDN aux directives de votre `connect-src` et `media-src` politique de sécurité du contenu (Content Security Policy).
* Définissez `crossorigin="anonymous"` sur l'élément `<video>` parent si nécessaire.

### Les sous-titres s'affichent mais ne sont pas synchronisés avec la vidéo

**Cause probable :** Le fichier de sous-titres a été créé avec des horodatages incorrects, ou le fichier est un fichier SRT chargé comme VTT sans conversion.

**Solution :**

* Récupérez l'URL du fichier de sous-titres et inspectez les horodatages par rapport à la lecture vidéo.
* Si le fichier est au format .srt et que votre lecteur ne prend en charge que le format .vtt, convertissez-le au moment de l'exécution (ajoutez au début `WEBVTT\n\n`, remplacez `,` par `.` dans les horodatages).

### L'URL de la transcription renvoie une erreur 404

**Cause probable :** La campagne a été mise à jour et le fichier de transcription a été supprimé, ou il s'agit d'un délai de propagation du CDN.

**Solution :**

* Récupérez à nouveau la réponse publicitaire pour obtenir l'URL du fichier actuel.
* Si le problème persiste, contactez le support.

Lorsque vous contactez le support, incluez :

* L'ID de requête (Request ID) ou l'ID de corrélation de l'appel generate
* L'horodatage (UTC) de la requête publicitaire
* L' `<ClosedCaptionFile>` or `videoTranscriptFiles` L'URL qui échoue
* L'erreur de la console du navigateur (pour les problèmes CORS)
* L'espace de noms (namespace) et l'ID de campagne

## Articles connexes

* [Annonces vidéo](/retail-media-interface/integration/fr/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Générer des annonces de bannière X pour différents emplacements](/retail-media-interface/integration/fr/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Référence de la bannière X](/retail-media-interface/integration/fr/references/banner-x-reference-1.md)
* [Prévisualiseur de bannière X](/retail-media-interface/integration/fr/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/fr/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.