DOM 要素からのメディアキャプチャ

captureStream() メソッドは、 メディア要素にレンダリングされるメディアのリアルタイムキャプチャを生成します。

キャプチャされた MediaStream は、 メディア要素からの 選択された（VideoTrack、または その他の排他的に選択される トラック型の場合）または 有効化された （AudioTrack、または 複数選択をサポートするその他の トラック型の場合） トラックの集合からのコンテンツをレンダリングする MediaStreamTrack群で 構成されます。メディア要素に、指定された型の選択済みまたは有効化済み トラックがない場合、その型の MediaStreamTrack はキャプチャされたストリーム内に存在しません。

したがって、 video 要素は、動画 MediaStreamTrack と任意の数の音声 MediaStreamTrackを キャプチャできます。 audio 要素は、任意の数の音声 MediaStreamTrackを キャプチャできます。 いずれの場合も、キャプチャされた MediaStreamTrackの 集合は空である可能性があります。

指定された型の トラックが選択または有効化されているまでは、 その型の MediaStreamTrack はキャプチャされたストリーム内に存在しません。特に、メディア要素にソースが割り当てられていない場合、 キャプチャされた MediaStream にはトラックがありません。したがって、ready state が HAVE_NOTHING であるメディア要素は、キャプチャされた MediaStreamTrack インスタンスを生成しません。メタデータが利用可能になり、 選択済みまたは有効化済みの トラックが決定されると、 新しいキャプチャ済み MediaStreamTrack インスタンスが作成され、 MediaStreamに追加されます。

キャプチャされた MediaStreamTrack は、 終了します。これは、 再生が 終了したとき（かつ ended イベントが発火したとき）、またはそれがキャプチャするトラックが 再生のために選択または有効化されなくなったときです。メディア要素の src または srcObject 属性を設定してソースが変更された場合、トラックは選択または有効化されなくなります。

キャプチャされた MediaStreamTrackの 集合は、メディア要素のソースが変更されると変化します。メディア要素のソースが終了した場合、 別のソースが選択されます。

メディア要素の選択された VideoTrack または有効化された AudioTrackが 変更された場合、 以前は選択または有効化されていなかった各 トラックについて、新しい MediaStreamTrackを伴う addtrack イベントが生成されます。また、選択または有効化されなくなった各 トラックについて、 removetrack イベントが生成されます。 MediaStreamTrack は、 MediaStreamから 削除される前に終了しなければなりません。

MediaStreamTrack は 一度しか終了できないため、有効化され、無効化され、再び有効化されたトラックは、 2 つの別々のトラックとしてキャプチャされます。同様に、再生終了後に再生を再開すると、 新しいキャプチャ済み MediaStreamTrack インスタンスの集合が作成されます。再生中にシークしても、トラック選択が変更されない限り、 イベントは生成されず、キャプチャされた MediaStreamTrack は終了しません。

キャプチャされた MediaStreamを構成する MediaStreamTrackは、 それらがキャプチャするトラックの状態が変化するにつれて、ミュートまたはミュート解除されます。 いつでも、メディア要素はさまざまな理由により、指定されたトラック上でキャプチャ可能な アクティブコンテンツを持たない場合があります。

• メディア再生が一時停止されている可能性があります。
• トラックは、現在の再生時刻が そのトラックのコンテンツの開始前または終了後である場合、その再生時刻のコンテンツを持たない可能性があります。
• ソースとして機能している MediaStreamTrack が、 ミュート または 無効化されている可能性があります。
• トラックの内容は、クロスオリジン保護により、 現在のオリジンからアクセスできなくなる可能性があります。たとえば、HTTP URL からレンダリングされるコンテンツは、 部分コンテンツのリクエストでリダイレクトの対象となる場合があり、または有効化もしくは選択されたトラックが クロスオリジンコンテンツを含むように変更される場合があります。

コンテンツの不在は、キャプチャされたトラックでは muted 属性を通じて反映されます。キャプチャされた MediaStreamTrack は、 対応するソース トラックに利用可能かつアクセス可能なコンテンツがない場合、 muted 属性を true に設定しなければなりません。 コンテンツの利用可能性が変化すると、 mute イベントが MediaStreamTrack上で 発生します。

ミュートされたキャプチャが結果として生成する出力は、メディアの型によって異なります。 VideoTrack は、 ミュートされると新しいフレームのキャプチャを停止し、 キャプチャされたストリームには最後にキャプチャされたフレームが表示されます。ミュートされた AudioTrack は 無音を生成します。

メディア要素が実際にコンテンツをレンダリングしているかどうか（たとえば画面や音声デバイスへ）は、 キャプチャされたストリームの内容に影響しません。メディア要素の音声をミュートしても、 キャプチャが無音を生成することはなく、メディア要素を非表示にしても、 キャプチャされた動画が停止することはありません。同様に、メディア要素の音声レベルまたは音量は、 キャプチャされた音声の音量に影響しません。

有効な 再生レートが 1.0 以外の要素からキャプチャされた音声は、タイムストレッチされなければなりません。 再生不能な再生レートは、キャプチャされた音声トラックをミュート状態にします。

captureStream() メソッドは、 canvas の表面のリアルタイム動画キャプチャを生成します。結果として得られるメディアストリームは、 canvas 要素の寸法と一致する単一の動画 CanvasCaptureMediaStreamTrack を持ちます。

origin-clean でない canvas からのコンテンツはキャプチャしてはなりません。このメソッドは、 canvas が origin-clean でない場合、 SecurityError 例外を投げます。

キャプチャされたストリームは、 captureStream() によって 作成された後に、ソース canvas の origin-clean フラグが false になった場合、 直ちにコンテンツのキャプチャを停止しなければなりません。 キャプチャされた MediaStreamTrack は、canvas がこの状態にある間、新しいコンテンツを生成せず、 ミュート状態にならなければなりません。

canvas をキャプチャする各トラックには、 canvas から新しいフレームがリクエストされたときに true に設定される [[frameCaptureRequested]] 内部スロットがあります。

新しいすべてのトラックにおける [[frameCaptureRequested]] の値は、 トラックが作成されたときに true に設定されます。特定の非ゼロの frameRequestRate を伴ってキャプチャされたトラックが作成されると、 ユーザー エージェントは 1/frameRequestRate 秒の間隔で周期タイマーを開始します。タイマーが作動するたびに、 [[frameCaptureRequested]] は true に設定されます。

requestFrame() メソッドによるフレームキャプチャの手動制御をサポートするため、 ブラウザーは frameRequestRate に値 0 をサポートしなければなりません。 ただし、キャプチャされたストリームは、frameRequestRate がゼロであっても、 作成時にフレームのキャプチャをリクエストしなければなりません。

frameRequestRate が負の場合、このメソッドは NotSupportedError を投げます。

[[frameCaptureRequested]] が true であり、canvas が描画されたとき、canvas から新しいフレームがリクエストされます。 キャプチャされた canvas が描画されるたびに、次の手順が実行されます。

1. canvas からキャプチャしている各 track について、次の手順を実行します。
   1. canvas が最後に描画されてから新しいコンテンツが canvas に描画されており、 track の [[frameCaptureRequested]] 内部スロットが設定されている場合、 canvas に描画された内容を含む新しいフレームを track に追加します。
   2. frameRequestRate 値が指定されていた場合、 track の [[frameCaptureRequested]] 内部スロットを false に設定します。

canvas に描画された内容を含む新しいフレームを track に追加するとき、 canvas が完全に不透明でない場合は、canvas のアルファチャンネルの内容をキャプチャして保持しなければなりません。 この track の消費者は、アルファチャンネルを保持しない可能性があります。