メディア要素

4.8.10 メディア要素

メディア要素 (本仕様においては、audiovideo のこと)とは、次のインタフェースを実装したものです:

interface HTMLMediaElement : HTMLElement {

  // error state
  readonly attribute MediaError error;

  // network state
           attribute DOMString src;
  readonly attribute DOMString currentSrc;
  const unsigned short NETWORK_EMPTY = 0;
  const unsigned short NETWORK_IDLE = 1;
  const unsigned short NETWORK_LOADING = 2;
  const unsigned short NETWORK_NO_SOURCE = 3;
  readonly attribute unsigned short networkState;
           attribute DOMString preload;
  readonly attribute TimeRanges buffered;
  void load();
  DOMString canPlayType(in DOMString type);

  // ready state
  const unsigned short HAVE_NOTHING = 0;
  const unsigned short HAVE_METADATA = 1;
  const unsigned short HAVE_CURRENT_DATA = 2;
  const unsigned short HAVE_FUTURE_DATA = 3;
  const unsigned short HAVE_ENOUGH_DATA = 4;
  readonly attribute unsigned short readyState;
  readonly attribute boolean seeking;

  // playback state
           attribute double currentTime;
  readonly attribute double initialTime;
  readonly attribute double duration;
  readonly attribute Date startOffsetTime;
  readonly attribute boolean paused;
           attribute double defaultPlaybackRate;
           attribute double playbackRate;
  readonly attribute TimeRanges played;
  readonly attribute TimeRanges seekable;
  readonly attribute boolean ended;
           attribute boolean autoplay;
           attribute boolean loop;
  void play();
  void pause();

  // media controller
           attribute DOMString mediaGroup;
           attribute MediaController controller;

  // controls
           attribute boolean controls;
           attribute double volume;
           attribute boolean muted;
           attribute boolean defaultMuted;

  // tracks
  readonly attribute MultipleTrackList audioTracks;
  readonly attribute ExclusiveTrackList videoTracks;
  readonly attribute TextTrack[] textTracks;
  MutableTextTrack addTextTrack(in DOMString kind, in optional DOMString label, in optional DOMString language);
};

メディア要素属性, src, preload, autoplay, mediagroup, loop, muted, controls は、すべてのメディア要素に適用されます。このセクションではそれらを定義します。

メディア要素は、オーディオ・データ、または、ビデオとオーディオ・データをユーザーに提供するために使います。このセクションでは、それをメディア・データと呼びます。それは、このセクションではオーディオもビデオも同等にメディア要素に適用するからです。メディア・リソースという用語は、メディア・データの完全なセットを指すために使われます。例えば、完全なビデオ・ファイルや、完全なオーディオ・ファイルです。

メディア・リソースは、複数のオーティオとビデオのトラックを持つことができます。メディア要素の目的において、メディア・リソースのビデオ・データとは、要素の videoTracks 属性から得られるトラックがあれば、そのうち、現在選択されているものだけを指します。そして、メディア・リソースのオーディオ・データとは、要素の audioTracks 属性から得られるトラックがあれば、そのうち、現在利用可能なトラックをすべてミックスした結果を指します。

audiovideo 要素はいずれも、オーディオとビデオのいずれにも使うことができます。この 2 つの主な違いは、ただ単に、audio 要素には目で見るコンテンツ(ビデオや字幕)のための再生領域が無いけれども、video 要素にはそれが存在する、という点だけです。

規定されていないことを除いて、このセクションとサブ・セクションでキューイングされるすべてのタスクに対するタスク・ソースは、メディア要素イベント・タスク・ソースとなります。

4.8.10.1 エラー・コード
media . error

該当の要素の現在のエラー状態を表す MediaError オブジェクトを返します。

エラーが無ければ null を返します。

すべてのメディア要素はエラー状態が関連づけられています。それは、該当の要素で直近のリソース選択アルゴリズムの呼び出しから後に発生した最後のエラーを記録したものです。error 属性は、取得時においては、この最後のエラーによって生成された MediaError オブジェクトを返されなければいけません。エラーが発生していなければ null を返さなければいけません。

interface MediaError {
  const unsigned short MEDIA_ERR_ABORTED = 1;
  const unsigned short MEDIA_ERR_NETWORK = 2;
  const unsigned short MEDIA_ERR_DECODE = 3;
  const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
  readonly attribute unsigned short code;
};
media . error . code

現在のエラーのエラー・コードを返します。詳細は下表の通りです。

MediaError オブジェクトの code 属性は、該当のエラーに相当するコードを返さなければいけません。それは、次のいずれかでなければいけません:

MEDIA_ERR_ABORTED (数値 1)
メディア・リソースのフェッチ・プロセスが、ユーザーのリクエストでユーザーエージェントによって中止された。
MEDIA_ERR_NETWORK (数値 2)
リソースが利用可能だと確定した後で、ネットワーク・エラーによって、ユーザーエージェントがメディア・リソースのフェッチを止めることになった。
MEDIA_ERR_DECODE (数値 3)
リソースが利用可能だと確定した後で、そのメディア・リソースのデコード中にエラーが発生した。
MEDIA_ERR_SRC_NOT_SUPPORTED (数値 4)
src 属性に指定されたメディア・リソースが不適切だった。
4.8.10.2 メディア・リソースのロケーション

メディア要素src コンテンツ属性には、表示させたいメディア・リソース(ビデオやオーディオ)のアドレスを指定します。この属性を指定するなら、潜在的にスペースで囲まれた空でない妥当な URL を入れなければいけません。

メディア要素src 属性がセットされたり変更されたら、ユーザーエージェントは、そのメディア要素メディア要素ロード・アルゴリズムを呼び出さなければいけません。(src 属性が削除された場合は、source 要素が存在したとしても、これは行われません。)

メディア要素src IDL 属性は、同じ名前のコンテンツ属性を反映しなければいけません。

media . currentSrc

現在のメディア・リソースのアドレスを返します。

メディア・リソースがなければ空文字列を返します。

currentSrc IDL 属性は空文字列で初期化されます。その値は、後で定義する通り、リソース選択アルゴリズムによって変更されます。

メディア・リソースを特定する方法は 2 つあります。src 属性、または、source 要素です。この属性は要素より優先されます。

4.8.10.3 MIME タイプ

メディア・リソースは、その type をもって特徴付けられます。具体的には MIME タイプです。codecs パラメータを伴う場合もあります。(codecs パラメータを使えるかどうかは、MIME タイプに依存します。)[RFC4281]

通常、タイプで完全に特徴を表すことはできません。例えば、"video/mpeg" は、コンテナのタイプが何であるかという点を除いて何も言っていないのです。"video/mp4; codecs="avc1.42E01E, mp4a.40.2"" のようなタイプですら、実際のビットレートのような情報を含んでいません(最大ビットレートだけです)。そのため、タイプを指定したとしても、ユーザーエージェントは、おおむね、そのタイプのメディアを再生できるかかもしれない(確信の度合いは状況次第で変わります)、または、そのタイプのメディアは絶対に再生できない、ということしか分からないのです。

ユーザーエージェントがレンダリングできないと認識するタイプとは、ユーザーエージェントが絶対にサポートしていないリソースを表したものを指します。例えば、コンテナ・タイプが認識できない、指定されたコーデックをサポートしていない、といった理由からです。

パラメータ無しの MIME タイプ "application/octet-stream" は、ユーザーエージェントがレンダリングできないと認識するタイプには決してなりません。ユーザーエージェントは、潜在的なメディア・リソースを分類するために Content-Type メタデータを使おうとしたにも関わらず、明示的にそれが指定されなかったのと同じように、そのタイプを扱わなければいけません。

"application/octet-stream" は、ここでは例外的です。もしパラメータが付いていれば、他の MIME タイプと同じように扱うべきです。これは、未知の MIME タイプ・パラメータは無視するべきという規則からもたらされた例外です。

media . canPlayType(type)

空文字列(否定的な回答)、"maybe"、"probably" を返します。指定されたタイプのメディア・リソースを再生できるかどうかを、ブラウザーがどれほど確信できるかどうかに基づきます。

canPlayType(type) メソッドは、typeユーザーエージェントがレンダリングできないと認識するタイプ、または、"application/octet-stream" なら、空文字列を返さなければいけません。該当の audiovideo 要素で使われる場合に、そのタイプはレンダリング可能なメディア・リソースを表すタイプだとユーザーエージェントが確信できるなら、"probably" を返さなければいけません。そうでなければ、"maybe" を返さなければいけません。実装者は、そのタイプをサポートしていると確信を持てない限り、"maybe" を返すことが推奨されます。通常は、ユーザーエージェントは、codecs パラメータを許すタイプであるにもかかわらずパラメータが存在しないのであれば、決して "probably" を返すべきではありません。

このスクリプトは、ユーザーエージェントが(架空の)新フォーマットをサポートしているかどうかをテストして、video 要素かプラグインのどちらを使うべきかを動的に決定します:

<section id="video">
 <p><a href="playing-cats.nfv">Download video</a></p>
</section>
<script>
 var videoSection = document.getElementById('video');
 var videoElement = document.createElement('video');
 var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
 if (support != "probably" && "New Fictional Video Plug-in" in navigator.plugins) {
   // not confident of browser support
   // but we have a plugin
   // so use plugin instead
   videoElement = document.createElement("embed");
 } else if (support == "") {
   // no support from browser and no plugin
   // do nothing
   videoElement = null;
 }
 if (videoElement) {
   while (videoSection.hasChildNodes())
     videoSection.removeChild(videoSection.firstChild);
   videoElement.setAttribute("src", "playing-cats.nfv");
   videoSection.appendChild(videoElement);
 }
</script>

source 要素の type 属性によって、ユーザーエージェントは、レンダリングできないフォーマットを使ったリソースはダウンロードしないようにすることが可能となります。

4.8.10.4 ネットワーク状態
media . networkState

該当の要素のネットワーク・アクティビティの現在の状を返します。後述のリストのコードを返します。

メディア要素がネットワークを使うとき、その現在のネットワーク・アクティビティは networkState 属性によって表されます。取得時においては、該当の要素の現在のネットワーク状態を返さなければいけません。それは、次の値のいずれかでなければいけません:

NETWORK_EMPTY (数値 0)
この要素はまだ初期化されていません。すべての属性は初期状態のままです。
NETWORK_IDLE (数値 1)
この要素のリソース選択アルゴリズムはアクティブで、かつ、リソースが選択された状態です。しかし、実際には、この時点でネットワークを使っていません。
NETWORK_LOADING (数値 2)
ユーザーエージェントは今なおデータをダウンロードしようとしています。
NETWORK_NO_SOURCE (数値 3)
この要素のリソース選択アルゴリズムはアクティブです。しかし、まだ採用するリソースは見つかっていません。

リソース選択アルゴリズムでは、後に定義しますが、いつ networkState 属性の値が変わるのか、そして、その状態が変わったときにどんなイベントが発出されるのかを正確に説明しています。

4.8.10.5 メディア・リソースのロード
media . load()

該当の要素をリセットします。そして、最初から新たなメディア・リソースを選択し、それをロードし始めます。

すべてのメディア要素自動再生フラグを持ちます。これは true 状態で開始しなければいけません。そして、load イベント遅延フラグも持ちます。これは false 状態で開始しなければいけません。load イベント遅延フラグが true となっている間は、この要素はドキュメントの load イベントを遅延させなければいけません。

メディア要素load() メソッドが呼び出されたら、ユーザーエージェントはメディア要素ロード・アルゴリズムを実行しなければいけません。

メディア要素ロード・アルゴリズムは次の手順から構成されます。

  1. この要素の実行中のリソース選択アルゴリズムのインスタンスをすべて中止します。

  2. タスク・キューのひとつにメディア要素メディア要素イベント・タスク・ソースがあれば、それらのタスクを削除します。

    基本的に、メディア要素のペンディングされたイベントとコールバックは、そのメディア要素が新たなリソースをローディングし始めるときに、破棄されます。

  3. メディア要素networkStateNETWORK_LOADING または NETWORK_IDLE にセットされるなら、そのメディア要素abort という名前のシンプルなイベントを発出するタスクをキューイングします。

  4. メディア要素networkStateNETWORK_EMPTY にセットされないのであれば、次の副手順を実行します:

    1. そのメディア要素emptied という名前のシンプルなイベントを発出するタスクをキューイングします。

    2. そのメディア要素でフェッチ・プロセスが進行中なら、ユーザーエージェントはそれを停止するべきです。

    3. networkState 属性を NETWORK_EMPTY にセットします。

    4. そのメディア要素のメディア要素固有のテキスト・トラックを忘れます

    5. readyStateHAVE_NOTHING にセットされないのであれば、その状態にセットします。

    6. paused 属性が false なら、true にセットします。

    7. seeking が true なら、false にセットします。

    8. 現在再生位置を 0 にセットします。

      これによって現在再生位置が変わるなら、そのメディア要素timeupdate という名前のシンプルなイベントを発出するタスクをキューイングします。

    9. 初期再生位置を 0 にセットします。

    10. タイムライン・オフセットを Not-a-Number (NaN) にセットします。

    11. duration 属性を Not-a-Number (NaN) にアップデートします。

      ユーザーエージェントは、この特別な尺の変更に対しては、durationchange イベントを発出しないでしょう

  5. playbackRate 属性を defaultPlaybackRate 属性の値にセットします。

  6. error 属性を null に、自動再生フラグを true にセットします。

  7. そのメディア要素リソース選択アルゴリズムを呼び出します。

  8. この要素ですでに再生しているメディア・リソースの再生は停止します。

メディア要素リソース選択アルゴリズムは次の通りです。このアルゴリズムは必ず同期的に呼び出されます。しかし、このアルゴリズムの最初の手順のひとつは返ってくこととしており、残りの手順を非同期に実行し続けることになります。つまり、これはスクリプトとともにバックグラウンドで実行され、平行して、他のタスクも実行されます。さらに、このアルゴリズムは、イベント・ループ・メカニズムと密接に作用し合います。とりわけ、これは同期セクションを持ちます(イベント・ループ・アルゴリズムの一環で呼び出されます)。このようなセクションにおける手順には ⌛ をマークしてあります。

  1. Set the networkState to NETWORK_NO_SOURCE.

  2. Asynchronously await a stable state, allowing the task that invoked this algorithm to continue. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)

  3. ⌛ If the media element has a src attribute, then let mode be attribute.

    ⌛ Otherwise, if the media element does not have a src attribute but has a source element child, then let mode be children and let candidate be the first such source element child in tree order.

    ⌛ Otherwise the media element has neither a src attribute nor a source element child: set the networkState to NETWORK_EMPTY, and abort these steps; the synchronous section ends.

  4. ⌛ Set the media element's delaying-the-load-event flag to true (this delays the load event), and set its networkState to NETWORK_LOADING.

  5. Queue a task to fire a simple event named loadstart at the media element.

  6. If mode is attribute, then run these substeps:

    1. Process candidate: If the src attribute's value is the empty string, then end the synchronous section, and jump down to the failed step below.

    2. ⌛ Let absolute URL be the absolute URL that would have resulted from resolving the URL specified by the src attribute's value relative to the media element when the src attribute was last changed.

    3. ⌛ If absolute URL was obtained successfully, set the currentSrc attribute to absolute URL.

    4. End the synchronous section, continuing the remaining steps asynchronously.

    5. If absolute URL was obtained successfully, run the resource fetch algorithm with absolute URL. If that algorithm returns without aborting this one, then the load failed.

    6. Failed: Reaching this step indicates that the media resource failed to load or that the given URL could not be resolved. In one atomic operation, run the following steps:

      1. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_SRC_NOT_SUPPORTED.

      2. Forget the media element's media-resource-specific text tracks.

      3. Set the element's networkState attribute to the NETWORK_NO_SOURCE value.

    7. Queue a task to fire a simple event named error at the media element.

    8. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

    9. Abort these steps. Until the load() method is invoked or the src attribute is changed, the element won't attempt to load another resource.

    Otherwise, the source elements will be used; run these substeps:

    1. ⌛ Let pointer be a position defined by two adjacent nodes in the media element's child list, treating the start of the list (before the first child in the list, if any) and end of the list (after the last child in the list, if any) as nodes in their own right. One node is the node before pointer, and the other node is the node after pointer. Initially, let pointer be the position between the candidate node and the next node, if there are any, or the end of the list, if it is the last node.

      As nodes are inserted and removed into the media element, pointer must be updated as follows:

      If a new node is inserted between the two nodes that define pointer
      Let pointer be the point between the node before pointer and the new node. In other words, insertions at pointer go after pointer.
      If the node before pointer is removed
      Let pointer be the point between the node after pointer and the node before the node after pointer. In other words, pointer doesn't move relative to the remaining nodes.
      If the node after pointer is removed
      Let pointer be the point between the node before pointer and the node after the node before pointer. Just as with the previous case, pointer doesn't move relative to the remaining nodes.

      Other changes don't affect pointer.

    2. Process candidate: If candidate does not have a src attribute, or if its src attribute's value is the empty string, then end the synchronous section, and jump down to the failed step below.

    3. ⌛ Let absolute URL be the absolute URL that would have resulted from resolving the URL specified by candidate's src attribute's value relative to the candidate when the src attribute was last changed.

    4. ⌛ If absolute URL was not obtained successfully, then end the synchronous section, and jump down to the failed step below.

    5. ⌛ If candidate has a type attribute whose value, when parsed as a MIME type (including any codecs described by the codecs parameter, for types that define that parameter), represents a type that the user agent knows it cannot render, then end the synchronous section, and jump down to the failed step below.

    6. ⌛ If candidate has a media attribute whose value does not match the environment, then end the synchronous section, and jump down to the failed step below.

    7. ⌛ Set the currentSrc attribute to absolute URL.

    8. End the synchronous section, continuing the remaining steps asynchronously.

    9. Run the resource fetch algorithm with absolute URL. If that algorithm returns without aborting this one, then the load failed.

    10. Failed: Queue a task to fire a simple event named error at the candidate element, in the context of the fetching process that was used to try to obtain candidate's corresponding media resource in the resource fetch algorithm.

    11. Asynchronously await a stable state. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)

    12. Forget the media element's media-resource-specific text tracks.

    13. Find next candidate: Let candidate be null.

    14. Search loop: If the node after pointer is the end of the list, then jump to the waiting step below.

    15. ⌛ If the node after pointer is a source element, let candidate be that element.

    16. ⌛ Advance pointer so that the node before pointer is now the node that was after pointer, and the node after pointer is the node after the node that used to be after pointer, if any.

    17. ⌛ If candidate is null, jump back to the search loop step. Otherwise, jump back to the process candidate step.

    18. Waiting: Set the element's networkState attribute to the NETWORK_NO_SOURCE value.

    19. ⌛ Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

    20. End the synchronous section, continuing the remaining steps asynchronously.

    21. Wait until the node after pointer is a node other than the end of the list. (This step might wait forever.)

    22. Asynchronously await a stable state. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)

    23. ⌛ Set the element's delaying-the-load-event flag back to true (this delays the load event again, in case it hasn't been fired yet).

    24. ⌛ Set the networkState back to NETWORK_LOADING.

    25. ⌛ Jump back to the find next candidate step above.

メディア要素リソース・フェッチ・アルゴリズムと、引き渡される絶対 URL は次の通りです:

  1. Let the current media resource be the resource given by the absolute URL passed to this algorithm. This is now the element's media resource.

  2. Begin to fetch the current media resource, from the media element's Document's origin, with the force same-origin flag set.

    Every 350ms (±200ms) or for every byte received, whichever is least frequent, queue a task to fire a simple event named progress at the element.

    The stall timeout is a user-agent defined length of time, which should be about three seconds. When a media element that is actively attempting to obtain media data has failed to receive any data for a duration equal to the stall timeout, the user agent must queue a task to fire a simple event named stalled at the element.

    User agents may allow users to selectively block or slow media data downloads. When a media element's download has been blocked altogether, the user agent must act as if it was stalled (as opposed to acting as if the connection was closed). The rate of the download may also be throttled automatically by the user agent, e.g. to balance the download with other connections sharing the same bandwidth.

    User agents may decide to not download more content at any time, e.g. after buffering five minutes of a one hour media resource, while waiting for the user to decide whether to play the resource or not, or while waiting for user input in an interactive resource. When a media element's download has been suspended, the user agent must set the networkState to NETWORK_IDLE and queue a task to fire a simple event named suspend at the element. If and when downloading of the resource resumes, the user agent must set the networkState to NETWORK_LOADING.

    The preload attribute provides a hint regarding how much buffering the author thinks is advisable, even in the absence of the autoplay attribute.

    When a user agent decides to completely stall a download, e.g. if it is waiting until the user starts playback before downloading any further content, the element's delaying-the-load-event flag must be set to false. This stops delaying the load event.

    The user agent may use whatever means necessary to fetch the resource (within the constraints put forward by this and other specifications); for example, reconnecting to the server in the face of network errors, using HTTP range retrieval requests, or switching to a streaming protocol. The user agent must consider a resource erroneous only if it has given up trying to fetch it.

    The networking task source tasks to process the data as it is being fetched must, when appropriate, include the relevant substeps from the following list:

    If the media data cannot be fetched at all, due to network errors, causing the user agent to give up trying to fetch the resource
    If the media resource is found to have Content-Type metadata that, when parsed as a MIME type (including any codecs described by the codecs parameter, if the parameter is defined for that type), represents a type that the user agent knows it cannot render (even if the actual media data is in a supported format)
    If the media data can be fetched but is found by inspection to be in an unsupported format, or can otherwise not be rendered at all

    DNS errors, HTTP 4xx and 5xx errors (and equivalents in other protocols), and other fatal network errors that occur before the user agent has established whether the current media resource is usable, as well as the file using an unsupported container format, or using unsupported codecs for all the data, must cause the user agent to execute the following steps:

    1. The user agent should cancel the fetching process.

    2. Abort this subalgorithm, returning to the resource selection algorithm.

    Once enough of the media data has been fetched to determine the duration of the media resource, its dimensions, and other metadata, and once the text tracks are ready

    This indicates that the resource is usable. The user agent must follow these substeps:

    1. Establish the media timeline for the purposes of the current playback position, the earliest possible position, and the initial playback position, based on the media data.

    2. Update the timeline offset to the date and time that corresponds to the zero time in the media timeline established in the previous step, if any. If no explicit time and date is given by the media resource, the timeline offset must be set to Not-a-Number (NaN).

    3. Set the current playback position to the earliest possible position.

    4. Update the duration attribute with the time of the last frame of the resource, if known, on the media timeline established above. If it is not known (e.g. a stream that is in principle infinite), update the duration attribute to the value positive Infinity.

      The user agent will queue a task to fire a simple event named durationchange at the element at this point.

    5. For video elements, set the videoWidth and videoHeight attributes.

    6. Set the readyState attribute to HAVE_METADATA.

      A loadedmetadata DOM event will be fired as part of setting the readyState attribute to a new value.

    7. Let jumped be false.

    8. If either the media resource or the address of the current media resource indicate a particular start time, then set the initial playback position to that time, seek to that time, and let jumped be true. Ignore any resulting exceptions (if the position is out of range, it is effectively ignored).

      For example, with media formats that support the Media Fragments URI fragment identifier syntax, the fragment identifier can be used to indicate a start position. [MEDIAFRAG]

    9. If either the media resource or the address of the current media resource indicate a particular set of audio or video tracks to enable, then the selected audio tracks must be enabled in the element's audioTracks object, and the first selected video track must be selected in the element's videoTracks object.

    10. If the media element has a current media controller, then: if jumped is true and the initial playback position, relative to the current media controller's timeline, is greater than the current media controller's media controller position, then seek the media controller to the media element's initial playback position, relative to the current media controller's timeline; otherwise, seek the media element to the media controller position, relative to the media element's timeline, discarding any resulting exceptions.

    11. Once the readyState attribute reaches HAVE_CURRENT_DATA, after the loadeddata event has been fired, set the element's delaying-the-load-event flag to false. This stops delaying the load event.

      A user agent that is attempting to reduce network usage while still fetching the metadata for each media resource would also stop buffering at this point, causing the networkState attribute to switch to the NETWORK_IDLE value.

    The user agent is required to determine the duration of the media resource and go through this step before playing.

    Once the entire media resource has been fetched (but potentially before any of it has been decoded)

    Queue a task to fire a simple event named progress at the media element.

    If the connection is interrupted, causing the user agent to give up trying to fetch the resource

    Fatal network errors that occur after the user agent has established whether the current media resource is usable must cause the user agent to execute the following steps:

    1. The user agent should cancel the fetching process.

    2. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_NETWORK.

    3. Queue a task to fire a simple event named error at the media element.

    4. If the media element's readyState attribute has a value equal to HAVE_NOTHING, set the element's networkState attribute to the NETWORK_EMPTY value and queue a task to fire a simple event named emptied at the element. Otherwise, set the element's networkState attribute to the NETWORK_IDLE value.

    5. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

    6. Abort the overall resource selection algorithm.

    If the media data is corrupted

    Fatal errors in decoding the media data that occur after the user agent has established whether the current media resource is usable must cause the user agent to execute the following steps:

    1. The user agent should cancel the fetching process.

    2. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_DECODE.

    3. Queue a task to fire a simple event named error at the media element.

    4. If the media element's readyState attribute has a value equal to HAVE_NOTHING, set the element's networkState attribute to the NETWORK_EMPTY value and queue a task to fire a simple event named emptied at the element. Otherwise, set the element's networkState attribute to the NETWORK_IDLE value.

    5. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

    6. Abort the overall resource selection algorithm.

    If the media data fetching process is aborted by the user

    The fetching process is aborted by the user, e.g. because the user navigated the browsing context to another page, the user agent must execute the following steps. These steps are not followed if the load() method itself is invoked while these steps are running, as the steps above handle that particular kind of abort.

    1. The user agent should cancel the fetching process.

    2. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_ABORTED.

    3. Queue a task to fire a simple event named abort at the media element.

    4. If the media element's readyState attribute has a value equal to HAVE_NOTHING, set the element's networkState attribute to the NETWORK_EMPTY value and queue a task to fire a simple event named emptied at the element. Otherwise, set the element's networkState attribute to the NETWORK_IDLE value.

    5. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

    6. Abort the overall resource selection algorithm.

    If the media data can be fetched but has non-fatal errors or uses, in part, codecs that are unsupported, preventing the user agent from rendering the content completely correctly but not preventing playback altogether

    The server returning data that is partially usable but cannot be optimally rendered must cause the user agent to render just the bits it can handle, and ignore the rest.

    If the media resource is found to declare a media-resource-specific text track that the user agent supports

    If the media resource's origin is the same origin as the media element's Document's origin, queue a task to run the steps to expose a media-resource-specific text track with the relevant data.

    Cross-origin files do not expose their subtitles in the DOM, for security reasons. However, user agents may still provide the user with access to such data in their user interface.

    When the networking task source has queued the last task as part of fetching the media resource (i.e. once the download has completed), if the fetching process completes without errors, including decoding the media data, and if all of the data is available to the user agent without network access, then, the user agent must move on to the next step. This might never happen, e.g. when streaming an infinite resource such as Web radio, or if the resource is longer than the user agent's ability to cache data.

    While the user agent might still need network access to obtain parts of the media resource, the user agent must remain on this step.

    For example, if the user agent has discarded the first half of a video, the user agent will remain at this step even once the playback has ended, because there is always the chance the user will seek back to the start. In fact, in this situation, once playback has ended, the user agent will end up dispatching a stalled event, as described earlier.

  3. If the user agent ever reaches this step (which can only happen if the entire resource gets loaded and kept available): abort the overall resource selection algorithm.


preload 属性は列挙属性です。次表は、この属性のキーワードと状態を一覧にしたものです。左の列にあるキーワードは、そのキーワードと同じ行の二つ目の列の状態と対応付けられています。

キーワード 状態 概要
none None ウェブ制作者は該当のメディア・リソースをユーザーが必要とすると期待していない、または、サーバーは不必要なトラフィックを最小化したい、ということをユーザーエージェントに伝えるヒントとなります。
metadata Metadata ウェブ制作者は該当のメディア・リソースをユーザーが必要とすると期待していないけれども、そのリソースのメタデータ(寸法、最初のフレーム、トラックのリスト、尺など)はあった方が良い、ということをユーザーエージェントに伝えるヒントとなります。
auto Automatic ユーザーエージェントはユーザーのニーズを優先して、サーバーのリスクを考慮せずとも、楽観的にリソース全体をダウンロードしても良い、ということをユーザーエージェントに伝えるヒントとなります。

空文字列も妥当なキーワードです。これは Automatic 状態に対応付けられます。サーバー・ロードの低減と最適なユーザー体験との妥協点が Metadata 状態だったとしても、この属性が指定されなかった時のデフォルトはユーザーエージェント側の定義となります。

preload 属性は、最適なユーザー体験を実現するためにウェブ制作者はどう考えているのかについて、ユーザーエージェントにヒントを与えることを意図しています。この属性を完全に無視することもできます。例えば、ユーザー設定があれば、それを基準にしたり、ネットワーク接続状況を基準にすることができます。

preload IDL 属性は同じ名前のコンテンツ属性を反映しなければいけません。ただし、既知の値に限定されます

autoplay 属性は preload 属性より優先されるでしょう(preload 属性によって指定されたヒントにかかわらず、メディアが再生してしまうと、必然的に、まず最初にバッファしなければなりません)。しかし、両方を入れてもエラーではありません。


media . buffered

ユーザーエージェントがバッファしたメディア・リソースの範囲を表す TimeRanges オブジェクトを返します。

buffered 属性は、新たな静的な 正規化 TimeRanges オブジェクト を返さなければいけません。これは、この属性が評価された時点で、ユーザーエージェントがすでにバッファしたメディア・リソースの範囲があれば、それを表します。ユーザーエージェントは、利用可能な範囲を正確に判定しなければいけません。たとえ、それが、メディア・ストリームのように、面倒な調査によってでしか判定できない場合だったとしてもです。

通常は、これは、ゼロ地点で固定された範囲ひとつだけになります。しかし、例えば、ユーザーエージェントが HTTP レンジ・リクエストを使ってシークする場合は、その範囲は複数になりえます。

ユーザーエージェントは、すでにバッファしたデータを破棄することができます。

ゆえに、ある時点で buffered 属性によって返されたオブジェクトの範囲内にある時間位置は、後の時間に同属性によって返されるオブジェクトの範囲(複数かもしれません)に含まれないということがあり得ます。

4.8.10.6 メディア・リソースのオフセット
media . duration

メディア・リソースの長さを返します。単位は秒です。メディア・リソースの開始は 0 と仮定します。

尺が取得できなければ NaN を返します。

無限のストリームでは Infinity を返します。

media . currentTime [ = value ]

現在再生位置を返します。単位は秒です。

値をセットして、指定の時間にシークすることができます。

メディア・リソースが選択されていない、または、現在のメディア・コントローラが無ければ、INVALID_STATE_ERR 例外を投げます。指定の時間が、ユーザーエージェントのシーク可能範囲内でなければ、INDEX_SIZE_ERR 例外を投げます。

media . initialTime

初期再生位置を返します。これは、メディア・リソースがロードされたときに自動的にシークされた時間位置のことです。初期再生位置がまだ不明なら 0 を返します。

メディア・リソースには、メディア・タイムラインがあります。これは、メディア・リソースにおける位置に時間(単位は秒)を対応付けたものです。タイムラインの起点は、その最前の定義位置です。タイムラインの尺は、その最後の定義位置になります。

メディア・タイムラインの確立: メディア・リソースが、何とかして起点が負とならない明確なタイムラインを確定できるなら、メディア・タイムラインは、そのタイムラインとするべきです。(メディア・リソースがタイムラインを確定できるかどうかは、そのメディア・リソースのフォーマットに依存します。)メディア・リソースが明確な開始の時刻と加えて日付まで確定できるなら、その時刻と日付をメディア・タイムラインにおけるゼロ地点と見なすべきです。タイムライン・オフセットは時刻と日付を持ち、startOffsetTime 属性を使ってアクセスすることができます。

メディア・リソースが不連続なタイムラインを持つなら、ユーザーエージェントは、そのタイムラインを拡張して、そのリソースの開始からリソース全体に及ぶようにしなければいけません。そうすることで、そのメディア・リソースメディア・タイムラインは、巻き戻し限界位置(後で定義します)から連続して増えていくことができるようになります。たとえ、下層のメディア・データの時間順がおかしかったり、時間コードがオーバーラップしていたとしてもです。

例えば、2 つのクリップをひとつのビデオ・ファイルに連結したけれども、そのビデオ・フォーマットから、その 2 つのクリップの起点時間を取り出せるなら、そのビデオ・データからタイムラインを取り出すことができるでしょう。それは、00:15..00:29 と 00:05..00:38 となるでしょう。しかし、ユーザーエージェントは、これらの時間を見せません。その代わり、00:15..00:29 と 00:29..01:02 という時間で、ひとつのビデオとして見せることになるでしょう。

明確なタイムラインが無くても、メディア・タイムラインのゼロ時間は、そのメディア・リソースの最初のフレームに合わせるべきです。静的なオーディオやビデオ・ファイルでは、これは通常は自明なことです。ストリーミング・リソースでは、サーバーから得た最初のフレームより前の位置にユーザーエージェントがシークできるのであれば、そのゼロ時間は、そのメディア・リソースの巻き戻し可能な範囲のうち最も前の時間に合わせるべきです。そうでなければ、サーバーから受信した最初のフレームに合わせるべきです(ユーザーエージェントがストリームを受信し始めた時点におけるメディア・リソースの位置です)。

他にもストリームの例があります。いくつかのフラグメントを連結してサーバーからブロードキャストする場合です。この場合、ユーザーエージェントは特定の時間をリクエストすることができませんが、事前に順番が決まっていれば、そのビデオ・データを配信することができます。ユーザーエージェントがこのストリームに接続して、タイムスタンプが 2010-03-20 23:15:00 UTC から 2010-03-21 00:05:00 UTC までと、2010-02-12 14:25:00 UTC から 2010-02-12 14:35:00 UTC までの範囲と定義されたフラグメントを受信したとすれば、これを、0 秒から始まり 3,600 秒(1時間)まで拡張したメディア・タイムラインとして見せることになるでしょう。ストリーミング・サーバーが 2 つ目のクリップの最後で切断すると仮定すれば、その duration 属性は 3,600 を返すことになります。startOffsetTime 属性は、2010-03-20 23:15:00 UTC に相当する時間を表す Date オブジェクトを返すことになります。しかし、別のユーザーエージェントが 5 分後に接続するとしたら、(恐らく)タイムスタンプが 2010-03-20 23:20:00 UTC から 2010-03-21 00:05:00 UTC までと、2010-02-12 14:25:00 UTC から 2010-02-12 14:35:00 UTC までの範囲となるフラグメントを受信することになります。そして、これを、0 秒から始まり 3,300 秒(55分)まで拡張したメディア・タイムラインとして見せることになります。この場合、startOffsetTime 属性は、2010-03-20 23:20:00 UTC に相当する時間を表す Date オブジェクトを返すことになります。

どんな場合でも、ユーザーエージェントは、確立したメディア・タイムラインを使って、巻き戻し限界位置(後で定義します)が必ず 0 以上となるようにしなければいけません。

メディア・タイムラインはクロックも結び付けられます。どのクロックを使うかは、ユーザーエージェント側の定義となり、メディア・リソース次第となりますが、ユーザーの実時間に近づけるべきです。

現在のメディア・コントローラを共有するすべてのメディア要素は、メディア・タイムラインに同じクロックを使います。

メディア要素には現在再生位置があります。これは、はじめ(つまり、メディア・データがない時点)は 0 秒でなければいけません。現在再生位置は、メディア・タイムライン上のひとつの時間です。

currentTime 属性は、取得時においては、現在再生位置を返さなければいけません。単位は秒です。セット時においては、もしメディア要素現在のメディア・コントローラがあるなら、INVALID_STATE_ERR 例外を投げなければいけません。そうでなければ、ユーザーエージェントは新たな値(例外を発するかもしれませんが)へシークしなければいけません。

メディア要素には初期再生位置,があります。これは、はじめ(つまり、メディア・データがない時点)は 0 秒でなければいけません。初期再生位置は、メディア・リソースがロードされたときに更新されます。初期再生位置は、メディア・タイムライン上のひとつの時間です。

initialTime 属性は、取得時においては、初期再生位置を返さなければいけません。単位は秒です。

メディア・リソースがストリーミング・リソースなら、ユーザーエージェントは、バッファから削除した後では、そのリソースの特定の部分を取得することができなくなります。同様に、0 で始まらないメディア・タイムラインを持つメディア・リソースもあります。巻き戻し限界位置とは、ストリームやリソースのうち、ユーザーエージェントがもう一度取り出すことができる最も前の位置のことです。これも、メディア・タイムライン上のひとつの時間です。

巻き戻し限界位置は API で明確に見せるものではありません。これは、seekable 属性の TimeRanges オブジェクトがあれば、その最初の範囲の開始時間に一致します。そうでなければ、現在再生位置となります。

巻き戻し限界位置が変わる場合:現在再生位置巻き戻し限界位置より前なら、ユーザーエージェントは巻き戻し限界位置にシークしなければいけません。そうでなければ、ユーザーエージェントが過去 15 ~ 250 ミリ秒に該当要素で timeupdate イベントを発出しておらず、かつ、そのイベントのイベント・ハンドラがまだ実行されていないなら、ユーザーエージェントは、その要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

前述の要件と、クリップのメタデータが不明になるときにキックするリソース・フェッチ・アルゴリズムでの要件のため、現在再生位置は決して巻き戻し限界位置より小さくなることはありません。

duration 属性は、メディア・タイムライン上のメディア・リソースの最後の時間を返さなければいけません。単位は秒です。利用可能なメディア・データがなければ、この属性は Not-a-Number (NaN) 値を返さなければいけません。メディア・リソースに範囲がない(ストリーミング・ラジオなど)と分かったら、この属性は正の Infinity 値を返さなければいけません。

ユーザーエージェントは、あらゆるメディア・データを再生する前、そして、readyStateHAVE_METADATA に等しいか大きい値をセットする前に、そのメディア・リソースの尺を決定しなければいけません。たとえ、そうするためにリソースの複数の部分をフェッチする必要があったとしてもです。

メディア・リソースの長さが既知の値(例えば、未知の値から既知の値へ、または、以前に確立した長さから別の値に)に変わるとき、ユーザーエージェントは、そのメディア要素durationchange という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。(尺が新たなメディア・リソースのロードの一環でリセットされるときには、このイベントは発出されません。)

もし、"無限の" ストリームが何らかの理由で終わってしまったら、その尺は、正の Infinity から、そのストリームの最後のフレームまたは出力の時間に変わることになります。そして、durationchange イベントが発出されることになります。同様に、ユーザーエージェントが、当初、メディア・リソースの尺を正確に判定せずに、見積もっただけで、その後に、新たな情報をもとに見積もりを訂正するとしたら、その尺は変更され、durationchange イベントが発出されることになります。

明確な時刻と日付をメディア・タイムラインのゼロ時間に対応付けするビデオ・ファイルもあります。これをタイムライン・オフセットと呼びます。タイムライン・オフセットは、最初に Not-a-Number (NaN) にセットされなければいけません。

startOffsetTime 属性は、現在のタイムライン・オフセットを表す Date オブジェクトを返さなければいけません。


loop 属性は論理属性です。指定すると、そのメディア要素は、終わりに到達したら、そのメディア・リソースの開始位置に戻ることを表します。

loop 属性は、該当の要素が現在のメディア・コントローラを持つ間は何も作用しません。

loop IDL 属性は、同じ名前のコンテンツ属性を反映しなければいけません。

4.8.10.7 準備状態
media . readyState

現在再生位置のレンダリングに関して、該当の要素の現在の状態を表す値を返します。下記のリストのコードのいずれかです。

メディア要素には準備状態があります。これは、現在再生位置でレンダリングする準備ができた度合いがどれくらいかを表します。その取り得る値は次の通りですが、特定の時間におけるメディア要素の準備状態は、その要素の状態を表している値のうちで最も大きい値になります:

HAVE_NOTHING (数値 0)
メディア・リソースに関する情報はまだ何も入手できていません。現在再生位置のデータも何も入手できていません。networkState 属性が NETWORK_EMPTY にセットされたメディア要素は、常に、HAVE_NOTHING 状態にあります。
HAVE_METADATA (数値 1)
十分なリソースが取得でき、そのリソースの尺が分かっています。video 要素の場合、そのビデオの寸法も分かっています。もう、シーク時に API から例外が発出されることはありません。現在再生位置の直近のメディア・データはまだ入手できていません。テキスト・トラック準備できています。
HAVE_CURRENT_DATA (数値 2)
現在再生位置の直近のデータが取得できています。しかし、ユーザーエージェントは、再生方向現在再生位置を進めようとすると、すぐに HAVE_METADATA 状態に戻ってしまう状態、または、再生方向に取得すべきデータがない状態のいずれかです。例えば、ビデオでは、これは、ユーザーエージェントが現在のフレームのデータを持っているけれども、次のフレームは持っていない状態に、そして、再生が終わったときに一致します。
HAVE_FUTURE_DATA (数値 3)
現在再生位置の直近のデータが取得できています。さらに、ユーザーエージェントは、すぐに HAVE_METADATA 状態に戻ること無しに、少なくとも少しは再生方向現在再生位置を進めることができる状態です。例えば、ビデオでは、これは、ユーザーエージェントが少なくとも現在のフレームと次のフレームのデータを持ち合わせている状態です。ユーザーエージェントは、再生が終わったら、この状態にいとどまることはできません。なぜなら、この場合は、現在再生位置を決して進めることができないからです。
HAVE_ENOUGH_DATA (数値 4)
HAVE_FUTURE_DATA 状態のすべての条件を満たしています。かつ、さらに、ユーザーエージェントは、実効再生レートで進めるとしても、再生がメディア・リソースの最後に到達する前に、現在再生位置が利用可能なデータを追い越してしまうことはないほどの割合でデータをフェッチしていると、見積もっています。

networkStateNETWORK_EMPTY でないメディア要素の準備状態が変化したとき、ユーザーエージェントは下記の手順に従わなければいけません:

  1. 次のリストから最初に適用可能な副手順を適用します:

    準備状態が HAVE_NOTHING から HAVE_METADATA になる場合

    この要素で loadedmetadata という名前のシンプルなイベントを発出するタスクをキューイングします。

    このタスクの実行前に、イベント・ループ・メカニズムの一環として、適切であれば、その video 要素をリサイズするためにレンダリングし直すでしょう。

    準備状態が HAVE_METADATA から HAVE_CURRENT_DATA 以上になる場合

    このメディア要素load() アルゴリズムが最後に呼び出されてからこれが起こるのが初めてなら、ユーザーエージェントはこの要素で loadeddata という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

    準備状態が HAVE_FUTURE_DATA または HAVE_ENOUGH_DATA になるなら、下記の関連の手順も実行しなければいけません。

    準備状態が HAVE_FUTURE_DATA 以上から HAVE_CURRENT_DATA 以下になる場合

    メディア要素readyState 属性が HAVE_FUTURE_DATA より小さい値に変わる前は潜在的に再生中だった、かつ、その要素は再生を終了していなかった、かつ、再生はエラーによって停止していなかった、かつ、再生はユーザー操作によって停止していなかったなら、ユーザーエージェントはその要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。そして、その要素で waiting という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

    準備状態が HAVE_CURRENT_DATA 以下から HAVE_FUTURE_DATA になる場合

    ユーザーエージェントは canplay という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

    この要素の paused 属性が false なら、ユーザーエージェントは playing という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

    準備状態が HAVE_ENOUGH_DATA になる場合

    準備状態が HAVE_CURRENT_DATA 以下だったなら、ユーザーエージェントは canplay という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。そして、その要素の paused 属性が false なら、playing という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

    自動再生フラグが true で、paused 属性が true で、そのメディア要素autoplay 属性が指定されており、そのメディア要素Documentブラウジング・コンテキストが、その Document が生成されたときに、サンドボックス化オートマチック・フィーチャー・ブラウジング・コンテキスト・フラグ がセットされていなかったのであれば、ユーザーエージェントは、paused 属性を false にセットし、play という名前のシンプルなイベントを発出するタスクをキューイングし、playing という名前のシンプルなイベントを発出するタスクをキューイングすることができます。

    ユーザーエージェントは autoplay をサポートする必要はありません。そして、ユーザーエージェントはユーザー設定を優先することが推奨されています。ウェブ制作者は、ビデオを強制的に再生させるのに、スクリプトを使うのではなく、autoplay 属性を使うことが推奨されます。そうすることで、ユーザーは希望通りに挙動を変えることができるようになります。

    いずれにせよ、ユーザーエージェントは、最終的には、canplaythrough という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

  2. メディア要素現在のメディア・コントローラがあるなら、そのメディア要素現在のメディア・コントローラコントローラ状態を報告します。

メディア要素の準備状態はこれらの状態の間を不連続に飛ぶことがあり得ます。例えば、メディア要素の状態が、HAVE_METADATA から、HAVE_CURRENT_DATAHAVE_FUTURE_DATA 状態を経ずに、HAVE_ENOUGH_DATA に直接に飛ぶことがあります。

readyState IDL 属性は、取得時においては、前述のメディア要素の現在の準備状態の説明された通りの値を返さなければいけません。

autoplay 属性は論理属性です。存在すれば、ユーザーエージェントは(ここで説明されたアルゴリズムに書かれた通り)、停止せずにそうすることができる範囲で、できる限り早くメディア・リソースの再生を自動的に開始します。

ウェブ制作者は、スクリプトを使って自動再生を行うのではなく、autoplay 属性を使うことが推奨されます。こうすることで、ユーザーは自動再生を望まなければそうすることができるからです。例えば、スクリーン・リーダーを使っているときなどです。ウェブ制作者は、また、自動再生という挙動をまったく使わないということも検討することが推奨されます。代わりに、ユーザーエージェントにユーザーが明示的に再生を開始するまで待たせるのです。

autoplay IDL 属性は、同じ名前のコンテンツ属性を反映しなければいけません。

4.8.10.8 メディア・リソースの再生
media . paused

再生が停止しているなら true を、そうでなければ false を返します。

media . ended

再生がメディア・リソースの最後に到達したら true を返します。

media . defaultPlaybackRate [ = value ]

ユーザーがメディア・リソースを早送りや巻き戻しする際のデフォルトの再生レートを返します。

値をセットして、デフォルトの再生レートを変更することができます。

デフォルトのレートは再生に直接に影響を及ぼしません。しかし、ユーザーが早送りモードに切り替え、通常再生モードに戻ったとき、その再生レートはデフォルトの再生レートに戻ることが期待されます。

要素が現在のメディア・コントローラを持つとき、その defaultPlaybackRate 属性は無視され、現在のメディア・コントローラdefaultPlaybackRate が代わりに使われます。

media . playbackRate [ = value ]

現在の再生レートを返します。通常の速度は 1.0 です。

値をセットして、再生レートを変更することができます。

要素が現在のメディア・コントローラを持つとき、その playbackRate 属性は無視され、現在のメディア・コントローラplaybackRate が代わりに使われます。

media . played

ユーザーエージェントが再生したメディア・リソースの範囲を表す TimeRanges オブジェクトを返します。

media . play()

paused 属性を false にセットし、必要に応じて、メディア・リソースをロードし、再生を開始します。再生が終わっていたら、最初から再開します。

media . pause()

paused 属性を true にセットし、必要に応じて、メディア・リソースをロードします。

paused 属性は、メディア要素が停止されているかどうかを表します。この属性は、最初は true でなければいけません。

readyState 属性が HAVE_NOTHING 状態か HAVE_METADATA 状態にある、または、その要素がユーザー操作待受停止されたなら、そのメディア要素ブロック化メディア要素であると言います。

paused 属性が false のとき、再生終了しておらず、再生はエラーによって停止されておらず、現在のメディア・コントローラがない、または、現在のメディア・コントローラはあるもののメディア・コントローラでブロックされていない、のいずれかで、かつ、ブロック化メディア要素でないとき、そのメディア要素潜在的に再生中と言います。

メディア要素は、次の状態のとき、再生終了されたと言います:

ended 属性は、メディア要素再生終了再生方向が前進なら true を、そうでなければ、false を返さなければいけません。

readyState 属性が HAVE_METADATA、または、それ以上であり、かつ、ユーザーエージェントがメディア・データ処理中に非致命的エラーに遭遇し、かつ、そのエラーによって、現在再生位置でコンテンツを再生することができないとき、そのメディア要素エラーによって停止したと言います。

paused 属性が false で、readyState 属性が HAVE_FUTURE_DATA または HAVE_ENOUGH_DATA のいずれかで、ユーザーエージェントが、メディア・リソースの中で、ユーザーがリソースを継続するかを選択しなければならない地点に到達したとき、そのメディア要素ユーザー操作待受停止したと言います。これが起こったときにメディア要素現在のメディア・コントローラがあるなら、ユーザーエージェントは、そのメディア要素現在のメディア・コントローラコントローラ状態を報告しなければいけません。ユーザーが選択を行うとき、そのメディア要素現在のメディア・コントローラがあり、再生の再開を許すのであれば、同様に、ユーザーエージェントはそのメディア要素現在のメディア・コントローラコントローラ状態を報告しなければいけません。

メディア要素再生終了ユーザー操作待受停止の両方の状態が同時に起こることがあり得ます。

ユーザー操作待受停止によって潜在的に再生中メディア要素が再生が停止するとき、ユーザーエージェントは、この要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

潜在的に再生中の要素が再生を停止した結果として、waiting DOM イベントが発出されることがあります。これは、その readyState 属性が HAVE_FUTURE_DATA より小さい値に変化するためです。

再生方向が前進の時に現在再生位置メディア・リソースの最後に到達したら、ユーザーエージェントは次の手順に従わなければいけません:

  1. メディア要素loop 属性が指定されており、現在のメディア・コントローラがなければ、そのメディア・リソース巻き戻し限界位置にシークして、これらの手順を中止します。

  2. 再生を停止します。

    ended 属性が true になります。

  3. ユーザーエージェントは、この要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

  4. ユーザーエージェントは、この要素で ended という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

再生方向が後進の時に現在再生位置メディア・リソース巻き戻し限界位置に到達したら、ユーザーエージェントは次の手順に従わなければいけません:

  1. 再生を停止します。

  2. ユーザーエージェントは、この要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。


defaultPlaybackRate 属性は、メディア・リソースを再生させたい速度を与えます。これは、その本来の速度の倍数です。この属性はミュータブルです。取得時においては、それにセットされた最後の値を返さなければいけません。まだセットされていなければ 1.0 を返さなければいけません。セット時においては、この属性は新たな値にセットされなければいけません。

defaultPlaybackRate は、ユーザーエージェントがユーザーにユーザー・インタフェースを見せる場合に使います。

playbackRate 属性は実効再生レートを与えます(それを置き換える現在のメディア・コントローラが無いとと仮定します)。これは、メディア・リソースが再生する速度のことで、その本来の速度の倍数です。これが defaultPlaybackRate と同じでなければ、ユーザーが早送りやスロー・モーション再生といった機能を使っていることになります。この属性はミュータブルです。取得時においては、最後にセットされた値を返さなければいけません。まだセットされていなければ 1.0 を返さなければいけません。セット時においては、この属性は新た値にセットされ、その再生の速度が変化します(この要素が潜在的に再生中で、かつ、現在のメディア・コントローラが無い場合)。

defaultPlaybackRate または playbackRate 属性の値が変わったとき(スクリプトからセットされたか、ユーザー・コントロールの応答などでユーザーエージェントから直接的に変更されたか、のいずれか。)、ユーザーエージェントは、そのメディア要素ratechange という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

defaultPlaybackRateplaybackRate 属性は、メディア要素現在のメディア・コントローラがあるときは、何も作用しません。代わりに、MediaController オブジェクトの同じ名前の属性が、その状況で使われます。


played 属性は、メディア・リソースの範囲があれば、これを表す新たな静的な正規化 TimeRanges オブジェクトを返さなければいけません。これは、ユーザーエージェントが、この属性が評価される時点で、すでにレンダリングした範囲です。


play() メソッドがメディア要素で呼び出されるとき、ユーザーエージェントは、次の手順を実行しなければいけません:

  1. メディア要素networkState 属性の値が NETWORK_EMPTY なら、そのメディア要素リソース選択アルゴリズムを呼び出します。

  2. 再生が終了し、再生方向が前進であり、かつ、そのメディア要素現在のメディア・コントローラが無いなら、そのメディア・リソース巻き戻し限界位置シークします。

    これによって、ユーザーエージェントは、そのメディア要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングすることになります

  3. メディア要素現在のメディア・コントローラがあれば、そのメディア要素を、その新たなメディア・コントローラのスピードまで引き上げます

  4. メディア要素paused 属性が true なら、次の副手順を実行します:

    1. paused の値を false に変更します。

    2. その要素で play という名前のシンプルなイベントを発出するタスクをキューイングします。

    3. そのメディア要素readyState 属性の値が HAVE_NOTHING, HAVE_METADATA, HAVE_CURRENT_DATA なら、その要素で waiting という名前のシンプルなイベントを発出するタスクをキューイングします。

      そうでなければ、そのメディア要素readyState 属性の値が HAVE_FUTURE_DATA, HAVE_ENOUGH_DATA なら、その要素で playing という名前のシンプルなイベントを発出するタスクをキューイングします。

  5. そのメディア要素自動再生フラグを false にセットします。

  6. そのメディア要素現在のメディア・コントローラがあるなら、そのメディア要素現在のメディア・コントローラコントローラ状態を報告します。


pause() メソッドが呼び出されたときに、さらに、ユーザーエージェントがメディア要素を停止する必要があるとき、ユーザーエージェントは次の手順を実行しなければいけません:

  1. そのメディア要素networkState 属性の値が NETWORK_EMPTY なら、そのメディア要素リソース選択アルゴリズムを呼び出します。

  2. そのメディア要素自動再生フラグを false にセットします。

  3. そのメディア要素paused 属性が false なら、次の手順を実行します:

    1. paused の値を true に変更します。

    2. その要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングします。

    3. その要素で pause という名前のシンプルなイベントを発出するタスクをキューイングします。

  4. そのメディア要素現在のメディア・コントローラがあるなら、そのメディア要素現在のメディア・コントローラコントローラ状態を報告します。


実効再生レートは必ずしもその要素の playbackRate であるとは限りません。メディア要素現在のメディア・コントローラがあるとき、その実効再生レートは、その MediaControllerメディア・コントローラ再生レートとなります。そうでなければ、その実効再生レートは、単にその要素の playbackRate となります。このように、現在のメディア・コントローラは、そのメディア要素より優先されます。

もし実効再生レートが正の値かゼロなら、その再生方向は前進となります。そうでなければ、後進となります。

メディア要素潜在的に再生中で、その Document完全にアクティブな Document であるとき、その現在再生位置は、そのメディア・タイムラインのクロックの単位時間で刻まれたメディア時間の実効再生レートの単位で、単調に増えていかなければいけません。

実効再生レートは 0.0 になることがあります。これは、再生が停止されていないにも関わらず、現在再生位置が動いていない場合です(paused は true にならず、pause イベントは発出されません )。

本仕様は、ユーザーエージェントが適切な再生レートを実現する方法を定義しません。これは、利用可能なプロトコルやメディアに依存します。そして、ユーザーエージェントは適切なレートでメディア・データをサーバーに提供してもらうために、サーバーとネゴシエートするのが妥当と言えます。そうすることで、(レートが変わったときと、サーバーがストリームの再生レートを変更したときの間の期間を除いて)クライアントは、実際にフレームを落としたり挿入する必要が無くなります。

再生方向が後進のとき、対応のオーディオはミュートしなければいけません。実効再生レートが、ユーザーエージェントが普通にオーディオを再生することができないほどに低いか高いときも、対応のオーディオをミュートしなければいけません。実効再生レートが 1.0 でなければ、ユーザーエージェントは、適切なレンダリングのために必要に応じて、そのオーディオにピッチ調整を適用することができます。

潜在的に再生中メディア要素Document に存在しなければ、ビデオを再生してはいけません。しかし、オーディオ・コンポーネントは再生するべきです。メディア要素は、自身へ向けられたリファレンスすべてが削除されたという理由だけで再生を停止してはいけません。メディア要素にもうこれ以上に再生されるオーディオがないという状態になって初めて、その要素をガーベッジ・コレクションの対象にすることができるのです。

たとえ要素がまだ再生中になっていなくても、そういった要素に、オーディオを再生する明確なリファレンスがひとつも存在しないということはあり得ます:例えば、まだリファレンスを持ちつつもまだ停止はしていない現在のメディア・コントローラを持つことが考えられます。また、停止はしていないのにもかかわらずコンテンツを待ちそびれてバッファに入れることができないということも考えられます。


メディア要素現在再生位置が変わるとき(例えば、再生やシークによって)、ユーザーエージェントは次の手順を実行しなければいけません。もし現在再生位置がこの手順の実行中に変わるなら、ユーザーエージェントはこの手順が完了するのを待ち、その直後にこの手順を再実行しなければいけません。(ゆえに、この手順は可能な限り必要に応じて頻繁に実行されます。もし一回の反復に時間がかかってしまうと、ユーザーエージェントが急いで "追いつこう" とするので、あるキューがスキップされてしまうことになります。)

  1. current cuesキューの順序リストとします。これは、メディア要素無効になっていないもの)のすべてのキューを含んだ状態で初期化されます。hiddenshowingShowing by defaultテキスト・トラックすべてが対象です。ただし、開始時刻現在再生位置より前か等しく、かつ、終了時刻現在再生位置より後となるものに限ります。これは、テキスト・トラック・キュー順です。

  2. other cuesキューの順序リストとします。これは、メディア要素のすべてのキューを含んだ状態で初期化されます。hiddenshowingshowing by defaultテキスト・トラックすべてが対象です。ただし、current cues には存在しないものに限ります。これもテキスト・トラック・キュー順です。

  3. 通常再生中に、現在再生位置の通常の単調増加を通して時間が到達したなら、かつ、ユーザーエージェントが過去 15 ~ 20 ミリ秒に該当の要素で timeupdate イベントを発出しておらず、そういったイベントのイベント・ハンドラをまだ実行していないのであれば、ユーザーエージェントは、その要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。(例えば、明示的なシークなど、上記に該当しない場合、現在再生位置が変化する全体的な処理の一環で、関連のイベントが発出されます。)

    ゆえに、イベントは 66Hz 程度よりも早く、または、4Hz より遅く発出されることはありません(イベント・ハンドラーが実行に 250 ミリ秒より長くかからないと仮定)。ユーザーエージェントは、都度、システム負荷と、イベント処理の平均コストに基づいて、イベントの周期を変えることが推奨されます。そうすることで、ユーザーエージェントがビデオをデコードしている間でも、UI アップデートを無理なく処理できるようになります。

  4. current cuesキューすべてにテキスト・トラック・キュー・アクティブ・フラグがセットされ、other cues のキューのいずれにもテキスト・トラック・キュー・アクティブ・フラグがセットされていなければ、これらの手順を中止します。

  5. 通常再生中に、現在再生位置の通常の単調増加を通して時間が到達し、かつ、other cues に、テキスト・トラック・キュー・アクティブ・フラグテキスト・トラック・キュー終了停止フラグの両方がセットされたキューがあるなら、すぐにメディア要素停止します。(例えば、明示的なシークなど、上記に該当しない場合、キューの終了時間を超えることで再生が停止することはありません。たとえ、そのキューテキスト・トラック・キュー終了停止フラグがセットされていたとしてもです。)

  6. affected tracks を、テキスト・トラックのリストとします。最初は空です。

  7. other cues の中にあるテキスト・トラック・キュー・アクティブ・フラグがセットされたテキスト・トラック・キューそれぞれに対して、リストの順番で、TextTrackCue オブジェクトで exit という名前のシンプルなイベントを発出するタスクをキューイングします。そして、もしそれがまだリストの中になければ、affected tracks にそのキューテキスト・トラックを追加します。

  8. current cues の中にあるテキスト・トラック・キュー・アクティブ・フラグがセットされていないテキスト・トラック・キューそれぞれに対して、リストの順番で、TextTrackCue オブジェクトで enter という名前のシンプルなイベントを発出するタスクをキューイングします。そして、もしそれがまだリストの中になければ、affected tracks にそのキューテキスト・トラックを追加します。

  9. affected tracksテキスト・トラックそれぞれに対して、リストに追加された順番(これは、メディア要素テキスト・トラック・リストにあるテキスト・トラックの相対的な順番と一致します)で、TextTrack オブジェクトでcuechange という名前のシンプルなイベントを発出するタスクをキューイングします。そして、そのテキスト・トラックと対応付けられた track 要素があるなら、その track 要素でも、cuechange という名前のシンプルなイベントを発出します。

  10. current cues にあるすべてのキューテキスト・トラック・キュー・アクティブ・フラグをセットし、other cues にあるすべてのキューテキスト・トラック・キュー・アクティブ・フラグを解除します。

  11. affected tracks の中で、showing、または、showing by defaultとなっている各テキスト・トラックテキスト・トラック・レンダリング・アップデート規則を実行します。

前述のアルゴリズムの観点では、テキスト・トラック・キューは、テキスト・トラックの一部と見なされます。ただし、それがキューのテキスト・トラック・リストにリストされているだけならです。それがテキスト・トラックと関連づけられるにすぎないならではありません。

メディア要素Document完全にアクティブなドキュメントでなくなれば、そのドキュメントが再びアクティブになるまで再生は停止します。

メディア要素Document から削除されるとき、ユーザーエージェントは次の手順を実行しなければいけません:

  1. 非同期に安定状態を待機し、Documentメディア要素を削除したタスクが継続できるようにします。同期セクションは、このアルゴリズムの残りの手順すべてとなります。(同期セクションの手順は ⌛ でマーキングされています)

  2. メディア要素Document の中ににあれば、これらの手順を中止します。

  3. メディア要素networkState 属性の値が NETWORK_EMPTY なら、これらの手順を中止します。

  4. メディア要素停止します。

4.8.10.9 シーク
media . seeking

ユーザーエージェントが今まさにシーク中なら true を返します。

media . seekable

ユーザーエージェントがシーク可能なメディア・リソースの範囲を表す TimeRanges オブジェクトを返します。

seeking 属性の値は、最初は false でなければいけません。

ユーザーエージェントがメディア・リソースの特定の new playback position(新たな再生位置)にシークする必要があるとき、それは、ユーザーエージェントは次の手順を実行しなければいけないことを意味します。このアルゴリズムは、イベント・ループ・メカニズムと密接に作用しあいます。とりわけ、これには同期セクションがある点です(イベント・ループ・アルゴリズムの一環で呼び出されます)。そのようなセクションにおける手順には、このマークを付けてあります。 ⌛

  1. メディア要素readyStateHAVE_NOTHING なら、INVALID_STATE_ERR 例外を発出し(シークが DOM メソッド呼び出し、または、IDL 属性のセットによるものだった場合)、これらの手順を中止します。

  2. 要素の seeking IDL 属性が true なら、このアルゴリズムの別のインスタンスはすでに実行中です。このアルゴリズムのその別のインスタンスを中止します。完了に至るまでに実行している手順を待ちません。

  3. seeking IDL 属性を true にセットします。

  4. シークが DOM メソッドの呼び出し、または、IDL 属性のセットによるものだったなら、スクリプトを継続します。これらの手順の残りは非同期に実行されなければいけません。xxx というマークが付けられた手順を除いて、これらは、このアルゴリズムを呼び出す別のインスタンスによって、いつでも、中止される可能性があります。

  5. new playback positionメディア・リソースの終わりより後なら、それをそのメディア・リソースの終わりとします。

  6. new playback position巻き戻し限界位置より前なら、それをその位置とします。

  7. (変わったばかりかもしれませんが)new playback positionseekable 属性の範囲のいずれにも含まれないなら、それを、seekable 属性の範囲のうち、new playback position に最も近い範囲の位置とします。この制約を満たす位置が 2 つあったら(つまり、new playback positionseekable 属性の 2 つの範囲のちょうど中間)、現在再生位置に近い方の位置を使います。seekable 属性に範囲が一つもなければ、seeking IDL 属性を false にセットして、これらの手順を中止します。

  8. この要素で seeking という名前のシンプルなイベントを発出するタスクをキューイングします。

  9. 現在再生位置を、指定の new playback position にセットします。

    シークを開始する直前にメディア要素潜在的に再生中だったけれども、シークによって readyState 属性が HAVE_FUTURE_DATA より小さい値に変わってしまったら、その要素で waiting発出されます。

  10. ユーザーエージェントが new playback positionメディア・データが利用可能かどうかを確定できるまで待ちます。もし利用可能なら、デコードが完了してその位置の再生が可能となるまで待ちます。

  11. 安定状態を待ちます同期セクションは、このアルゴリズムの残りの手順すべてとなります。(同期セクションの手順は ⌛ でマーキングされています。)

  12. seeking IDL 属性を false にセットします。

  13. この要素で timeupdate という名前のシンプルなイベントを発出するタスクをキューイングします。

  14. ⌛ この要素で seeked という名前のシンプルなイベントを発出するタスクをキューイングします。

seekable 属性は、メディア・リソースの範囲を表す新たな静的な正規化 TimeRanges オブジェクトがあれば、それを返さなければいけません。これは、この属性が評価された時点において、ユーザーエージェントがシーク可能な範囲を指します。

単純な動画ファイルで、ユーザーエージェントとサーバーが HTTP Range リクエストをサポートしているといった理由で、ユーザーエージェントがメディア・リソースのどこにでもシークできるのであれば、この属性はひとつの範囲を伴ったオブジェクトを返すでしょう。この範囲の開始は最初のフレームの時間(巻き戻し限界位置、通常はゼロ)であり、最後は最初のフレームの時間に duration 属性の値(最後のフレームの時間と同じでしょうが、正の Infinity となる場合もあります)を加えたのと同じです。

その範囲は連続的に変わり続けるかもしれません。例えば、ユーザーエージェントが無限ストリームでスライディング・ウィンドウをバッファリングしている場合です。これは、例えば、DVR を使ってテレビの生放送を視聴したときに見られる挙動です。

メディア・リソースは内部的にスクリプトされておりインタラクティブな場合があります。ゆえに、メディア要素が非線形に再生されることが考えられます。もしこれが起こったら、ユーザーエージェントは、現在再生位置が不連続に変わるとき、シークのアルゴリズムが使われたかのように振る舞わなければいけません(そうすることで、関連のイベントが発出します)。メディア要素現在のメディア・コントローラがあれば、ユーザーエージェントは、代わりに適切にメディア・コントローラをシークしなければいけません。

4.8.10.10 複数のメディア・トラックを伴うメディア・リソース

メディア・リソースには複数のオーディオおよびビデオのトラックを組み込むことができます。例えば、主となるビデオとオーディオのトラックに加えて、外国語の吹き替え、監督の解説、音声解説、別のアングル映像、手話映像などをメディア・リソースに入れることができます。

media . audioTracks

メディア・リソースの中で利用可能なオーディオ・トラックを表す MultipleTrackList オブジェクトを返します。

media . videoTracks

メディア・リソースの中で利用可能なビデオ・トラックを表す ExclusiveTrackList オブジェクトを返します。

メディア要素の audioTracks 属性は、メディア要素メディア・リソースの中で利用可能なオーディオ・トラックを表す MultipleTrackList オブジェクトを返さなければいけません。このオブジェクトはライブです。いつでも同じオブジェクトが返されなければいけません。

メディア要素の videoTracks 属性は、メディア要素メディア・リソースの中で利用可能なビデオ・トラックを表す ExclusiveTrackList オブジェクトを返さなければいけません。このオブジェクトはライブです。いつでも同じオブジェクトが返されなければいけません。

ひとつのメディア要素につき、TrackList オブジェクトは 2 つしかありません(ひとつは MultipleTrackList オブジェクトで、もうひとつは ExclusiveTrackList オブジェクトです)。たとえ、他のメディア・リソースが該当の要素にロードされたとしてもです。このオブジェクトは再利用されます。

4.8.10.10.1 TrackList オブジェクト

MultipleTrackListExclusiveTrackList インタフェースは、前セクションで定義された属性に使われますが、これらは、ほとんど同じです。共通の機能は TrackList インタフェースで定義され、いずれにも継承されます。

interface TrackList {
  readonly attribute unsigned long length;
  DOMString getID(in unsigned long index);
  DOMString getKind(in unsigned long index);
  DOMString getLabel(in unsigned long index);
  DOMString getLanguage(in unsigned long index);

           attribute Function onchange;
};

interface MultipleTrackList : TrackList {
  boolean isEnabled(in unsigned long index);
  void enable(in unsigned long index);
  void disable(in unsigned long index);
};

interface ExclusiveTrackList : TrackList {
  readonly attribute unsigned long selectedIndex;
  void select(in unsigned long index);
};
tracks . length

リストのトラック数を返します。

id = tracks . getID( index )

指定のトラックの ID を返します。この ID は、該当のフォーマットが Fragments URI URI 構文をサポートしている場合に、フラグメント識別子と一緒に使うことができます。 [MEDIAFRAG]

kind = tracks . getKind( index )

指定のトラックが属するカテゴリを返します。想定されるトラック・カテゴリは後述の通りです。

label = tracks . getLabel( index )

指定のトラックのラベルが分かれば、それを返します。分からなければ空文字列を返します。

language = tracks . getLanguage( index )

指定の後ラックの言語が分かれば、それを返します。分からなければ空文字列を返します。

enabled = audioTracks . isEnabled( index )

指定のトラックがアクティブなら true を、そうでなければ false を返します。

audioTracks . enable( index )

指定のトラックを有効にします。

audioTracks . disable( index )

指定のトラックを無効にします。

videoTracks . isEnabled

現在選択されているトラックがあれば、そのインデックスを返します。なければ -1 を返します。

videoTracks . select( index )

指定のトラックを選択します。

length 属性は、取得の時点で TrackList オブジェクトによって表されるトラック数を返さなければいけません。

TrackList オブジェクトにあるトラックは、抜けがないよう順に並べられなければいけません。メディア・リソースが順序を定義するフォーマットにあるなら、その順番が使われなければいけません。そうでなければ、その順番は、トラックがメディア・リソースの中で宣言された相対的順序でなければいけません。最初のインデックスは 0 で、以降のトラックは、前のより 1 だけ大きい順番が割り振られます。

getID(index) メソッドは、インデックスが index となるトラックがあれば、その識別子を返さなければいけません。該当するトラックがなければ、このメソッドは INDEX_SIZE_ERR 例外を投げなければいけません。メディア・リソースMedia Fragments URI のフラグメント識別子構文をサポートするフォーマットにあるなら、返される識別子は、そのようなフラグメント識別子のトラック次元でトラック名として使ったら、そのトラックを有効にするであろう識別子と同じでなければいけません。 [MEDIAFRAG]

getKind(index) メソッドは、インデックスが index となるトラックがあれば、そのカテゴリーを返さなければいけません。無ければ、このメソッドは INDEX_SIZE_ERR 例外を投げなければいけません。

トラックのカテゴリーは下表の最初の列に入れられた文字列ですが、それは、この表の二番目と三番目の列の定義に基づいたトラックに最も適していることを表しています。これは、メディア・リソースのトラックに含まれるメタデータによって決定されます。Ogg ファイルでは、トラックの Role ヘッダーから関連のメタデータを取得できます。三番目の列にあるセルは、同じ行の最初の列にあるセルに入れられたカテゴリーは何に適用されるのかを言っています。カテゴリーがオーディオ・トラックに適用されるなら、それはオーディオ・トラックにのみ適しています。そして、カテゴリーがビデオ・トラックに適用されるなら、それはビデオ・トラックにのみ適しています。

getKind() が返す値
カテゴリー 定義 適用先
"alternative" 主トラックの代わりになり得るもの。歌の違う録音セッション(オーディオ)や違うアングル(ビデオ)など。 オーディオとビデオ Ogg: "audio/alterate" または "video/alternate".
"description" ビデオ・トラックの音声解説 オーディオのみ Ogg: "audio/audiodesc".
"main" 主となるオーディオやビデオのトラック オーディオとビデオ Ogg: "audio/main" または "video/main"; WebM: "FlagDefault" 要素がセットされる。
"sign" オーディオ・トラックの手話通訳 ビデオのみ Ogg: "video/sign".
"translation" 主トラックの翻訳バージョン オーディオのみ Ogg: "audio/dub".
"" (空文字列) はっきりとした種類がない。または、トラックのメタデータからユーザーエージェントが認識できる種類が得られない。 オーディオとビデオ それ以外のトラック・タイプや役割

getLabel(index) メソッドは、インデックスが index となるトラックがあり、それにラベルがあれば、そのラベルを返さなければいけません。そのようなトラックがなければ、このメソッドは INDEX_SIZE_ERR 例外を投げなければいけません。インデックスが index となるトラックがあるけれども、それにラベルがなければ、このメソッドは空文字列を返さなければいけません。

getLanguage(index) メソッドは、インデックスが index となるトラックがあり、それに言語があれば、その言語を表す BCP 47 言語タグを返さなければいけません。そのようなトラックがなければ、このメソッドは INDEX_SIZE_ERR 例外を投げなければいけません。インデックスが index となるトラックがあるけれども、それに言語が無い、または、ユーザーエージェントが BCP 47 言語タグとしてその言語を表現することができない(例えば、メディア・リソースのフォーマットの言語情報が、規定外の自由形式の文字列を許している)のであれば、このメソッドは空文字列を返さなければいけません。


MultipleTrackList オブジェクトは、同時に複数のトラックを有効にできるトラック・リストを表します。各トラックは有効か無効のいずれかになります。

isEnabled(index) メソッドは、インデックスが index となるトラックがあり、かつ、それがその時点で有効であれば、true を返さなければいけません。インデックスが index となるトラックがあるけれども、それがその時点で無効なのであれば、false を返さなければいけません。インデックスが index となるトラックが無ければ、INDEX_SIZE_ERR 例外を投げなければいけません。

enable(index) メソッドは、インデックスが index となるトラックがあれば、それを有効にしなければいけません。無ければ、INDEX_SIZE_ERR 例外を投げなければいけません。

disable(index) メソッドは、インデックスが index となるトラックがあれば、それを無効にしなければいけません。無ければ、INDEX_SIZE_ERR 例外を投げなければいけません。

トラックが有効か無効になるとき、ユーザーエージェントは、MultipleTrackList オブジェクトで change という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。


ExclusiveTrackList オブジェクトは、一度にひとつのトラックしか選択できないトラック・リストを表します。

selectedIndex 属性は、現在選択されているトラックのインデックスを返さなければいけません。ExclusiveTrackList オブジェクトがどのトラックも表していないのであれば、-1 を返さなければいけません。

select(index) は、インデックスが index となるトラックがあれば、それを選択して、前に選択されていたトラックを非選択にしなければいけません。インデックスが index となるトラックが無ければ、INDEX_SIZE_ERR 例外を投げなければいけません。

選択トラックが変わったら、ユーザーエージェントは、MultipleTrackList オブジェクトで change という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。


次は、TrackList インタフェースを実装するすべてのオブジェクトによって、IDL 属性として、サポートされなければならないイベント・ハンドラー(そして、それに関連するイベント・ハンドラのイベント・タイプ)です:

イベント・ハンドラ イベント・ハンドラのイベント・タイプ
onchange change

本セクションで挙げたタスクに対するタスク・ソースは、DOM 操作タスク・ソースです。

4.8.10.10.2 特定のオーディオとビデオ・トラックを宣言的に選択する

audioTracksvideoTracks 属性によって、スクリプトから再生すべきトラックを選択することができますが、宣言的に特定のトラックを選択することもできます。それは、メディア・リソースURL のフラグメント識別子に特定のトラックを指定します。フラグメント識別子のフォーマットは、メディア・リソースMIME タイプに依存します。 [RFC2046] [RFC3986]

この例では、Media Fragments URI フラグメント識別子構文をサポートするフォーマットを使ったビデオが組み込まれますが、デフォルトのビデオ・トラックではなく、"Alternative" とラベル付けされた別アングルが組み込まれます。[MEDIAFRAG]

<video src="myvideo#track=Alternative"></video>
4.8.10.11 複数のメディア要素を同期する
4.8.10.11.1 イントロダクション

メディア要素MediaController を持たせることができます。MediaController は、複数のメディア要素の再生を連携させるオブジェクトです。例えば、手話通訳のトラックをビデオ・トラックに重ねて表示させ、その 2 つを同期させることができます。

デフォルトでは、メディア要素MediaController はありません。mediagroup コンテンツ属性を使うことで、暗黙的に MediaController を割り当てることができます。controller IDL 属性を使えば、明示的に MediaController を直接的に割り当てることができます。

メディア要素MediaController を持つことを、コントローラに従属していると言います。MediaController は、それに従属している各メディア要素の再生レートや再生ボリュームを変えます。そして、従属するメディア要素のひとつでも意図せずに止まってしまったら、確実にその他も同時に停止させます。

メディア要素MediaController に従属すると、その再生レートは、同じ MediaController の他のトラックと同じに固定され、ループはすべて無効になります。

4.8.10.11.2 メディア・コントローラ
[Constructor]
interface MediaController {
  readonly attribute TimeRanges buffered;
  readonly attribute TimeRanges seekable;
  readonly attribute double duration;
           attribute double currentTime;

  readonly attribute boolean paused;
  readonly attribute TimeRanges played;
  void play();
  void pause();

           attribute double defaultPlaybackRate;
           attribute double playbackRate;

           attribute double volume;
           attribute boolean muted;

           attribute Function onemptied;
           attribute Function onloadedmetadata;
           attribute Function onloadeddata;
           attribute Function oncanplay;
           attribute Function oncanplaythrough;
           attribute Function onplaying;
           attribute Function onwaiting;

           attribute Function ondurationchange;
           attribute Function ontimeupdate;
           attribute Function onplay;
           attribute Function onpause;
           attribute Function onratechange;
           attribute Function onvolumechange;
};
controller = new MediaController()

新たな MediaController オブジェクトを返します。

media . controller [ = controller ]

メディア要素に現在の MediaController があれば、それを返します。無ければ null を返します。

明示的に MediaController をセットすることができます。その場合、mediagroup 属性があれば、それを削除することになります。

controller . buffered

ユーザーエージェントが持っているすべての従属メディア要素のすべての関連のメディア・データの時間範囲の共通部分を表す TimeRanges オブジェクトを返します。

controller . seekable

ユーザーエージェントがすべての従属メディア要素に対してシーク可能なの時間範囲の共通部分を表す TimeRanges オブジェクトを返します。

controller . duration

巻き戻し可能な限界の時間と早送り可能な限界の時間の間の差分を返します(該当のデータが実際いバッファーされたかどうかや、直接的にシーク可能かどうかは考慮しません。しかし、無限ストリームでは未来の時間が含まれることはありません)。メディアが無ければゼロを返します。

controller . currentTime [ = value ]

ゼロ時間と現在の duration の間の位置として、現在再生位置を秒で返します。単位は秒です。

値をセットして指定の時間にシークすることができます。

controller . paused

再生が停止していれば true を、そうでなければ false を返します。この属性が true なら、このコントローラに従属するメディア要素はすべて停止しています。

controller . played

再生済みのすべての従属メディア要素の時間範囲の和集合を表す TimeRanges オブジェクトを返します。

controller . play()

paused 属性を false にセットします。

controller . pause()

paused 属性を true にセットします。

controller . defaultPlaybackRate [ = value ]

デフォルトの再生レートを返します。

値をセットして、デフォルトの再生レートを変更することができます。

このデフォルトのレートは、再生において直接的な影響を及ぼすことはありません。しかし、ユーザーが早送りモードに切り替えて、通常再生モードに戻るとき、再生レート (playbackRate) はこのデフォルトのレートに戻ります。

controller . playbackRate [ = value ]

現在の再生レートを返します。

値をセットして、再生レートを変更することができます。

controller . volume [ = value ]

現在の再生音量の乗数を 0.0 から 1.0 の範囲の数値として返します。0.0 は無音で 1.0 は最大音量を意味します。

値をセットして、音量の乗数を変更することができます。

新たな値が 0.0 ~ 1.0 の範囲にないなら、INDEX_SIZE_ERR を投げます。

controller . muted [ = value ]

すべてのオーディオがミュート(該当のコントローラやそのコントローラに従属したメディア要素における他の属性に関係なく)されていれば true を、そうでなければ false を返します。

値をセットして、オーディオのミュート状態を切り替えることができます。

メディア要素現在のメディア・コントローラを持つことができます。これは、MediaController オブジェクトのことです。メディア要素mediagroup 属性を伴わずに生成されるときは、現在のメディア・コントローラを持ちません。(そういった属性を伴って生成されれば、後述の通り、この属性は現在のメディア・コントローラを初期化します。)

MediaController従属メディア要素とは、現在のメディア・コントローラがその MediaController となるメディア要素のことです。MediaController のすべての従属メディア要素は、メディア・タイムラインの単位時間の定義に同じクロックを使わなければいけません。


メディア要素controller 属性は、取得時においては、その要素に現在のメディア・コントローラがあれば、それを返し、なければ null を返さなければいけません。セット時においては、まず、その要素に mediagroup 属性があれば、それを削除し、そして、その現在のメディア・コントローラを指定の値にセットしなければいけません。指定の値が null なら、その要素の現在のメディア・コントローラは無くなります。null でなければ、ユーザーエージェントは、その新たなメディア・コントローラを使って、そのメディア要素のスピードを合わせなければいけません。


MediaController() コンストラクタは、呼び出されたら、新たに生成された MediaController オブジェクトを返さなければいけません。


seekable 属性は、新たな静的な正規化 TimeRanges オブジェクトを返さなければいけません。これは、ユーザーエージェントが、この属性を評価した時点で、従属メディア要素メディア・リソースのうち、シーク可能な範囲の共通部分を表します。

buffered 属性は、新たな静的な正規化 TimeRanges オブジェクトを返さなければいけません。これは、ユーザーエージェントが、この属性を評価した時点で、従属メディア要素メディア・リソースのうち、すでにバッファ済みの範囲の共通部分を表します。ユーザーエージェントは、その範囲が利用可能かを正確に判定しなければいけません。たとえ、面倒な調査をしなければ判定できないようなメディア・ストリームだったとしてもです。

duration は、メディア・コントローラの尺を返さなければいけません。

15 ~ 250 ミリ秒ごと、または、MediaControllerメディア・コントローラの尺が変わるたびに、どちらが発生しても最短の頻度で、ユーザーエージェントは、その MediaControllerdurationchange という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。MediaControllerメディア・コントローラの尺が減っていき、そのメディア・コントローラの位置が、そのメディア・コントローラの尺より大きくなれば、ユーザーエージェントは、即座にそのメディア・コントローラをメディア・コントローラの尺シークしなければいけません。

currentTime 属性は、取得時においては、メディア・コントローラの位置を返さなければいけません。そして、セット時においては、メディア・コントローラを新たな値にシークしなければいけません。

15 ~ 250 ミリ秒ごと、または、MediaControllerメディア・コントローラの位置が変わるたびに、どちらが発生しても最短の頻度で、ユーザーエージェントは、その MediaControllertimeupdate という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。


MediaController が生成されるとき、それは再生中メディア・コントローラとなります。それは、停止中メディア・コントローラに変わることもありますし、ユーザーエージェントのユーザー・インタフェース(その要素がユーザーにユーザー・インタフェースを表示している場合)や、本セクション(後述します)で定義している API を使ったスクリプトのいずれかを通して、戻ることもあります。

paused 属性は、MediaController停止中メディア・コントローラなら true を返し、そうでなければ false を返します。

played 属性は、新たな静的な正規化 TimeRanges オブジェクトを返さなければいけません。これは、ユーザーエージェントが、この属性を評価した時点で、従属メディア要素メディア・リソースのうち、すでにレンダリングした範囲の和集合を表します。

pause() メソッドが呼び出されたとき、その MediaController再生中メディア・コントローラなら、ユーザーエージェントは、その MediaController停止中メディア・コントローラに変更し、その MediaControllerpause という名前のシンプルなイベントを発出するタスクをキューイングし、そして、その MediaControllerコントローラの状態を報告しなければいけません。

play() メソッドが呼び出されるとき、その MediaController停止中メディアコントローラなら、ユーザーエージェントは、その MediaController再生中メディア・コントローラに変更し、その MediaControllerplay という名前のシンプルなイベントを発出するタスクをキューイングし、そして、その MediaControllerコントローラの状態を報告しなければいけません。


MediaController には、メディア・コントローラ・デフォルト再生レートメディア・コントローラ再生レートがあります。これらはいずれも、その MediaController が生成されるときに 1.0 にセットされなければいけません。

defaultPlaybackRate 属性は、取得時においては、その MediaControllerメディア・コントローラ・デフォルト再生レートを返さなければいけません。取得時においては、その MediaControllerメディア・コントローラ・デフォルト再生レートを新たな値にセットし、その MediaControllerratechange という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。

playbackRate 属性は、取得時においては、その MediaControllerメディア・コントローラ再生レートを返さなければいけません。取得時においては、その MediaControllerメディア・コントローラ再生レートを新たな値にセットし、その MediaControllerratechange という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。


MediaController は、メディア・コントローラ音量乗数を持ちます。これは、その MediaController オブジェクトが生成されるときに 1.0 にセットされなければいけません。さらに、メディア・コントローラ・ミュート・オーバーライドを持ちますが、これは false で初期化されなければいけません。

volume 属性は、取得時においては、MediaControllerメディア・コントローラ音量乗数を返さなければいけません。そして、セット時においては、新たな値が 0.0 ~ 1.0 の範囲内であれば、その MediaControllerメディア・コントローラ音量乗数を、その新たな値にセットし、その MediaControllervolumechange という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。新たな値が 0.0 ~1.0 の範囲外なら、セット時に、INDEX_SIZE_ERR 例外が発出されなければいけません。

muted 属性は、取得時においては、その MediaControllerメディア・コントローラ・ミュート・オーバーライドを返さなければいけません。そして、セット時においては、その MediaControllerメディア・コントローラ・ミュート・オーバーライドを新たな値にセットし、その MediaControllervolumechange という名前のシンプルなイベントを発出するタスクをキューイングしなければいけません。


MediaController のすべての従属メディア要素メディア・リソースは、それぞれのゼロ時間の間の相対的なオフセットを提供する定義済みの一時的な関係性を持ちます。タイムライン・オフセットを持つメディア・リソースでは、その相対的なオフセットは、そのタイムライン・オフセット間の差となります。タイムライン・オフセットを持たないすべてのメディア・リソースのゼロ時間は、お互いからのオフセットではありません(つまり、そのタイムラインの起源は相互に一時的なものとなります。)。そして、最後に、最も前のタイムライン・オフセットを持つメディア・リソースのゼロ時間(もしあれば)は、タイムライン・オフセットを持たないメディア・リソースのゼロ時間からのオフセットではありません(つまり、タイムライン・オフセットを持たないメディア・リソースの起源は、最も前のタイムライン・オフセットを持つメディア・リソースのタイムライン上の最も前の定義済み地点を使って、さらに相互に一時的なものとなります)。

メディア要素にあるメディア・リソースメディア・リソース最終地点とは、次の通りに定義されます:メディア・リソースが有限で尺が分かるのであれば、そのメディア・リソース最終地点は、そのメディア・リソースのタイムラインの尺(そのタイムライン上の最後の定義済み地点)となります。そうでなければ、そのメディア・リソースの尺は無限で不明となり、そのメディア・リソース最終地点は、その時点でメディア・リソースにとって利用可能なメディア・データの最後のフレームの時間となります。

MediaController には、それ自身にも定義済みタイムラインがあります。このタイムラインでは、その MediaController のすべての従属メディア要素のすべてのメディア・リソースは、定義済みオフセットによって一時的に並べられます。MediaControllerメディア・コントローラの尺とは、最も手前となる巻き戻し可能位置からの時間です。これは、この MediaController のタイムラインと相対的で、その MediaController の従属メディア要素のメディア・リソースのいずれかのものとなり、その MediaController の数ある従属メディア要素メディア・リソースのうち最後のメディア・リソース最終地点の時間までで、これも、この MediaController のタイムラインから相対的となります。

MediaController にはメディア・コントローラ位置があります。これは、ユーザーエージェントが従属メディア要素を再生しようとしている MediaController のタイムライン上にあります。MediaController が生成されるとき、そのメディア・コントローラ位置は最初はゼロになります。

ユーザーエージェントが、メディア要素を新たなメディア・コントローラのスピードに合わせることになったとき、そのメディア要素を、そのメディア要素のタイムラインから見て、その MediaControllerメディア・コントローラ位置シークしなければいけません。その結果で例外が発生しても破棄します。

ユーザーエージェントが特定の new playback positionメディア・コントローラをシークすることになったとき、これらの手順に従わなければいけません:

  1. new playback position が 0 未満なら、それを 0 にセットします。

  2. new playback positionメディア・コントローラの尺より大きければ、それをメディア・コントローラの尺にセットします。

  3. メディア・コントローラ位置new playback position にセットします。

  4. それぞれの従属メディア要素を、そのメディア要素のタイムラインから見て new playback position にシークします。その結果で例外が発生しても破棄します。

MediaController停止中メディア・コントローラである、または、その従属メディア要素ブロックされたメディア要素がある、または、自動再生フラグが true の従属メディア要素のうち、その paused 属性が true のままになっているものがある、または、従属メディア要素のすべての paused 属性が true にセットされているなら、その MediaController のことをブロックされたメディア・コントローラと言います。

MediaControllerブロックされたメディア・コントローラである、または、そのメディア・コントローラの位置が、その MediaController のタイムラインから見て、そのメディア・リソース巻き戻し限界位置より前である、または、その MediaController のタイムラインから見て、そのメディア・リソースの最後より後ろであるなら、そのメディア要素は、そのメディア・コントローラでブロックされていると言います。

MediaControllerブロックされたメディア・コントローラではなく、かつ、Document完全にアクティブDocument となる従属メディア要素を少なくとも一つ持つとき、その MediaControllerメディア・コントローラ位置は、単調に増えていかなければいけません。ただし、その従属メディア要素が使っているクロックの単位時間を持った MediaController のタイムライン上で、メディア・コントローラ再生レートの時間単位で増えていかなければいけません。

MediaController のタイムライン上のゼロ地点が、従属メディア要素のタイムラインと 時間差 ΔT で動くとき、その MediaControllerメディア・コントローラ位置ΔT だけ減らされなければいけません。

例えば、バッファリングなしにライブ・ストリームを再生するときなど、ある状況においては、そのメディア・コントローラ位置は単調に増えていくでしょう。前述の通り、前の段落で説明した ΔT と同じレートになり、結果的に、すべての意図と目的のため、そのメディア・コントローラ位置は、一定のままに見えるでしょう(恐らく値は 0 です)。


MediaController は、直前に報告された読取状態というものを持ちます。これは 0 ~ 4 までの数値となり、該当のメディア要素readyState 属性に使われる数値に相当します。直前に報告された再生状態とは、playingwaitingended のいずれかのことです。

MediaController が生成されるとき、その直近に報告された読取状態は 0 にセットされなければいけません。そして、その直近に報告された再生状態waiting にセットされなければいけません。

ユーザーエージェントが MediaController に対してコントローラ状態を報告する必要があるとき、ユーザーエージェントは次の手順を実行しなければいけません:

  1. MediaController従属メディア要素が無ければ、new readiness state を 0 にセットします。

    そうでなければ、すべての従属メディア要素readyState IDL 属性のうち、最も低い値にセットします。

  2. MediaController直近に報告された読取状態が、new readiness state と等しくないなら、該当の MediaController オブジェクトでシンプルなイベントを発出するタスクをキューイングします。このイベントの名前は下表にある new readiness state の値に相当するイベント名になります:

    new readiness state の値 イベント名
    0 emptied
    1 loadedmetadata
    2 loadeddata
    3 canplay
    4 canplaythrough
  3. MediaController直近に報告された読取状態を、new readiness state とします。

  4. new playback state を、次のリストの中から最初に一致する条件に指定された状態にセットして、初期化します:

    MediaController従属メディア要素が無い場合
    new playback statewaiting とします。
    MediaController従属メディア要素のすべてが再生終了となっており、かつ、メディア・コントローラ再生レートが 0 以上の場合
    new playback stateended とします。
    MediaControllerブロックされたメディア・コントローラの場合
    new playback statewaiting とします。
    いずれにも該当しない場合
    new playback stateplaying とします。
  5. MediaController直近に報告された再生状態new playback state に等しくないなら、該当の MediaController オブジェクトでシンプルなイベントを発出するタスクをキューイングします。その名前は、new playback stateplaying なら playing となり、new playback stateended なら ended となり、それ以外の場合は waiting となります。

  6. MediaController直近に報告された再生状態を、new playback state とします。


次は、サポートされなければいけないイベント・ハンドラです。これは MediaController インタフェースを実装するすべてのオブジェクトで、IDL 属性としてサポートされなければいけません:

イベント・ハンドラ イベント・ハンドラのイベント・タイプ
onemptied emptied
onloadedmetadata loadedmetadata
onloadeddata loadeddata
oncanplay canplay
oncanplaythrough canplaythrough
onplaying playing
onwaiting waiting
ondurationchange durationchange
ontimeupdate durationchange
onplay play
onpause pause
onratechange ratechange
onvolumechange volumechange

本セクションに挙げたタスクに対するタスク・ソースは、DOM マニピュレーション・タスク・ソースです。

4.8.10.11.3 メディア・コントローラの割当宣言

メディア要素mediagroup コンテンツ属性は、複数のメディア要素を一緒に連携させ暗黙的に MediaController を生成するために使うことができます。

メディア要素mediagroup 属性を伴って生成されるとき、そして、mediagroupmediagroup 属性がセット、変更、削除されるとき、ユーザーエージェントは次の手順を実行しなければいけません:

  1. m を該当のメディア要素とします。

  2. m にメディア・コントローラがあれば、現在のメディア・コントローラを持たせません。

  3. mmediagroup 属性が削除されているなら、これらの手順を中止します。

  4. DocumentmDocument と同じ(たとえ、これらの要素のひとつまたは両方が、実際にその Document の中にないとしてもです)であり、かつ、mediagroup 属性も持ち、かつ、mediagroup 属性が mmediagroup 属性の新たな値と同じ値を持つ別のメディア要素があるなら、controller を、そのメディア要素現在のメディア・コントローラとします。

    なければ、controller を新たに生成された MediaController とします。

  5. m現在のメディア・コントローラcontroller とします。

  6. メディア要素を、その新メディア・コントローラの速度に合わせます

メディア要素mediaGroup IDL 属性は、mediagroup コンテンツ属性を反映しなければいけません。

同じメディア・リソースを参照する複数のメディア要素は、一つのネットワーク・リクエストを共有します。これは、スクリーン上に二つの異なる場所に同じメディア・リソースの二つの(ビデオ)トラックを効率的に再生するために使うことができます。mediagroup 属性と一緒に使えば、これらの要素は同期し続けることもできます。

この例では、二つの video 要素、CSS、そして暗黙的な MediaController を使って、映画ファイルの手話通訳のトラックが、同じビデオ・ファイルの主ビデオ・トラックに重ねて表示されます:

<article>
 <style scoped>
  div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
  video { position; absolute; bottom: 0; right: 0; }
  video:first-child { width: 100%; height: 100%; }
  video:last-child { width: 30%; }
 </style>
 <div>
  <video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
  <video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
 </div>
</article>
4.8.10.12 タイミング同期テキスト・トラック
4.8.10.12.1 テキスト・トラック・モデル

メディア要素は関連のテキスト・トラックのグループを持つことができます。これをメディア要素テキスト・トラック・リストと呼びます。テキスト・トラックは次の通りに並べ替えられます:

  1. メディア要素の子となる track 要素に対応するテキスト・トラックツリー順です。
  2. addTextTrack() メソッドを使って加えられたテキスト・トラック。それらが追加された順で、最初のが最も古くなります。
  3. メディア・リソース特定のテキスト・トラックメディア・リソースの中のデータに対応するテキスト・トラック)。メディア・リソースのフォーマットの仕様で規定された順です。

テキスト・トラックは以下のものから構成されます:

テキスト・トラック種別

これは、トラックがユーザーエージェントによってどう扱われるかを決定します。この種別は文字列によって表されます。利用可能な文字列は以下の通りです:

  • subtitles
  • captions
  • descriptions
  • chapters
  • metadata

track 要素がテキスト・トラックに対応付けられている場合には、トラック種別を動的に変更することができます。

ラベル

これは、ユーザーに対してトラックを識別できるようにすることを目的にした人間が解読可能な文字列です。場合によっては、このラベルは自動的に生成されることもあります。

track 要素がテキスト・トラックに対応付けられている場合、または、ユーザー設定のユーザー・インタフェース言語のように、値が変動要因に異存してしまうような自動生成ラベルの場合においては、トラックのラベルを動的に変更することができます。

言語

これは、テキスト・トラックのキューの言語を表す文字列(BCP 47 言語タグ)です。 [BCP47]

track 要素がテキスト・トラックに対応付けられている場合には、テキスト・トラックの言語を動的に変更することができます。

読取状態

次のいずれか一つになります:

Not loaded

テキスト・トラックが存在していることは分かっているけれども(例えば、track 要素で宣言されている)、そのキューがまだ取得できていないことを表します。

Loading

テキスト・トラックがロード中で、今のところ致命的なエラーはないことを表します。まだ、さらなるキューがトラックに加えられるでしょう。

Loaded

致命的なエラーも無くテキスト・トラックがロードされたことを表します。トラックに新たなキューが加えられることはありません。ただし、テキスト・トラックMutableTextTrack オブジェクトに関連付いている場合は除きます。

Failed to load

テキスト・トラックは利用可能ではあったが、ユーザーエージェントがそれを取得しようとしたら、何かしらの理由で失敗したことを表します(例えば、URL解決できなかったり、ネットワークエラーだったり、テキスト・トラックのフォーマットが未知のものだったなど)。いくつか、または、すべてのキューが見つからず、取得できません。

テキスト・トラック読取状態は、そのトラックが取得できると、動的に変わります。

モード

次のいずれか一つになります:

Disabled

テキスト・トラックはアクティブでないことを表します。DOM でそのトラックにアクセスできるようにするという目的を除き、ユーザーエージェントはそのテキスト・トラックを無視します。アクティブなキューはなく、イベントも発出されません。ユーザーエージェントはそのトラックのキューを取得しようとはしません。

Hidden

テキスト・トラックはアクティブですが、ユーザーエージェントはそのキューを自発的に表示しません。トラックの取得の試みがなければ、ユーザーエージェントはすぐに試みを実行します。ユーザーエージェントはアクティブなキューのリストを維持しており、必要に応じてイベントが発出されます。

Showing
Showing by default

テキスト・トラックはアクティブということを表します。そのトラックのキューを取得しようとする試みがなされていなければ、ユーザーエージェントはすぐにその試みを実行します。ユーザーエージェントは、アクティブなキューのリストを維持しており、必要に応じてイベントが発出されます。さらに、kindsubtitlescaptions のテキスト・トラックに対しては、そのキューは適切なときにビデオ上に表示されています。kinddescriptions のテキスト・トラックに対しては、ユーザーエージェントは非ビジュアルにユーザーに利用できるようにしています。kindchapters のテキスト・トラックに対しては、ユーザーエージェントは、ユーザーがキューを選択することによってメディア・リソースのあらゆる地点へ飛ぶことができるメカニズムをユーザーが利用できるようにしています。

showing by default 状態は track 要素の default 属性と一緒に使い、テキスト・トラックはその属性によって利用可能だと示すことができます。こうすることで、ユーザーエージェントは、後ろのトラックが発見され、それがユーザー設定でより適切だと分かれば、その状態を優先することができます。

0 個以上のキューで構成されるリスト

テキスト・トラック・キューのリストのことです。テキスト・トラックのレンダリングを更新する規則を持っています。

テキスト・トラックのキューのリストは動的に変化します。これは、テキスト・トラックまだロードされていない、または、まだロード中である、または、テキスト・トラックMutableTextTrack オブジェクトに対応付いているといった理由からです。このオブジェクトの API は、動的に個々のキューを追加したり削除することができます。

テキスト・トラックは、TextTrack オブジェクトと対応付けられます。

メディア要素テキスト・トラックは、該当の要素のリソース選択アルゴリズムが最後に開始したときに、モードdisabled 状態にないすべてのテキスト・トラックテキスト・トラック読取状態loaded または failed to load なのであれば、準備完了であるといいます。


テキスト・トラック・キューとは、テキスト・トラックの中の、時間に影響を受けるデータの単位のことです。これは、サブタイトルやキャプションなどをテキストと対応付け、それは特定の時間に表示され、それ以外では非表示になります。

それぞれのテキスト・トラック・キューは、以下から構成されます:

識別子

任意の文字列です。

開始時間

キューが関係することになる時間です。単位は小数を伴う秒です。

終了時間

キューが関連しなくなる時間です。単位は小数を伴う秒です。

pause-on-exit フラグ

キューが関連しなくなるときに、メディア・リソースの再生が停止することになるかどうかを表す真偽値です。

書式方向

書式方向とは、横書き(行は横に伸び、それぞれの行は縦に配置され、行の続きはその下に表示されます)、縦書き行送り左方向(行は縦に伸び、それぞれの行は横に配置され、行の続きはその左に配置されます)、縦書き行送り右方向(行は縦に伸び、それぞれの行は横に配置され、行の続きはその右に配置されます)のいずれかです。

サイズ

キューの各行のテキストが配置されることになるボックスのサイズを表す数値です。これは、ビデオのパーセンテージとして解釈され、書式方向で決まります。

キューのテキスト

キューの生のテキスト、および、その解釈のための規則です。これによって、そのテキストは DOM フラグメントに変換されレンダリングすることができます。

テキスト・トラック・キューは不変です。

テキスト・トラック・キューは、TextTrackCue オブジェクトと対応付けられます。そして、特定のテキスト・トラックと結び付けることができます。テキスト・トラック・キューが特定のテキスト・トラックと結び付けられたら、その関係は不変となります。

さらに、各テキスト・トラック・キューは、二つの動的な情報を持ちます:

アクティブ・フラグ

このフラグは最初はセットされてはいけません。このフラグは、キューがアクティブまたは非アクティブになるときに、確実にイベントが適切に発出されるようにするために使います。そして、確実に正しいキューがレンダリングされるようにするために使います。

ユーザーエージェントは、テキスト・トラック・キューがそのテキスト・トラックテキスト・トラック・リストから削除されるときは常に、このフラグを同期的に落とさなければいけません。テキスト・トラック自身がそのメディア要素テキスト・トラック・リストから削除される、または、そのテキスト・トラック・モードdisabled に変更されるとき、そして、メディア要素readyStateHAVE_NOTHING に戻るときはも同様です。表示されていた、または、関連のインシデントに優先してデフォルトによって表示されていたテキスト・トラックのひとつ以上のキューに対して、この理由でフラグが落とされているとき、ユーザーエージェントは、影響を受けるすべてのキューに対してフラグを落とした後、それらのテキスト・トラックテキスト・トラック・レンダリングを更新する規則を適用しなければいけません。

表示状態

これは、適切な位置にキューを保つために、レンダリング・モデルの一環で使われます。これは最初は空でなければいけません。テキスト・トラック・キューのアクティブ・フラグが落とされているときは常に、ユーザーエージェントは、テキスト・トラック・キューの表示状態を空にしなければいけません。

メディア要素テキスト・トラックテキスト・トラック・キューは、テキスト・トラック・キュー順に、並べられます。この順番は次のように決定されます:最初に、テキスト・トラックキューをグループ化します。このグループは、テキスト・トラックが、メディア要素テキスト・トラック・リストに現れる順番と同じになるように並べられます。次に、それぞれのグループの中で、キューは、開始時刻が早い順に並べられなければいけません。次に、同じ開始時刻となるキューがいくつもあれば、それらは終了時刻が早い順に並べられなければいけません。最後に、同じ終了時刻となるキューがいくつもあれば、それらは作成順に並べられなければいけません(例えば、WebVTT ファイルのキューであれば、そのキューがファイルの中でリストされている順番になるでしょう)。

4.8.10.12.2 帯域内テキスト・トラックの抽出

メディア・リソース固有のテキスト・トラックとは、メディア・リソースの中にあるデータに相当するテキスト・トラックのことです。

このようなデータの処理やレンダリングの規則は、関連の仕様で定義されています。例えば、メディア・リソースがビデオであれば、そのビデオ形式の仕様です。

ユーザーエージェントがテキスト・トラックと等価であると認識できサポートしているデータをメディア・リソースが含んでいるとき、次のように、ユーザーエージェントは、その関連データを使って、メディア・リソース固有のテキスト・トラック公開する手順実行します:

  1. 関連データを、新たなテキスト・トラックと、それに相当する新たな TextTrack オブジェクトに関連付けます。そのテキスト・トラックが、メディア・リソース固有のテキスト・トラックです。

  2. 新たなテキスト・トラック種別ラベル言語を、関連データのセマンティクスに基づいて、セットします。これは関連仕様で定義されているものです。

  3. 新たなテキスト・トラックキュー・リストを、その時点で解析されたキューを使って装着します。キュー公開のガイドラインに従います。そして、必要に応じてそれを動的にアップデートします。

  4. 新たなテキスト・トラック読取状態を、現在の状態を最も正確に表す値にセットし、必要に応じて、それを動的にアップデートし始めます。

    例えば、メディア・リソースの関連データがすべて解析され、完全にキューを表すことができるのであれば、そのテキスト・トラックloaded になります。一方、キューのデータがメディア・データと交互に配置されており、そのメディア・リソース全体がまだダウンロードされていないのであれば、loading 状態のほうが正確と言えるでしょう。

  5. 新たなテキスト・トラックモードを、ユーザー設定や、そのデータの関連仕様の要件に一致するモードにセットします。

  6. テキスト・トラック・キュー・リストを空にして、それを該当の形式に適したテキスト・トラック・レンダリング・アップデート規則と関連付けます。

  7. 新たなテキスト・トラックを、メディア要素テキスト・トラック・リストに追加します。

メディア要素が、メディア要素のメディア・リソース固有のテキスト・トラックを忘れることになったら、ユーザーエージェントは、そのメディア要素テキスト・トラック・リストから、すべてのメディア・リソース固有のテクスト・トラックを削除しなければいけません。

4.8.10.12.3 帯域外テキスト・トラックの抽出

track 要素が生成されるとき、それは、新たなテキスト・トラック(後で定義する通り、その値を使います)と、それに相当する新たな TextTrack オブジェクトに関連付けられなければいけません。

テキスト・トラック種別は、下表の通り、要素の kind 属性の状態から決定されます。最初のカラムのセルにある状態に対応する種別は、その次のカラムにある文字列となります:

状態 文字列
Subtitles subtitles
Captions captions
Descriptions descriptions
Chapters chapters
Metadata metadata

テキスト・トラック・ラベルは、その要素のトラック・ラベルです。

テキスト・トラック言語は、その要素のトラック言語です。なければ空文字列です。

kind, label, srclang 属性がセット、変更、削除されたら、テキスト・トラックは、前述の定義従って、適切にアップデートしなければいけません。

トラック URL の変更は、後述のアルゴリズムで扱われます。

テキスト・トラック・キュー・リストは最初は空です。参照ファイルが解析できたら動的に変わります。該当の形式に適したテキスト・トラック・レンダリングをアップデートする規則によってリストと関連付けられます。WebVTT なら、WebVTT テキスト・トラックの表示をアップデートする規則です。

track 要素の親要素が変わり、新たな親がメディア要素なら、ユーザーエージェントは、そのメディア要素テキスト・トラック・リストに、track 要素に相当するテキスト・トラックを追加しなければいけません。

track 要素の親要素が変わり、古い親がメディア要素だったなら、ユーザーエージェントは、そのメディア要素テキスト・トラック・リストから、track 要素に相当するテキスト・トラックを削除しなければいけません。

track 要素に相当するテキスト・トラックメディア要素テキスト・トラック・リストに追加されるとき、ユーザーエージェントはテキスト・トラック・モードを適切にセットしなければいけません。次の条件によって決定します:

テキスト・トラック種別subtitlescaptions で、かつ、ユーザーが、テキスト・トラック種別テキスト・トラック言語テキスト・トラック・ラベルを使ってトラックを有効にすることに興味を示し、かつ、メディア要素テキスト・トラック・リストに、テキスト・トラック・モードshowing で、テキスト・トラック種別subtitlescaptionsテキスト・トラックが他に無い場合
テキスト・トラック種別descriptions で、かつ、ユーザーが、テキスト・トラック言語テキスト・トラック・ラベルを使ってテキスト記述を有効にすることに興味を示し、かつ、メディア要素テキスト・トラック・リストに、テキスト・トラック・モードshowing で、テキスト・トラック種別descriptionsテキスト・トラックが他に無い場合
テキスト・トラック種別chapters で、かつ、テキスト・トラック言語は、ユーザーエージェントがユーザーにとって適切だと信じるに値する理由を持てる言語であり、かつ、メディア要素テキスト・トラック・リストに、テキスト・トラック・モードshowing で、テキスト・トラック種別chaptersテキスト・トラックが他に無い場合

テキスト・トラック・モードshowing とします。

メディア要素テキスト・トラック・リストに、テキスト・トラック・モードshowing by default となるテキスト・トラックがあれば、ユーザーエージェントは、さらに、そのテキスト・トラックテキスト・トラック・モードhidden に変更しなければいけません。

track 要素に default 属性が指定され、メディア要素テキスト・トラック・リストに、テキスト・トラック・モードshowingshowing by default となるテキスト・トラックが他にない場合

テキスト・トラック・モードshowing by default とします。

該当しない場合

テキスト・トラック・モードdisabled とします。

track 要素に相当するテキスト・トラックが、テキスト・トラック・モードhidden, showing, showing by default のいずれかがセットされて生成されるとき、そして、track 要素に相当するテキスト・トラックが、テキスト・トラック・モードdisabled がセットされて生成され、続いて、そのテキスト・トラック・モードhidden, showing, showing by default のいずれかに初めて変更されるとき、ユーザーエージェントは、すぐに同期で次のアルゴリズムを実行しなければいけません。このアルゴリズムは、イベント・ループ・メカニズムに密接に作用します。とりわけ、同期セクションイベント・ループ・メカニズ・アルゴリズムの一環で呼び出されます)がある点です。そのセクションの手順には ⌛ がマーキングされています。

  1. テキスト・トラック読取状態loading にセットします。

  2. URL を、track 要素のトラック URL とします。

  3. 非同期に残りの手順を実行しながら、テキスト・トラックの生成やテキスト・トラック・モードの変更のタスクが生じたら、それらを実行します。

  4. Download: URL が空文字列ではなく、かつ、そのオリジンが、メディア要素Documentオリジンと同じなのであれば、そのメディア要素Documentオリジンから、force same-origin flag をセットして、URLフェッチします。

    フェッチしているデータを処理するために、ネットワーキング・タスク・ソースにおけるフェッチ・アルゴリズムによってキューイングされたタスクは、それを入手できたら、そのリソースの Content Type メタデータを調べなければいけません。Content Type メタデータが入手できなかった、または、そのタイプがテキスト・トラック形式として認識できなかったら、そのリソースの形式は未サポートと見なさなければいけません(後述の通り、これによってロードは失敗になります)。タイプが入手でき、それがサポートしているテキスト・トラック形式を表していれば、そのリソースのデータは、受信時に、そのパーサーの出力に使われているテキスト・トラック・キュー・リストとともに、適切なパーサーに引き渡されなければいけません。

    フェッチ・アルゴリズムが何かしらの理由(ネットワーク・エラー、サーバーがエラー・コードを返した、クロス・オリジン・チェックが失敗した、など)で失敗した、または、URL が空文字列、または、この手順の始めで、条件によって決定されたのとは異なるオリジンを持つ、または、フェッチされたリソースがサポート対象の形式ではないなら、まずは、テキスト・トラック読取状態failed to load に変更するタスクをキューイングします。それから、track 要素で error という名前のシンプルなイベントを発出します。そして、このタスクキューイングされたら、後述の monitoring と書かれた手順へ移動します。

    フェッチ・アルゴリズムが失敗しなければ、それが完了するときに、まずは、テキスト・トラック読取状態を loadied に変更するタスクをキューイングします。それから、track 要素で load という名前のシンプルなイベントを発出します。そして、このタスクキューイングされたら、後述の monitoring と書かれた手順へ移動します。

    フェッチ・アルゴリズムがアクティブとなっている間に、次のいずれかならば:

    ... ユーザーエージェントは次の手順を実行しなければいけません:

    1. フェッチ・アルゴリズムを中止します。

    2. track 要素で abort という名前のシンプルなイベントを発出するタスクをキューイングします。

    3. URL を新たなトラック URL とします。

    4. download と書かれた手順の最初へ戻ります。

    上記の状態の一つが発生するまで、ユーザーエージェントは、この手順でとどまっていなければいけません。

  5. Monitoring: トラック URLURL と同じでなくなるまで待機します。その時点で、テキスト・トラック・モードhidden, showing, showing by default にセットされます。

  6. テキスト・トラック読取状態loading にセットされないようになるまで待機します。

  7. 安定状態を待ちます同期セクションは次の手順から構成されます。(同期セクションのこの手順は ⌛ でマーキングされています。)

  8. テキスト・トラック読取状態loading にセットします。

  9. 同期セクションを終了し、残りの手順を非同期に継続します。

  10. download と書かれた手順へ飛びます。

4.8.10.12.4 テキスト・トラック API
media . textTracks . length

メディア要素に関連付けられたテキスト・トラックtrack 要素など)の数を返します。これは、メディア要素テキスト・トラック・リストにあるテキスト・トラックの数です。

media . textTracks[ n ]

メディア要素テキスト・トラック・リストにある n 番目のテキスト・トラックを表す TextTrack オブジェクトを返します。

track . track

track 要素のテキスト・トラックを表す TextTrack オブジェクトを返します。

メディア要素textTracks 属性は、TextTrack タイプのオブジェクト用の配列ホスト・オブジェクトを返さなければいけません。これは固定長読み取り専用です。この属性がアクセスされる都度、同じオブジェクトが返されなければいけません。 [WEBIDL]

この配列は、メディア要素テキスト・トラック・リストにあるテキスト・トラックTextTrack オブジェクトを、テキスト・トラック・リストと同じ順番で、含まなければいけません。


interface TextTrack {
  readonly attribute DOMString kind;
  readonly attribute DOMString label;
  readonly attribute DOMString language;

  const unsigned short NONE = 0;
  const unsigned short LOADING = 1;
  const unsigned short LOADED = 2;
  const unsigned short ERROR = 3;
  readonly attribute unsigned short readyState;
           attribute Function onload;
           attribute Function onerror;

  const unsigned short OFF = 0;
  const unsigned short HIDDEN = 1;
  const unsigned short SHOWING = 2;
           attribute unsigned short mode;

  readonly attribute TextTrackCueList cues;
  readonly attribute TextTrackCueList activeCues;

           attribute Function oncuechange;
};
TextTrack implements EventTarget;
textTrack . kind

テキスト・トラック種別の文字列を返します。

textTrack . label

テキスト・トラック・ラベルを返します。

textTrack . language

テキスト・トラック言語の文字列を返します。

textTrack . readyState

テキスト・トラック読取状態を返します。これは次のリストの数字で表されます:

TextTrack . NONE (0)

テキスト・トラック not loaded 状態。

TextTrack . LOADING (1)

テキスト・トラック loading 状態。

TextTrack . LOADED (2)

テキスト・トラック loaded 状態。

TextTrack . ERROR (3)

テキスト・トラック failed to load 状態。

textTrack . mode

テキスト・トラック・モードを返します。これは次のリストの数字で表されます:

TextTrack . OFF (0)

テキスト・トラック disabled モード。

TextTrack . HIDDEN (1)

テキスト・トラック hidden モード。

TextTrack . SHOWING (2)

テキスト・トラック showing および showing by default モード。

値をセットしてモードを変更することができます。

textTrack . cues

テキスト・トラック・キュー・リストTextTrackCueList オブジェクトとして返します。

textTrack . activeCues

現在アクティブ(つまり、現在再生位置より前に始まり、それより後に終わる)のテキスト・トラック・キュー・リストテキスト・トラック・キューを、TextTrackCueList オブジェクトとして返します。

The kind attribute must return the text track kind of the text track that the TextTrack object represents.

The label attribute must return the text track label of the text track that the TextTrack object represents.

The language attribute must return the text track language of the text track that the TextTrack object represents.

The readyState attribute must return the numeric value corresponding to the text track readiness state of the text track that the TextTrack object represents, as defined by the following list:

NONE (numeric value 0)
The text track not loaded state.
LOADING (numeric value 1)
The text track loading state.
LOADED (numeric value 2)
The text track loaded state.
ERROR (numeric value 3)
The text track failed to load state.

The mode attribute, on getting, must return the numeric value corresponding to the text track mode of the text track that the TextTrack object represents, as defined by the following list:

OFF (numeric value 0)
The text track disabled mode.
HIDDEN (numeric value 1)
The text track hidden mode.
SHOWING (numeric value 2)
The text track showing and showing by default modes.

On setting, if the new value is not either 0, 1, or 2, the user agent must throw an INVALID_ACCESS_ERR exception. Otherwise, if the new value isn't equal to what the attribute would currently return, the new value must be processed as follows:

If the new value is 0

Set the text track mode of the text track that the TextTrack object represents to the text track disabled mode.

If the new value is 1

Set the text track mode of the text track that the TextTrack object represents to the text track hidden mode.

If the new value is 2

Set the text track mode of the text track that the TextTrack object represents to the text track showing mode.

If the mode had been showing by default, this will change it to showing, even though the value of mode would appear not to change.

If the text track mode of the text track that the TextTrack object represents is not the text track disabled mode, then the cues attribute must return a live TextTrackCueList object that represents the subset of the text track list of cues of the text track that the TextTrack object represents whose start times occur before the earliest possible position when the script started, in text track cue order. Otherwise, it must return null. When an object is returned, the same object must be returned each time.

The earliest possible position when the script started is whatever the earliest possible position was the last time the event loop reached step 1.

If the text track mode of the text track that the TextTrack object represents is not the text track disabled mode, then the activeCues attribute must return a live TextTrackCueList object that represents the subset of the text track list of cues of the text track that the TextTrack object represents whose active flag was set when the script started, in text track cue order. Otherwise, it must return null. When an object is returned, the same object must be returned each time.

A text track cue's active flag was set when the script started if its text track cue active flag was set the last time the event loop reached step 1.


interface MutableTextTrack : TextTrack {
 void addCue(in TextTrackCue cue);
 void removeCue(in TextTrackCue cue);
};
mutableTextTrack = media . addTextTrack( kind [, label [, language ] ] )

Creates and returns a new MutableTextTrack object, which is also added to the media element's list of text tracks.

mutableTextTrack . addCue( cue )

Adds the given cue to mutableTextTrack's text track list of cues.

Raises an exception if the argument is null, associated with another text track, or already in the list of cues.

mutableTextTrack . removeCue( cue )

Removes the given cue from mutableTextTrack's text track list of cues.

Raises an exception if the argument is null, associated with another text track, or not in the list of cues.

The addTextTrack(kind, label, language) method of media elements, when invoked, must run the following steps:

  1. If kind is not one of the following strings, then throw a SYNTAX_ERR exception and abort these steps:

  2. If the label argument was omitted, let label be the empty string.

  3. If the language argument was omitted, let language be the empty string.

  4. Create a new text track, and set its text track kind to kind, its text track label to label, its text track language to language, its text track readiness state to the text track loaded state, its text track mode to the text track hidden mode, and its text track list of cues to an empty list.

  5. Add the new text track to the media element's list of text tracks.

The addCue(cue) method of MutableTextTrack objects, when invoked, must run the following steps:

  1. If cue is null, then throw an INVALID_ACCESS_ERR exception and abort these steps.

  2. If the given cue is already associated with a text track other than the method's MutableTextTrack object's text track, then throw an INVALID_STATE_ERR exception and abort these steps.

  3. Associate cue with the method's MutableTextTrack object's text track, if it is not currently associated with a text track.

  4. If the given cue is already listed in the method's MutableTextTrack object's text track's text track list of cues, then throw an INVALID_STATE_ERR exception.

  5. Add cue to the method's MutableTextTrack object's text track's text track list of cues.

The removeCue(cue) method of MutableTextTrack objects, when invoked, must run the following steps:

  1. If cue is null, then throw an INVALID_ACCESS_ERR exception and abort these steps.

  2. If the given cue is not associated with the method's MutableTextTrack object's text track, then throw an INVALID_STATE_ERR exception.

  3. If the given cue is not currently listed in the method's MutableTextTrack object's text track's text track list of cues, then throw a NOT_FOUND_ERR exception.

  4. Remove cue from the method's MutableTextTrack object's text track's text track list of cues.

In this example, an audio element is used to play a specific sound-effect from a sound file containing many sound effects. A cue is used to pause the audio, so that it ends exactly at the end of the clip, even if the browser is busy running some script. If the page had relied on script to pause the audio, then the start of the next clip might be heard if the browser was not able to run the script at the exact time specified.

var sfx = new Audio('sfx.wav');
var sounds = a.addTextTrack('metadata');

// add sounds we care about
sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
sounds.addCue(new TextTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));

function playSound(id) {
  sfx.currentTime = sounds.getCueById(id).startTime;
  sfx.play();
}

sfx.oncanplaythrough = function () {
  playSound('dog bark');
}
window.onbeforeunload = function () {
  playSound('kitten mew');
  return 'Are you sure you want to leave this awesome page?';
}

interface TextTrackCueList {
  readonly attribute unsigned long length;
  getter TextTrackCue (in unsigned long index);
  TextTrackCue getCueById(in DOMString id);
};
cuelist . length

Returns the number of cues in the list.

cuelist[index]

Returns the text track cue with index index in the list. The cues are sorted in text track cue order.

cuelist . getCueById( id )

Returns the first text track cue (in text track cue order) with text track cue identifier id.

Returns null if none of the cues have the given identifier or if the argument is the empty string.

A TextTrackCueList object represents a dynamically updating list of text track cues in a given order.

The length attribute must return the number of cues in the list represented by the TextTrackCueList object.

The supported property indicies of a TextTrackCueList object at any instant are the numbers from zero to the number of cues in the list represented by the TextTrackCueList object minus one, if any. If there are no cues in the list, there are no supported property indicies.

To determine the value of an indexed property for a given index index, the user agent must return the indexth text track cue in the list represented by the TextTrackCueList object.

The getCueById(id) method, when called with an argument other than the empty string, must return the first text track cue in the list represented by the TextTrackCueList object whose text track cue identifier is id, if any, or null otherwise. If the argument is the empty string, then the method must return null.


interface TextTrackCue {
  readonly attribute TextTrack track;
  readonly attribute DOMString id;

  readonly attribute double startTime;
  readonly attribute double endTime;
  readonly attribute boolean pauseOnExit;


  DOMString getCueAsSource();
  DocumentFragment getCueAsHTML();

           attribute Function onenter;
           attribute Function onexit;
};
TextTrackCue implements EventTarget;
cue . track

Returns the TextTrack object to which this text track cue belongs, if any, or null otherwise.

cue . id

Returns the text track cue identifier.

cue . startTime

Returns the text track cue start time, in seconds.

cue . endTime

Returns the text track cue end time, in seconds.

cue . pauseOnExit

Returns true if the text track cue pause-on-exit flag is set, false otherwise.

source = cue . getCueAsSource()

Returns the text track cue text in raw unparsed form.

fragment = cue . getCueAsHTML()

Returns the text track cue text as a DocumentFragment of HTML elements and other DOM nodes.

The track attribute must return the TextTrack object of the text track with which the text track cue that the TextTrackCue object represents is associated, if any; or null otherwise.

The id attribute must return the text track cue identifier of the text track cue that the TextTrackCue object represents.

The startTime attribute must return the text track cue start time of the text track cue that the TextTrackCue object represents, in seconds.

The endTime attribute must return the text track cue end time of the text track cue that the TextTrackCue object represents, in seconds.

The pauseOnExit attribute must return true if the text track cue pause-on-exit flag of the text track cue that the TextTrackCue object represents is set; or false otherwise.

The direction attribute must return the text track cue writing direction of the text track cue that the TextTrackCue object represents.

The getCueAsSource() method must return the raw text track cue text.

The getCueAsHTML() method must convert the text track cue text to a DocumentFragment for the media element's Document, using the appropriate rules for doing so.

4.8.10.12.5 Event definitions

The following are the event handlers that must be supported, as IDL attributes, by all objects implementing the TextTrack interface:

Event handler Event handler event type
onload load
onerror error
oncuechange cuechange

The following are the event handlers that must be supported, as IDL attributes, by all objects implementing the TextTrackCue interface:

Event handler Event handler event type
onenter enter
onexit exit
4.8.10.13 User interface

The controls attribute is a boolean attribute. If present, it indicates that the author has not provided a scripted controller and would like the user agent to provide its own set of controls.

If the attribute is present, or if scripting is disabled for the media element, then the user agent should expose a user interface to the user. This user interface should include features to begin playback, pause playback, seek to an arbitrary position in the content (if the content supports arbitrary seeking), change the volume, change the display of closed captions or embedded sign-language tracks, select different audio tracks or turn on audio descriptions, and show the media content in manners more suitable to the user (e.g. full-screen video or in an independent resizable window). Other controls may also be made available.

If the media element has a current media controller, then the user agent should expose audio tracks from all the slaved media elements (although avoiding duplicates if the same media resource is being used several times). If a media resource's audio track exposed in this way has no known name, and it is the only audio track for a particular media element, the user agent should use the element's title attribute, if any, as the name (or as part of the name) of that track.

Even when the attribute is absent, however, user agents may provide controls to affect playback of the media resource (e.g. play, pause, seeking, and volume controls), but such features should not interfere with the page's normal rendering. For example, such features could be exposed in the media element's context menu.

Where possible (specifically, for starting, stopping, pausing, and unpausing playback, for seeking, for changing the rate of playback, for fast-forwarding or rewinding, for listing, enabling, and disabling text tracks, and for muting or changing the volume of the audio), user interface features exposed by the user agent must be implemented in terms of the DOM API described above, so that, e.g., all the same events fire.

When a media element has a current media controller, the user agent's user interface for pausing and unpausing playback, for seeking, for changing the rate of playback, for fast-forwarding or rewinding, and for muting or changing the volume of audio of the entire group must be implemented in terms of the MediaController API exposed on that current media controller.

The "play" function in the user agent's interface must set the playbackRate attribute to the value of the defaultPlaybackRate attribute before invoking the play() method. When a media element has a current media controller, the attributes and method with those names on that MediaController object must be used. Otherwise, the attributes and method with those names on the media element itself must be used.

Features such as fast-forward or rewind must be implemented by only changing the playbackRate attribute (and not the defaultPlaybackRate attribute). Again, when a media element has a current media controller, the attributes with those names on that MediaController object must be used; otherwise, the attributes with those names on the media element itself must be used.

When a media element has a current media controller, and all the slaved media elements of that MediaController are paused, the user agent should unpause all the slaved media elements when the user invokes a user agent interface control for beginning playback.

When a media element has a current media controller, seeking must be implemented in terms of the seek() method on that MediaController object. Otherwise, the user agent must directly seek to the requested position in the media element's media timeline.

When a media element has a current media controller, user agents may additionally provide the user with controls that directly manipulate an individual media element without affecting the MediaController, but such features are considered relatively advanced and unlikely to be useful to most users.

For the purposes of listing chapters in the media resource, only text tracks in the media element's list of text tracks showing or showing by default and whose text track kind is chapters should be used. Each cue in such a text track represents a chapter starting at the cue's start time. The name of the chapter is the text track cue text, interpreted literally.

The controls IDL attribute must reflect the content attribute of the same name.


media . volume [ = value ]

Returns the current playback volume, as a number in the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.

Can be set, to change the volume.

Throws an INDEX_SIZE_ERR if the new value is not in the range 0.0 .. 1.0.

media . muted [ = value ]

Returns true if audio is muted, overriding the volume attribute, and false if the volume attribute is being honored.

Can be set, to change whether the audio is muted or not.

The volume attribute must return the playback volume of any audio portions of the media element, in the range 0.0 (silent) to 1.0 (loudest). Initially, the volume must be 1.0, but user agents may remember the last set value across sessions, on a per-site basis or otherwise, so the volume may start at other values. On setting, if the new value is in the range 0.0 to 1.0 inclusive, the attribute must be set to the new value. If the new value is outside the range 0.0 to 1.0 inclusive, then, on setting, an INDEX_SIZE_ERR exception must be raised instead.

The muted attribute must return true if the audio channels are muted and false otherwise. Initially, the audio channels should not be muted (false), but user agents may remember the last set value across sessions, on a per-site basis or otherwise, so the muted state may start as muted (true). On setting, the attribute must be set to the new value.

Whenever either the muted or volume attributes are changed, the user agent must queue a task to fire a simple event named volumechange at the media element.

An element's effective media volume is determined as follows:

  1. If the element's muted attribute is true, the element's effective media volume is zero. Abort these steps.

  2. If the element has a current media controller and that MediaController object's media controller mute override is true, the element's effective media volume is zero. Abort these steps.

  3. Let volume be the value of the element's volume attribute.

  4. If the element has a current media controller, multiply volume by that MediaController object's media controller volume multiplier.

  5. The element's effective media volume is volume, interpreted relative to the range 0.0 to 1.0, with 0.0 being silent, and 1.0 being the loudest setting, values in between increasing in loudness. The range need not be linear. The loudest setting may be lower than the system's loudest possible setting; for example the user could have set a maximum volume.

The muted attribute on the video element controls the default state of the audio channel of the media resource, potentially overriding user preferences.

When a media element is created, if it has a muted attribute specified, the user agent must set the muted IDL attribute to true, overriding any user preference.

The defaultMuted IDL attribute must reflect the muted content attribute.

This attribute has no dynamic effect (it only controls the default state of the element).

This video (an advertisment) autoplays, but to avoid annoying users, it does so without sound, and allows the user to turn the sound on.

<video src="adverts.cgi?kind=video" controls autoplay loop muted></video>
4.8.10.14 Time ranges

Objects implementing the TimeRanges interface represent a list of ranges (periods) of time.

interface TimeRanges {
  readonly attribute unsigned long length;
  double start(in unsigned long index);
  double end(in unsigned long index);
};
media . length

Returns the number of ranges in the object.

time = media . start(index)

Returns the time for the start of the range with the given index.

Throws an INDEX_SIZE_ERR if the index is out of range.

time = media . end(index)

Returns the time for the end of the range with the given index.

Throws an INDEX_SIZE_ERR if the index is out of range.

The length IDL attribute must return the number of ranges represented by the object.

The start(index) method must return the position of the start of the indexth range represented by the object, in seconds measured from the start of the timeline that the object covers.

The end(index) method must return the position of the end of the indexth range represented by the object, in seconds measured from the start of the timeline that the object covers.

These methods must raise INDEX_SIZE_ERR exceptions if called with an index argument greater than or equal to the number of ranges represented by the object.

When a TimeRanges object is said to be a normalized TimeRanges object, the ranges it represents must obey the following criteria:

  • The start of a range must be greater than the end of all earlier ranges.
  • The start of a range must be less than the end of that same range.

In other words, the ranges in such an object are ordered, don't overlap, aren't empty, and don't touch (adjacent ranges are folded into one bigger range).

The timelines used by the objects returned by the buffered, seekable and played IDL attributes of media elements must be that element's media timeline.

4.8.10.15 Event summary

This section is non-normative.

The following events fire on media elements as part of the processing model described above:

Event name Interface Dispatched when... Preconditions
loadstart Event The user agent begins looking for media data, as part of the resource selection algorithm. networkState equals NETWORK_LOADING
progress Event The user agent is fetching media data. networkState equals NETWORK_LOADING
suspend Event The user agent is intentionally not currently fetching media data, but does not have the entire media resource downloaded. networkState equals NETWORK_IDLE
abort Event The user agent stops fetching the media data before it is completely downloaded, but not due to an error. error is an object with the code MEDIA_ERR_ABORTED. networkState equals either NETWORK_EMPTY or NETWORK_IDLE, depending on when the download was aborted.
error Event An error occurs while fetching the media data. error is an object with the code MEDIA_ERR_NETWORK or higher. networkState equals either NETWORK_EMPTY or NETWORK_IDLE, depending on when the download was aborted.
emptied Event A media element whose networkState was previously not in the NETWORK_EMPTY state has just switched to that state (either because of a fatal error during load that's about to be reported, or because the load() method was invoked while the resource selection algorithm was already running). networkState is NETWORK_EMPTY; all the IDL attributes are in their initial states.
stalled Event The user agent is trying to fetch media data, but data is unexpectedly not forthcoming. networkState is NETWORK_LOADING.
loadedmetadata Event The user agent has just determined the duration and dimensions of the media resource and the text tracks are ready. readyState is newly equal to HAVE_METADATA or greater for the first time.
loadeddata Event The user agent can render the media data at the current playback position for the first time. readyState newly increased to HAVE_CURRENT_DATA or greater for the first time.
canplay Event The user agent can resume playback of the media data, but estimates that if playback were to be started now, the media resource could not be rendered at the current playback rate up to its end without having to stop for further buffering of content. readyState newly increased to HAVE_FUTURE_DATA or greater.
canplaythrough Event The user agent estimates that if playback were to be started now, the media resource could be rendered at the current playback rate all the way to its end without having to stop for further buffering. readyState is newly equal to HAVE_ENOUGH_DATA.
playing Event Playback is ready to start after having been paused or delayed due to lack of media data. readyState is newly equal to or greater than HAVE_FUTURE_DATA and paused is false, or paused is newly false and readyState is equal to or greater than HAVE_FUTURE_DATA. Even if this event fires, the element might still not be potentially playing, e.g. if the element is blocked on its media controller (e.g. because the current media controller is paused, or another slaved media element is stalled somehow, or because the media resource has no data corresponding to the media controller position), or the element is paused for user interaction.
waiting Event Playback has stopped because the next frame is not available, but the user agent expects that frame to become available in due course. readyState is equal to or less than HAVE_CURRENT_DATA, and paused is false. Either seeking is true, or the current playback position is not contained in any of the ranges in buffered. It is possible for playback to stop for other reasons without paused being false, but those reasons do not fire this event (and when those situations resolve, a separate playing event is not fired either): e.g. the element is newly blocked on its media controller, or playback ended, or playback stopped due to errors, or the element has paused for user interaction.
seeking Event The seeking IDL attribute changed to true and the seek operation is taking long enough that the user agent has time to fire the event.
seeked Event The seeking IDL attribute changed to false.
ended Event Playback has stopped because the end of the media resource was reached. currentTime equals the end of the media resource; ended is true.
durationchange Event The duration attribute has just been updated.
timeupdate Event The current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously.
play Event The element is no longer paused. Fired after the play() method has returned, or when the autoplay attribute has caused playback to begin. paused is newly false.
pause Event The element has been paused. Fired after the pause() method has returned. paused is newly true.
ratechange Event Either the defaultPlaybackRate or the playbackRate attribute has just been updated.
volumechange Event Either the volume attribute or the muted attribute has changed. Fired after the relevant attribute's setter has returned.

The following events fire on MediaController objects:

Event name Interface Dispatched when...
emptied Event All the slaved media elements newly have readyState set to HAVE_NOTHING or greater, or there are no longer any slaved media elements.
loadedmetadata Event All the slaved media elements newly have readyState set to HAVE_METADATA or greater.
loadeddata Event All the slaved media elements newly have readyState set to HAVE_CURRENT_DATA or greater.
canplay Event All the slaved media elements newly have readyState set to HAVE_FUTURE_DATA or greater.
canplaythrough Event All the slaved media elements newly have readyState set to HAVE_ENOUGH_DATA or greater.
playing Event The MediaController is no longer a blocked media controller.
waiting Event The MediaController is now a blocked media controller.
ended Event All the slaved media elements have newly ended playback.
durationchange Event The duration attribute has just been updated.
timeupdate Event The media controller position changed.
play Event The paused attribute is newly false.
pause Event The paused attribute is newly true.
ratechange Event Either the defaultPlaybackRate attribute or the playbackRate attribute has just been updated.
volumechange Event Either the volume attribute or the muted attribute has just been updated.
4.8.10.16 Security and privacy considerations

The main security and privacy implications of the video and audio elements come from the ability to embed media cross-origin. There are two directions that threats can flow: from hostile content to a victim page, and from a hostile page to victim content.


If a victim page embeds hostile content, the threat is that the content might contain scripted code that attempts to interact with the Document that embeds the content. To avoid this, user agents must ensure that there is no access from the content to the embedding page. In the case of media content that uses DOM concepts, the embedded content must be treated as if it was in its own unrelated top-level browsing context.

For instance, if an SVG animation was embedded in a video element, the user agent would not give it access to the DOM of the outer page. From the perspective of scripts in the SVG resource, the SVG file would appear to be in a lone top-level browsing context with no parent.


If a hostile page embeds victim content, the threat is that the embedding page could obtain information from the content that it would not otherwise have access to. The API does expose some information: the existence of the media, its type, its duration, its size, and the performance characteristics of its host. Such information is already potentially problematic, but in practice the same information can more or less be obtained using the img element, and so it has been deemed acceptable.

However, significantly more sensitive information could be obtained if the user agent further exposes metadata within the content such as subtitles or chapter titles. This version of the API does not expose such information. Future extensions to this API will likely reuse a mechanism such as CORS to check that the embedded content's site has opted in to exposing such information. [CORS]

An attacker could trick a user running within a corporate network into visiting a site that attempts to load a video from a previously leaked location on the corporation's intranet. If such a video included confidential plans for a new product, then being able to read the subtitles would present a confidentiality breach.

4.8.10.17 Best practices for authors using media elements

This section is non-normative.

Playing audio and video resources on small devices such as set-top boxes or mobile phones is often constrained by limited hardware resources in the device. For example, a device might only support three simultaneous videos. For this reason, it is a good practice to release resources held by media elements when they are done playing, either by being very careful about removing all references to the element and allowing it to be garbage collected, or, even better, by removing the element's src attribute and any source element descendants, and invoking the element's load() method.

Similarly, when the playback rate is not exactly 1.0, hardware, software, or format limitations can cause video frames to be dropped and audio to be choppy or muted.

4.8.10.18 Best practices for implementors of media elements

This section is non-normative.

How accurately various aspects of the media element API are implemented is considered a quality-of-implementation issue.

For example, when implementing the buffered attribute, how precise an implementation reports the ranges that have been buffered depends on how carefully the user agent inspects the data. Since the API reports ranges as times, but the data is obtained in byte streams, a user agent receiving a variable-bit-rate stream might only be able to determine precise times by actually decoding all of the data. User agents aren't required to do this, however; they can instead return estimates (e.g. based on the average bit rate seen so far) which get revised as more information becomes available.

As a general rule, user agents are urged to be conservative rather than optimistic. For example, it would be bad to report that everything had been buffered when it had not.

Another quality-of-implementation issue would be playing a video backwards when the codec is designed only for forward playback (e.g. there aren't many key frames, and they are far apart, and the intervening frames only have deltas from the previous frame). User agents could do a poor job, e.g. only showing key frames; however, better implementations would do more work and thus do a better job, e.g. actually decoding parts of the video forwards, storing the complete frames, and then playing the frames backwards.

Similarly, while implementations are allowed to drop buffered data at any time (there is no requirement that a user agent keep all the media data obtained for the lifetime of the media element), it is again a quality of implementation issue: user agents with sufficient resources to keep all the data around are encouraged to do so, as this allows for a better user experience. For example, if the user is watching a live stream, a user agent could allow the user only to view the live video; however, a better user agent would buffer everything and allow the user to seek through the earlier material, pause it, play it forwards and backwards, etc.

When multiple tracks are synchronised with a MediaController, it is possible for scripts to add and remove media elements from the MediaController's list of slaved media elements, even while these tracks are playing. How smoothly the media plays back in such situations is another quality-of-implementation issue.


When a media element that is paused is removed from a document and not reinserted before the next time the event loop spins, implementations that are resource constrained are encouraged to take that opportunity to release all hardware resources (like video planes, networking resources, and data buffers) used by the media element. (User agents still have to keep track of the playback position and so forth, though, in case playback is later restarted.)


※ 原文:http://www.w3.org/TR/2011/WD-html5-20110525/the-iframe-element.html#media-elements