メディアキャプチャとストリーム

MediaStream

MediaStream コンストラクターアルゴリズムを参照

パラメーターなし。

MediaStream

MediaStream コンストラクターアルゴリズムを参照

MediaStream

MediaStream コンストラクターアルゴリズムを参照

id（型: DOMString、 読み取り専用）

id 属性は、オブジェクト作成時に 初期化された値を返さなければなりません。

MediaStream が 作成されたとき、ユーザー エージェントは識別子文字列を生成しなければならず、また、 ストリーム ID をどのように初期化しなければならないかを規定する特殊用途のアルゴリズムの一部として オブジェクトが作成される場合を除き、オブジェクトの id 属性をその文字列で初期化しなければなりません。 良い慣行は UUID [rfc4122] を使用することであり、 その正規形式は 36 文字です。フィンガープリンティングを避けるため、 実装は UUID を生成するとき RFC 4122 のセクション 4.4 または 4.5 の形式を使用するべきです。

ストリーム ID をどのように初期化しなければならないかを規定するアルゴリズムの例として、 受信ネットワークコンポーネントを MediaStream オブジェクトに関連付けるアルゴリズムがあります。 [WEBRTC]

active（型: boolean、読み取り専用）

active 属性は、この MediaStream が アクティブである場合は true を、それ以外の場合は false を返さなければなりません。

onaddtrack（型: EventHandler）

このイベントハンドラーのイベント型は addtrack です。

onremovetrack（型: EventHandler）

このイベントハンドラーのイベント型は removetrack です。

getAudioTracks()

このストリーム内の音声トラックを表す MediaStreamTrack オブジェクトのシーケンスを返します。

getAudioTracks メソッドは、このストリームの トラック集合内にある MediaStreamTrack オブジェクトのうち、 [[Kind]] が "audio" に等しいものすべての スナップショットを表すシーケンスを返さなければなりません。 トラック集合からシーケンスへの変換は ユーザーエージェントによって定義され、 呼び出し間で順序が安定している必要はありません。

getVideoTracks()

このストリーム内の映像トラックを表す MediaStreamTrack オブジェクトのシーケンスを返します。

getVideoTracks メソッドは、このストリームの トラック集合内にある MediaStreamTrack オブジェクトのうち、 [[Kind]] が "video" に等しいものすべての スナップショットを表すシーケンスを返さなければなりません。 トラック集合からシーケンスへの変換は ユーザーエージェントによって定義され、 呼び出し間で順序が安定している必要はありません。

getTracks()

このストリーム内のすべてのトラックを表す MediaStreamTrack オブジェクトのシーケンスを返します。

getTracks メソッドは、 [[Kind]] に関係なく、 このストリームの トラック集合内のすべての MediaStreamTrack オブジェクトの スナップショットを表すシーケンスを返さなければなりません。 トラック集合からシーケンスへの 変換はユーザー エージェントによって定義され、呼び出し間で順序が安定している必要はありません。

getTrackById()

getTrackById メソッドは、このストリームの トラック集合から、 [[Id]] が trackId に等しい MediaStreamTrack オブジェクトを返すか、そのようなトラックが 存在しない場合は null を返さなければなりません。

addTrack()

指定された MediaStreamTrack を、この MediaStream に追加します。

addTrack メソッドが 呼び出されたとき、ユーザーエージェントは 次の手順を実行しなければなりません:

1. track をメソッドの引数とし、 stream をメソッドが呼び出された MediaStream オブジェクトとします。

2. track がすでに stream の トラック集合に存在する場合、この 手順を中止します。

3. track を stream の トラック集合に 追加します。

removeTrack()

指定された MediaStreamTrack オブジェクトを この MediaStream から削除します。

removeTrack メソッドが呼び出されたとき、ユーザーエージェントは 次の手順を実行しなければなりません:

1. track をメソッドの引数とし、 stream をメソッドが呼び出された MediaStream オブジェクトとします。

2. track が stream's の トラック集合に存在しない場合、この手順を中止します。

3. track を stream の トラック集合から 削除します。

clone()

指定された MediaStream と、 そのすべてのトラックをクローンします。

clone() メソッドが 呼び出されたとき、ユーザー エージェントは次の手順を実行しなければなりません:

1. streamClone を、新しく構築された MediaStream オブジェクトとします。

2. streamClone.MediaStream.id を、新しく 生成された値に初期化します。

3. この MediaStream オブジェクト内の 各トラックをクローンし、 その結果を streamClone の トラック 集合に追加します。

4. streamClone を返します。

addtrack または removetrack イベントを発火することを想定するユーザーエージェントコードは、 別のオブジェクトからの参照によって、対象となる MediaStream オブジェクトを存続させることが期待されます。 addtrack または removetrack のイベントリスナーが存在することは、 MediaStream オブジェクトをガベージコレクションしようとする際に 考慮する必要はありません。

constructor()

新しい MediaStreamTrackEvent を構築します。

track（型: MediaStreamTrack、読み取り専用）

track 属性は、このイベントに関連付けられた MediaStreamTrack オブジェクトを表します。

track（型: MediaStreamTrack、必須）

mediaDevices（型: MediaDevices、読み取り専用）

this の関連する グローバルオブジェクトの関連付けられた MediaDevicesを返します。

ondevicechange（型: EventHandler）

このイベントハンドラーのイベント型は devicechange です。

enumerateDevices

ユーザーエージェントが利用可能なメディア 入力および出力デバイスに関する情報を収集します。

このメソッドは promise を返します。列挙に成功した場合、 promise は、 ユーザーエージェントが利用可能なメディア入力および出力 デバイスを表す MediaDeviceInfo オブジェクトの シーケンスで履行されます。

このシーケンス内で入力デバイスを表す要素は、 MediaDeviceInfo を拡張する InputDeviceInfo 型になります。

カメラおよびマイクのソースは列挙可能であるべきです。 追加のソース型を追加する仕様では、そのソース型を 列挙可能にするべきかどうかについて推奨事項を提供します。

enumerateDevices() メソッドが呼び出されたとき、ユーザーエージェントは 次の手順を実行しなければなりません:

1. p を新しい promise とします。

2. proceed を、this を指定した デバイス 列挙を続行できるの結果とします。

3. mediaDevices を this とします。

4. 次の手順を並列に実行します:

   1. proceed が false の間、 ユーザーエージェントは、 mediaDevices を指定した デバイス列挙を 続行できるの結果を proceed に設定するため キューに入れられたタスクが、proceed を true に 設定することになるまで、次の手順への進行を待たなければなりません。

   2. resultList を、 mediaDevices および mediaDevices.[[storedDeviceList]] を指定して デバイス情報オブジェクトの リストを作成した結果とします。

   3. p を resultList で 解決します。

5. p を返します。

mediaDevices および deviceList を指定して デバイス情報オブジェクトのリストを作成するには、 次の手順を実行します:

1. resultList を空のリストとします。

2. microphoneList、cameraList、および otherDeviceList を空のリストとします。

3. document を、mediaDevices の 関連する グローバルオブジェクトの関連付けられた Document とします。

4. deviceList 内で検出された各デバイス device について、 次のサブ手順を実行します:

   1. device がマイクでない場合、または document が "microphone" で識別される機能を使用することを 許可されていない場合、 これらのサブ手順を中止し、次のデバイス（存在する場合）に進みます。

   2. deviceInfo を、 mediaDevices を指定して device を表す デバイス情報 オブジェクトを作成した結果とします。

   3. device がシステムデフォルトのマイクである場合、 deviceInfo を microphoneList の先頭に追加します。 それ以外の場合、deviceInfo を microphoneList の末尾に追加します。

5. deviceList 内で検出された各デバイス device について、 次のサブ手順を実行します:

   1. device がカメラでない場合、または document が "camera" で識別される機能を使用することを 許可されていない場合、 これらのサブ手順を中止し、次のデバイス（存在する場合）に進みます。

   2. deviceInfo を、 mediaDevices を指定して device を表す デバイス情報 オブジェクトを作成した結果とします。

   3. device がシステムデフォルトのカメラである場合、 deviceInfo を cameraList の先頭に追加します。 それ以外の場合、deviceInfo を cameraList の末尾に追加します。

6. mediaDevices において マイク情報を 公開できるが false の場合、 microphoneList を最初の項目までに切り詰めます。

7. mediaDevices において カメラ 情報を公開できるが false の場合、 cameraList を最初の項目までに切り詰めます。

8. deviceList 内で検出された各デバイス device について、 次のサブ手順を実行します:

   1. device がマイクまたはカメラである場合、 これらのサブ手順を中止し、次のデバイス（存在する場合）に進みます。

   2. device、microphoneList、cameraList、 および mediaDevices を入力として、 カメラおよびマイク以外のデバイスに対する公開 決定アルゴリズムを実行します。 このアルゴリズムの結果が false の場合、 これらのサブ手順を中止し、次のデバイス（存在する場合）に進みます。

   3. deviceInfo を、 mediaDevices を指定して device を表す デバイス情報 オブジェクトを作成した結果とします。

   4. deviceInfo を otherDeviceList の末尾に追加します。

   5. device がシステムデフォルトの音声出力である場合、 次のサブ手順を実行します:

      1. defaultAudioOutputInfo を、 mediaDevices を指定して device を表す デバイス情報 オブジェクトを作成した結果とします。

      2. defaultAudioOutputInfo の deviceId を "default" に設定します。

      3. ユーザーエージェントは、 これがシステムデフォルトの音声出力であることを明示するように defaultAudioOutputInfo の label を更新するべきです。

      4. defaultAudioOutputInfo を otherDeviceList の先頭に追加します。

9. microphoneList のすべてのデバイスを順番に resultList の末尾に追加します。

10. cameraList のすべてのデバイスを順番に resultList の末尾に追加します。

11. otherDeviceList のすべてのデバイスを順番に resultList の末尾に追加します。

12. resultList を返します。

このメソッドは、メディアキャプチャデバイスの 利用可能性を通じて、ブラウジングセッションおよびオリジンをまたいで永続的な 情報を返すため、 ユーザー エージェントが公開するフィンガープリンティング面を増加させます。

関連する グローバルオブジェクトの 関連付けられた Document がキャプチャを行っていない限り、このメソッドは 公開する情報を、カメラが存在するかどうか、およびマイクが存在するかどうかという 2 ビットの情報に制限します。ユーザー エージェントは、たとえば 関連する グローバルオブジェクトの関連付けられた Document が、妥当と判断された制約を指定して getUserMedia() を呼び出すまで、システムにカメラとマイクがあるように装うことで、 これを緩和できます。

関連する グローバルオブジェクトの関連付けられた Document が キャプチャを開始した後は、すべてのメディアキャプチャデバイスのリストを通じて、 そのグループ化やキャプチャデバイスに関連付けられた人間が読めるラベルを含む、 オリジンをまたぐ追加の永続的 情報を提供するため、フィンガープリンティング面がさらに増加します。

ユーザーエージェントは、デバイスラベルをサニタイズすることで 公開を制限できます。たとえば、ラベル内に含まれるユーザー名を削除し、 デバイスの製造元またはモデル情報を残すことが考えられます。 サニタイズされたラベルによって、ユーザーが対応するデバイスを識別できることが 重要です。

deviceId （型: DOMString、 読み取り専用）

表されているデバイスの識別子です。デバイスは、その識別子と kind によって 一意に識別されなければなりません。

保存された識別子が認識されるようにするため、識別子は トップレベル トラバーサブル内の同一 オリジンの Document間で 同一でなければなりません。 子 ナビゲータブルでは、 文書間で識別子を同一にするかどうかの判断は、 クロスサイト相関に対する緩和策を妨げないよう、 localStorage などのストレージに対するユーザー エージェントのパーティショニング規則が存在する場合、 それに従わなければなりません。 識別子によってユーザーを一意に識別できる場合、 異なるオリジン間で同一ユーザーを 相関させるために識別子が使用されることを防ぐため、 他のオリジンの文書から推測不可能でなければなりません。 識別子がユーザーに結び付けられておらず、 User-Agent 文字列のような他の手段で推測できる限り、 オリジン間で再利用できます。

このオリジンのページで、いずれかのローカルデバイスが live な MediaStreamTrack に接続された場合、 またはローカル デバイスへのアクセスに対する保存された許可が このオリジンに付与されている場合、この識別子は、以下で詳述する場合を除いて 永続化されなければなりません。一意で安定した 識別子により、アプリケーションは複数回の訪問にわたって、 特定のソースを保存し、その利用可能性を識別し、 直接要求できます。

ただし、このオリジンのページでローカルデバイスが live MediaStreamTrack に接続されたことがなく、かつローカル デバイスへのアクセスに対する保存された許可もこのオリジンに付与されていない限り、 ユーザー エージェントは、このオリジンからの最後のブラウジングセッションが 閉じられた時点で、この識別子を消去してもかまいません。 ユーザー エージェントがこの条件で識別子を消去しないことを選択した場合、 Cookie と同様に、ユーザーがその識別子を目視で確認し削除できる手段を 提供しなければなりません。

deviceId は ブラウジングセッションをまたいで永続化される可能性があり、 フィンガープリンティング機構としての可能性を低減するため、 deviceId は、 Cookie [COOKIES] などの他の永続的ストレージ機構と同様に 扱われます。すなわち、ユーザーエージェントは、 Cookie の使用をブロックされているサイトについてデバイス 識別子を永続化してはならず、 ユーザーエージェントは、 他の永続的ストレージが消去されたとき、オリジンごとのデバイス識別子を ローテーションしなければなりません。

kind（型: MediaDeviceKind、 読み取り専用）

表されているデバイスの種別です。

label（型: DOMString、 読み取り専用）

このデバイスを説明するラベル（たとえば「External USB Webcam」）です。このラベルは、エンドユーザーがデバイス間の 違いを識別できるようにすることを意図しています。アプリケーションは、 ラベルにデバイスの種類やモデルなどの特定の情報が含まれると 仮定できません。 デバイスに関連付けられたラベルがない場合、この 属性は空文字列を返さなければなりません。

groupId （型: DOMString、 読み取り専用）

表されているデバイスのグループ識別子です。2 つのデバイスが 同じ物理デバイスに属する場合、それらは同じグループ識別子を 持ちます。たとえば、同じヘッドセットのスピーカーとマイクを表す 音声入力および出力デバイスは、同じ groupId を持ちます。

グループ識別子は、各 文書について一意に生成されなければなりません。

toJSON

呼び出されたとき、[WEBIDL] のデフォルトの toJSON 手順を実行します。

getCapabilities

ユーザーが指定した制約がない場合に、デバイスの MediaStream の 主要な音声または映像トラック（その kind 値に従う）を記述する MediaTrackCapabilities オブジェクトを返します。 これらの能力は、この MediaDeviceInfo の deviceId 属性の値を id として、 getUserMedia({deviceId: id}) によって返された MediaStream 内の、この型の最初の MediaStreamTrack に対して getCapabilities() を呼び出して得られる能力と同一でなければなりません。

どのローカルデバイスへのアクセスも許可されておらず、この InputDeviceInfo が 一意に識別できる情報に関してフィルタリングされている場合（上記の enumerateDevices() の結果の説明を参照）、このメソッドは 空の辞書を返します。

constructor()

this.devices を、 eventInitDict.devices から 凍結配列を作成した 結果に初期化します。

devices（型: FrozenArray<MediaDeviceInfo>、 読み取り専用）

devices 属性は、 現時点で利用可能なデバイスのリストを表す MediaDeviceInfo オブジェクトの配列を返します。

userInsertedDevices（型: FrozenArray<MediaDeviceInfo>、 読み取り専用）

userInsertedDevices 属性は、devices 内の MediaDeviceInfo オブジェクトのうち、 ユーザーが最近物理的に挿入または有効化し、その結果このイベントで 新たに公開されたものだけを含む配列を返します。 それ以外の場合は、空のリストを返します。

ユーザーエージェントは、 getUserMedia() が呼び出される前にユーザーが挿入または有効化したデバイスも、 このイベントがそれらの初回公開を示し、かつ ユーザーが getUserMedia() 内でデバイスを選択していない場合に限り、 含めてもかまいません。

MediaDeviceInfo オブジェクトが存在する場合、 それらは devices にも 存在しなければなりません。

注記

ユーザーが通話中（または通話直前）にデバイスを挿入することは、 そのデバイスをすぐに使用したいという 強いシグナルになり得ます。

アプリケーションには、この属性を利用して、 このシグナルを、デバイス情報の公開の変更によって生じ得る devices の差異と区別することが推奨されます。

注記

この属性が存在しない場合、この UA はまだこのバージョンの仕様を 実装するようアップグレードされていないことを意味します。

devices（型: sequence<MediaDeviceInfo>、 デフォルト値: []）

devices メンバーは、 利用可能なデバイスを表す MediaDeviceInfo オブジェクトの 配列です。

getSupportedConstraints

ユーザーエージェントが認識する 制約可能なプロパティをメンバーとして持つ辞書を返します。サポートされる 制約可能なプロパティは表現されなければならず、 ユーザーエージェントが サポートしない制約可能なプロパティは、返される 辞書に存在してはなりません。返される値は ユーザー エージェントが実装するものを表し、ブラウジングセッション中に変更されません。

getUserMedia

Web カメラまたはその他の 映像もしくは音声入力を使用する許可をユーザーに求めます。

constraints 引数は、 MediaStreamConstraints 型の辞書です。

このメソッドは promise を返します。以下で説明するように ユーザーが有効なトラックを受け入れた場合、promise は適切な MediaStream オブジェクトで 履行されます。

有効なトラックの検索に失敗した場合、または 以下で説明するようにユーザーが許可を拒否した場合、promise は 拒否されます。

getUserMedia() メソッドが 呼び出されたとき、ユーザーエージェントは 次の手順を実行しなければなりません:

1. constraints をメソッドの最初の 引数とします。

2. requestedMediaTypes を、constraints 内で 辞書値または true の値を持つメディア 型の集合とします。

3. requestedMediaTypes が空集合の場合、 TypeError で拒否された promise を返します。 WebIDL の規則により WebIDL には "optional" という 語がありますが、呼び出しを成功させるには引数を 指定しなければなりません。

4. document を、関連する グローバルオブジェクトの 関連付けられた Document とします。

5. document が 完全に アクティブでない場合、 name 属性の値が「InvalidStateError」 である DOMException オブジェクトで 拒否された promise を返します。

6. requestedMediaTypes に "audio" が含まれ、 document が "microphone" 許可名で識別される 機能を使用することを 許可されていない場合、 下の 許可失敗 とラベル付けされた手順にジャンプします。

7. requestedMediaTypes に "video" が含まれ、 document が "camera" 許可名で識別される 機能を使用することを 許可されていない場合、 下の 許可失敗 とラベル付けされた手順にジャンプします。

8. mediaDevices を this とします。

9. isInView を 表示中であるアルゴリズムの結果とします。

10. p を新しい promise とします。

11. 次の手順を並列に実行します:

    1. isInView が false の間、 ユーザーエージェントは、 表示中である アルゴリズムの結果を isInView に設定するため キューに入れられたタスクが、 isInView を true に設定することになるまで、 次の手順への進行を待たなければなりません。

    2. finalSet を（初期状態では）空の 集合とします。

    3. requestedMediaTypes 内の各メディア型 kind について、次の手順を実行します:

       1. kind 型のメディアの、考えられる各ソースデバイスの 考えられる各構成について、ソースデバイスを保持し、 その固有の設定で構成された 設定 辞書を持つ、最終的な MediaStreamTrack のプレースホルダーとして 候補を想定します。

          この候補集合を candidateSet と呼びます。

          candidateSet が空集合の場合、 下の NotFound 失敗 とラベル付けされた手順にジャンプします。

       2. constraints の kind エントリの値が true の場合、CS を 空の制約集合（制約なし）に設定します。それ以外の場合、 CS を constraints の kind エントリの値に設定したまま続行します。
       3. CS 内の制約可能なプロパティのうち、 kind 型の MediaStreamTrack オブジェクトについて定義されていないものをすべて削除します。 これは、"video" 内の音声専用制約と、 "audio" 内の映像専用制約は、 OverconstrainedError を発生させるのではなく、 単に無視されることを意味します。

       4. CS に、 必須 制約であり、その名前が デバイス選択で許可される 必須制約の一覧にないメンバーが含まれる場合、 p を TypeError で拒否し、 この手順を中止します。

       5. candidateSet 内の各候補に対して、 CS を制約集合として SelectSettings アルゴリズムを実行します。アルゴリズムが undefined を返す場合、その候補を candidateSet から削除します。これにより、 制約を満たす設定辞書が少なくとも 1 つ存在することを 確認して、制約を満たせないデバイスを除外します。

          candidateSet が空集合の場合、 failedConstraint を、 SelectSettings アルゴリズムの実行中に調べたすべての設定辞書について 適合度距離が無限大であった 必須 制約のいずれかとするか、 そのようなものがない場合は "" とし、 下の 制約失敗 とラベル付けされた手順にジャンプします。

          このエラーは、 ユーザーがどのデバイスにも認可を与える前に、 基礎となるデバイスが生成できないものについての情報を 提供するため、フィンガープリンティング面として 使用できます。

       6. candidateSet 内の、現在の Document 内の live な MediaStreamTrack に接続されていないすべての候補デバイスについて、 現在の許可 状態を読み取ります。 デバイスの許可状態が「denied」 である候補を candidateSet から削除します。

          candidateSet がここで空になり、 この型のすべてのデバイスが 「denied」 状態であることを示す場合、 下の PermissionFailure とラベル付けされた手順に ジャンプします。

       7. 任意で、たとえば以前に設定された ユーザーの選好、セキュリティ上の理由、またはプラットフォームの 制約に基づき、下の 許可 失敗 とラベル付けされた手順にジャンプします。

       8. candidateSet のすべての候補を finalSet に追加します。

    4. stream を新しい空の MediaStream オブジェクトとします。

    5. requestedMediaTypes 内の各メディア型 kind について、できれば同時に次のサブ手順を 実行します:

       注記

       ユーザー エージェントには、異なる種類のメディアに対する 同時要求を、ユーザー向けの単一の 許可プロンプトにまとめることが推奨されます。

       1. kind に関連付けられた許可名 （たとえば "video" には "camera"、 "audio" には "microphone"） に name メンバーを設定した PermissionDescriptor を使用する許可を 要求し、 現在の Document 内の live かつ同一許可の MediaStreamTrack に接続されたすべてのデバイスは、許可状態が 「granted」 であるものとして扱い、その結果として提供されるメディアの集合を得ます。 この文脈での 同一許可とは、 現在要求されているものと同じレベルの 許可を取得するために必要とした MediaStreamTrack を意味します（たとえば隔離されたものではない）。

          ユーザーに許可を求める際、 ユーザー エージェントは、 許可が選択されたデバイスのみに付与されるのか、 それともその kind のすべてのデバイスに 付与されるのかを開示しなければなりません。

          注記

          ユーザーが応答しない場合、このアルゴリズムはこの 手順で停止したままになります。

       2. 要求の結果が「denied」 の場合、下の 許可失敗 とラベル付けされた手順にジャンプします。

    6. hasSystemFocus を false とします。

    7. hasSystemFocus が false の間、 ユーザーエージェントは、 システムフォーカスを持つ アルゴリズムの結果を hasSystemFocus に設定するため キューに入れられたタスクが、 hasSystemFocus を true に設定することになるまで、 次の手順への進行を待たなければなりません。

    8. mediaDevices において、 requestedMediaTypes および true を指定して デバイス 情報の公開を設定します。

    9. requestedMediaTypes 内の各メディア型 kind について、次のサブ手順を実行します:

       1. finalCandidate を提供されたメディアとします。これは finalSet 内の kind 型の 候補を正確に 1 つ でなければなりません。 finalSet からどの候補を選択するかの判断は 完全に ユーザー エージェントに委ねられ、ユーザーに尋ねることで決定してもかまいません。

          ユーザー エージェントは、 SelectSettings アルゴリズムから算出された 適合度距離の値を、 選択アルゴリズムへの入力として使用するべきです。 ただし、ユーザーの選好など、 デバイスについて内部的に利用可能な他の情報も 使用してかまいません。

          注記

          これは、非必須 制約の値は保証されないことを意味します。

          ユーザー エージェントには、可能であれば、kind について ユーザーの主要デバイスまたはシステムデフォルトデバイスを デフォルトで使用することが推奨されます。 ユーザーエージェントは、 事前録画されたメディアファイルを含む任意のメディア ソースをユーザーが使用できるようにしてもかまいません。

       2. 要求の結果は「granted」です。 OS／プログラム／Web ページのロックなどのハードウェアエラーにより アクセスできない場合、 対応する候補を finalSet から削除します。 finalSet に kind 型の候補がない場合、 p を、 name 属性の値が 「NotReadableError」 である新しい DOMException オブジェクトで 拒否し、 この手順を中止します。 それ以外の場合、更新された finalSet を使用してこれらのサブ手順を再開します。

          上記以外の理由でデバイスアクセスに失敗した場合、 対応する候補を finalSet から削除します。 finalSet に kind 型の候補がない場合、 p を、name 属性の値が「AbortError」 である新しい DOMException オブジェクトで拒否し、 この手順を中止します。 それ以外の場合、更新された finalSet を使用してこれらのサブ手順を再開します。

       3. grantedDevice を finalCandidate のソースデバイスとします。

       4. grantedDevice の deviceId deviceId を使用して、 mediaDevices.[[devicesLiveMap]][deviceId] がまだ true でなければ true に設定し、 mediaDevices.[[devicesAccessibleMap]][deviceId] がまだ true でなければ true に設定します。

       5. track を、 grantedDevice および mediaDevices を指定して MediaStreamTrack を 作成した結果とします。 MediaStreamTrack のソースは変更してはなりません。

       6. track を stream のトラック集合に追加します。

    10. stream 内のすべての トラックに対して適切な制約を指定し、 ApplyConstraints アルゴリズムを実行します。 いずれかが undefined 以外を返した場合、 failedConstraint をその結果とし、 下の 制約失敗 とラベル付けされた手順にジャンプします。

    11. stream 内の各 track について、 track.[[Source]] および mediaDevices を指定して、 トラックソースを MediaDevices に関連付けます。

    12. p を stream で 解決し、 この手順を中止します。

    13. NotFound 失敗:

        1. requestedMediaTypes を指定した getUserMedia 固有の失敗が許可されるが false を返す場合、下の 許可失敗 とラベル付けされた手順にジャンプします。

        2. p を、 name 属性の値が「NotFoundError」 である新しい DOMException オブジェクトで 拒否します。

    14. 制約失敗:

        1. requestedMediaTypes を指定した getUserMedia 固有の失敗が許可されるが false を返す場合、下の 許可失敗 とラベル付けされた手順にジャンプします。

        2. message を undefined または情報を提供する 人間が読めるメッセージのいずれかとし、 デバイス 情報を公開できるが true の場合は constraint を failedConstraint とし、それ以外の場合は "" とします。

        3. OverconstrainedError(constraint, message) を呼び出して作成した新しい OverconstrainedError で p を拒否します。

    15. 許可失敗: p を、 name 属性の値が 「NotAllowedError」 である新しい DOMException オブジェクトで拒否します。

12. p を返します。

video（型: (boolean または MediaTrackConstraints)、 デフォルト値: false）

true の場合、返される MediaStream に映像トラックを含めるよう要求します。 Constraints 構造が指定された場合、映像トラックの性質と 設定をさらに指定します。false の場合、 MediaStream に 映像トラックを含めてはなりません。

audio（型: (boolean または MediaTrackConstraints)、 デフォルト値: false）

true の場合、返される MediaStream に音声トラックを含めるよう要求します。 Constraints 構造が指定された場合、 音声トラックの性質と設定をさらに指定します。 false の場合、MediaStream に 音声トラックを含めてはなりません。

getCapabilities

getCapabilities() メソッドは、オブジェクトがサポートする制約可能な プロパティ名の辞書を返します。呼び出されたとき、 ユーザーエージェントは [[Capabilities]] 内部 スロットの値を返さなければなりません。

注記

基礎となるハードウェアが、制約可能なプロパティに対して 定義された範囲に正確には対応しない場合があります。 その可能性がある場合、そのエントリでは、ハードウェア設定を プロパティに対して定義された値に変換し、 スケーリングする方法を定義するべきです。 たとえば、仮想的な fluxCapacitance プロパティが -10（min）から 10（max）までの範囲を持つ一方で、 一般的なハードウェアデバイスが "off"、"medium"、"full" の値しかサポートしないとします。 制約可能なプロパティの定義では、そのようなハードウェアについて、 ユーザーエージェントが 範囲値 -10 を "off"、10 を "full"、0 を "medium" に対応付けるべきであると指定できます。また、 3 という厳密な値を課す ConstraintSet が指定された場合、 ユーザーエージェントは ハードウェア上で "medium" の値を設定しようとするべきであり、 getSettings() は fluxCapacitance として 0 を返すべきであることも 示せます。これは、それが "medium" に対応する値として 定義されているためです。

getConstraints

getConstraints() メソッドは、 オブジェクトに対する ApplyConstraints アルゴリズムの直近の成功した呼び出しへの引数であった Constraints を、 指定された順序を維持して返します。 返される高度な ConstraintSet の一部は現在 満たされていない場合があることに注意してください。どの ConstraintSet が現在有効かを確認するには、 アプリケーションは getSettings を使用するべきです。 上記のとおり正確な制約を返す代わりに、UA は、 適用された制約とあらゆる状況で同一の効果を持つ 制約集合を返してもかまいません。 呼び出されたとき、ユーザーエージェントは [[Constraints]] 内部スロットの値を 返さなければなりません。

getSettings

getSettings() メソッドは、 オブジェクトのすべての制約可能なプロパティの現在の 設定を、それらがプラットフォームのデフォルトであるか ApplyConstraints アルゴリズムによって設定されたかにかかわらず返します。 設定は制約に適合する 目標値であるため、場合によっては測定された性能と 異なる可能性があることに注意してください。呼び出されたとき、ユーザー エージェントは [[Settings]] 内部スロットの値を返さなければなりません。

applyConstraints

applyConstraints テンプレートメソッドが 呼び出されたとき、 ユーザーエージェントは 次の手順を実行しなければなりません:

1. object を、このメソッドが 呼び出されたオブジェクトとします。

2. newConstraints を、この メソッドへの引数とします。

3. p を新しい promise とします。

4. このメソッドが複数回呼び出された場合には呼び出し順序を維持しつつ、 次の手順を並列に実行します:

   1. failedConstraint を、 newConstraints を引数として ApplyConstraints アルゴリズムを実行した結果とします。

   2. successfulSettings を、上記の手順のアルゴリズムが 完了した後の object の現在の設定とします。

   3. 次の手順を実行するタスクをキューに入れます:

      1. failedConstraint が undefined でない場合、 message を undefined または 情報を提供する人間が読めるメッセージのいずれかとし、 OverconstrainedError(failedConstraint, message) を呼び出して作成した 新しい OverconstrainedError で p を拒否し、 この手順を中止します。この場合、既存の制約は有効なままです。

      2. object の [[Constraints]] 内部スロットを newConstraints または newConstraints とあらゆる状況で 同一の効果を持つ Constraints 辞書に設定します。

      3. object の [[Settings]] 内部スロットを successfulSettings に設定します。

      4. p を undefined で 解決します。

5. p を返します。

制約を適用するための ApplyConstraints アルゴリズムを以下に示します。ここでは、アルゴリズムの記述で 使用される予備的な定義をいくつか示します:

オブジェクトに設定として適用され得る値の集合を指すため、 設定辞書という用語を使用します。

文字列値の制約について、以下では、シーケンス内の値の 1 つが 比較対象の値と正確に同じである場合に "==" を true と定義します。

設定辞書と制約集合 CS の間の適合度距離を、 CS 内に存在する 各メンバー（constraintName と constraintValue の組で表される） について、次の値の合計として定義します:

1. constraintName が ユーザーエージェントによってサポートされていない場合、 適合度距離は 0 です。

2. 制約が必須であり （constraintValue が 'min'、'max'、または 'exact' という名前のメンバーを 1 つ以上含むか、 または高度な ConstraintSet 内でそれ自体が裸の値である）、 設定 辞書の constraintName メンバーの値が制約を満たさないか、 存在しない場合、 適合度距離は 正の無限大です。

3. この種類のオブジェクトに制約が適用されない場合、 適合度距離は 0 です（すなわち、その制約は 適合度距離に影響しません）。

4. constraintValue が boolean である一方、 制約可能なプロパティがそうでない場合、適合度距離は、 設定 辞書の constraintName メンバーが存在するかどうかに基づき、 次の式から求められます

   (constraintValue == exists) ? 0 : 1

5. 設定 辞書の constraintName メンバーが存在しない場合、 適合度距離は 1 です。

6. ideal 値が指定されていない場合（constraintValue が 'ideal' という名前のメンバーを含まないか、裸の値を 'ideal' として扱う場合に裸の値でない場合）、適合度距離は 0 です。
7. すべての正の数値制約（height、width、frameRate、 aspectRatio、sampleRate、sampleSize など）について、適合度距離は 次の式の結果です

   (actual == ideal) ? 0 : |actual - ideal| / max(|actual|, |ideal|)

8. すべての文字列、enum、および boolean 制約（たとえば deviceId、groupId、facingMode、resizeMode、echoCancellation）について、 適合度距離は次の式の結果です

   (actual == ideal) ? 0 : 1

その他の定義:

• ConstraintSet の各要素（特別な用語 'advanced' を除く）を「制約」と呼びます。これは、 ConstrainablePattern オブジェクトの対応する Capability に示された完全なリストまたは範囲から、 指定された範囲または値リスト内の値へ、 指定されたプロパティの許容可能な設定を制限することを 意図しているためです。
• オブジェクト O の「有効な Capability」C とは、 環境上の制限および／または他の制約によって課された 制限を考慮した、C の可能な値（getCapabilities から返される）の 真部分集合である場合もある集合を指します。たとえば、aspectRatio、 height、および width プロパティを制約する ConstraintSet がある場合、 そのうち 2 つのプロパティに割り当てられた値によって、 3 つ目の有効な Capability が制限されます。有効な Capability の集合は プラットフォームに依存する場合があります。たとえば、リソースが制限された デバイスでは、プロパティ P1 と P2 の両方を 'high' に設定できない場合がありますが、より制限の少ない別のデバイスでは 可能な場合があります。
• オブジェクト O の制約可能なプロパティの値の集合である設定辞書は、 その集合と CS の間の適合度距離が 無限大より小さい場合、ConstraintSet CS を満たします。
• ConstraintSet の集合 CS1...CSn（n >= 1）は、 CS1...CSn を同時に満たす O の設定 辞書を見つけることが可能な場合、オブジェクト O によって 満たすことができます。
• ConstraintSet の集合 CS1...CSn をオブジェクト O に適用するとは、 CS1...CSn を満たすそのような値のシーケンスを選択し、 それらを O のプロパティの設定として割り当てることです。

SelectSettings アルゴリズムを次のように 定義します:

1. 各制約は、そのプロパティについて 1 つ以上の 値（または値の範囲）を指定します。プロパティは 'advanced' ConstraintSet のリスト内に複数回現れてもかまいません。 制約の値として空のリストが指定された場合、それは 制約が指定されていないかのように解釈されなければなりません （言い換えると、空の制約 == 制約なし）。

   未知のプロパティは WebIDL によって破棄されるため、 未知／サポートされていない必須制約は暗黙に消えることに注意してください。 これが意外な動作にならないよう、アプリケーション作成者はまず、 以下の例に示すように getSupportedConstraints() メソッドを使用することが期待されます。

2. object を、このアルゴリズムが適用される ConstrainablePattern オブジェクトとします。copy を、object の制約なしの コピーとします（すなわち、copy は、すべての ConstraintSet が 削除された object であるかのように動作するべきです）。

3. copy の可能なすべての 設定 辞書について、その適合度 距離を計算し、プロパティの裸の値を ideal 値として扱います。 candidates を、適合度距離が有限である 設定辞書の集合とします。

4. candidates が空の場合、 SelectSettings アルゴリズムの結果として undefined を返します。

5. newConstraints 内の 'advanced' ConstraintSet を、 指定された順序で反復処理します。各 ConstraintSet について:

   1. それと candidates 内の各設定辞書との 適合度 距離を計算し、プロパティの裸の値を exact として扱います。

   2. candidates 内の 1 つ以上の 設定辞書について適合度距離が有限である場合、それらの 設定辞書を candidates に保持し、 その他を破棄します。

      candidates 内のすべての設定 辞書について適合度距離が無限大である場合、この ConstraintSet を無視します。

6. candidates から 1 つの設定辞書を選択し、 SelectSettings アルゴリズムの結果として返します。 ユーザーエージェントは、 ステップ 3 で計算された 適合度距離が最小のものを 使用しなければなりません。複数の設定辞書が 最小の適合度距離を持つ場合、 ユーザーエージェントは、 システムのデフォルトプロパティ値および ユーザーエージェントの デフォルトプロパティ値に基づいて、そのうち 1 つを選択します。

選択されたデバイスについてシステムデフォルト値を持つすべてのプロパティでは、 上記のアルゴリズムと互換性がある場合、そのシステムデフォルト 値を使用するべきです。これは通常、 sampleRate や sampleSize などのプロパティで該当します。 echoCancellation や resizeMode などの他のプロパティには、 通常、システムデフォルト値がありません。 ユーザーエージェントは、 これらのプロパティについて独自のデフォルト値を定義します。 これらはメディアコンテンツの生成方法にしばしば影響するため、 実装者は適切なデフォルト値を選択する際に注意する必要があります。

注記

意味のあるデフォルト値を選択するため、 既存の実装を確認することが推奨されます。 デフォルト値はシステムによって、たとえばデスクトップと モバイルで異なる場合があることに注意してください。 執筆時点では、ユーザーエージェントの 実装は、RTCPeerConnection をシンクとして使用するのに適していることから選ばれた、 次のデフォルト値を使用する傾向があります:

1. width を 640 に設定。

2. height を 480 に設定。

3. frameRate を 30 に設定。

4. echoCancellation を true に設定。

newConstraints を引数として object に ApplyConstraints アルゴリズムを適用するには、 ユーザーエージェントは 次の手順を実行しなければなりません:

1. successfulSettings を、 newConstraints を制約集合として SelectSettings アルゴリズムを実行した結果とします。

2. successfulSettings が undefined の場合、 failedConstraint を、 SelectSettings アルゴリズムの実行中に調べた すべての設定辞書について適合度距離が無限大であった 必須制約のいずれかとするか、 そのようなものがない場合は "" とし、 その後 failedConstraint を返して この手順を中止します。

3. 単一の操作で、object から既存の制約を削除し、 newConstraints を適用し、 successfulSettings を現在の設定として適用します。
4. undefined を返します。

注記

UA が、たとえばトラックが ミュートされているために デバイスを解放した場合、 設定を適用することはデバイス構成を変更することを意味しません。 代わりに、UA がデバイスを再取得するとき、 たとえばトラックが ミュート解除されたときに、 UA はトラック設定と一致するようデバイスを構成します。

注記

上記のアルゴリズムと同じ結果になる実装であれば、 どのような実装も許可されます。たとえば、 実装は、設定について可能なすべての値を 追跡する代わりに、検討された制約の下で許容される 設定の最大値と最小値を追跡することを選択できます。

注記

設定辞書を選択するとき、UA は利用可能な任意の 情報を使用できます。そのような情報の例には、 選択が getUserMedia におけるデバイス選択の一部として行われるか、 カメラのエネルギー使用量が設定辞書間で異なるか、 または設定辞書を使用することでデバイスドライバーが リサンプリングを適用することになるかどうか、などがあります。

ユーザーエージェントは、 オブジェクトの制約可能なプロパティに対していつでも新しい設定を 選択してもかまいません。その場合、上記のアルゴリズムで説明した方法で 現在のすべての Constraints を満たそうとしなければならず、 successfulSettings を結果として得られた新しい設定とし、 次の手順を実行するタスクをキューに入れます:

1. object を、 1 つ以上の制約可能なプロパティの新しい設定が変更された ConstrainablePattern オブジェクトとします。

2. object の [[Settings]] 内部 スロットを successfulSettings に設定します。

max（型: double）

このプロパティの有効な最大値です。

min（型: double）

このプロパティの最小値です。

exact（型: double）

このプロパティに必須の正確な値です。

ideal（型: double）

このプロパティの理想的な（目標）値です。

max（型: unsigned long）

このプロパティの有効な最大値です。

min（型: unsigned long）

このプロパティの最小値です。

exact （型: unsigned long）

このプロパティに必須の正確な値です。

ideal （型: unsigned long）

このプロパティの理想的な（目標）値です。

exact（型: boolean）

このプロパティに必須の正確な値です。

ideal（型: boolean）

このプロパティの理想的な（目標）値です。

exact（型: (DOMString または sequence<DOMString>)）

このプロパティに必須の正確な値です。

ideal（型: (DOMString または sequence<DOMString>)）

このプロパティの理想的な（目標）値です。

exact（型: boolean または DOMString）

このプロパティに必須の正確な値です。

ideal（型: boolean または DOMString）

このプロパティの理想的な（目標）値です。