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

# Titulky k videu Banner X

## Přehled

Tento Epsilon Retail Media platforma podporuje soubory se skrytými titulky a přepisy pro Banner X videokampaně. Inzerenti nahrávají soubory s titulky (`.vtt`, `.srt`) a soubory s přepisy (`.txt`) vedle svých video podkladů. Vaše integrace tyto URL adresy souborů načte z odpovědi na reklamu a vykreslí titulky ve vašem přehrávači videa.

Tato integrace vám pomůže splnit požadavky na přístupnost, jako je Evropský akt o přístupnosti (EAA), který vyžaduje uživatelem ovládané skryté titulky u videoobsahu určeného pro veřejnost.

* Soubory s titulky jsou časově synchronizované stopy s titulky pro váš přehrávač videa.
* Soubory s přepisy jsou textové reprezentace zvukového obsahu videa pro použití v SEO a čtečkách obrazovky.

Tento průvodce popisuje:

* Jak se soubory s titulky a přepisy zobrazují v odpovědích na reklamu VAST a JSON
* VAST 4.3 `<ClosedCaptionFile>` struktura prvku
* JSON `videoTranscriptFiles[]` struktura pole
* Jak vykreslit titulky pomocí poskytnutých URL adres z CDN
* Testování a ověřování

### Model doručování

URL adresy souborů s titulky (`.vtt` / `.srt`) jsou doručovány pouze prostřednictvím VAST, nikoli JSON.\
URL adresy souborů s přepisy (`.txt`) jsou doručovány pouze prostřednictvím JSON, nikoli VAST.\
Titulky zpracovává váš přehrávač videa; přepisy se zpracovávají na úrovni stránky.

## Průběh integrace

Soubory s titulky a přepisy sledují stejnou cestu doručení jako video podklady. Nejsou vyžadována žádná další volání API nad rámec vaší stávající Banner X žádosti o reklamu.

1. Inzerent nahraje video, soubory s titulky a přepisy prostřednictvím průvodce kampaní.
2. Soubory jsou ověřeny, uloženy a doručovány prostřednictvím CDN.
3. Vaše stávající Banner X žádost o reklamu vrátí URL adresy titulků ve VAST a URL adresy přepisů v JSON.
4. Váš přehrávač videa přečte URL adresu souboru s titulky a vykreslí titulky.
5. Vaše stránka volitelně zobrazí text přepisu pro přístupnost nebo SEO.

## Podporované typy souborů

| Podklad        | Formáty                          | Maximální velikost                                                        |
| -------------- | -------------------------------- | ------------------------------------------------------------------------- |
| Skryté titulky | `.vtt` (WebVTT), `.srt` (SubRip) | Nakonfigurovatelné podle standardu obsahu maloobchodníka (obvykle 1–4 MB) |
| Přepis         | `.txt` (čistý text)              | Nakonfigurovatelné podle standardu obsahu maloobchodníka (obvykle 1–4 MB) |

Soubory jsou doručovány v původním stavu; platforma převod formátů neprovádí. Za vykreslení titulků odpovídá váš přehrávač videa.

## Předpoklady

Před integrací titulků a přepisů potvrdíte následující:

* Stávající Banner X integrace videa — již zpracováváte `<MediaFiles>` z tagu VAST v poli adm. Viz [Videoreklamy](/retail-media-interface/integration/cs/generating-ads/banner-x-responsive/video-ads-banner-x.md) pro kompletní příklad odpovědi na reklamu, který zahrnuje doručení souboru s titulky a přepisů.
* Přehrávač videa s podporou titulků — stopy titulků WebVTT nebo SRT (např. HTML5 `<track>` prvek nebo ekvivalentní API nativního přehrávače).
* Funkce povolená pro váš jmenný prostor — kontaktujte svůj klientský tým pro povolení nahrávání titulků a přepisů pro váš jmenný prostor.
* Nakonfigurované CORS — povolte cross-origin načítání `.vtt` souborů z domény Epsilon CDN při použití HTML5 `<track>` prvků.

## Autentizace a zabezpečení

Není vyžadována žádná další autentizace. Soubory s titulky a přepisy jsou doručovány prostřednictvím stejné CDN jako video podklady. URL adresy souborů vrácené v odpovědi na reklamu jsou veřejně přístupné a používají stejný bezpečnostní model jako URL adresy videosouborů.

Pokud váš přehrávač videa používá HTML5 `<track>` prvky k načtení `.vtt` souborů, ujistěte se, že Zásady bezpečnosti obsahu (CSP) vaší stránky povolit načítání z domény Epsilon CDN. CDN nastavuje odpovídající hlavičky CORS pro cross-origin `<track>` načítání.

## Krok 1: Extrahujte soubory s titulky z odpovědi VAST

**Účel:** Získejte časově synchronizované URL adresy souborů s titulky z VAST XML v poli adm pro vykreslení ve vašem přehrávači videa.

### Co musíte udělat

* Ve svém parseru VAST vyhledejte `<ClosedCaptionFiles>` prvek v rámci každého `<Linear>` reklamního materiálu (uvnitř `<MediaFiles>`).
* Každý `<ClosedCaptionFile>` podřízený prvek obsahuje jako svůj textový obsah URL adresu z CDN.
* Atribut `type` označuje typ MIME (`text/vtt` or `application/x-subrip` pro SRT).
* Atribut `language` atribut uvádí jazyk titulků (např. `en`).

### Příklad odpovědi 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>
```

### Validace

* Potvrďte, že váš parser VAST extrahuje `<ClosedCaptionFile>` URL, pokud je přítomna.
* Potvrďte, že váš parser správně zpracuje absenci `<ClosedCaptionFiles>` (ne všechny kampaně obsahují titulky).

### Běžné chyby

| Chyba                             | Příčina                                                                                                                                            |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` nenalezeno | Kampaň nemusí mít schválený soubor s titulky, nebo doručování titulků ještě není pro vaše prostředí povoleno. To se u kampaní bez titulků očekává. |

## Krok 2: Parsejte soubory s transkripty z odpovědi JSON

**Účel:** Získejte URL adresy prostých textových souborů s transkripty z odpovědi ad v JSON pro účely SEO nebo přístupnosti pro čtečky obrazovky.

### Co musíte udělat

* V Banner X odpovědi generate vyhledejte `videoTranscriptFiles` pole u každého objektu reklamy.
* Každá položka obsahuje `videoFileId` takže můžete transkripty přiřadit k odpovídajícímu videu.
* Transkripty jsou prostý text (`.txt`) — použijte je pro metadata SEO, čtečky obrazovky nebo zobrazení alternativního textu.

### Příklad odpovědi JSON

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

### Validace

* Potvrďte, že váš parser JSON čte `videoTranscriptFiles` pole, pokud je přítomno.
* Potvrďte správné zpracování, pokud je pole prázdné nebo chybí.

{% hint style="info" %}
URL adresy souborů s titulky (pro `.vtt`/`.srt`) jsou doručovány pouze prostřednictvím VAST, nikoli JSON. Soubory s transkripty (`.txt`) jsou doručovány pouze prostřednictvím JSON, nikoli VAST. Toto rozdělení odráží různé způsoby použití: titulky jsou pro přehrávače videa (VAST), transkripty jsou pro přístupnost na úrovni stránky (JSON).\*\*
{% endhint %}

## Krok 3: Vykreslete titulky ve svém přehrávači videa

**Účel:** Zobrazujte skryté titulky nakupujícím během přehrávání videa.

### Co musíte udělat

* Po parseování URL adresy titulků z VAST přidejte prvek `<track>` do vašeho HTML5 přehrávače videa (nebo ekvivalentu ve vaší nativní sadě SDK přehrávače).
* Nastavte `kind="captions"`. Použijte atribut `default` pokud chcete mít titulky povoleny ve výchozím nastavení.
* U souborů .srt vyžadují některé přehrávače převod na WebVTT za běhu (předsaďte `WEBVTT\n\n` a nahraďte čárku tečkou v časových razítkách).

### Příklad HTML5 implementace

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

### Validace

* Přehoďte video a potvrďte, že se titulky zobrazují jako překryvná vrstva.
* Potvrďte, že nakupující může zapínat/vypínat titulky pomocí ovládacích prvků přehrávače.
* Potvrďte, že titulky jsou časově synchronizovány se zvukem videa.

### Běžné chyby

| Chyba                                        | Řešení                                                                                                                           |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Titulky se nenačítají (chyba CORS v konzoli) | Ujistěte se, že vaše konfigurační zásady bezpečnosti obsahu a CORS umožňují načítání `.vtt` souborů z domény Epsilon domény CDN. |
| Titulky se zobrazují komoleně nebo prázdné   | Ověřte, že URL adresa souboru vrací platný obsah WebVTT. Načtěte URL přímo a zkontrolujte soubor.                                |

## Krok 4: (Volitelné) Zobrazte text transkriptu

**Účel:** Poskytněte přístupný textový obsah vedle nebo pod videem pro čtečky obrazovky a SEO.

### Co musíte udělat

* Načtěte URL transkriptu z `videoTranscriptFiles` položky v odpovědi JSON.
* Použijte text transkriptu pro přístupnost, SEO, čtečky obrazovky nebo jiné konkrétní případy použití prodejce.

### Příklad

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

## Datové modely a definice polí

### VAST: `ClosedCaptionFile` prvek

| Atribut / pole | Typ           | Povinné | Popis                      | Akceptované hodnoty              |
| -------------- | ------------- | ------- | -------------------------- | -------------------------------- |
| `type`         | řetězec       | Ano     | MIME typ souboru s titulky | `text/vtt, application/x-subrip` |
| `language`     | řetězec       | No      | Jazyk stopy titulků        | e.g. `en`                        |
| Text prvku     | řetězec (URL) | Ano     | CDN URL souboru s titulky  | HTTPS URL                        |

### JSON: `videoTranscriptFiles`

| Pole          | Typ           | Povinné | Popis                                           | Akceptované hodnoty |
| ------------- | ------------- | ------- | ----------------------------------------------- | ------------------- |
| `videoFileId` | řetězec       | Ano     | ID video souboru, ke kterému tento přepis patří | UUID                |
| `format`      | řetězec       | Ano     | Formát souboru přepisu                          | `txt`               |
| `url`         | řetězec (URL) | Ano     | CDN URL souboru s přepisům                      | HTTPS URL           |
| `language`    | řetězec       | Ano     | Jazyk přepisu                                   | e.g. `en`           |

## Zpětná kompatibilita

Tato rozšíření jsou plně zpětně kompatibilní:

* Pokud k kampani nejsou připojeny žádné soubory s titulky, `<ClosedCaptionFiles>` prvek je z VAST zcela vynechán.
* Pokud nejsou připojeny žádné soubory s přepisem, `videoTranscriptFiles` chybí nebo je v JSON prázdným polem.
* Stávající integrace, které tyto nové prvky neanalyzují, fungují i nadále bez změn.

## Testování, sandbox a uvedení do provozu

### Sandbox / testovací prostředí

* Požádejte o přístup k testovacímu jmennému prostoru s povoleným nahráváním titulků a přepisů (kontaktujte svůj klientský tým).
* Nahrajte testovací kampaň s ukázkovým `.vtt` souborem titulků pomocí průvodce kampaní.
* Schvalte kampaň v rámci schvalovacího cyklu.
* Zavolejte Banner X koncový bod generování a zkontrolujte odpověď VAST a JSON.

### Ukázkové testovací případy

| Test                          | Kroky                                                        | Očekávaný výsledek                                          |
| ----------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| VAST titulky přítomny         | Zažádejte o reklamu pro kampaň se schválenými `.vtt` titulky | VAST obsahuje `<ClosedCaptionFiles>` s platnou CDN URL      |
| VAST titulky nepřítomny       | Zažádejte o reklamu pro kampaň bez titulků                   | No `<ClosedCaptionFiles>` prvek ve VAST                     |
| JSON přepis přítomen          | Zažádejte o reklamu pro kampaň se schválenými `.txt` přepis  | JSON obsahuje `videoTranscriptFiles` pole s položkou        |
| Soubor s titulky je přístupný | Načtěte CDN URL přímo z odpovědi VAST                        | Vrací platný `WebVTT` obsah s hlavičkou WEBVTT              |
| Přehrávač zobrazuje titulky   | Načtěte video + stopu titulků do svého přehrávače            | Titulky se zobrazují časově synchronizované se zvukem videa |
| CORS pro prvek track          | Načíst `.vtt` přes `<track>` cross-origin                    | Žádné chyby CORS v konzoli prohlížeče; titulky se zobrazují |

### Kontrolní seznam pro spuštění do ostrého provozu

* [ ] VAST parser extrahuje `<ClosedCaptionFile>` URL, pokud jsou přítomny
* [ ] JSON parser čte `videoTranscriptFiles[]` pokud je přítomen
* [ ] Bezproblémové záložní řešení, pokud titulky nebo přepisy chybí
* [ ] Videopřehrávač zobrazuje titulky z URL adresy CDN
* [ ] Nakupující může zapnout/vypnout titulky
* [ ] CORS ověřeno pro cross-origin `.vtt` načtení
* [ ] Text přepisu je přístupný (pokud implementujete krok 4)
* [ ] Testováno s oběma `.vtt` a `.srt` formáty titulků

## Řešení problémů a časté dotazy

### `<ClosedCaptionFiles>` prvek chybí v odpovědi VAST

**Pravděpodobná příčina:** Kampaň nemá schválený soubor s titulky nebo doručování titulků není ve vašem prostředí povoleno.

**Řešení:**

* Ověřte, že kampaň má schválený soubor s titulky (nahraný a prošel kontrolou).
* Kontaktujte svůj klientský tým a ověřte, zda je tato funkce pro váš jmenný prostor povolena.

### Chyba CORS při načítání `.vtt` přes `<track>` prvku

**Pravděpodobná příčina:** Zásady bezpečnosti obsahu (Content Security Policy) nebo vynucení CORS v prohlížeči blokují načtení z jiného původu (cross-origin) pro `.vtt` soubor.

**Řešení:**

* Přidejte Epsilon doménu CDN do vašich Zásad bezpečnosti obsahu (Content Security Policy) `connect-src` a `media-src` direktiv.
* Nastavte `crossorigin="anonymous"` na nadřazeném `<video>` prvku, pokud je to vyžadováno.

### Titulky se zobrazují, ale nejsou synchronizovány s videem

**Pravděpodobná příčina:** Soubor s titulky byl vytvořen s nesprávnými časovými razítky nebo se jedná o soubor SRT načítaný jako VTT bez převodu.

**Řešení:**

* Načtěte URL souboru s titulky a zkontrolujte časová razítka oproti přehrávání videa.
* Pokud je soubor .srt a váš přehrávač podporuje pouze .vtt, převeďte jej při spuštění (přidejte na začátek `WEBVTT\n\n`, nahraďte `,` za `.` v časových razítkách).

### URL přepisu vrací 404

**Pravděpodobná příčina:** Kampaň byla aktualizována a soubor s přepisům byl odebrán, nebo došlo k prodlení při propagaci na CDN.

**Řešení:**

* Znovu načtěte odpověď reklamy a získejte aktuální URL souboru.
* Pokud problém přetrvává, kontaktujte podporu.

Při kontaktování podpory uveďte:

* ID požadavku nebo korelační ID z volání generate
* Časové razítko (UTC) požadavku na reklamu
* Atribut `<ClosedCaptionFile>` or `videoTranscriptFiles` URL, která selhává
* Chybu v konzoli prohlížeče (pro problémy s CORS)
* Jmenný prostor a ID kampaně

## Související články

* [Videoreklamy](/retail-media-interface/integration/cs/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Generovat Banner X reklamy pro různé umístění](/retail-media-interface/integration/cs/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Banner X reference](/retail-media-interface/integration/cs/references/banner-x-reference-1.md)
* [Banner X náhled](/retail-media-interface/integration/cs/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/cs/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.