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

MediaStream

MediaStream コンストラクターアルゴリズムを参照してください

パラメーターなし。

MediaStream

MediaStream コンストラクターアルゴリズムを参照してください

MediaStream

MediaStream コンストラクターアルゴリズムを参照してください

id 型 DOMString, 読み取り専用

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

MediaStream が作成される際、ユーザーエージェントは識別子文字列を生成し、 オブジェクトのid 属性をその文字列で初期化しなければなりません。 ただし、ストリームIDの初期化方法を定めた特別なアルゴリズムの一部としてオブジェクトが作成される場合は除きます。 UUID [rfc4122]（標準形式で36文字）が推奨されます。 フィンガープリント防止のため、実装はRFC 4122の4.4または4.5の形式を使うべきです。

ストリームID初期化方法を指定するアルゴリズムの例として、ネットワークコンポーネントと MediaStreamオブジェクトを関連付ける方法があります。[WEBRTC]

active 型 boolean, 読み取り専用

active 属性は、このMediaStreamが アクティブならtrue、 そうでなければfalseを返さなければなりません。

onaddtrack 型 EventHandler

このイベントハンドラのイベントタイプはaddtrackです。

onremovetrack 型 EventHandler

このイベントハンドラのイベントタイプはremovetrackです。

getAudioTracks()

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

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

getVideoTracks()

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

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

getTracks()

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

getTracksメソッドは、 トラックセット内の MediaStreamTrack オブジェクトすべてのスナップショットを表すシーケンスを返さなければなりません（[[Kind]]の値は問わない）。シーケンスへの変換はユーザーエージェント定義であり、呼び出しごとに順序は安定している必要はありません。

getTrackById()

getTrackByIdメソッドは、 トラックセット内で [[Id]]が trackIdと一致するMediaStreamTrack オブジェクトを返さなければなりません。該当トラックがなければnullを返します。

addTrack()

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

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

1. 引数trackと、メソッドが呼ばれた MediaStream オブジェクトstreamとする。

2. もしtrackがstreamの トラックセットに存在する場合は、手順を中止する。

3. 追加操作で trackをstreamのトラックセットに追加する。

removeTrack()

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

removeTrack メソッドが呼び出されたとき、 ユーザーエージェントは以下を実施しなければなりません：

1. 引数trackと、メソッドが呼ばれた MediaStream オブジェクトstreamとする。

2. もしtrackがstreamのトラックセットに存在しない場合は、手順を中止する。

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、readonly

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

track 型 MediaStreamTrack、required

mediaDevices 型 MediaDevices、readonly

返す値は、thisの 関連するグローバルオブジェクトの 関連付けられたMediaDevicesです。

ondevicechange 型 EventHandler

このイベントハンドラのイベントタイプは devicechange です。

enumerateDevices

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

このメソッドはpromiseを返します。promiseは fulfilled時、 MediaDeviceInfoオブジェクトのシーケンス（ ユーザーエージェントが利用可能なメディア入力・出力デバイスを表す）で解決されます。

このシーケンスの要素のうち、入力デバイスを表すものは InputDeviceInfo型（MediaDeviceInfoを継承）です。

カメラとマイクのソースは推奨で列挙可能であるべきです。追加のソースタイプを加える仕様は、そのタイプが列挙されるべきかどうかの推奨を提供します。

enumerateDevices() メソッドが呼ばれると、ユーザーエージェントは以下の手順を実行します：

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

2. proceed を デバイス列挙が可能か（引数は this）の結果とする。

3. mediaDevices を thisとする。

4. 次の手順を並行して実行：

   1. proceedがfalseの間は、ユーザーエージェント 必須でタスクキューを待機し、proceedが デバイス列挙が可能か（引数はmediaDevices）の結果でtrueになるまで先へ進まない。

   2. resultListを デバイス情報オブジェクトのリスト作成（引数はmediaDevicesと mediaDevices.[[storedDeviceList]]）の結果とする。

   3. resolve 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を デバイス情報オブジェクト作成（deviceとmediaDevices）の結果とする。

   3. deviceがシステムデフォルトマイクならmicrophoneListに deviceInfoを先頭に、 そうでなければ末尾に追加する。

5. deviceListの各デバイスdeviceについて以下のサブ手順を実行：

   1. deviceがカメラでない、またはdocumentが機能使用許可で "camera"でない場合、 サブ手順中断・次のデバイスへ。

   2. deviceInfoを デバイス情報オブジェクト作成（deviceとmediaDevices）の結果とする。

   3. deviceがシステムデフォルトカメラならcameraListに deviceInfoを先頭に、 そうでなければ末尾に追加する。

6. マイク情報公開可が mediaDevicesでfalseなら、 microphoneListを先頭1件に切り詰める。

7. カメラ情報公開可が mediaDevicesでfalseなら、 cameraListを先頭1件に切り詰める。

8. deviceListの各デバイスdeviceについて以下のサブ手順を実行：

   1. deviceがマイクまたはカメラならサブ手順を中断し次のデバイスへ。

   2. カメラ・マイク以外のデバイス公開判定アルゴリズム（device、microphoneList、cameraList、mediaDevices）を実行し、その結果がfalseなら中断し次のデバイスへ。

   3. deviceInfoを デバイス情報オブジェクト作成（deviceとmediaDevices）の結果とする。

   4. deviceInfo を otherDeviceList に追加する。

   5. もし device がシステムのデフォルトオーディオ出力である場合は、以下のサブステップを実行する：

      1. defaultAudioOutputInfo を device を表す device info object の作成 の結果とし、mediaDevices を用いる。

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

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

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

9. microphoneList のすべてのデバイスを順番に resultList に追加する。

10. cameraList のすべてのデバイスを順番に resultList に追加する。

11. otherDeviceList のすべてのデバイスを順番に resultList に追加する。

12. resultList を返す。

このメソッドは、キャプチャデバイスの有無という形でブラウジングセッションやオリジンをまたいで永続情報を返すため、 ユーザーエージェントによるフィンガープリント面を拡大します。

関連グローバルオブジェクトの 関連付けられたDocumentがキャプチャしていない限り、このメソッドは「カメラがあるか」「マイクがあるか」の2ビットしか公開しません。 ユーザーエージェントは （例えばgetUserMedia()で妥当な制約が来るまで）システムにカメラ・マイクがあると偽装してもよいです。

関連グローバルオブジェクトの 関連付けられたDocumentがキャプチャを開始した後は、全キャプチャデバイスのリスト（グループ・ラベル含む）によってさらに永続的なクロスオリジン情報を公開するため、フィンガープリント面が拡大します。

ユーザーエージェントは、デバイスラベルをサニタイズして公開範囲を制限してもよいです。例えば、ラベル内のユーザー名は削除し、メーカー名やモデル情報は残すなど。ただし、サニタイズ後もユーザーがデバイス識別可能であることが重要です。

deviceId 型 DOMString, readonly

表現されるデバイスの識別子。このデバイスは識別子とkindによって一意に識別されなければならない。

保存された識別子を認識するため、識別子はDocumentの同一オリジン・トップレベルトラバーサブル間で同一でなければならない。 子ナビゲーションでは、 識別子がドキュメント間で同一かどうかの判断は、ユーザーエージェントのストレージ分割ルール（例：localStorage） に従わなければならない。識別子がユーザーを一意に識別できる場合、他のオリジンのドキュメントでは識別子が推測できないようにしなければならない（クロスオリジン関連付け回避）。ユーザーに紐付かず、他の手段（例：User-Agent文字列）で推測可能ならオリジン間で再利用可能。

ローカルデバイスがこのオリジンのページでライブなMediaStreamTrackにアタッチされた場合や、このオリジンにローカルデバイスへの保存された許可がある場合、この識別子は必ず永続化される（後述の例外を除く）。一意かつ安定した識別子により、アプリケーションは複数回アクセス時に特定ソースの保存・利用可否判定・直接リクエストが可能となる。

ただし、ローカルデバイスがこのオリジンのページでライブなMediaStreamTrackにアタッチされておらず、また保存された許可もない場合、ユーザーエージェントはこの識別子を最後のセッション終了時にクリアしてもよい。クリアしない場合は必ずユーザーが識別子を目視・削除できる手段（例：Cookie同様）を提供しなければならない。

deviceIdはセッションをまたいで残る場合があり、フィンガープリント防止のため、deviceIdはCookie等と同様に扱う。ユーザーエージェントはCookie利用不可サイトには識別子を永続化してはならない、他の永続ストレージをクリアした際は必ずオリジンごと識別子をローテーションしなければならない。

kind 型 MediaDeviceKind、readonly

表現されるデバイスの種別。

label 型 DOMString、readonly

このデバイスの説明用ラベル（例："External USB Webcam"）。ユーザーがデバイスを区別できるよう設計されているが、アプリケーションはラベル内容（デバイスタイプや型番等）を仮定してはならない。ラベルがない場合は空文字列を返す必須。

groupId 型 DOMString、readonly

表現されるデバイスのグループ識別子。同じ物理デバイスに属する場合は同じグループIDとなる（例：同じヘッドセットのスピーカーとマイク）。

グループ識別子は各documentごとに一意に生成必須。

toJSON

呼び出し時、[WEBIDL]の既定のtoJSON手順を実行する。

getCapabilities

デバイスの主トラック（MediaStream内で kind値に応じた音声または映像トラック）の MediaTrackCapabilitiesオブジェクトを返す（ユーザー指定制約なしの場合）。 これらのケイパビリティは、getUserMedia({deviceId: id})で取得された MediaStreamTrackの最初の MediaStreamで deviceId属性がidの getCapabilities() を呼んだ場合と同一でなければならない。

ローカルデバイスへのアクセス許可がなく、この InputDeviceInfoが一意情報でフィルタ済みの場合（enumerateDevices()の説明参照）、 このメソッドは空の辞書を返す。

constructor()

this.devices を eventInitDict.devicesから frozen arrayを作成した結果で初期化します。

devices 型 FrozenArray<MediaDeviceInfo>, readonly

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

userInsertedDevices 型 FrozenArray<MediaDeviceInfo>, readonly

userInsertedDevices 属性は、 MediaDeviceInfo オブジェクトのうち devices 配列の中から、 ユーザーが物理的に挿入・有効化したばかりで、今回イベントで新たに公開されたもののみを含む配列を返します。 それ以外の場合は空リストを返します。

ユーザーエージェントは 任意で、 getUserMedia()呼び出し前に ユーザーが挿入・有効化したデバイスを含めてもよい。ただしこのイベントが初公開となり、 ユーザーが getUserMedia()でそのデバイスを選択していない場合のみ。

MediaDeviceInfo オブジェクトが含まれる場合、 必ず devicesにも同じオブジェクトが存在していなければならない。

注記

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

アプリケーションは、この属性を頼りに、デバイス情報公開の違いによる devices の変化と区別することを推奨します。

注記

この属性が存在しない場合は、このUAがまだ本仕様のこのバージョンに対応していないことを意味します。

devices 型 sequence<MediaDeviceInfo>, 既定値 []

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

getSupportedConstraints

現行標準におけるユーザーエージェントが認識している 制約可能プロパティをメンバーとするディクショナリを返します。サポートされている制約可能プロパティは必須で 表現される必要があり、サポートされていない制約可能プロパティは ユーザーエージェントから 絶対に返されてはなりません。返される値は ユーザーエージェント が実装している内容を示し、ブラウジングセッション中は変化しません。

getUserMedia

ユーザーにWebカメラやその他のビデオ・オーディオ入力の利用許可を求めます。

constraints引数はMediaStreamConstraints型のディクショナリです。

このメソッドはpromiseを返します。promiseは fulfilled時、 下記の通り有効なトラックが許可された場合、適切な MediaStream オブジェクトで解決されます。

promiseは、下記の通り有効なトラックが見つからない場合やユーザーが許可しない場合は rejectedとなります。

getUserMedia() メソッドが呼び出されたとき、 ユーザーエージェントは必須で以下の手順を実行します：

1. constraintsをメソッドの第1引数とする。

2. requestedMediaTypesをconstraints内で ディクショナリ値またはtrue値を持つメディアタイプ集合とする。

3. requestedMediaTypesが空集合の場合、 rejectedなpromiseをTypeErrorで返す。 WebIDL上"optional"と記載されているが、引数は必須でなければ成功しない。

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

5. documentが 完全にアクティブ でない場合、promiseはInvalidStateErrorの DOMException でrejectedとなる。

6. requestedMediaTypesが"audio"を含み、 documentが "microphone"権限名で識別される機能の 使用許可 を持たない場合、下記Permission Failure手順へジャンプ。

7. requestedMediaTypesが"video"を含み、 documentが "camera"権限名で識別される機能の 使用許可 を持たない場合、下記Permission Failure手順へジャンプ。

8. mediaDevicesをthisとする。

9. isInViewをビューに入っているかアルゴリズムの結果とする。

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

11. 以下の手順を並行して実行：

    1. isInViewがfalseの間、 ユーザーエージェント 必須で、isInViewが ビューに入っているか アルゴリズムの結果でtrueになるまで、次へ進まない。

    2. finalSetを初期値空集合として用意。

    3. requestedMediaTypesの各メディアタイプkindについて以下の手順を実行：

       1. 各種kindソースデバイスの全構成パターンについて、candidate（デバイスとその設定ディクショナリを保持する MediaStreamTrack のプレースホルダー）を考える。

          この候補集合をcandidateSetとする。

          candidateSetが空なら下記NotFound Failure手順へジャンプ。

       2. constraintsのkind値がtrueならCSを制約なし（空セット）に設定、そうでなければconstraintsのkind値でCSを設定。
       3. CS内の制約可能プロパティで、kind型の MediaStreamTrack に定義されていないものは除外する（音声専用制約がvideoに、映像専用制約がaudioに含まれていても無視され、OverconstrainedErrorにはならない）。

       4. CSに 必須制約があり、その名前が デバイス選択に許可された必須制約 リストに存在しない場合、pをTypeErrorで rejectし、以降を中断。

       5. 全候補についてSelectSettingsアルゴリズムをCS制約セットで実行。アルゴリズムがundefinedを返す候補はcandidateSetから除外。制約を満たせないデバイスは除外される。

          candidateSetが空なら、failedConstraintを 必須制約のうち fitness distanceが全て無限大だったもの（なければ""）にし、下記Constraint Failure手順へジャンプ。

          このエラーは、ユーザーがデバイスに許可を与える前に、デバイスが何を生成できないかという情報を提供するため、フィンガープリント面となる可能性があります。

       6. 現行の パーミッション状態 を、現ドキュメントでライブな MediaStreamTrack にアタッチされていない全候補デバイスについて取得。パーミッション状態が"denied"の候補はcandidateSetから除外。

          この時点でcandidateSetが空（全デバイス"denied"）なら、下記PermissionFailure手順へジャンプ。

       7. ユーザープリファレンスやセキュリティ、プラットフォーム制約等で任意にPermission Failureへジャンプしてもよい。

       8. candidateSetの全候補をfinalSetに追加。

    4. streamを新規・空の MediaStreamオブジェクトとする。

    5. requestedMediaTypesの各kindについて、できれば同時に以下のサブ手順を実行：

       注記

       ユーザーエージェントは複数種メディアの同時リクエストを 一つのユーザー向け許可プロンプトにまとめることが推奨されます。

       1. 利用許可リクエストを PermissionDescriptorの name にkindに対応する権限名（例："camera"は"video"用、"microphone"は"audio"用）で指定して実行。 現ドキュメントでライブかつ同一許可の MediaStreamTrackに アタッチされた全デバイスは"granted"とみなす。得られるメディア集合を「provided media」とする。 同一許可とは、取得時に同じレベルの権限（例：隔離されていない）を必要とした MediaStreamTrackを指す。

          ユーザーに許可を求める際、ユーザーエージェントは 許可は選択したデバイスのみに与えられるか、 kindの全デバイスに与えられるかを明示必須。

          注記

          ユーザーが応答しなければ、このアルゴリズムはこのステップで停止します。

       2. リクエスト結果が"denied"なら下記Permission Failureへジャンプ。

    6. hasSystemFocusをfalseにする。

    7. hasSystemFocusがfalseの間、 ユーザーエージェント 必須で、hasSystemFocusが システムフォーカスあり アルゴリズムの結果でtrueになるまで、次へ進まない。

    8. デバイス情報公開の設定を mediaDevicesに対しrequestedMediaTypesとtrueで実行。

    9. requestedMediaTypesの各kindについて以下のサブ手順を実行：

       1. finalCandidate を提供されたメディアとし、これは finalSet から kind 型の candidate が正確に1つ必須です。どの candidate を finalSet から選ぶかは完全にユーザーエージェントの裁量であり、ユーザーに選択させても構いません。

          ユーザーエージェントは、計算されたfitness distance を SelectSettings アルゴリズムの入力の1つとして推奨で利用すべきです。ただし、ユーザーの好みなどデバイスに関する他の内部情報を使ってもよいです。

          注

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

          ユーザーエージェントは、可能ならkindについてユーザーの主デバイスまたはシステム既定デバイスを使うことをデフォルトとすることが推奨されます。ユーザーエージェントは、ユーザーが任意のメディアソース（録画済みファイル等も含む）を使うことを許可しても構いません。

       2. リクエストの結果は "granted" です。OSやプログラム、ウェブページのロックなどハードウェアエラーでアクセスできない場合は、該当 candidate を finalSet から除外してください。finalSet に kind 型の candidate が1つもなければ、reject p を新規 DOMException オブジェクト（属性 name が "NotReadableError"）でrejectし、これらの手順を中止してください。それ以外の場合は、更新された finalSet でこれらのサブ手順を再実行してください。

          デバイスアクセスが上記以外の理由で失敗した場合も、該当 candidate を finalSet から除外してください。finalSet に kind 型の candidate がなければ、reject p を新規 DOMException（属性 name が "AbortError"）でrejectし、手順を中止してください。それ以外の場合は、更新された finalSet でこれらのサブ手順を再実行してください。

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

       4. grantedDevice の deviceId（deviceId）を使い、mediaDevices.[[devicesLiveMap]][deviceId] を true（すでに true でなければ）にし、mediaDevices.[[devicesAccessibleMap]][deviceId] も true（すでに true でなければ）にしてください。

       5. track を MediaStreamTrack作成（引数 grantedDevice と mediaDevices）の結果としてください。MediaStreamTrack のソースは変更してはなりません。

       6. track を stream のトラック集合に追加してください。

    10. 全トラックに対してApplyConstraintsアルゴリズムを適用。結果がundefined以外ならfailedConstraintにセットし、下記Constraint Failureへジャンプ。

    11. 全trackについて トラックソースをMediaDevicesに紐付け（track.[[Source]]とmediaDevices）。

    12. resolve p（streamで）し、手順中断。

    13. NotFound Failure:

        1. getUserMedia 固有失敗許可（requestedMediaTypes）がfalseなら、下記Permission Failureへジャンプ。

        2. reject p（name値は"NotFoundError"の DOMException）で返す。

    14. Constraint Failure:

        1. getUserMedia 固有失敗許可（requestedMediaTypes）がfalseなら、下記Permission Failureへジャンプ。

        2. messageをundefinedまたは説明用文字列とし、constraintを failedConstraint（デバイス情報公開可がtrueならそれ、そうでなければ""）とする。

        3. reject p（OverconstrainedError(constraint, message)で作成した新規OverconstrainedError）で返す。

    15. Permission Failure: reject 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～10の範囲でも、ハードは"off" "medium" "full"しか対応しない場合、定義で-10→"off"、10→"full"、0→"medium"と対応付けること。ConstraintSetで厳密値3が来た場合は"medium"を設定し、getSettings()は0を返す（"medium"に対応する値）。

getConstraints

getConstraints() メソッドは、 直近で成功した ApplyConstraints algorithm の引数だったConstraintsを順序保持して返します。高度ConstraintSetの一部は現状満たされていない可能性もあるので、現状有効なConstraintSetの確認には getSettings を使うこと。UAは上記内容と同じ効果のConstraintSetを返してもよいです。呼び出し時、ユーザーエージェント 必須で[[Constraints]]内部スロットの値を返します。

getSettings

getSettings() メソッドは、 そのオブジェクトの制約可能プロパティすべての現設定値（プラットフォーム既定値またはApplyConstraints algorithmで設定した値）を返します。設定値は制約を満たすターゲット値であり、実際の計測値と異なる場合もあります。呼び出し時、ユーザーエージェント必須で[[Settings]] 内部スロットの値を返します。

applyConstraints

applyConstraintsテンプレートメソッドが呼ばれた場合、 ユーザーエージェントは必須で以下を実行します：

1. object：このメソッドが呼ばれたオブジェクト

2. newConstraints：このメソッドの引数

3. p：新規promise

4. 以下を並行実行（多重呼び出し時は順序保持）：

   1. failedConstraint＝ApplyConstraints algorithm（引数newConstraints）の結果

   2. successfulSettings＝上記アルゴリズム終了後のobjectの現設定値

   3. 以下をタスクキューに登録：

      1. failedConstraintがundefinedでなければ、message（undefinedまたは説明文字列）を用い、OverconstrainedError(failedConstraint, message)で新規OverconstrainedErrorを生成しpをrejectして中断。既存制約は有効のまま。

      2. objectの[[Constraints]] 内部スロットにnewConstraintsまたは同効果のConstraints辞書を設定。

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

      4. resolve p（undefinedで）。

5. pを返す。

制約適用用ApplyConstraints algorithmは以下。まず用語定義：

settings dictionary（設定値辞書）は、 オブジェクトに設定しうる値の集合。

文字列値制約では「==」はシーケンス内どれかが比較値と完全一致ならtrue。

settings dictionaryと制約セットCS間の fitness distanceは、 CSに存在する各(constraintName, constraintValue)ペアについて以下の値の合計：

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

2. 制約がrequired（constraintValueが「min」「max」「exact」いずれかのメンバーを1つ以上含む場合、またはadvanced ConstraintSet内で値のみの場合）であり、settings dictionaryのconstraintNameメンバーの値が制約を満たさない、または存在しない場合、適合度距離は正の無限大となる。

3. この型のオブジェクトに制約が適用されない場合、適合度距離は0（つまり、その制約は適合度距離に影響しない）。

4. constraintValueが真偽値だが、制約可能なプロパティが真偽値でない場合、適合度距離はsettings dictionaryのconstraintNameメンバーが存在するかどうかによって、次の式で決まる：

   (constraintValue == exists) ? 0 : 1

5. settings dictionaryのconstraintNameメンバーが存在しない場合、適合度距離は1となる。

6. 理想値が指定されていない場合（constraintValueに「ideal」メンバーがなく、または値のみの場合に「ideal」とみなされない場合）、適合度距離は0となる。
7. 全ての正の数値制約（height, width, frameRate, aspectRatio, sampleRate, sampleSizeなど）については、適合度距離は以下の式による：

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

8. 全ての文字列・列挙型・真偽値の制約（deviceId, groupId, facingMode, resizeMode, echoCancellationなど）については、適合度距離は以下の式による：

   (actual == ideal) ? 0 : 1

用語補足：

• ConstraintSetの各要素（'advanced'以外）は「制約」と呼ぶ。Capabilityで指定された値集合から、指定値/範囲に絞る。
• 「有効ケイパビリティ」Cは、getCapabilitiesで得られる値集合の環境制限・他制約による部分集合。例えばaspectRatio, height, widthに制約をかけると、2つの値で3つ目の有効ケイパビリティが制限される。プラットフォーム依存。
• settings dictionaryがConstraintSet CSを満たすとは、fitness distanceが∞未満であること。
• ConstraintSets CS1...CSn（n≥1）が同時に満たせるとは、Oのsettings dictionaryで全部同時に満たせるものがあること。
• ConstraintSets CS1...CSnをOに適用するとは、それらを満たす値列を選び、Oのプロパティ設定値とすること。

SelectSettingsアルゴリズムは以下：

1. 各制約は、そのプロパティの1つ以上の値（または値の範囲）を指定します。プロパティは「advanced」ConstraintSetのリスト内に複数回現れてもよいです。制約値として空リストが指定された場合、それは制約が指定されていないものと必須でみなされます（つまり、空制約＝制約なし）。

   未知のプロパティはWebIDLで破棄されるため、未知・非対応のrequired制約は黙って消えます。これによる意外性を避けるため、アプリケーション作者は下記例のようにまずgetSupportedConstraints()メソッドの利用が期待されます。

2. object をこのアルゴリズムが適用される ConstrainablePattern オブジェクトとする。copy を object の非制約コピー（すなわち全ConstraintSetを除去した状態で object のように振る舞う）とする。

3. copy の可能なすべてのsettings dictionaryについて、そのfitness distanceを計算し、プロパティの値が裸値の場合は理想値として扱う。candidates を、fitness distance が有限となるsettings dictionaryの集合とする。

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

5. newConstraintsの「advanced」ConstraintSetを指定順に繰り返す。各ConstraintSetについて：

   1. それとcandidates内の各settings dictionaryとのfitness distanceを計算し、プロパティの裸値は厳密値として扱う。

   2. fitness distanceが有限のsettings dictionaryがcandidatesに1つ以上ある場合、それらのみcandidatesに残し、他は除外する。

      すべてのsettings dictionaryでfitness distanceが無限なら、このConstraintSetは無視する。

6. candidatesから1つsettings dictionaryを選び、SelectSettingsアルゴリズムの結果として返す。ユーザーエージェントはstep3で計算されたfitness distanceが最小のものを必須で使うこと。最小fitness distanceが複数ある場合、ユーザーエージェントはシステム既定プロパティ値やユーザーエージェント既定プロパティ値に基づきその中から1つを選択する。

選択デバイスにシステム既定値がある場合、互換性あれば既定値を推奨で使う（例：sampleRate, sampleSize）。echoCancellation, resizeMode等は既定値がなくUA独自既定値となる。既定値選択はメディア生成に影響するため慎重に。

注記

現実装を参考に意味のある既定値を選ぶことが推奨。既定値はデスクトップ／モバイル等システム依存で異なる場合あり。執筆時点でUAはRTCPeerConnection用途に次を既定値としている場合が多い：

1. width＝640

2. height＝480

3. frameRate＝30

4. echoCancellation＝true

ApplyConstraints algorithmをobjectにnewConstraintsを引数で適用するには、ユーザーエージェント必須で以下を実行：

1. successfulSettings を、newConstraints を制約セットとして SelectSettings アルゴリズムを実行した結果とする。

2. もし successfulSettings が undefined であれば、failedConstraint を、必須制約 の中で SelectSettings アルゴリズムの実行中に調べられたすべての設定ディクショナリについて、フィットネス距離が無限大であったもののいずれかとする。該当するものがなければ "" とし、その後 failedConstraint を返してこれらの手順を中止する。

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

注記

UAがデバイス解放（例：トラックがミュート）した場合は、設定適用はデバイス構成変更を意味しません。代わりに、トラックがアンミュート等で再取得する時点でトラック設定に合わせて構成します。

注記

上記アルゴリズムと同じ結果になる実装はすべて許容されます。例えば、設定値の全候補値ではなく、制約下でOKな最大・最小値だけを追跡する実装でもよいです。

注記

settings dictionary選択時、UAは取得可能なあらゆる情報を使えます。例：getUserMediaのデバイス選択時かどうか、カメラの消費電力の違い、設定値によるドライバでリサンプリングが発生するか等。

ユーザーエージェントは任意のタイミングで制約可能プロパティの新設定値を選択してもよい。選択時は必ず現制約を満たすよう上記アルゴリズム通りに処理し、successfulSettings新値で以下をタスクキューに登録：

1. object：新設定値変更対象の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)

このプロパティの理想（目標）値。