index.md

---
title: ウェブビデオテキストトラック形式 (WebVTT)
slug: Web/API/WebVTT_API
l10n:
  sourceCommit: c6dbc4ff96451887b908b46c8e70bcfec1c2c48c
---

{{DefaultAPISidebar("WebVTT")}}

**ウェブビデオテキストトラック形式 (WebVTT)** は、{{HTMLElement("track")}} 要素を使用して時間指定のテキストトラック（字幕やキャプションなど）を表示するための形式です。 WebVTT ファイルの主な目的は、テキストオーバーレイを {{HTMLElement("video")}} に追加することです。WebVTT はテキストベースの形式であり、{{Glossary("UTF-8")}} を使用してエンコードする必要があります。スペースを使用できる場所では、タブも使用できます。これらのトラックと、正しい時刻にテキストの再生を実行するために必要なデータを表現および管理するために使用できる小さな API もあります。

## WebVTT ファイル

WebVTT の MIME タイプは `text/vtt` です。

WebVTT ファイル（`.vtt`）にはキューが含まれています。キューは、次のように単一行または複数行になります。

```plain
WEBVTT

00:01.000 --> 00:04.000
- 液体窒素を絶対に飲まないでください。

00:05.000 --> 00:09.000
- それはあなたの胃に穴をあけます。
- あなたは死ぬ可能性があります。
```

## WebVTT の本体

WebVTT の構造は、以下のコンポーネントで構成されています。一部のコンポーネントはオプションです。

- オプションのバイトオーダーマーク (BOM)。
- 文字列 "`WEBVTT`"。
- `WEBVTT` の右側にあるオプションのテキストヘッダー。

  - `WEBVTT` の後には少なくとも 1 つのスペースが必要です。
  - これを使用してファイルに説明を追加できます。
  - 改行または文字列 "`-->`" を除いて、テキストヘッダーには何でも使用できます。

- 空白行。2 つの連続した改行に相当します。
- ゼロ個以上のキューまたはコメント。（訳注：これらのブロックは 1 つ以上の空白行で互いに区切られています。）
- ゼロ行以上の空白行。（訳注：ファイルの終りも空白行という扱いです。）

### 例

- 最も単純な WebVTT ファイル

  ```plain
  WEBVTT
  ```

- テキストヘッダーを持つ非常に単純な WebVTT ファイル

  ```plain
  WEBVTT - このファイルにはキューがありません。
  ```

- ヘッダーとキューを使用した一般的な WebVTT の例

  ```plain
  WEBVTT - このファイルにはキューがあります。

  14
  00:01:14.815 --> 00:01:18.114
  - What?
  - Where are we now?

  15
  00:01:18.171 --> 00:01:20.991
  - This is big bat country.

  16
  00:01:21.058 --> 00:01:23.868
  - [ Bats Screeching ]
  - They won't get in your hair. They're after the bugs.
  ```

### WebVTT ファイルの内部構造

前の例の 1 つを再検討し、キューの構造をもう少し詳しく見てみましょう。

```plain
WEBVTT

00:01.000 --> 00:04.000
- 液体窒素を絶対に飲まないでください。

00:05.000 --> 00:09.000
- それはあなたの胃に穴をあけます。
- あなたは死ぬ可能性があります。
```

各キューは、

- 最初の行は時刻で始まります。これは、下にあるテキストを表示するための開始時刻です。
- 同じ行に、`-->` という文字列があります。
- 最初の行を 2 つ目の時刻で終了します。これは、関連するテキストを表示するための終了時刻です。
- ハイフン (-) で始まる 1 行以上の行を表示できます。各行には表示するテキストトラックの一部が含まれています。

ファイルの一部に関する重要な情報を思い出すのに役立つように、`.vtt` ファイルにコメントを入れることもできます。これらは、文字列 `NOTE` で始まる別々の行にあるべきです。以下のセクションでこれらについての詳細を見つけるでしょう。

タイミング行とキュー本体の間など、キュー内で「余分な」空白行を使用しないことが重要です。WebVTT は行ベースで、空白行がキューを閉じます。

## WebVTT のコメント

コメントは、WebVTT ファイルに情報を追加するために使用できるオプションのコンポーネントです。コメントはファイルを読む人のためのものであり、ユーザーには見えません。コメントには改行を含めることができますが、空白行を含めることはできません。これは、連続する 2 行の改行と同じです。空白行はコメントの終わりを表します。

コメントには、文字列 "`-->`"、アンパサンド文字 (`&`)、小なり記号 (`<`) を含めることはできません。このような文字を使用したい場合は、アンパサンドには `&amp;`、小なりには `&lt;` を使用してエスケープする必要があります。タグとの混同を避けるために、大なり記号（`>`）の代わりに大なりエスケープシーケンス (`&gt;`) を使用することをお勧めします。

コメントは次の 3 つの部分で構成されています。

- 文字列 `NOTE`。
- スペースまたは改行。
- 上記以外のゼロ個以上の文字。

### 例

- 一般的な WebVTT の例

  ```plain
  NOTE これはコメントです
  ```

- 複数行のコメント

  ```plain
  NOTE
  複数行に
  またがる別のコメント。

  NOTE このように複数行にまたがって
  コメントすることもできます。
  ```

- 一般的なコメントの使い方

  ```plain
  WEBVTT - 好きな映画の翻訳

  NOTE
  何人かの友人が両親と一緒に見ることができるように、
  Kyle が翻訳しました。

  1
  00:02:15.000 --> 00:02:20.000
  - Ta en kopp varmt te.
  - Det är inte varmt.

  2
  00:02:20.000 --> 00:02:25.000
  - Har en kopp te.
  - Det smakar som te.

  NOTE この最後の行はうまく翻訳されていないかもしれません。

  3
  00:02:25.000 --> 00:02:30.000
  - Ta en kopp
  ```

## WebTT キューのスタイル設定

{{cssxref("::cue")}} 擬似要素に一致する要素を探すことで WebTT キューをスタイル設定することができます。

### サイトの CSS の中

```css
video::cue {
  background-image: linear-gradient(to 下端, dimgray, lightgray);
  color: papayawhip;
}

video::cue(b) {
  color: peachpuff;
}
```

ここでは、すべての動画要素は背景として灰色の線形グラデーションを使用するようにスタイル設定しており、前景色は `"papayawhip"` です。また、{{HTMLElement("b")}} 要素を使用して太字になっているテキストは、`"peachpuff"` で色づけしています。

以下の HTML スニペットは実際にメディア自体の表示を処理します。

```html
<video controls autoplay src="video.webm">
  <track default src="track.vtt" />
</video>
```

### WebVTT ファイル自体の中

WebVTT ファイルで直接スタイルを定義することもできます。この場合、CSS のルールをファイルに挿入します。次に示すように、各ルールの前には、すべてに一行のテキストで文字列 `"STYLE"` が付いています。

```plain
WEBVTT

STYLE
::cue {
  background-image: linear-gradient(to 下端, dimgray, lightgray);
  color: papayawhip;
}
/* スタイルブロックは空白行も "ハイフンハイフン大なり" も使用できません */

NOTE コメントブロックはスタイルブロックの間で使用できます。

STYLE
::cue(b) {
  color: peachpuff;
}

00:00:00.000 --> 00:00:10.000
- Hello <b>world</b>.

NOTE スタイルブロックは、最初のキューの後には出現できません。
```

WebVTT ファイル内で識別子を使用することもできます。これは、ファイル内の特定のキューに対する新しいスタイルを定義するために使用できます。転記テキスト (transcription text) を赤で強調表示し、他の部分を通常のままにしたい例は、CSS を使用して次のように定義できます。CSS が HTML のページで使用しているのと同じ方法でエスケープシーケンスを使用していることに注意する必要があります。

```plain
WEBVTT

1
00:00.000 --> 00:02.000
That's an, an, that's an L!

crédit de transcription
00:04.000 --> 00:05.000
Transcrit par Célestes™
```

```css
::cue(#\31) {
  color: lime;
}
::cue(#crédit\ de\ transcription) {
  color: red;
}
```

以下に示すように、キュー内のタイミングの後に位置情報を含めることで、テキストトラックの位置指定にも対応しています（詳細については、[キュー設定](#キュー設定)を参照してください）。

```plain
WEBVTT

00:00:00.000 --> 00:00:04.000 position:10%,line-left align:left size:35%
Where did he go?

00:00:03.000 --> 00:00:06.500 position:90% align:right size:35%
I think he went down this lane.

00:00:04.000 --> 00:00:06.500 position:45%,line-right align:center size:35%
What are you waiting for?
```

## WebVTT のキュー

キューは、単一の開始時刻、終了時刻、およびテキスト本体を持つ単一の字幕ブロックです。キューは次の 5 つの要素で構成されています。

- オプションのキュー識別子とそれに続く改行。
- キューのタイミング。
- 最初の設定の前と各設定の間に少なくとも 1 つのスペースを持つオプションのキュー設定。
- 1 つの改行。
- キュー本体のテキスト。

こちらがキューの例です。

```plain
1 - Title Crawl
00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start
Some time ago in a place rather distant....
```

### キュー識別子

識別子は、キューを識別する名前です。スクリプトからキューを参照するために使用できます。改行を含むことはできず、文字列 "`-->`" を含むことはできません。それは単一の改行で終わらなければなりません。番号をつけるのが一般的ですが（例えば、1、2、3、...）、それらは一意である必要はありません。

いくつか例を紹介します。

- 基本的なキュー識別子

  ```plain
  1 - Title Crawl
  ```

- 識別子の一般的な使い方

  ```plain
  WEBVTT

  1
  00:00:22.230 --> 00:00:24.606
  This is the first subtitle.

  2
  00:00:30.739 --> 00:00:34.074
  This is the second.

  3
  00:00:34.159 --> 00:00:35.743
  Third
  ```

### キューのタイミング

キューのタイミングは、キューがいつ表示されるかを示します。タイムスタンプで表される開始時刻と終了時刻があります。終了時刻は開始時刻より後でなければならず、開始時刻は前のすべての開始時刻より後でなければなりません。キューは、タイミングが重複するかもしれません。

WebVTT ファイルをチャプターに使用している場合（{{HTMLElement("track")}} の [`kind`](/ja/docs/Web/HTML/Element/track#kind) は `chapters` です）、ファイルは重複するタイミングを持つことはできません。

各キューのタイミングには次の 5 つの要素があります。

- 開始時刻のタイムスタンプ。
- 少なくとも 1 つのスペース。
- 文字列 "`-->`"。
- 少なくとも 1 つのスペース。
- 終了時刻のタイムスタンプ。開始時刻より後でなければなりません。

タイムスタンプは、次の 2 つの形式のいずれかになります。

- `mm:ss.ttt`
- `hh:mm:ss.ttt`

そのコンポーネントは次のように定義されています。

- `hh`
  - : 時を表し、2 桁以上でなければなりません。2 桁を超えることがあります（例えば、9999:00:00.00）。
- `mm`
  - : 分を表し、00 以上 59 以下でなければなりません。
- `ss`
  - : 秒を表し、00 以上 59 以下でなければなりません。
- `ttt`
  - : ミリ秒を表し、000 以上 999 以下でなければなりません。

キューのタイミングの例をいくつか示します。

- 基本的なキューのタイミングの例

  ```plain
  00:00:22.230 --> 00:00:24.606
  00:00:30.739 --> 00:00:34.074
  00:00:34.159 --> 00:00:35.743
  00:00:35.827 --> 00:00:40.122
  ```

- 重複するキューのタイミングの例

  ```plain
  00:00:00.000 --> 00:00:10.000
  00:00:05.000 --> 00:01:00.000
  00:00:30.000 --> 00:00:50.000
  ```

- 重複しないキューのタイミングの例

  ```plain
  00:00:00.000 --> 00:00:10.000
  00:00:10.000 --> 00:01:00.581
  00:01:00.581 --> 00:02:00.100
  00:02:01.000 --> 00:02:01.000
  ```

### キュー設定

キュー設定は、動画上にキュー本体のテキストを表示する位置を決めるために使用するオプションのコンポーネントです。これには、テキストを水平に表示するか垂直に表示するかが含まれます。それらは 0 個以上存在することができ、各設定が 2 回以上使用されない限り、それらは任意の順序で使用できます。

キュー設定は、キューのタイミングの右側に追加します。キューのタイミングと最初の設定の間、および各設定の間には 1 つ以上のスペースが必要です。設定の名前と値はコロンで区切ります。設定では大文字と小文字が区別されるため、次のように小文字を使用してください。次の 5 つのキュー設定があります。

- `vertical`
  - : 一部のアジアの言語のように、テキストを水平ではなく垂直に表示することを示します。取りうる値は 2 つあります。
    - `rl`
      - : 記述方向は右から左
    - `lr`
      - : 記述方向は左から右
- `line`

  - : vertical が設定されていない場合は、テキストを垂直方向に表示する場所を指定します。vertical が設定されている場合、line はテキストを水平方向に表示する場所を指定します。値は次の何れかです。

    - 行番号
      - : 数値は、映像に表示されるキューの最初の行の垂直位置です。正の数値はトップダウン、負の数値はボトムアップを示します。
    - パーセント値
      - : 0 から 100 までの整数（小数点を含まない）で、その後にパーセント記号 (%) を付けなければなりません。

    | line        | `vertical` を省略 | `vertical:rl` | `vertical:lr` |
    | ----------- | ----------------- | ------------- | ------------- |
    | `line:0`    | 上端              | 右端          | 左端          |
    | `line:-1`   | 下端              | 左端          | 右端          |
    | `line:0%`   | 上端              | 右端          | 左端          |
    | `line:100%` | 下端              | 左端          | 右端          |

- `position`

  - : テキストを水平方向に表示する場所を指定します。vertical を設定している場合、position はテキストを垂直方向に表示する場所を指定します。値はパーセント値で、0 から 100 までの整数（小数点なし）でなければならず、その後にパーセント記号（`%`）を付ける必要があります。

    | position        | `vertical` を省略 | `vertical:rl` | `vertical:lr` |
    | --------------- | ----------------- | ------------- | ------------- |
    | `position:0%`   | 左端              | 上端          | 上端          |
    | `position:100%` | 右端              | 下端          | 下端          |

- `size`

  - : テキスト領域の幅を指定します。vertical を設定している場合、size はテキスト領域の高さを指定します。値はパーセントで、0 から 100 までの整数（つまり、小数点なし）でなければならず、その後にパーセント記号 (`%`) を付ける必要があります。

    | size        | `vertical` omitted | `vertical:rl` | `vertical:lr` |
    | ----------- | ------------------ | ------------- | ------------- |
    | `size:100%` | full width         | full height   | full height   |
    | `size:50%`  | half width         | half height   | half height   |

- `align`

  - : テキストの配置を指定します。設定している場合、テキストは size キュー設定で指定したスペース内に配置されます。

    | align          | `vertical` を省略  | `vertical:rl`      | `vertical:lr`      |
    | -------------- | ------------------ | ------------------ | ------------------ |
    | `align:start`  | 左端               | 上端               | 上端               |
    | `align:center` | 水平方向に中央揃え | 垂直方向に中央揃え | 垂直方向に中央揃え |
    | `align:end`    | 右端               | 下端               | 下端               |

キュー設定の例を見てみましょう。

最初の行は設定がないことを示しています。2 行目は、サインやラベルの上にテキストを重ねるために使用します。3 行目はタイトルに使用できます。最後の行はアジアの言語に使われるかもしれません。

```plain
00:00:05.000 --> 00:00:10.000
00:00:05.000 --> 00:00:10.000 line:63% position:72% align:start
00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start
00:00:05.000 --> 00:00:10.000 vertical:rt line:-1 align:end
```

### キュー本体

本体は、主な情報またはコンテンツを配置する場所です。通常の使用法では、本体には表示する字幕が含まれています。本体のテキストには改行を含めることができますが、空白行を含めることはできません。これは、2 つの連続する改行に相当します。空白行はキューの終わりを表します。

キュー本体のテキストには、文字列 `-->`、アンパサンド文字 (`&`)、小なり記号 (`<`) を含めることはできません。代わりに、アンパサンドにはエスケープシーケンス `&amp;` を使用し、小なりには `&lt;` を使用します。タグとの混同を避けるために、大なり記号 (`>`) の代わりに大なりエスケープシーケンス `&gt;` を使用することをお勧めします。メタデータに WebVTT ファイルを使用している場合、これらの制限は適用されません。

上記の 3 つのエスケープシーケンスに加えて、他にも 4 つあります。以下の表に示します。

| 名前             | 文字   | エスケープシーケンス |
| ---------------- | ------ | -------------------- |
| アンパサンド     | `&`    | `&amp;`              |
| 小なり           | `<`    | `&lt;`               |
| 大なり           | `>`    | `&gt;`               |
| 左書き           | _なし_ | `&lrm;`              |
| 右書き           | _なし_ | `&rlm;`              |
| 改行なしスペース |        | `&nbsp;`             |

### キュー本体のテキストタグ

使用できるタグは `<b>` など多数あります。ただし、WebVTT ファイルが {{HTMLElement("track")}} 要素の中で使われていて、その属性 [`kind`](/ja/docs/Web/HTML/Element/track#kind) が `chapters` である場合は、タグを使うことができません。

- タイムスタンプタグ

  - : タイムスタンプは、キューの開始タイムスタンプより大きく、キュー本体内の前のタイムスタンプより大きく、キューの終了タイムスタンプより小さくなければなりません。*アクティブテキスト*は、タイムスタンプと次のタイムスタンプの間、または本体に別のタイムスタンプがない場合は本体の最後までのテキストです。本体内の*アクティブテキスト*より前のテキストはすべて*過去のテキスト*です。*アクティブテキスト*より後のテキストはすべて*将来のテキスト*です。これによりカラオケ風のキャプションが実現できます。

    ```plain
    1
    00:16.500 --> 00:18.500
    When the moon <00:17.500>hits your eye

    1
    00:00:18.500 --> 00:00:20.500
    Like a <00:19.000>big-a <00:19.500>pizza <00:20.000>pie

    1
    00:00:20.500 --> 00:00:21.500
    That's <00:00:21.000>amore
    ```

次のタグは、キューで使用できる HTML タグで、開始タグと終了タグ（例えば、`<b>テキスト</b>`）が必要です。

- クラスタグ (`<c></c>`)

  - : CSS クラスを使用して含まれているテキストをスタイルします。

    ```xml
    <c.classname>text</c>
    ```

- イタリック体タグ (`<i></i>`)

  - : 含まれているテキストをイタリック体にします。

    ```xml
    <i>text</i>
    ```

- **太字タグ** (`<b></b>`)

  - : 含まれているテキストを太字にします。

    ```xml
    <b>text</b>
    ```

- 下線タグ (`<u></u>`)

  - : 含まれているテキストに下線を引きます。

    ```xml
    <u>text</u>
    ```

- ルビタグ (`<ruby></ruby>`)

  - : [ルビ文字](https://ja.wikipedia.org/wiki/%E3%83%AB%E3%83%93)（すなわち、他の文字の上にある小さな注釈文字）を表示するためにルビテキストタグと共に使用します。

    ```xml
    <ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
    ```

- ルビテキストタグ (`<rt></rt>`)

  - : [ルビ文字](https://ja.wikipedia.org/wiki/%E3%83%AB%E3%83%93)（つまり、他の文字の上にある小さな注釈文字）を表示するためにルビタグとともに使用します。

    ```xml
    <ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
    ```

- ボイスタグ (`<v></v>`)

  - クラスタグと同様に、CSS を使用して含まれているテキストをスタイルするためにも使用します。

    ```xml
    <v Bob>text</v>
    ```

## インスタンスメソッドとプロパティ

WebVTT で使用するメソッドは、両方のインターフェイスの属性が異なるため、キューまたは領域を変更するために使用するものです。WebVTT の各インターフェイスに関する理解を深めるために、それらを分類することができます。

### VTTCue

- {{domxref("VTTCue")}} インターフェイスで利用できるメソッドは次のとおりです。

- {{domxref("VTTCue.getCueAsHTML", "getCueAsHTML()")}}: そのキューの HTML を取得します。
- コンストラクター、{{domxref("VTTCue.VTTCue", "VTTCue()")}} はこのインターフェイスの新しいインスタンスを生成します。

キューの位置、配置、サイズなど、キューの特性を読み取り、設定するためのさまざまなプロパティも用意されています。完全なリストは {{domxref("VTTCue")}} を参照してください。

### VTTRegion

{{domxref("VTTRegion")}} では、機能の説明とともにメソッドを提供します。特に、与えられた領域内に存在するすべてのノードのスクロール設定を調整することができます。

## WebVTT ファイルの書き方に関するチュートリアル

簡単な WebVTT ファイルを作成するには、いくつかのステップを踏む必要があります。まず、メモ帳を使い、'.vtt' ファイルとして保存します。手順は以下の通りです。

- メモ帳を開きます。
- WebVTT の最初の行は、ファイルがファイルの種類を示し始めるときに他の言語ではヘッダーを配置するように要求されるのと同様に標準化されています。最初の 1 行は次のように書く必要があります。

  ```plain
  WEBVTT
  ```

- 2 行目を空白のままにして、3 行目で最初のキューの時間を指定します。例えば、時間が 1 秒で始まり 5 秒で終わる最初のキューでは、次のようになります。

  ```plain
  00:01.000 --> 00:05.000
  ```

- 次の行に、このキューのキャプションを書くことができます。キャプションは 1 秒から 5 秒までです。
- 同様の手順に従って、特定の動画または音声ファイル用の完全な WebVTT ファイルを作成できます。

## CSS 擬似クラス

CSS 擬似クラスを使用すると、他の種類のオブジェクトと区別したいオブジェクトの種類を分類できます。WebVTT ファイルでも HTML ファイルと同じように機能します。

WebVTT が備えている優れた機能には、ローカライズと class 要素の使用があります。class 要素は、HTML や CSS で特定の型のオブジェクトのスタイルを分類するために使われるのと同じように使用できますが、ここでは、以下のようにキューのスタイルと分類に使用されています。

```plain
WEBVTT

04:02.500 --> 04:05.000
J'ai commencé le basket à l'âge de 13, 14 ans

04:05.001 --> 04:07.800
Sur les <i.foreignphrase><lang en>playground</lang></i>, ici à Montpellier
```

上記の例では、キャプションの言語を定義するために識別子と擬似クラス名を使用できることがわかります。`<i>` タグはイタリック体のためのものです。

擬似クラスの型はそれを使用しているセレクターによって決定し、それは HTML で機能するのと同じように機能します。以下の CSS 擬似クラスを使用することができます。

- `lang` (Language): 例えば、`p:lang(it)`。
- `link`: 例えば、`a:link`。
- `nth-last-child`: 例えば、`p:nth-last-child(2)`。
- `nth-child(n)`: 例えば、`p:nth-child(2)`。

ここで、`p` と `a` はそれぞれ HTML で段落とリンクに使われるタグで、WebVTT ファイルの Cue に使われる識別子に置き換えることができます。

## 仕様書

{{Specifications}}

## ブラウザーの互換性

{{Compat}}

### メモ

Firefox 50 より前のバージョンでは、`AlignSetting` 列挙体（{{domxref("VTTCue.align")}} に指定可能な値を表す）に、`"center"` ではなく `"middle"` という値が誤って含まれていました。これは修正されました。

WebVTT は Firefox 24 では `media.webvtt.enabled` の設定に隠されて実装されており、既定では無効になっています。この設定を `true` に設定することで有効にできます。WebVTT は Firefox 31 以降では既定で有効になっていますが、設定を `false` に設定することで無効にすることができます。

Firefox 58 より前のバージョンでは、`REGION` キーワードは {{domxref("VTTRegion")}} オブジェクトを作成していましたが、使用していませんでした。Firefox 58 は現在 `VTTRegion` とその使用を完全にサポートしています。ただし、この機能は設定 `media.webvtt.regions.enabled` に隠されて既定で無効になっています。Firefox 58 で領域のサポートを有効にするには、`true` に設定してください。領域は Firefox 59 以降で既定で有効になっています（[Firefox bug 1338030](https://bugzil.la/1338030) および [Firefox bug 1415805](https://bugzil.la/1415805) のバグを参照）。

## 関連情報

- CSS の [`::cue` および `::cue()`](/ja/docs/Web/CSS/::cue) 擬似要素