--- title: Web ビデオテキストトラックフォーマット (WebVTT) slug: Web/API/WebVTT_API tags: - API - Intermediate - Media - Reference - Video - Web Video Text Tracks - WebVTT - captions - subtitles - text tracks translation_of: Web/API/WebVTT_API ---
{{DefaultAPISidebar("WebVTT")}}

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

WebVTT ファイル

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

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

WEBVTT

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

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

WebVTT の本体

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

例 1 - 最も単純な WebVTT ファイル
WEBVTT
例 2 - テキストヘッダーを持つ非常に単純な WebVTT ファイル
WEBVTT - このファイルにはキューがありません。
例 3 - ヘッダーとキューを使用した一般的な WebVTT の例
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つを再検討し、キューの構造をもう少し詳しく見てみましょう。

WEBVTT

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

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

NOTE これはファイルの最後の行です

各キューは、

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

タイミング行とキューペイロードの間など、キュー内で「余分な」空白行を使用しないことが重要です。WebVTT は行ベースで、空白行がキューを閉じます。（訳注：空白行は、キュー以外のブロックも閉じます。--> があるべき場所にあるのが、キューブロックということです。ファイル内のそれ以外の場所での --> の存在は許されていません。）

WebVTT のコメント

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

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

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

例 4 - 一般的な WebVTT の例
NOTE これはコメントです
例 5 - 複数行のコメント
NOTE
複数行に
またがる別のコメント。

NOTE このように複数行にまたがって
コメントすることもできます。
例 6 - 一般的なコメントの使い方
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 の中

video::cue {
  background-image: linear-gradient(to bottom, dimgray, lightgray);
  color: papayawhip;
}

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

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

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

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

WebVTT ファイル自体の中

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

WEBVTT

STYLE
::cue {
  background-image: linear-gradient(to bottom, 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 のページで使用しているのと同じ方法でエスケープシーケンスを使用していることに注意する必要があります。

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™

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

以下に示すように、キュー内のタイミングの後に位置情報を含めることで、テキストトラックの位置もサポートします（詳細については、{{anch("Cue settings","キュー設定")}}を参照してください）。

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?

WebTT キュー

キューは、単一の開始時間、終了時間、およびテキストペイロードを持つ単一の字幕ブロックです。例 6 は、ヘッダー、空白行、および空白行で区切られた5つのキューから構成されています。キューは次の5つの要素で構成されています。

例 7 - キューの例
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、...）、それらは一意である必要はありません。

例 8 - 例 7 のキュー識別子
1 - Title Crawl
例 9 - 識別子の一般的な使い方
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")}} の {{htmlattrxref("kind","track")}} は chapters です）、ファイルは重複するタイミングを持つことはできません。

各キューのタイミングには次の5つのコンポーネントがあります。

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

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

例 10 - 基本的なキューのタイミングの例
00:22.230 --> 00:24.606
00:30.739 --> 00:00:34.074
00:00:34.159 --> 00:35.743
00:00:35.827 --> 00:00:40.122
例 11 - 重複したキューのタイミングの例
00:00:00.000 --> 00:00:10.000
00:00:05.000 --> 00:01:00.000
00:00:30.000 --> 00:00:50.000
例 12 - 重複しないキューのタイミングの例
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つのキュー設定があります。

例 13 - キュー設定の例

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

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つあります。それらは以下の表にリストされています。

表 6 - エスケープシーケンス
名前 文字 エスケープシーケンス
アンパサンド & &amp;
小なり < &lt;
大なり > &gt;
左から右へのマーク &lrm;
右から左へのマーク &rlm;
改行なしスペース &nbsp;

キューペイロードのテキストタグ

<bold> のような、使用できるタグがいくつかあります。ただし、WebVTT ファイルを {{htmlattrxref("kind","track")}} 属性が chapters である {{HTMLElement("track")}} 要素で使用している場合は、タグを使用できません。

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

インターフェイス

WebVTT で使用するインターフェイスまたは API は次の2つがあります。

VTTCue インターフェイス

これは、Document Object Model API でインターフェイスを提供するために使用し、そこでサポートしているさまざまな属性を使用して、さまざまな方法でキューを準備および変更できます。

コンストラクタは、キューの開始時間、終了時間、およびテキストを調整できるデフォルトのコンストラクタ VTTCue(startTime, endTime, text) を使用して定義された、キューを開始する最初のポイントです。その後、cue.region を使って、このキューが属する特定のキューの領域を設定できます。CSS を使用して HTML でオブジェクトのフォーム、シェイプ、および表示を変更するのと同じように、vertical、horizontal、line、lineAlign、position、positionAlign、text、size、および align を使用して、キューとそのフォーメーションを変更できます。しかし、VTTCue インターフェイスは WebVTT 内にあり、キューを変更するために直接使用できる幅広い調整変数を提供します。以下のインターフェイスは、DOM API で WebVTT キューを公開するために使用できます。

enum AutoKeyword { "auto" };
enum DirectionSetting { "" /* horizontal */, "rl", "lr" };
enum LineAlignSetting { "start", "center", "end" };
enum PositionAlignSetting { "line-left", "center", "line-right", "auto" };
enum AlignSetting { "start", "center", "end", "left", "right" };
[Constructor(double startTime, double endTime, DOMString text)]
interface VTTCue : TextTrackCue {
  attribute VTTRegion? region;
  attribute DirectionSetting vertical;
  attribute boolean snapToLines;
  attribute (double or AutoKeyword) line;
  attribute LineAlignSetting lineAlign;
  attribute (double or AutoKeyword) position;
  attribute PositionAlignSetting positionAlign;
  attribute double size;
  attribute AlignSetting align;
  attribute DOMString text;
  DocumentFragment getCueAsHTML();
};

VTT Region インターフェイス

これは WebVTT API の2番目のインターフェイスです。

new キーワードは、複数のキューを含めるために使用できる新しい VTTRegion オブジェクトを定義するために使用できます。この VTT 領域の外観を指定するために使用できる width、lines、regionAnchorX、regionAnchorY、viewportAnchorX、viewportAnchorY、および scroll という VTTRegion のいくつかのプロパティがあります。DOM API で WebVTT 領域を公開するために使用できるインターフェイスコードを以下に示します。

enum ScrollSetting { "" /* none */, "up" };
[Constructor]
interface VTTRegion {
  attribute double width;
  attribute long lines;
  attribute double regionAnchorX;
  attribute double regionAnchorY;
  attribute double viewportAnchorX;
  attribute double viewportAnchorY;
  attribute ScrollSetting scroll;
};

メソッドとプロパティ

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

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

簡単な WebVTT ファイルを書くために従うことができるいくつかのステップがあります。開始する前に、メモ帳を使用してからファイルを「.vtt」ファイルとして保存できることに注意する必要があります。手順は以下のとおりです。

  1. メモ帳を開きます。
  2. WebVTT の最初の行は、ファイルがファイルの種類を示し始めるときに他の言語ではヘッダーを配置するように要求されるのと同様に標準化されています。最初の1行は次のように書く必要があります。
WEBVTT
  1. 2行目を空白のままにして、3行目で最初のキューの時間を指定します。例えば、時間が1秒で始まり5秒で終わる最初のキューでは、次のようになります。
00:01.000 --> 00:05.000
  1. 次の行に、このキューのキャプションを書くことができます。キャプションは1秒から5秒までです。
  2. 同様の手順に従って、特定の動画または音声ファイル用の完全な WebVTT ファイルを作成できます。

CSS 疑似クラス

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

WebVTT がサポートしている優れた機能の1つは、特定のタイプのオブジェクトのスタイルを分類するために HTML や CSS で使用しているのと同じ方法で使用できるクラス要素のローカライズと使用です。しかし、ここでは、次のようにキューのスタイルと分類に使用します。

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 疑似クラスを使用することができます。

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

仕様

仕様 状態 コメント
{{SpecName("WebVTT")}} {{Spec2("WebVTT")}} 初期定義

ブラウザーの互換性

VTTCue インターフェイス

{{Compat("api.VTTCue", 0)}}

TextTrack インターフェイス

{{Compat("api.TextTrack", 0)}}

注

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

WebVTT は Firefox 24 ではデフォルトの {{pref("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 以降でデフォルトで有効になっています（{{bug(1338030)}} および {{bug(1415805)}} のバグを参照）。