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

# Banner X-Videountertitel

## Übersicht

Die Epsilon Retail Media Plattform unterstützt Closed-Caption- und Transkript-Dateien für Banner X Video-Kampagnen. Werbetreibende laden Untertitel-Dateien (`.vtt`, `.srt`) und Transkript-Dateien (`.txt`) zusammen mit ihren Video-Assets hoch. Ihre Integration bezieht diese Datei-URLs aus der Anzeigen-Antwort und rendert die Untertitel in Ihrem Video-Player.

Diese Integration hilft Ihnen, Barrierefreiheitsanforderungen wie den European Accessibility Act (EAA) zu erfüllen, der benutzergesteuerte Closed Captions für öffentlich zugängliche Videoinhalte vorschreibt.

* Untertitel-Dateien sind zeitlich synchronisierte Untertitel-Spuren für Ihren Video-Player.
* Transkript-Dateien sind reine Textdarstellungen des Audioinhalts des Videos für SEO und die Nutzung von Screenreadern.

Dieser Leitfaden umfasst:

* Wie Untertitel- und Transkript-Dateien in VAST- und JSON-Anzeigen-Antworten erscheinen
* VAST 4.3 `<ClosedCaptionFile>` -Elementstruktur
* JSON `videoTranscriptFiles[]` -Array-Struktur
* So rendern Sie Untertitel mit den bereitgestellten CDN-URLs
* Testen und Validieren

### Bereitstellungsmodell

Untertitel-Datei-URLs (`.vtt` / `.srt`) werden nur über VAST bereitgestellt, nicht über JSON.\
Transkript-Datei-URLs (`.txt`) werden nur über JSON bereitgestellt, nicht über VAST.\
Untertitel werden von Ihrem Video-Player verarbeitet; Transkripte werden auf Seitenebene verarbeitet.

## Integrationsablauf

Untertitel- und Transkript-Dateien folgen demselben Bereitstellungspfad wie Video-Assets. Es sind keine zusätzlichen API-Aufrufe über Ihre bestehende Banner X Anzeigenanforderung hinaus erforderlich.

1. Ein Werbetreibender lädt Video-, Untertitel- und Transkript-Dateien über den Kampagnen-Assistenten hoch.
2. Dateien werden validiert, gespeichert und über CDN bereitgestellt.
3. Ihre bestehende Banner X Anzeigenanforderung gibt Untertitel-URLs in VAST und Transkript-URLs in JSON zurück.
4. Ihr Video-Player liest die Untertitel-Datei-URL und rendert Untertitel.
5. Ihre Seite zeigt optional Transkript-Text für Barrierefreiheit oder SEO an.

## Unterstützte Dateitypen

| Asset           | Formate                          | Maximale Größe                                                           |
| --------------- | -------------------------------- | ------------------------------------------------------------------------ |
| Closed Captions | `.vtt` (WebVTT), `.srt` (SubRip) | Konfigurierbar nach Inhaltsstandard des Händlers (typischerweise 1–4 MB) |
| Transkript      | `.txt` (Klartext)                | Konfigurierbar nach Inhaltsstandard des Händlers (typischerweise 1–4 MB) |

Dateien werden unverändert bereitgestellt; die Plattform konvertiert keine Formate. Ihr Video-Player ist für das Rendern der Untertitel verantwortlich.

## Voraussetzungen

Bestätigen Sie vor der Integration von Untertiteln und Transkripten Folgendes:

* Bestehende Banner X Video-Integration – Sie verarbeiten bereits `<MediaFiles>` aus dem VAST-Tag im adm-Feld. Siehe [Video-Anzeigen](/retail-media-interface/integration/de/generating-ads/banner-x-responsive/video-ads-banner-x.md) für ein vollständiges Beispiel einer Anzeigen-Antwort, das die Bereitstellung von Untertitel- und Transkript-Dateien enthält.
* Video-Player mit Untertitel-Unterstützung – WebVTT- oder SRT-Untertitel-Spuren (z. B. HTML5 `<track>` -Element oder entsprechende native Player-API).
* Funktion für Ihren Namespace aktiviert – kontaktieren Sie Ihr Account-Team, um das Hochladen von Untertiteln und Transkripten für Ihren Namespace zu aktivieren.
* CORS konfiguriert – erlauben Sie das domänenübergreifende Abrufen von `.vtt` -Dateien von der Epsilon CDN-Domain bei Verwendung von HTML5 `<track>` -Elementen.

## Authentifizierung und Sicherheit

Es ist keine zusätzliche Authentifizierung erforderlich. Untertitel- und Transkript-Dateien werden über dasselbe CDN bereitgestellt wie Video-Assets. In der Anzeigen-Antwort zurückgegebene Datei-URLs sind öffentlich zugänglich und nutzen dasselbe Sicherheitsmodell wie Video-Datei-URLs.

Wenn Ihr Video-Player HTML5 `<track>` -Elemente verwendet, um `.vtt` -Dateien zu laden, stellen Sie sicher, dass die Content Security Policy Ihrer Seite das Abrufen aus der Epsilon CDN-Domain erlaubt. Das CDN setzt entsprechende CORS-Header für domänenübergreifendes `<track>` Laden.

## Schritt 1: Untertitel-Dateien aus der VAST-Antwort parsen

**Zweck:** Abrufen zeitlich synchronisierter Untertitel-Datei-URLs aus dem VAST-XML im adm-Feld zum Rendern in Ihrem Video-Player.

### Was Sie tun müssen

* Suchen Sie in Ihrem VAST-Parser nach dem `<ClosedCaptionFiles>` Element innerhalb jedes `<Linear>` Werbemittel (innerhalb von `<MediaFiles>`).
* Jedes `<ClosedCaptionFile>` Unterelement enthält die CDN-URL als seinen Textinhalt.
* Das `type` -Attribut gibt den MIME-Typ an (`text/vtt` or `application/x-subrip` für SRT).
* Das `language` -Attribut gibt die Untertitelsprache an (z. B. `en`).

### Beispiel für eine VAST-Antwort

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

### Validierung

* Bestätigen Sie, dass Ihr VAST-Parser die `<ClosedCaptionFile>` -URL extrahiert, wenn sie vorhanden ist.
* Bestätigen Sie, dass Ihr Parser das Fehlen von `<ClosedCaptionFiles>` ordnungsgemäß verarbeitet (nicht alle Kampagnen enthalten Untertitel).

### Häufige Fehler

| Fehler                                | Ursache                                                                                                                                                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `<ClosedCaptionFiles>` nicht gefunden | Die Kampagne verfügt möglicherweise nicht über eine genehmigte Untertiteldatei oder die Auslieferung von Untertiteln ist für Ihre Umgebung noch nicht aktiviert. Dies wird für Kampagnen ohne Untertitel erwartet. |

## Schritt 2: Transkriptdateien aus der JSON-Antwort parsen

**Zweck:** Abrufen von Klartext-Transkriptdatei-URLs aus der JSON-Anzeigenantwort für SEO oder Screenreader-Barrierefreiheit.

### Was Sie tun müssen

* Suchen Sie in der Banner X generate-Antwort nach dem Array `videoTranscriptFiles` auf jedem Anzeigenobjekt.
* Jeder Eintrag enthält eine `videoFileId` , damit Sie Transkripte ihrem entsprechenden Video zuordnen können.
* Transkripte sind Klartext (`.txt`) — verwenden Sie diese für SEO-Metadaten, Screenreader oder alternative Textanzeigen.

### Beispiel für eine JSON-Antwort

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

### Validierung

* Bestätigen Sie, dass Ihr JSON-Parser das Array `videoTranscriptFiles` liest, wenn es vorhanden ist.
* Bestätigen Sie die ordnungsgemäße Handhabung, wenn das Array leer ist oder fehlt.

{% hint style="info" %}
Untertiteldatei-URLs (für `.vtt`/`.srt`) werden nur über VAST ausgeliefert, nicht über JSON. Transkriptdateien (`.txt`) werden nur über JSON ausgeliefert, nicht über VAST. Diese Trennung spiegelt die unterschiedlichen Nutzungsmuster wider: Untertitel sind für Videoplayer (VAST), Transkripte sind für die Barrierefreiheit auf Seitenebene (JSON).\*\*
{% endhint %}

## Schritt 3: Untertitel in Ihrem Videoplayer rendern

**Zweck:** Anzeigen von Untertiteln für Käufer während der Videowiedergabe.

### Was Sie tun müssen

* Nachdem Sie die Untertitel-URL aus VAST geparst haben, fügen Sie ein `<track>` -Element zu Ihrem HTML5-Videoplayer hinzu (oder das Äquivalent in Ihrem nativen Player-SDK).
* Setzen Sie `kind="captions"`. Verwenden Sie das Attribut `default` , wenn Sie möchten, dass Untertitel standardmäßig aktiviert sind.
* Bei .srt-Dateien erfordern einige Player zur Laufzeit eine Konvertierung in WebVTT (stellen Sie `WEBVTT\n\n` voran und ersetzen Sie Kommas in Zeitstempeln durch Punkte).

### Beispiel für eine HTML5-Implementierung

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

### Validierung

* Spielen Sie das Video ab und bestätigen Sie, dass die Untertitel als Overlay erscheinen.
* Bestätigen Sie, dass der Käufer die Untertitel über die Player-Steuerelemente ein- und ausschalten kann.
* Bestätigen Sie, dass die Untertitel zeitlich mit dem Video-Audio synchronisiert sind.

### Häufige Fehler

| Fehler                                                       | Lösung                                                                                                                                                 |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Untertitel werden nicht geladen (CORS-Fehler in der Konsole) | Stellen Sie sicher, dass Ihre Content Security Policy und Ihre CORS-Konfiguration das Abrufen der `.vtt` -Dateien von der Epsilon CDN-Domain zulassen. |
| Untertitel erscheinen unleserlich oder leer                  | Überprüfen Sie, ob die Datei-URL gültigen WebVTT-Inhalt zurückgibt. Rufen Sie die URL direkt auf, um die Datei zu überprüfen.                          |

## Schritt 4: (Optional) Transkripttext anzeigen

**Zweck:** Bereitstellung von barrierefreiem Textinhalt neben oder unter dem Video für Screenreader und SEO.

### Was Sie tun müssen

* Rufen Sie die Transkript-URL aus dem Eintrag `videoTranscriptFiles` in der JSON-Antwort ab.
* Verwenden Sie den Transkripttext für Barrierefreiheit, SEO, Screenreader oder andere händlerspezifische Anwendungsfälle.

### Beispiel

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

## Datenmodelle und Felddefinitionen

### VAST: `ClosedCaptionFile` -Element

| Attribut / Feld | Typ          | Erforderlich | Beschreibung                  | Akzeptierte Werte                |
| --------------- | ------------ | ------------ | ----------------------------- | -------------------------------- |
| `type`          | String       | Ja           | MIME-Typ der Untertitel-Datei | `text/vtt, application/x-subrip` |
| `language`      | String       | No           | Sprache der Untertitel-Spur   | e.g. `en`                        |
| Element-Text    | String (URL) | Ja           | CDN-URL der Untertitel-Datei  | HTTPS-URL                        |

### JSON: `videoTranscriptFiles`

| Feld          | Typ          | Erforderlich | Beschreibung                                       | Akzeptierte Werte |
| ------------- | ------------ | ------------ | -------------------------------------------------- | ----------------- |
| `videoFileId` | String       | Ja           | ID der Videodatei, zu der dieses Transkript gehört | UUID              |
| `format`      | String       | Ja           | Dateiformat des Transkripts                        | `txt`             |
| `url`         | String (URL) | Ja           | CDN-URL der Transkript-Datei                       | HTTPS-URL         |
| `language`    | String       | Ja           | Sprache des Transkripts                            | e.g. `en`         |

## Rückwärtskompatibilität

Diese Ergänzungen sind vollständig rückwärtskompatibel:

* Wenn einer Kampagne keine Untertitel-Dateien angehängt sind, wird das `<ClosedCaptionFiles>` Element im VAST vollständig weggelassen.
* Wenn keine Transkript-Dateien angehängt sind, `videoTranscriptFiles` ist in JSON nicht vorhanden oder ein leeres Array.
* Bestehende Integrationen, die diese neuen Elemente nicht parsen, funktionieren weiterhin ohne Änderungen.

## Testen, Sandbox und Go-Live

### Sandbox- / Testumgebung

* Fordern Sie Zugriff auf einen Test-Namespace mit aktivierten Untertitel- und Transkript-Uploads an (kontaktieren Sie Ihr Account-Team).
* Laden Sie eine Testkampagne mit einer Beispiel- `.vtt` Untertitel-Datei über den Kampagnen-Assistenten hoch.
* Genehmigen Sie die Kampagne durch den Prüfzyklus.
* Rufen Sie den Banner X generate-Endpunkt auf und prüfen Sie die VAST- und JSON-Antwort.

### Beispiel-Testfälle

| Test                            | Schritte                                                                         | Erwartetes Ergebnis                                                     |
| ------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| VAST-Untertitel vorhanden       | Fordern Sie eine Anzeige für eine Kampagne mit genehmigten `.vtt` Untertiteln an | VAST enthält `<ClosedCaptionFiles>` mit gültiger CDN-URL                |
| VAST-Untertitel nicht vorhanden | Fordern Sie eine Anzeige für eine Kampagne ohne Untertitel an                    | No `<ClosedCaptionFiles>` Element in VAST                               |
| JSON-Transkript vorhanden       | Fordern Sie eine Anzeige für eine Kampagne mit genehmigten `.txt` Transkript     | JSON enthält `videoTranscriptFiles` Array mit Eintrag                   |
| Untertitel-Datei zugänglich     | Rufen Sie die CDN-URL direkt aus der VAST-Antwort ab                             | Gibt gültigen `WebVTT` Inhalt mit WEBVTT-Header zurück                  |
| Player rendert Untertitel       | Laden Sie Video + Untertitel-Spur in Ihren Player                                | Untertitel werden zeitlich synchronisiert mit dem Video-Audio angezeigt |
| CORS für track-Element          | Laden Sie `.vtt` über `<track>` cross-origin                                     | Keine CORS-Fehler in der Browser-Konsole; Untertitel werden gerendert   |

### Checkliste für das Go-Live

* [ ] VAST-Parser extrahiert `<ClosedCaptionFile>` URLs, sofern vorhanden
* [ ] JSON-Parser liest `videoTranscriptFiles[]` sofern vorhanden
* [ ] Aufgeräumter Fallback, wenn Untertitel oder Transkripte fehlen
* [ ] Videoplayer rendert Untertitel von der CDN-URL
* [ ] Shopper kann Untertitel ein-/ausschalten
* [ ] CORS für domänenübergreifende Abrufe validiert `.vtt` fetch
* [ ] Transkripttext zugänglich (falls Schritt 4 implementiert wird)
* [ ] Getestet mit beiden `.vtt` und `.srt` Untertitelformaten

## Fehlerbehebung und FAQ

### `<ClosedCaptionFiles>` Element fehlt in der VAST-Antwort

**Mögliche Ursache:** Die Kampagne hat keine genehmigte Untertiteldatei oder die Untertitelbereitstellung ist in Ihrer Umgebung nicht aktiviert.

**Lösung:**

* Bestätigen Sie, dass die Kampagne eine genehmigte Untertiteldatei hat (hochgeladen und Überprüfung bestanden).
* Wenden Sie sich an Ihr Account-Team, um zu überprüfen, ob die Funktion für Ihren Namespace aktiviert ist.

### CORS-Fehler beim Laden des `.vtt` über `<track>` Elements

**Mögliche Ursache:** Content Security Policy oder Browser-CORS-Durchsetzung blockiert den domänenübergreifenden Abruf der `.vtt` Datei.

**Lösung:**

* Fügen Sie die Epsilon CDN-Domäne zu den `connect-src` und `media-src` Direktiven Ihrer Content Security Policy hinzu.
* Setzen Sie `crossorigin="anonymous"` auf dem übergeordneten `<video>` Element, falls erforderlich.

### Untertitel werden gerendert, sind aber nicht mit dem Video synchronisiert

**Mögliche Ursache:** Die Untertiteldatei wurde mit falschen Zeitstempeln erstellt oder die Datei ist eine SRT-Datei, die ohne Konvertierung als VTT geladen wird.

**Lösung:**

* Rufen Sie die URL der Untertiteldatei ab und überprüfen Sie die Zeitstempel im Vergleich zur Videowiedergabe.
* Wenn die Datei eine .srt-Datei ist und Ihr Player nur .vtt unterstützt, konvertieren Sie sie zur Laufzeit (voranstellen von `WEBVTT\n\n`, ersetzen von `,` durch `.` in Zeitstempeln).

### Transkript-URL gibt 404 zurück

**Mögliche Ursache:** Die Kampagne wurde aktualisiert und die Transkriptdatei wurde entfernt, oder es liegt eine CDN-Verzögerung vor.

**Lösung:**

* Rufen Sie die Anzeigenantwort erneut ab, um die aktuelle Datei-URL zu erhalten.
* Wenn das Problem weiterhin besteht, wenden Sie sich an den Support.

Wenn Sie den Support kontaktieren, geben Sie Folgendes an:

* Anfrage-ID oder Korrelations-ID aus dem Generate-Aufruf
* Zeitstempel (UTC) der Anzeigenanfrage
* Das `<ClosedCaptionFile>` or `videoTranscriptFiles` URL, die fehlschlägt
* Browser-Konsolenfehler (bei CORS-Problemen)
* Namespace und Kampagnen-ID

## Ähnliche Artikel

* [Video-Anzeigen](/retail-media-interface/integration/de/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Generieren Sie Banner X-Anzeigen für verschiedene Platzierungen](/retail-media-interface/integration/de/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Banner X-Referenz](/retail-media-interface/integration/de/references/banner-x-reference-1.md)
* [Banner X-Vorschau](/retail-media-interface/integration/de/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/de/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.