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

# Banner X動画の字幕

## Overview

The Epsilon Retail Media プラットフォームは、以下のクローズドキャプションおよび文字起こしファイルをサポートしています： Banner X 動画キャンペーン。広告主はキャプションファイル（`.vtt`, `.srt`）と文字起こしファイル（`.txt`）を動画アセットとともにアップロードします。お客様の連携機能は広告レスポンスからこれらのファイルURLを取得し、動画プレーヤー内にキャプションを表示します。

この連携により、公共向け動画コンテンツでのユーザー制御型クローズドキャプションを義務付ける欧州アクセシビリティ法（EAA）などのアクセシビリティ要件を満たすことができます。

* キャプションファイルは、動画プレーヤー用の時間同期された字幕トラックです。
* 文字起こしファイルは、SEOやスクリーンリーダーでの使用を目的とした、動画の音声内容のプレーンテキスト表現です。

このガイドで扱う内容：

* VASTおよびJSON広告レスポンスにおけるキャプションおよび文字起こしファイルの表示形式
* VAST 4.3の `<ClosedCaptionFile>` 要素の構造
* JSONの `videoTranscriptFiles[]` 配列構造
* 提供されたCDN URLを使用したキャプションの表示方法
* テストと検証

### 配信モデル

キャプションファイルのURL（`.vtt` / `.srt`）はVAST経由でのみ配信され、JSONでは配信されません。\
文字起こしファイルのURL（`.txt`）はJSON経由でのみ配信され、VASTでは配信されません。\
キャプションは動画プレーヤーによって消費され、文字起こしはページレベルで消費されます。

## 連携フロー

キャプションおよび文字起こしファイルは、動画アセットと同じ配信パスに従います。既存の Banner X 広告リクエスト以外の追加のAPI呼び出しは必要ありません。

1. 広告主はキャンペーンウィザードを介して動画、キャプション、および文字起こしファイルをアップロードします。
2. ファイルは検証、保存され、CDN経由で配信されます。
3. 既存の Banner X 広告リクエストにより、VAST内のキャプションURLとJSON内の文字起こしURLが返されます。
4. 動画プレーヤーがキャプションファイルのURLを読み込み、字幕を表示します。
5. ページは、アクセシビリティやSEOのためにオプションで文字起こしテキストを表示します。

## サポートされているファイル形式

| アセット        | フォーマット                           | 最大サイズ                            |
| ----------- | -------------------------------- | -------------------------------- |
| クローズドキャプション | `.vtt` (WebVTT), `.srt` (SubRip) | リテーラーのコンテンツ基準に応じて設定可能 (通常1〜4 MB) |
| 文字起こし       | `.txt` (プレーンテキスト)                | リテーラーのコンテンツ基準に応じて設定可能 (通常1〜4 MB) |

ファイルはそのまま配信されます。プラットフォームはフォーマットを変換しません。キャプションのレンダリングはご使用のビデオプレーヤーが行います。

## 前提条件

キャプションと文字起こしを統合する前に、以下を確認してください:

* 既存の Banner X ビデオ統合 — adm フィールド内の `<MediaFiles>` VAST タグをすでに利用していること。以下を参照してください: [動画広告](/retail-media-interface/integration/ja/generating-ads/banner-x-responsive/video-ads-banner-x.md) キャプションおよび文字起こしファイルの配信を含む、完全な広告レスポンスの例。
* キャプションをサポートするビデオプレーヤー — WebVTT または SRT キャプショントラック (例: HTML5 `<track>` 要素、または同等のネイティブプレーヤー API）。
* 機能がお客さまのネームスペースで有効化されていること — ネームスペースでのキャプションおよび文字起こしのアップロードを有効にするには、アカウントチームにお問い合わせください。
* CORS が設定されていること — 次のからの `.vtt` ファイルのクロスオリジン取得を許可すること Epsilon HTML5 を使用している場合の CDN ドメイン `<track>` 要素。

## 認証とセキュリティ

追加の認証は必要ありません。キャプションと文字起こしファイルは、動画アセットと同じ CDN 経由で配信されます。広告レスポンスで返されるファイル URL は、動画ファイルの URL と同じセキュリティモデルを使用してパブリックにアクセスできます。

動画プレーヤーが HTML5 を使用している場合 `<track>` 読み込む要素 `.vtt` ファイルについては、ページのコンテンツセキュリティポリシーが次からの取得を許可していることを確認してください： Epsilon CDNドメイン。CDNはクロスオリジン用の適切なCORSヘッダーを設定します `<track>` 読み込み。

## ステップ 1: VAST レスポンスからキャプションファイルを解析する

**目的:** 動画プレーヤーで描画するために、adm フィールド内の VAST XML から時間同期されたキャプションファイルの URL を取得します。

### 対応が必要な事項

* VAST パーサー内で、以下を検索します: `<ClosedCaptionFiles>` 内部の要素 `<Linear>` クリエイティブ (内側 `<MediaFiles>`).
* 各 `<ClosedCaptionFile>` 子要素には、そのテキストコンテンツとして CDN URL が含まれます。
* この `type` 属性は MIME タイプを示します (`text/vtt` or `application/x-subrip` SRT の場合)。
* この `language` 属性は字幕の言語を示します (例: `en`).

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

### 検証

* VAST パーサーが存在する場合に `<ClosedCaptionFile>` URL を抽出することを確認します。
* パーサーが `<ClosedCaptionFiles>` の不在を適切に処理することを確認します (すべてのキャンペーンに字幕が含まれているわけではありません)。

### よくあるエラー

| エラー                             | 原因                                                                           |
| ------------------------------- | ---------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` が見つかりません | キャンペーンに承認済みの字幕ファイルがないか、環境で字幕配信がまだ有効になっていない可能性があります。これは字幕のないキャンペーンで予想される動作です。 |

## ステップ 2: JSON レスポンスから文字起こしファイルを解析する

**目的:** SEO またはスクリーンリーダーのアクセシビリティのために、JSON 広告レスポンスからプレーンテキストの文字起こしファイル URL を取得します。

### 対応が必要な事項

* 内 Banner X 生成レスポンスで、各広告オブジェクトの `videoTranscriptFiles` 配列を確認します。
* 各エントリには `videoFileId` が含まれているため、文字起こしを対応する動画と照合できます。
* 文字起こしはプレーンテキスト (`.txt`) です — SEO メタデータ、スクリーンリーダー、または代替テキスト表示に使用します。

### JSON レスポンスの例

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

### 検証

* JSON パーサーが存在する場合に `videoTranscriptFiles` 配列を読み込むことを確認します。
* 配列が空または存在しない場合の適切な処理を確認します。

{% hint style="info" %}
キャプションファイルのURL（ `.vtt`/`.srt`用）はVAST経由でのみ配信され、JSONでは配信されません。文字起こしファイル（`.txt`用）はJSON経由でのみ配信され、VASTでは配信されません。この分離は異なる利用パターンを反映しています。キャプションは動画プレーヤー用（VAST）、文字起こしはページレベルのアクセシビリティ用（JSON）です。\*\*
{% endhint %}

## ステップ 3: 動画プレーヤーでキャプションをレンダリングする

**目的:** 動画再生中にクローズドキャプションを表示します。

### 対応が必要な事項

* VASTからキャプションURLを解析した後、HTML5動画プレーヤー（またはネイティブプレーヤーSDKの同等物）に `<track>` 要素を追加します。
* を `kind="captions"`に設定します。デフォルトでキャプションを有効にしたい場合は、 `default` 属性を使用します。
* .srtファイルの場合、一部のプレーヤーでは実行時にWebVTTへの変換が必要です（先頭に `WEBVTT\n\n` を付加し、タイムスタンプのカンマをピリオドに置き換えます）。

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

### 検証

* 動画を再生し、キャプションがオーバーレイとして表示されることを確認します。
* 買い物客がプレーヤーのコントロールを介してキャプションのオン/オフを切り替えられることを確認します。
* キャプションが動画の音声と時間同期していることを確認します。

### よくあるエラー

| エラー                            | 解決策                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| キャプションが読み込まれない（コンソールでのCORSエラー） | コンテンツセキュリティポリシーとCORS設定で、 `.vtt` ファイルのクロスオリジン取得を許可すること Epsilon CDNドメインからの取得が許可されていることを確認します。 |
| キャプションが文字化けして表示される、または空で表示される  | ファイルURLが有効なWebVTTコンテンツを返すことを確認します。URLを直接取得してファイルを検査します。                                     |

## ステップ 4: (オプション) 文字起こしテキストを表示する

**目的:** スクリーンリーダーやSEOのために、動画の横または下にアクセシブルなテキストコンテンツを提供します。

### 対応が必要な事項

* JSONレスポンス内の `videoTranscriptFiles` エントリから文字起こしURLを取得します。
* アクセシビリティ、SEO、スクリーンリーダー、またはその他のリテールメディア固有のユースケースに文字起こしテキストを使用します。

### 例

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

## データモデルとフィールド定義

### VAST: `ClosedCaptionFile` 要素

| 属性 / フィールド | タイプ       | 必須 | 説明                 | 使用可能な値                           |
| ---------- | --------- | -- | ------------------ | -------------------------------- |
| `type`     | 文字列       | はい | キャプションファイルのMIMEタイプ | `text/vtt, application/x-subrip` |
| `language` | 文字列       | No | キャッショントラックの言語      | e.g. `en`                        |
| 要素のテキスト    | 文字列 (URL) | はい | キャプションファイルのCDN URL | HTTPS URL                        |

### JSON: `videoTranscriptFiles`

| フィールド         | タイプ       | 必須 | 説明                    | 使用可能な値    |
| ------------- | --------- | -- | --------------------- | --------- |
| `videoFileId` | 文字列       | はい | この文字起こしが属するビデオファイルのID | UUID      |
| `format`      | 文字列       | はい | 文字起こしのファイル形式          | `txt`     |
| `url`         | 文字列 (URL) | はい | 文字起こしファイルのCDN URL     | HTTPS URL |
| `language`    | 文字列       | はい | 文字起こしの言語              | e.g. `en` |

## 下位互換性

これらの追加は完全に下位互換性があります:

* キャンペーンにキャプションファイルが添付されていない場合、 `<ClosedCaptionFiles>` 要素はVASTから完全に省略されます。
* 文字起こしファイルが添付されていない場合、 `videoTranscriptFiles` JSONでは非表示にするか、空の配列になります。
* これらの新しい要素を解析しない既存の統合は、変更なしで機能し続けます。

## テスト、サンドボックス、および本番公開

### サンドボックス/テスト環境

* キャプションと文字起こしのアップロードが有効になっているテスト名前空間へのアクセスをリクエストします (アカウントチームにお問い合わせください)。
* サンプルを含むテストキャンペーンをアップロードします `.vtt` キャンペーンウィザード経由のキャプションファイル。
* レビューサイクルを通じてキャンペーンを承認します。
* を呼び出します Banner X generate エンドポイントを呼び出し、VAST と JSON のレスポンスを確認します。

### テストケースのサンプル

| テスト                   | 手順                                      | 期待される結果                                               |
| --------------------- | --------------------------------------- | ----------------------------------------------------- |
| VAST キャプションあり         | 承認済みのキャンペーンの広告をリクエストします `.vtt` キャプション   | VAST に以下が含まれている `<ClosedCaptionFiles>` 有効な CDN URL 付き |
| VAST キャプションなし         | キャプションなしのキャンペーンの広告をリクエストします             | No `<ClosedCaptionFiles>` VAST 内の要素                   |
| JSON トランスクリプトあり       | 承認済みのキャンペーンの広告をリクエストします `.txt` トランスクリプト | JSON に以下が含まれている `videoTranscriptFiles` エントリ付きの配列      |
| キャプションファイルにアクセス可能     | VAST レスポンスから CDN URL を直接取得します           | 有効なを返します `WebVTT` WEBVTT ヘッダー付きのコンテンツ                 |
| プレーヤーがキャプションをレンダリングする | プレーヤーに動画 + キャプション トラックを読み込みます           | 動画の音声と同調してキャプションが表示される                                |
| track 要素の CORS        | 読み込み `.vtt` 経由 `<track>` クロスオリジン        | ブラウザコンソールにCORSエラーがないこと。キャプションが描画されること                 |

### 運用開始前チェックリスト

* [ ] VASTパーサーが抽出する `<ClosedCaptionFile>` URLが存在する場合
* [ ] JSONパーサーが読み取る `videoTranscriptFiles[]` 存在する場合
* [ ] キャプションまたは文字起こしがない場合の適切なフォールバック
* [ ] ビデオプレーヤーがCDN URLからキャプションを描画する
* [ ] ショッパーがキャプションのオン/オフを切り替えられる
* [ ] クロスオリジンに対してCORSが検証されている `.vtt` フェッチする
* [ ] トランスクリプトのテキストにアクセス可能（ステップ4を実装する場合）
* [ ] 両方でテスト済み `.vtt` および `.srt` キャプション形式

## トラブルシューティングとFAQ

### `<ClosedCaptionFiles>` 要素がVAST応答にありません

**考えられる原因:** キャンペーンに承認されたキャプションファイルがないか、お使いの環境でキャプション配信が有効になっていません。

**解決策:**

* キャンペーンに承認されたキャプションファイルがある（アップロードされレビューに合格している）ことを確認します。
* アカウントチームに問い合わせて、ネームスペースで機能が有効になっているか確認します。

### 読み込み時のCORSエラー `.vtt` 経由 `<track>` 要素

**考えられる原因:** コンテンツセキュリティポリシーまたはブラウザのCORS強制により、クロスオリジンフェッチがブロックされている `.vtt` ファイル。

**解決策:**

* 以下を追加します Epsilon CDNドメインをコンテンツセキュリティポリシーの `connect-src` および `media-src` ディレクティブに追加します。
* を `crossorigin="anonymous"` 親 `<video>` 要素に（必要な場合）。

### 字幕は表示されるがビデオと同期しない

**考えられる原因:** 字幕ファイルが誤ったタイムスタンプで作成されているか、ファイルがSRT形式のまま変換されずにVTTとして読み込まれています。

**解決策:**

* 字幕ファイルのURLを取得し、ビデオの再生内容とタイムスタンプを照合します。
* ファイルが.srtであり、プレーヤーが.vttしかサポートしていない場合は、実行時に変換します（先頭に `WEBVTT\n\n`を追加し、 `,` を `.` にタイムスタンプ内で置換）。

### 文字起こしURLが404を返す

**考えられる原因:** キャンペーンが更新されて文字起こしファイルが削除されたか、CDNの反映遅延が発生しています。

**解決策:**

* 広告レスポンスを再取得して、現在のファイルURLを取得します。
* 問題が解消されない場合は、サポートにお問い合わせください。

サポートにお問い合わせの際は、以下を含めてください:

* generate呼び出しのRequest IDまたは correlation ID
* 広告リクエストのタイムスタンプ（UTC）
* この `<ClosedCaptionFile>` or `videoTranscriptFiles` 失敗しているURL
* ブラウザのコンソールエラー（CORS問題の場合）
* ネームスペースとキャンペーンID

## 関連記事

* [動画広告](/retail-media-interface/integration/ja/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [異なる配置用のバナーX広告を生成する](/retail-media-interface/integration/ja/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [バナーXリファレンス](/retail-media-interface/integration/ja/references/banner-x-reference-1.md)
* [バナー X プレビューワー](/retail-media-interface/integration/ja/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/ja/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.