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

# Legendas de vídeo do Banner X

## Visão geral

A Epsilon Retail Media plataforma oferece suporte a arquivos de legenda oculta e transcrição para Banner X campanhas de vídeo. Os anunciantes enviam arquivos de legenda (`.vtt`, `.srt`) e arquivos de transcrição (`.txt`) junto com seus ativos de vídeo. Sua integração consome essas URLs de arquivo a partir da resposta do anúncio e exibe as legendas no seu reprodutor de vídeo.

Esta integração ajuda você a cumprir requisitos de acessibilidade, como a Lei Europeia de Acessibilidade (EAA), que exige legendas ocultas controladas pelo usuário em conteúdos em vídeo públicos.

* Arquivos de legenda são faixas de legendas sincronizadas com o tempo para o seu reprodutor de vídeo.
* Arquivos de transcrição são representações em texto simples do conteúdo de áudio do vídeo para uso em SEO e leitores de tela.

Este guia cobre:

* Como os arquivos de legenda e transcrição aparecem nas respostas de anúncio VAST e JSON
* VAST 4.3 `<ClosedCaptionFile>` estrutura de elementos
* JSON `videoTranscriptFiles[]` estrutura de array
* Como exibir legendas usando as URLs de CDN fornecidas
* Testes e validação

### Modelo de entrega

URLs de arquivos de legenda (`.vtt` / `.srt`) são entregues apenas via VAST, não JSON.\
URLs de arquivos de transcrição (`.txt`) são entregues apenas via JSON, não VAST.\
As legendas são consumidas pelo seu reprodutor de vídeo; as transcrições são consumidas no nível da página.

## Fluxo de integração

Os arquivos de legenda e transcrição seguem o mesmo caminho de entrega dos ativos de vídeo. Nenhuma chamada de API adicional é necessária além da sua Banner X solicitação de anúncio existente.

1. Um anunciante envia arquivos de vídeo, legenda e transcrição por meio do assistente de campanha.
2. Os arquivos são validados, armazenados e servidos via CDN.
3. Sua solicitação de anúncio Banner X existente retorna URLs de legenda em VAST e URLs de transcrição em JSON.
4. Seu reprodutor de vídeo lê a URL do arquivo de legenda e exibe as legendas.
5. Sua página exibe opcionalmente o texto da transcrição para acessibilidade ou SEO.

## Tipos de arquivo suportados

| Ativo            | Formatos                         | Tamanho máximo                                                            |
| ---------------- | -------------------------------- | ------------------------------------------------------------------------- |
| Legendas ocultas | `.vtt` (WebVTT), `.srt` (SubRip) | Configurável por padrão de conteúdo do varejista (geralmente de 1 a 4 MB) |
| Transcrição      | `.txt` (texto simples)           | Configurável por padrão de conteúdo do varejista (geralmente de 1 a 4 MB) |

Os arquivos são servidos como estão; a plataforma não converte formatos. Seu reprodutor de vídeo é responsável por exibir as legendas.

## Pré-requisitos

Antes de integrar legendas e transcrições, confirme o seguinte:

* Integração de vídeo Banner X existente — você já consome `<MediaFiles>` a partir da tag VAST no campo adm. Veja [Anúncios de vídeo](/retail-media-interface/integration/pt-br/generating-ads/banner-x-responsive/video-ads-banner-x.md) para um exemplo completo de resposta de anúncio que inclui a entrega de arquivos de legenda e transcrição.
* Reprodutor de vídeo com suporte a legendas — faixas de legenda WebVTT ou SRT (por exemplo, elemento HTML5 `<track>` , ou API equivalente do reprodutor nativo).
* Recurso habilitado para seu namespace — entre em contato com sua equipe de conta para habilitar o envio de legendas e transcrições para seu namespace.
* CORS configurado — permita a busca de origem cruzada de arquivos `.vtt` a partir do domínio CDN Epsilon ao usar elementos HTML5 `<track>` .

## Autenticação e segurança

Nenhuma autenticação adicional é necessária. Os arquivos de legenda e transcrição são servidos via a mesma CDN dos ativos de vídeo. As URLs de arquivo retornadas na resposta do anúncio são acessíveis publicamente, usando o mesmo modelo de segurança das URLs de arquivo de vídeo.

Se o seu reprodutor de vídeo usar elementos HTML5 `<track>` para carregar arquivos `.vtt` , garanta que a Política de Segurança de Conteúdo da sua página permita a busca a partir do domínio CDN Epsilon . A CDN define os cabeçalhos CORS apropriados para carregamento `<track>` de origem cruzada.

## Etapa 1: Analisar arquivos de legenda a partir da resposta VAST

**Objetivo:** Recuperar URLs de arquivos de legenda sincronizados com o tempo a partir do XML do VAST no campo adm para exibição em seu reprodutor de vídeo.

### O que você precisa fazer

* No seu analisador VAST, procure por `<ClosedCaptionFiles>` elemento dentro de cada `<Linear>` criativo (dentro do `<MediaFiles>`).
* Cada `<ClosedCaptionFile>` elemento filho contém a URL da CDN como seu conteúdo de texto.
* O `type` atributo indica o tipo MIME (`text/vtt` or `application/x-subrip` para SRT).
* O `language` atributo indica o idioma da legenda (ex.: `en`).

### Exemplo de resposta 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>
```

### Validação

* Confirme se o seu analisador VAST extrai a `<ClosedCaptionFile>` URL quando presente.
* Confirme se o seu analisador lida adequadamente com a ausência de `<ClosedCaptionFiles>` (nem todas as campanhas incluem legendas).

### Erros comuns

| Erro                                  | Causa                                                                                                                                                                       |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` não encontrado | A campanha pode não ter um arquivo de legenda aprovado ou a entrega de legendas ainda não está habilitada para o seu ambiente. Isso é esperado para campanhas sem legendas. |

## Etapa 2: Analisar arquivos de transcrição a partir da resposta JSON

**Objetivo:** Recuperar URLs de arquivos de transcrição em texto simples da resposta de anúncio JSON para SEO ou acessibilidade de leitor de tela.

### O que você precisa fazer

* No Banner X gerar resposta, procure pelo `videoTranscriptFiles` matriz em cada objeto de anúncio.
* Cada entrada inclui um `videoFileId` para que você possa corresponder as transcrições ao seu vídeo correspondente.
* As transcrições são em texto simples (`.txt`) — use-as para metadados de SEO, leitores de tela ou exibição de texto alternativo.

### Exemplo de resposta JSON

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

### Validação

* Confirme se o seu analisador JSON lê o `videoTranscriptFiles` matriz quando presente.
* Confirme o tratamento adequado quando a matriz estiver vazia ou ausente.

{% hint style="info" %}
URLs de arquivos de legenda (para `.vtt`/`.srt`) são entregues apenas via VAST, não JSON. Arquivos de transcrição (`.txt`) são entregues apenas via JSON, não VAST. Essa separação reflete os diferentes padrões de consumo: legendas são para reprodutores de vídeo (VAST), transcrições são para acessibilidade no nível da página (JSON).\*\*
{% endhint %}

## Etapa 3: Renderizar legendas no seu reprodutor de vídeo

**Objetivo:** Exibir legendas oculta para os compradores durante a reprodução do vídeo.

### O que você precisa fazer

* Após analisar a URL da legenda do VAST, adicione um `<track>` elemento ao seu reprodutor de vídeo HTML5 (ou equivalente no SDK do seu reprodutor nativo).
* Defina `kind="captions"`. Use o `default` atributo se quiser que as legendas fiquem habilitadas por padrão.
* Para arquivos .srt, alguns reprodutores exigem a conversão para WebVTT em tempo de execução (adicione `WEBVTT\n\n` e substitua a vírgula por ponto nos carimbos de data/hora).

### Exemplo de implementação 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>
```

### Validação

* Reproduza o vídeo e confirme se as legendas aparecem como uma sobreposição.
* Confirme se o comprador pode ativar/desativar as legendas por meio dos controles do reprodutor.
* Confirme se as legendas estão sincronizadas no tempo com o áudio do vídeo.

### Erros comuns

| Erro                                               | Solução                                                                                                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| As legendas não carregam (erro de CORS no console) | Certifique-se de que sua Política de Segurança de Conteúdo e a configuração de CORS permitam a busca `.vtt` a partir do domínio CDN Epsilon domínio da CDN. |
| As legendas aparecem ilegíveis ou vazias           | Verifique se a URL do arquivo retorna conteúdo WebVTT válido. Busque a URL diretamente para inspecionar o arquivo.                                          |

## Etapa 4: (Opcional) Exibir o texto da transcrição

**Objetivo:** Fornecer conteúdo de texto acessível ao lado ou abaixo do vídeo para leitores de tela e SEO.

### O que você precisa fazer

* Busque a URL da transcrição a partir da `videoTranscriptFiles` entrada na resposta JSON.
* Use o texto da transcrição para acessibilidade, SEO, leitores de tela ou outros casos de uso específicos do varejista.

### Exemplo

```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 dados e definições de campos

### VAST: `ClosedCaptionFile` elemento

| Atributo / campo  | Tipo         | Obrigatório | Descrição                        | Valores aceitos                  |
| ----------------- | ------------ | ----------- | -------------------------------- | -------------------------------- |
| `type`            | string       | Sim         | Tipo MIME do arquivo de legenda  | `text/vtt, application/x-subrip` |
| `language`        | string       | No          | Idioma da faixa de legenda       | e.g. `en`                        |
| Texto do elemento | string (URL) | Sim         | URL da CDN do arquivo de legenda | URL HTTPS                        |

### JSON: `videoTranscriptFiles`

| Campo         | Tipo         | Obrigatório | Descrição                                                | Valores aceitos |
| ------------- | ------------ | ----------- | -------------------------------------------------------- | --------------- |
| `videoFileId` | string       | Sim         | ID do arquivo de vídeo ao qual esta transcrição pertence | UUID            |
| `format`      | string       | Sim         | Formato de arquivo da transcrição                        | `txt`           |
| `url`         | string (URL) | Sim         | URL da CDN do arquivo de transcrição                     | URL HTTPS       |
| `language`    | string       | Sim         | Idioma da transcrição                                    | e.g. `en`       |

## Compatibilidade com versões anteriores

Estas adições são totalmente compatíveis com versões anteriores:

* Se nenhum arquivo de legenda estiver anexado a uma campanha, o `<ClosedCaptionFiles>` elemento é omitido do VAST inteiramente.
* Se nenhum arquivo de transcrição estiver anexado, `videoTranscriptFiles` está ausente ou é uma matriz vazia no JSON.
* Integrações existentes que não analisam esses novos elementos continuam funcionando sem alterações.

## Testes, sandbox e go-live

### Ambiente de sandbox / teste

* Solicite acesso a um namespace de teste com uploads de legenda e transcrição habilitados (entre em contato com sua equipe de conta).
* Faça upload de uma campanha de teste com um exemplo de `.vtt` arquivo de legenda por meio do assistente de campanha.
* Aprove a campanha por meio do ciclo de revisão.
* Chame o Banner X endpoint de geração e inspecione a resposta VAST e JSON.

### Exemplos de casos de teste

| Teste                        | Etapas                                                         | Resultado esperado                                                        |
| ---------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Legenda VAST presente        | Solicitar anúncio para campanha com legenda `.vtt` aprovada    | VAST contém `<ClosedCaptionFiles>` com URL da CDN válida                  |
| Legenda VAST ausente         | Solicitar anúncio para campanha sem legendas                   | No `<ClosedCaptionFiles>` elemento no VAST                                |
| Transcrição JSON presente    | Solicitar anúncio para campanha com legenda `.txt` transcrição | JSON contém `videoTranscriptFiles` array com entrada                      |
| Arquivo de legenda acessível | Buscar a URL da CDN diretamente da resposta VAST               | Retorna válido `WebVTT` conteúdo com cabeçalho WEBVTT                     |
| O reprodutor exibe legendas  | Carregar vídeo + faixa de legenda no seu reprodutor            | As legendas são exibidas sincronizadas com o áudio do vídeo               |
| CORS para elemento track     | Carregar `.vtt` via `<track>` cross-origin                     | Nenhum erro de CORS no console do navegador; as legendas são renderizadas |

### Checklist de go-live

* [ ] O parser de VAST extrai `<ClosedCaptionFile>` URLs quando presentes
* [ ] O parser de JSON lê `videoTranscriptFiles[]` quando presente
* [ ] Fallback gracioso quando legendas ou transcrições estiverem ausentes
* [ ] O reprodutor de vídeo renderiza legendas a partir da URL da CDN
* [ ] O comprador pode ativar/desativar as legendas
* [ ] CORS validado para cross-origin `.vtt` fetch
* [ ] Texto da transcrição acessível (se implementar a Etapa 4)
* [ ] Testado com ambos `.vtt` e `.srt` formatos de legenda

## Solução de problemas e FAQ

### `<ClosedCaptionFiles>` elemento ausente da resposta VAST

**Causa provável:** A campanha não tem um arquivo de legenda aprovado ou a entrega de legendas não está habilitada no seu ambiente.

**Solução:**

* Confirme se a campanha possui um arquivo de legenda aprovado (enviado e aprovado na revisão).
* Entre em contato com sua equipe de conta para verificar se o recurso está habilitado para seu namespace.

### Erro de CORS ao carregar `.vtt` via `<track>` elemento

**Causa provável:** Content Security Policy ou imposição de CORS do navegador bloqueando o fetch cross-origin do `.vtt` arquivo.

**Solução:**

* Adicione o domínio da CDN do Epsilon às diretivas da sua Content Security Policy `connect-src` e `media-src` diretivas.
* Defina `crossorigin="anonymous"` no elemento pai `<video>` se necessário.

### As legendas são renderizadas, mas não estão sincronizadas com o vídeo

**Causa provável:** O arquivo de legenda foi criado com marcações de tempo incorretas ou o arquivo é um SRT sendo carregado como VTT sem conversão.

**Solução:**

* Busque a URL do arquivo de legenda e inspecione as marcações de tempo em relação à reprodução do vídeo.
* Se o arquivo for .srt e seu player suportar apenas .vtt, converta em tempo de execução (adicione no início `WEBVTT\n\n`e substitua `,` por `.` nas marcações de tempo).

### URL da transcrição retorna 404

**Causa provável:** A campanha foi atualizada e o arquivo de transcrição foi removido, ou há um atraso na propagação da CDN.

**Solução:**

* Busque novamente a resposta do anúncio para obter a URL do arquivo atual.
* Se o problema persistir, entre em contato com o suporte.

Ao entrar em contato com o suporte, inclua:

* ID da solicitação ou ID de correlação da chamada generate
* Marca de tempo (UTC) da solicitação de anúncio
* O `<ClosedCaptionFile>` or `videoTranscriptFiles` URL que está falhando
* Erro do console do navegador (para problemas de CORS)
* Namespace e ID da campanha

## Artigos relacionados

* [Anúncios de vídeo](/retail-media-interface/integration/pt-br/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Gerar anúncios de banner X para posicionamentos diferentes](/retail-media-interface/integration/pt-br/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Referência de Banner X](/retail-media-interface/integration/pt-br/references/banner-x-reference-1.md)
* [Visualizador de Banner X](/retail-media-interface/integration/pt-br/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/pt-br/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.