WebRTC：ブラウザでのリアルタイム通信

iceServers 型 sequence<RTCIceServer>, デフォルト値は []。

ICEが利用可能なサーバー（STUNやTURNサーバーなど）を記述するオブジェクトの配列です。 ICEサーバーの数が実装定義の制限を超えた場合、制限を超えたICEサーバーは無視されます。この実装定義の制限は 必須で少なくとも32でなければなりません。

iceTransportPolicy 型 RTCIceTransportPolicy, デフォルト値は "all"。

ICEエージェント が 使用できる候補を示します。

bundlePolicy 型 RTCBundlePolicy, デフォルト値は "balanced"。

ICE候補を収集する際に使用する メディアバンドルポリシー を示します。

rtcpMuxPolicy 型 RTCRtcpMuxPolicy, デフォルト値は "require"。

ICE候補を収集する際に使用する rtcp-muxポリシー を示します。

certificates 型 sequence<RTCCertificate>, デフォルト値は []。

RTCPeerConnection が認証に使用する証明書セットです。

このパラメータの有効な値は、 generateCertificate() 関数の呼び出しによって作成されます。

いずれのDTLS接続も1つの証明書のみを使用しますが、この属性によって異なるアルゴリズムをサポートする複数の証明書を指定できます。 実際に使用される証明書はDTLSハンドシェイクによって選択され、許可された証明書が確立されます。 RTCPeerConnection の実装が どの証明書を使用するか選択しますが、証明書の選択方法はこの仕様の範囲外です。

注記

既存の実装では最初の証明書のみが利用され、他の証明書は無視されます。

この値が存在しない場合、各 RTCPeerConnection インスタンスごとにデフォルトの証明書セットが生成されます。

このオプションによりアプリケーションはキーの継続性を確立できます。 RTCCertificate は [INDEXEDDB] に保存して再利用できます。保存と再利用により、 キー生成コストも回避できます。

この構成オプションの値は初期選択後に変更できません。

iceCandidatePoolSize 型 octet, デフォルト値は 0

[RFC9429] (セクション 3.5.4. および セクション 4.1.1.) で定義されるプリフェッチされたICEプールのサイズです。

urls 型 (DOMString または sequence<DOMString>), 必須

[RFC7064] や [RFC7065]、 その他のURIタイプで定義されるSTUNまたはTURNのURIです。

username 型 DOMString

この RTCIceServer オブジェクトが TURNサーバーを表す場合、この属性はそのTURNサーバーで使用するユーザー名を指定します。

credential 型 DOMString

この RTCIceServer オブジェクトが TURNサーバーを表す場合、この属性はそのTURNサーバーで使用する認証情報を指定します。

credential は [RFC5389]、 セクション10.2で説明されている長期認証用のパスワードを表します。

iceRestart 型 boolean, デフォルト値は false

この辞書メンバーの値が trueの場合、または該当するRTCPeerConnection オブジェクトの [[LocalIceCredentialsToReplace]] スロットが空でない場合、生成される記述には現在の認証情報と異なるICE認証情報が含まれます （currentLocalDescription 属性のSDPで確認できます）。生成された記述を適用すると、[RFC5245] セクション9.1.1.1で説明されているようにICEが再起動されます。

この辞書メンバーの値が falseで、該当するRTCPeerConnection オブジェクトの [[LocalIceCredentialsToReplace]] スロットが空であり、 currentLocalDescription 属性に有効なICE認証情報がある場合、生成される記述には currentLocalDescription 属性の現在値と同じICE認証情報が含まれます。

注記

iceConnectionState が "failed" に遷移した時にICEの再起動を行うことが推奨されます。 アプリケーションはさらに、 iceConnectionState が "disconnected" に遷移した際に getStats などで数秒後送受信バイト数が増加しているかを測定するなど 他の情報源を使ってICE再起動が適切か判断することもできます。

localDescription の型は RTCSessionDescription, readonly, nullable

localDescription 属性は [[PendingLocalDescription]] が null でない場合それを返し、そうでない場合は [[CurrentLocalDescription]] を返さなければならない (MUST)。

注意: [[CurrentLocalDescription]].sdp と [[PendingLocalDescription]].sdp は、対応する sdp 値を setLocalDescription 呼び出しに渡した文字列と逐語的に同一である必要はない (SDP がパースされ再整形されることや、ICE candidate が追加されることがある)。

currentLocalDescription の型は RTCSessionDescription, readonly, nullable

currentLocalDescription 属性は [[CurrentLocalDescription]] を返さなければならない (MUST)。

これは RTCPeerConnection が最後に stable 状態へ遷移した時に 正常にネゴシエートされたローカル記述と、その offer または answer が作成されて以後 ICE Agent によって生成されたすべてのローカル candidate を合わせたものを表す。

pendingLocalDescription の型は RTCSessionDescription, readonly, nullable

pendingLocalDescription 属性は [[PendingLocalDescription]] を返さなければならない (MUST)。

これはネゴシエーション中のローカル記述と、その offer または answer が作成されて以後 ICE Agent により生成された すべてのローカル candidate を含んだものを表す。RTCPeerConnection が stable 状態にある場合、この値は null である。

remoteDescription の型は RTCSessionDescription, readonly, nullable

remoteDescription 属性は [[PendingRemoteDescription]] が null でない場合それを返し、そうでない場合は [[CurrentRemoteDescription]] を返さなければならない (MUST)。

注意: [[CurrentRemoteDescription]].sdp と [[PendingRemoteDescription]].sdp は、対応する sdp 値を setRemoteDescription 呼び出しに渡した文字列と逐語的に同一である必要はない (SDP がパースされ再整形されることや、ICE candidate が追加されることがある)。

currentRemoteDescription の型は RTCSessionDescription, readonly, nullable

currentRemoteDescription 属性は [[CurrentRemoteDescription]] を返さなければならない (MUST)。

これは RTCPeerConnection が最後に stable 状態へ遷移した時に 正常にネゴシエートされた最新のリモート記述と、その offer または answer が作成されて以後 addIceCandidate() により供給されたすべてのリモート candidate を合わせたものを表す。

pendingRemoteDescription の型は RTCSessionDescription, readonly, nullable

pendingRemoteDescription 属性は [[PendingRemoteDescription]] を返さなければならない (MUST)。

これはネゴシエーション中のリモート記述と、その offer または answer が作成されて以後 addIceCandidate() によって供給されたすべてのリモート candidate を含むものを表す。RTCPeerConnection が stable 状態にある場合、この値は null である。

signalingState の型は RTCSignalingState, readonly

signalingState 属性は RTCPeerConnection オブジェクトの [[SignalingState]] を返さなければならない (MUST)。

iceGatheringState の型は RTCIceGatheringState, readonly

iceGatheringState 属性は RTCPeerConnection オブジェクトの [[IceGatheringState]] を返さなければならない (MUST)。

iceConnectionState の型は RTCIceConnectionState, readonly

iceConnectionState 属性は RTCPeerConnection オブジェクトの [[IceConnectionState]] を返さなければならない (MUST)。

connectionState の型は RTCPeerConnectionState, readonly

connectionState 属性は RTCPeerConnection オブジェクトの [[ConnectionState]] を返さなければならない (MUST)。

canTrickleIceCandidates の型は boolean, readonly, nullable

canTrickleIceCandidates 属性はリモートピアが trickle ICE candidate [RFC8838] を受け入れ可能かどうかを示す。この値はリモート記述が [RFC9429] (section 4.1.17.) に定義されるとおり trickle ICE サポートを示しているかどうかに基づき決定される。 setRemoteDescription の完了前は、この値は null である。

onnegotiationneeded の型は EventHandler

このイベントハンドラのイベント型は negotiationneeded である。

onicecandidate の型は EventHandler

このイベントハンドラのイベント型は icecandidate である。

onicecandidateerror の型は EventHandler

このイベントハンドラのイベント型は icecandidateerror である。

onsignalingstatechange の型は EventHandler

このイベントハンドラのイベント型は signalingstatechange である。

oniceconnectionstatechange の型は EventHandler

このイベントハンドラのイベント型は iceconnectionstatechange である

onicegatheringstatechange の型は EventHandler

このイベントハンドラのイベント型は icegatheringstatechange である。

onconnectionstatechange の型は EventHandler

このイベントハンドラのイベント型は connectionstatechange である。

createOffer

createOffer メソッドは、このセッションでサポートされる 構成を含む RFC 3264 オファーを格納した SDP の blob を生成する。これには、 この RTCPeerConnectionに接続されたローカルのMediaStreamTrackの記述、この実装がサポートする コーデック/RTP/RTCP 機能、およびICE エージェントと DTLS 接続のパラメーターが含まれる。 生成されるオファーをさらに制御するために、 optionsパラメーターを指定できる。

システムのリソースが限られている場合（たとえば、デコーダーの数が有限である場合）、 createOffer はシステムの現在の状態を反映したオファーを返す必要があり、それによって setLocalDescription がそれらのリソースを取得しようとしたときに成功するようにする。 セッション記述は、返された Promise の履行 コールバックが少なくとも終了するまでは、エラーを発生させることなくsetLocalDescription で使用可能な状態を維持しなければならない（MUST）。

SDP の作成は、[RFC9429] に記述された オファー生成の適切なプロセスに従わなければならない（MUST）。ただし、この場合、 ユーザーエージェントは RFC9429 の目的上、stopping 状態のトランシーバーをstoppedとして扱わなければならない（MUST）。

オファーとして、生成される SDP には、 セッションがサポートまたは優先するコーデック/RTP/RTCP 機能の完全な集合が含まれる （使用する特定のネゴシエーション済みサブセットのみを含むアンサーとは対照的である）。 セッション確立後に createOfferが 呼び出された場合、 createOffer は現在のセッションと互換性のあるオファーを生成し、 トラックの追加や削除など、前回の完全な オファー・アンサー交換以降にセッションへ加えられた変更を 組み込む。変更が加えられていない場合、オファーには 現在のローカル記述の機能に加えて、 更新されたオファーでネゴシエーション可能な追加機能も 含まれる。

生成される SDP には、ICE エージェントの usernameFragment、 passwordおよび ICE オプション（[RFC5245] の 14節で定義されている）も含まれ、エージェントが収集した 任意のローカル候補も含まれることがある。

certificates の configuration内の値は、RTCPeerConnection に対してアプリケーションが構成した証明書を RTCPeerConnectionに提供する。これらの 証明書は、任意のデフォルト証明書とともに 証明書フィンガープリントの集合を生成するために使用される。 これらの証明書フィンガープリントは SDP の構築に使用される。

SDP を生成するプロセスは、基盤となるシステムの メディア機能の一部を公開し、これはデバイスに関する 一般に永続的なオリジン横断情報を提供する。 したがって、アプリケーションのフィンガープリンティング面を 拡大する。プライバシーに敏感な状況では、ブラウザーは 機能の共通サブセットのみに一致する SDP を生成するなどの 緩和策を検討できる。

メソッドが呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

1. connectionを、メソッドが呼び出されたRTCPeerConnection オブジェクトとする。

2. connection.[[IsClosed]]が trueである場合、新たに作成されたInvalidStateErrorで 拒否された Promise を返す。

3. connectionを用いてオファーを 作成する結果を、 connectionの操作チェーンにチェーンする結果を返す。

connectionを与えてオファーを作成するには、 次の手順を実行する。

1. connection.[[SignalingState]] が "stable" でも "have-local-offer" でもない場合、 新たに作成されたInvalidStateErrorで 拒否された Promise を返す。

2. pを新しい Promise とする。

3. 並行して、connectionと pを与えて、オファーを作成する 並行手順を開始する。

4. pを返す。

connectionと Promise pを与えた場合の オファーを作成する並行手順 は次のとおりである。

1. connectionが証明書の集合を用いて構築されておらず、 まだ証明書が生成されていない場合、 生成されるまで待つ。

2. [RFC9429] （4.1.8 節）に記述されているように、 オファーを生成するために必要な現在利用可能なリソースを 決定するため、オファー側のシステム状態 を検査する。

3. この検査が何らかの理由で失敗した場合、新たに作成された OperationErrorで pを拒否し、 これらの手順を中止する。

4. connectionとpを与えて、オファーを作成する 最終手順を実行するタスクをキューに入れる。

connectionと Promise pを与えた場合の オファーを作成する最終手順は 次のとおりである。

1. connection.[[IsClosed]]が trueである場合、これらの手順を中止する。

2. connectionが、オファー側のシステム状態を 追加で検査する必要があるように変更されている場合、 並行して、connectionとpを与えて オファーを作成する 並行手順を再度開始し、これらの 手順を中止する。

   注記

   これは、たとえば音声のRTCRtpTransceiver のみがconnectionに追加されているときにcreateOffer が呼び出されたものの、 オファーを作成する 並行手順の実行中に、映像の RTCRtpTransceiver が追加され、映像システムのリソースを 追加で検査する必要が生じた場合などに必要となることがある。

3. 以前の検査から得られた情報、connectionの現在の状態 およびそのRTCRtpTransceiver群をもとに、 [RFC9429] （5.2 節）に記述されているように、SDP オファー sdpStringを生成する。

   1. [RFC8843] （7節）で説明されているように、 バンドルを使用する場合（RTCBundlePolicyを参照）、 BUNDLE グループをネゴシエーションするために、 オファー側タグ付き m= セクションを選択しなければならない。 ユーザーエージェントは、トランシーバーの集合のうち 最初の停止していないトランシーバーに対応する m= セクションを、 オファー側タグ付き m= セクションとして 選択しなければならない（MUST）。 これにより、リモートエンドポイントは SDP を解析することなく、どのトランシーバーが オファー側タグ付き m= セクションであるかを予測できる。

   2. filteredCodecsを、 transceiver.[[PreferredCodecs]] に次のフィルターを適用した結果とする。 フィルタリングはコーデック 優先設定の順序を変更してはならない（MUST NOT）。

      1. kindをtransceiverの [[Receiver]]の [[ReceiverTrack]]の kindとする。

      3. transceiver.direction が "sendonly" または "sendrecv" である場合、kindについての 実装済み送信コーデックの リストに含まれないコーデックを除外する。 その際、コーデック 辞書一致 アルゴリズムを使用し、ignoreLevelsを trueに設定する。

      4. transceiver.direction が "recvonly" または "sendrecv" である場合、kindについての 実装済み受信コーデックの リストに含まれないコーデックを除外する。 その際、コーデック 辞書一致 アルゴリズムを使用し、ignoreLevelsを trueに設定する。

      メディア 記述に関連付けられたトランシーバー transceiverのコーデック優先設定は、 filteredCodecsが空でない場合はその値であるとし、 それ以外の場合は未設定であるとする。

   3. RTCRtpSenderの [[SendEncodings]] スロットの長さが1より大きい場合、 RTCRtpSenderの [[SendEncodings]] に与えられた各エンコーディングについて、 対応するメディアセクションにa=rid send行を追加し、 encodings フィールドに与えられた順序と同じ順序で RID を指定する a=simulcast:send 行を追加する。RID の制限は設定しない。

      注記

      [RFC8853] の5.2節では、a=simulcast 行における RID の順序が、提案される優先順位を示すことを規定している。 ブラウザーがすべてのエンコーディングを送信しないことを 決定した場合、まずリストの最後のエンコーディングの 送信を停止すると予想される。

4. offerを、新たに作成した RTCSessionDescriptionInit 辞書とし、その type メンバーを文字列 "offer" で初期化し、 sdp メンバーを sdpStringで初期化する。

5. [[LastCreatedOffer]] 内部スロットを sdpStringに設定する。

6. offerでpを解決する。

createAnswer

createAnswer メソッドは、リモート構成のパラメーターと互換性のある セッションのサポート対象構成を含む [SDP] アンサーを生成する。 createOffer と同様に、返される SDP の blob には、このRTCPeerConnectionに接続された ローカルMediaStreamTrackの記述、 このセッションについてネゴシエーションされたコーデック/RTP/RTCP オプション、 およびICE エージェントによって 収集された任意の候補が含まれる。 生成されるアンサーをさらに制御するために、 optionsパラメーターを指定できる。

createOffer と同様に、返される記述はシステムの現在の状態を 反映することが推奨される（SHOULD）。 セッション記述は、返された Promise の履行コールバックが少なくとも終了するまでは、 エラーを発生させることなくsetLocalDescription で使用可能な状態を維持しなければならない（MUST）。

アンサーとして、生成される SDP には、 対応するオファーとともにメディアプレーンをどのように 確立するかを指定する特定のコーデック/RTP/RTCP 構成が含まれる。 SDP の生成は、 [RFC9429] に記述された アンサー生成の適切なプロセスに従わなければならない（MUST）。

生成される SDP には、ICE エージェントの usernameFragment、 passwordおよび ICE オプション（[RFC5245] の 14節で定義されている）も含まれ、エージェントが収集した 任意のローカル候補も含まれることがある。

configuration内の certificates 値は、RTCPeerConnection に対してアプリケーションが構成した証明書を RTCPeerConnectionに提供する。これらの 証明書は、任意のデフォルト証明書とともに 証明書フィンガープリントの集合を生成するために使用される。 これらの証明書フィンガープリントは SDP の構築に使用される。

[RFC9429] （4.1.10.1 節）に記述されているように、 typeを "pranswer" に設定することで、アンサーを暫定としてマークできる。

メソッドが呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

1. connectionを、メソッドが呼び出されたRTCPeerConnection オブジェクトとする。

2. connection.[[IsClosed]]が trueである場合、新たに作成されたInvalidStateErrorで 拒否された Promise を返す。

3. connectionを用いてアンサーを 作成する結果を、 connectionの操作チェーンにチェーンする結果を返す。

connectionを与えてアンサーを作成するには、 次の手順を実行する。

1. connection.[[SignalingState]] が "have-remote-offer" でも "have-local-pranswer" でもない場合、 新たに作成されたInvalidStateErrorで 拒否された Promise を返す。

2. pを新しい Promise とする。

3. 並行して、connectionと pを与えて、アンサーを作成する 並行手順を開始する。

4. pを返す。

connectionと Promise pを与えた場合の アンサーを作成する 並行手順は 次のとおりである。

1. connectionが証明書の集合を用いて構築されておらず、 まだ証明書が生成されていない場合、 生成されるまで待つ。

2. [RFC9429] （4.1.9 節）に記述されているように、 アンサーを生成するために必要な現在利用可能なリソースを 決定するため、アンサー側のシステム状態 を検査する。

3. この検査が何らかの理由で失敗した場合、新たに作成された OperationErrorで pを拒否し、 これらの手順を中止する。

4. pを与えて、アンサーを作成する 最終手順を実行するタスクをキューに入れる。

Promise pを与えた場合の アンサーを作成する最終手順は 次のとおりである。

1. connection.[[IsClosed]]が trueである場合、これらの手順を中止する。

2. connectionが、アンサー側のシステム状態を 追加で検査する必要があるように変更されている場合、 並行して、connectionとpを与えて アンサーを作成する 並行手順を再度開始し、これらの 手順を中止する。

   注記

   これは、たとえばRTCRtpTransceiverの direction が "recvonly" のときにcreateAnswer が呼び出されたものの、 アンサーを作成する 並行手順の実行中に direction が "sendrecv" に変更され、 映像エンコーディングリソースを追加で検査する必要が生じた場合などに必要となることがある。

3. 以前の検査から得られた情報と、 connectionおよびそのRTCRtpTransceiver群の現在の状態をもとに、 [RFC9429] （5.3 節）に記述されているように、 SDP アンサー sdpStringを生成する。

   候補修正 26:createAnswer() の encodings と sLD(answer) の SendEncodings を 削減する。 (PR #2801)

   候補修正 27:カンマ区切りの rid 代替候補を無視する。 (PR #2813)

   現在と将来を表示 現在を 表示将来を 表示

   1. m= セクションに関連付けられたトランシーバーの コーデック優先設定は、 RTCRtpTransceiver.[[PreferredCodecs]] に次のフィルタリングを適用した値であるとする （または[[PreferredCodecs]]が空の場合は未設定であるとする）。

      1. direction が "sendrecv" である場合、 RTCRtpSender.getCapabilities(kind).codecs と RTCRtpReceiver.getCapabilities(kind).codecs の共通部分に含まれないコーデックを除外する。

      2. direction が "sendonly" である場合、 RTCRtpSender.getCapabilities(kind).codecs に含まれないコーデックを除外する。

      3. direction が "recvonly" である場合、 RTCRtpReceiver.getCapabilities(kind).codecs に含まれないコーデックを除外する。

      フィルタリングはコーデック優先設定の 順序を変更してはならない（MUST NOT）。

   2. RTCRtpSender の[[SendEncodings]] スロットの長さが1より大きい場合、 RTCRtpSender の[[SendEncodings]] に与えられた各エンコーディングについて、 対応する メディアセクションにa=rid send行を追加し、 encodings フィールドに与えられた順序と同じ順序で RID を指定する a=simulcast:send行を追加する。RID の制限は設定しない。

   3. filteredCodecsを、 transceiver.[[PreferredCodecs]] に次のフィルターを適用した結果とする。 フィルタリングはコーデック 優先設定の順序を変更してはならない（MUST NOT）。

      1. kindをtransceiverの [[Receiver]]の [[ReceiverTrack]]の kindとする。

      2. transceiver.direction が "sendonly" または "sendrecv" である場合、kindについての 実装済み送信コーデックの リストに含まれないコーデックを除外する。 その際、コーデック 辞書一致 アルゴリズムを使用し、ignoreLevelsを trueに設定する。

      3. transceiver.direction が "recvonly" または "sendrecv" である場合、kindについての 実装済み受信コーデックの リストに含まれないコーデックを除外する。 その際、コーデック 辞書一致 アルゴリズムを使用し、ignoreLevelsを trueに設定する。

      メディア 記述に関連付けられたトランシーバー transceiverのコーデック優先設定は、 filteredCodecsが空でない場合はその値であるとし、 それ以外の場合は未設定であるとする。

   4. これがサイマルキャストの受信を求めるオファーへのアンサーである場合、 サイマルキャストの受信を要求する各メディアセクションについて、 次の手順を実行する。

      1. a=simulcast 属性に RID のカンマ区切りの代替候補が含まれている場合、 最初のもの以外をすべて削除する。

      2. a=simulcast属性に 同じ名前の RID がある場合、 最初のもの以外をすべて削除する。RID の制限は設定しない。

      3. アンサーのメディアセクションから、対応するトランシーバーの [[Sender]].[[SendEncodings]] に見つからない RID をすべて除外する。

      注記

      setRemoteDescription(offer) が送信側の提案された エンベロープを確立すると、 送信側の[[SendEncodings]] は "have-remote-offer" で更新され、 ロールバック可能になる。しかし、送信側について サイマルキャスト エンベロープが確立された後は、 送信側の[[SendEncodings]] の後続の削減は、このアンサーが setLocalDescription で設定されるときに行われる。

4. answerを、新たに作成した RTCSessionDescriptionInit 辞書とし、その type メンバーを文字列 "answer" で初期化し、 sdp メンバーを sdpStringで初期化する。

5. [[LastCreatedAnswer]] 内部スロットを sdpStringに設定する。

6. answerでpを解決する。

setLocalDescription

setLocalDescription メソッドは、 RTCPeerConnectionに、 指定された RTCLocalSessionDescriptionInit をローカル 記述として適用するよう指示する。

この API はローカルメディア状態を変更する。 アプリケーションが、あるメディア形式から別の互換性のない形式へ 変更することを提案しようとするシナリオを正常に処理するため、 RTCPeerConnectionは、 最終アンサーを受信するまで、現在のローカル記述と 保留中のローカル記述の両方を同時に使用できるよう サポートしなければならない（MUST）（たとえば、両方の記述に存在するコーデックをサポートする）。 最終アンサーを受信した時点で、RTCPeerConnectionは 保留中のローカル記述を完全に採用できる。または、 リモート側が変更を拒否した場合は現在の 記述へロールバックできる。

記述を渡すことは任意である。省略した場合、 setLocalDescription は必要に応じて暗黙的にオファーを作成するか、 アンサーを作成する。 [RFC9429] （5.4 節）で述べられているように、 SDP を含む記述が渡された場合、その SDP は、 createOfferまたは createAnswerから返された時点から 変更されていてはならない。

メソッドが呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

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

2. connectionを、メソッドが呼び出されたRTCPeerConnection オブジェクトとする。

3. sdpを description.sdp とする。

4. 次の手順を connectionの操作チェーンにチェーンする結果を返す。

   1. typeを、 description.type が存在する場合はその値とし、存在せず、 connection.[[SignalingState]] が "stable"、 "have-local-offer"、 または "have-remote-pranswer" のいずれかである場合は "offer" とし、それ以外の場合は "answer" とする。

   2. typeが "offer" であり、 sdpが空文字列ではなく、かつ connection.[[LastCreatedOffer]] と等しくない場合、新たに 作成された InvalidModificationError で拒否された Promise を返し、 これらの手順を中止する。

   3. typeが "answer" または "pranswer" であり、sdpが 空文字列ではなく、かつ connection.[[LastCreatedAnswer]] と等しくない場合、新たに 作成された InvalidModificationError で拒否された Promise を返し、 これらの手順を中止する。

   4. sdpが空文字列であり、 typeが "offer" である場合、次の サブ手順を実行する。

      1. sdpを connection.[[LastCreatedOffer]] の値に設定する。

      2. sdpが空文字列である場合、または connectionのオファー側の システム状態を もはや正確に表していない場合、pを connectionを用いてオファーを 作成する結果とし、 pに対して、最初の引数で示されるローカル セッション記述を設定する履行手順を用いて 反応する結果を返す。

   5. sdpが空文字列であり、 typeが "answer" または "pranswer" である場合、次の サブ手順を実行する。

      1. sdpを connection.[[LastCreatedAnswer]] の値に設定する。

      2. sdpが空文字列である場合、または connectionのアンサー側の システム状態を もはや正確に表していない場合、pを connectionを用いてアンサーを 作成する結果とし、 pに対して次の 履行手順を用いて 反応する結果を返す。

         1. answerを、これらの履行手順への 第1引数とする。

         2. {type, answer.sdp} で示されるローカル セッション記述を設定する結果を返す。

   6. {type, sdp}で示されるローカルセッション 記述を設定する結果を返す。

注記

[RFC9429] （5.9 節）で述べられているように、この メソッドを呼び出すと、ICE エージェントによる ICE 候補収集プロセスが開始されることがある。

setRemoteDescription

setRemoteDescription メソッドは、 RTCPeerConnectionに、 指定された RTCSessionDescriptionInit をリモートオファーまたは アンサーとして適用するよう指示する。この API はローカルメディア状態を変更する。

メソッドが呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

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

2. connectionを、メソッドが呼び出されたRTCPeerConnection オブジェクトとする。

3. 次の手順を connectionの操作チェーンにチェーンする結果を返す。

   1. もし description.type が "offer" であり、 かつ [RFC9429] （5.5 節および5.6 節）で説明されているように、 現在の connection.[[SignalingState]] に対して無効である場合、 次のサブステップを実行する。

      1. pを、 {type: "rollback"} で示されるローカル セッション記述を設定する結果とする。

      2. pに対して、descriptionを リモート セッション記述として設定する履行手順を用いて 反応する結果を返し、 これらの手順を中止する。

   2. descriptionをリモートセッション 記述として設定する結果を返す。

addIceCandidate

addIceCandidate メソッドは、リモート候補を ICE エージェントに提供する。このメソッドは、 candidateメンバーに 空文字列を指定して呼び出すことで、 リモート候補の終端を示すためにも使用できる。 このメソッドが使用する引数のメンバーは、 candidate、sdpMid、 sdpMLineIndex、 および usernameFragment のみであり、残りは無視される。 メソッドが呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

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

2. connectionを、メソッドが呼び出されたRTCPeerConnection オブジェクトとする。

3. candidate.candidate が空文字列ではなく、かつ candidate.sdpMidと candidate.sdpMLineIndex の両方がnullである場合、新たに作成されたTypeErrorで 拒否された Promise を返す。

4. 次の手順を connectionの操作チェーンにチェーンする結果を返す。

   1. remoteDescription が nullである場合、新たに作成された InvalidStateErrorで 拒否された Promise を返す。

   2. candidate.sdpMid がnullでない場合、次の手順を実行する。

      1. candidate.sdpMid が、 remoteDescription 内のいずれのメディア記述の mid とも等しくない場合、 新たに作成されたOperationErrorで 拒否された Promise を返す。

   3. それ以外の場合、candidate.sdpMLineIndex がnullでなければ、次の手順を実行する。

      1. candidate.sdpMLineIndex が remoteDescription 内のメディア記述の数以上である場合、 新たに作成されたOperationErrorで 拒否された Promise を返す。

   4. candidate.sdpMid または candidate.sdpMLineIndex のいずれかが、 remoteDescription 内の、関連付けられたトランシーバーがstoppedである メディア記述を示している場合、 undefinedで解決された Promise を返す。

   5. candidate.usernameFragment がnullでなく、かつ、適用されたリモート 記述の対応するメディア 記述内に存在するいずれの username fragment とも等しくない場合、 新たに作成されたOperationErrorで 拒否された Promise を返す。

   6. pを新しい Promise とする。

   7. 並行して、候補が管理上 禁止されていない場合、 [RFC9429] （4.1.19 節）に記述されているように、 ICE 候補candidateを追加する。 ICE の世代を識別するために candidate.usernameFragment を使用する。 usernameFragment が nullである場合、candidateを 最新の ICE 世代について処理する。

      candidate.candidate が空文字列である場合、candidateを、 対応するメディア記述と ICE 候補世代に対する 候補終端の指示として処理する。 candidate.sdpMid と candidate.sdpMLineIndex の両方がnullである場合、この候補終端 の指示はすべてのメディア記述に適用される。

      1. candidateを正常に 追加できなかった場合、ユーザーエージェントは 次の手順を実行するタスクをキューに入れなければならない（MUST）。

         1. connection.[[IsClosed]] がtrueである場合、これらの 手順を中止する。

         2. 新たに作成されたOperationError でpを拒否し、 これらの手順を中止する。

      2. candidateが正常に適用された場合、 または候補が管理上 禁止されていた場合、ユーザーエージェントは 次の手順を実行するタスクをキューに入れなければならない （MUST）。

         1. connection.[[IsClosed]] がtrueである場合、これらの 手順を中止する。

         2. connection.[[PendingRemoteDescription]] がnullでなく、 candidateが処理された ICE 世代を表す場合、 candidateを connection.[[PendingRemoteDescription]].sdp に追加する。

         3. connection.[[CurrentRemoteDescription]] がnullでなく、 candidateが処理された ICE 世代を表す場合、 candidateを connection.[[CurrentRemoteDescription]].sdp に追加する。

         4. undefinedで pを解決する。

   8. pを返す。

UA がこのアドレスへの接続試行を許可しないと 決定した場合、候補は管理上禁止されている。

プライバシー上の理由から、 アドレス／ポートがブロックされているかどうかについて 開発者に示される情報はなく、 そのアドレスから応答がなかった場合とまったく同じように動作する。

UA は、[Fetch] の不正なポートをブロックするリストにあるアドレスへの 接続を禁止しなければならず（MUST）、 その他のアドレスへの接続を 禁止することを選択してもよい（MAY）。

RTCConfigurationの iceTransportPolicy メンバーが relay である場合、mDNS 候補や DNS 候補など、外部での名前解決を必要とする候補は禁止されなければならない（MUST）。

注記

WebIDL 処理により、 addIceCandidate(null) はデフォルト辞書が存在する呼び出しとして 解釈される。これは上記のアルゴリズムでは、すべてのメディア記述と ICE 候補世代について候補の終端を示す。 これはレガシー上の理由から意図された設計である。

restartIce

restartIce メソッドは、ICE を再起動すべきことをRTCPeerConnection に通知する。後続の createOffer 呼び出しは、[RFC5245] の9.1.1.1節に記述されているように、 ICE を再起動する記述を作成する。

このメソッドが呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

1. connectionを、メソッドが呼び出されたRTCPeerConnection とする。

2. connection.[[LocalIceCredentialsToReplace]] を空にし、 connection.[[CurrentLocalDescription]] 内に見つかるすべての ICE 資格情報 （[RFC5245] の15.4節で定義される ice-ufrag および ice-pwd）と、 connection.[[PendingLocalDescription]] 内に見つかるすべての ICE 資格情報を そこに格納する。

3. connectionについてネゴシエーション必要 フラグを更新する。

getConfiguration

このRTCPeerConnectionオブジェクトの 現在の構成を表すRTCConfigurationオブジェクトを 返す。

このメソッドが呼び出された場合、ユーザーエージェントは、 [[Configuration]]内部 スロットに格納された RTCConfigurationオブジェクトを 返さなければならない（MUST）。

setConfiguration

setConfiguration メソッドは、この RTCPeerConnection オブジェクトの構成を更新する。 これには、ICE エージェントの構成の変更も含まれる。 [RFC9429] （3.5.1 節）で述べられているように、 ICE の構成が新たな収集フェーズを必要とするように 変更された場合、ICE の再起動が必要となる。

setConfiguration メソッドが呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

1. connectionを、メソッドが呼び出されたRTCPeerConnection とする。

2. connection.[[IsClosed]]が trueである場合、 InvalidStateErrorを 投げる。

3. configurationによって指定された構成を 設定する。

close

closeメソッドが 呼び出された場合、ユーザーエージェントは 次の手順を実行しなければならない（MUST）。

1. connectionを、メソッドが呼び出されたRTCPeerConnection オブジェクトとする。

2. connectionと値falseを用いて接続を閉じる。

connectionとdisappearブール値を与えた場合の 接続を閉じるアルゴリズムは、 次のとおりである。

1. connection.[[IsClosed]]が trueである場合、これらの手順を中止する。

2. connection.[[IsClosed]]を trueに設定する。

3. connection.[[SignalingState]] を "closed" に設定する。 これはいかなるイベントも発火しない。

4. transceiversを、 CollectTransceivers アルゴリズムを実行した結果とする。 transceivers内のすべての RTCRtpTransceiver transceiverについて、 次の手順を実行する。

   1. transceiver.[[Stopped]]が trueである場合、これらのサブ手順を中止する。

   2. transceiverとdisappearを用いて RTCRtpTransceiver を 停止する。

5. connectionの各RTCDataChannelの [[ReadyState]]スロットを "closed" に設定する。

   注記

   RTCDataChannel群は 即座に閉じられ、 クローズ手続きは呼び出されない。

6. connection.[[SctpTransport]]が nullでない場合、SCTP ABORT チャンクを送信して 基盤となる SCTP アソシエーションを破棄し、 [[SctpTransportState]] を "closed" に設定する。

7. connectionの各RTCDtlsTransportの [[DtlsTransportState]] スロットを "closed" に設定する。

8. connectionのICE エージェントを破棄し、 アクティブな ICE 処理を即座に終了して、 関連するリソース（たとえば TURN 権限）を解放する。

9. connectionの各RTCIceTransportの [[IceTransportState]] スロットを "closed" に設定する。

10. connection.[[IceConnectionState]] を "closed" に設定する。 これはいかなるイベントも 発火しない。

11. connection.[[ConnectionState]] を "closed" に設定する。 これはいかなるイベントも 発火しない。

constructor()

RTCSessionDescription() コンストラクタは辞書引数 description を受け取り、その内容で新しい RTCSessionDescription オブジェクトを初期化する。このコンストラクタは非推奨であり、レガシー互換性のためだけに存在する。

type (型: RTCSdpType), readonly

このセッション記述の種類。

sdp (型: DOMString), readonly, 既定値 ""

SDP [SDP] の文字列表現。

toJSON()

呼び出されたとき、[WEBIDL] の default toJSON steps を実行する。

type (型: RTCSdpType), required

このセッション記述の種類。

sdp (型: DOMString)

SDP [SDP] の文字列表現。 type が "rollback" の場合、このメンバーは使用されない。

type (型: RTCSdpType)

この記述の種類。指定されていない場合、 setLocalDescription は RTCPeerConnection の [[SignalingState]] に基づいて型を推論する。

sdp (型: DOMString)

SDP [SDP] の文字列表現。 type が "rollback" の場合、このメンバーは使用されない。

constructor()

RTCIceCandidate() コンストラクターは 辞書引数 candidateInitDict を受け取り、 その内容を使用して新しい RTCIceCandidate オブジェクトを初期化する。

呼び出された場合、次の手順を実行する。

1. candidateInitDict の sdpMid と sdpMLineIndex メンバーの両方が null である場合、投げる、TypeError を。

2. candidateInitDict を用いてRTCIceCandidate を 作成する 結果を返す。

candidateInitDict 辞書を用いてRTCIceCandidate を 作成するには、次の手順を実行する。

1. iceCandidate を新たに作成した RTCIceCandidate オブジェクトとする。
2. iceCandidate の次の属性について内部スロットを作成し、 null で初期化する。 foundation、 component、priority、address、 protocol、port、type、tcpType、 relatedAddress、 および relatedPort。
3. iceCandidate の次の属性について内部スロットを作成し、 candidateInitDict 内の同名の値で初期化する。candidate、sdpMid、 sdpMLineIndex、 usernameFragment。
4. candidate を、 candidateInitDict の candidate 辞書メンバーとする。candidate が 空文字列でない場合、次の手順を実行する。
   1. candidate-attribute 文法を使用して candidate を構文解析する。
   2. candidate-attribute の構文解析に失敗した場合、 これらの手順を中止する。
   3. 構文解析結果のいずれかのフィールドが、 iceCandidate 内の対応する属性に対して無効な値を表す場合、これらの手順を中止する。
   4. iceCandidate 内の対応する内部スロットを、 構文解析結果のフィールド値に 設定する。
5. iceCandidate を返す。

注記

RTCIceCandidate のコンストラクターは、 candidateInitDict 内の辞書メンバーについて基本的な 構文解析と型チェックのみを行う。 candidate、 sdpMid、 sdpMLineIndex、 usernameFragment と対応するセッション記述との 適格性に関する詳細な検証は、 RTCIceCandidate オブジェクトを addIceCandidate() に渡す際に行われる。

後方互換性を維持するため、 candidate 属性の構文解析時のエラーはすべて無視される。その 場合、candidate 属性は、 candidateInitDict で指定された未処理の candidate 文字列を保持するが、 foundation、 priority などの派生属性は null に設定される。

以下のほとんどの属性は [RFC5245] セクション 15.1 で定義される。

candidate 型 DOMString、readonly

これは [RFC5245] セクション 15.1 で定義される candidate-attribute を保持する。 この RTCIceCandidate が end-of-candidates 指示または peer reflexive リモート candidate を表す場合、 candidate は空文字列となる。

sdpMid 型 DOMString、readonly、nullable

null でない場合、これは該当候補が関連付けられるメディアコンポーネントの [RFC5888] で定義された メディアストリーム "identification-tag" を含む。

sdpMLineIndex 型 unsigned short、readonly、nullable

null でない場合、候補が対応する SDP 内の media description のインデックス（0 起算）を示す。

foundation 型 DOMString、readonly、nullable

複数の RTCIceTransport 上に出現する候補を ICE が相関付けるための一意識別子。

component 型 RTCIceComponent、 readonly、nullable

候補に割り当てられたネットワークコンポーネント ("rtp" または "rtcp")。 これは candidate-attribute の component-id フィールドに対応し、 RTCIceComponent で定義される文字列表現にデコードされる。

priority 型 unsigned long、readonly、nullable

候補に割り当てられた優先度。

address 型 DOMString、readonly、nullable

候補のアドレス。IPv4 / IPv6 アドレスおよび FQDN を許容。 これは candidate-attribute 内の connection-address フィールドに対応する。

リモート候補は、たとえば [[SelectedCandidatePair]].remote を介して公開されることがある。 デフォルトでは、ユーザーエージェントは、公開される すべてのリモート候補について address 属性をnullのままにしておかなければならない （MUST）。 RTCPeerConnection インスタンスが、 Web アプリケーションによる addIceCandidate の使用を通じてアドレスを認識すると、 ユーザーエージェントは、その新たに認識された アドレスを持つリモート候補を表す、 その RTCPeerConnection インスタンスの任意の RTCIceCandidateで address 属性値を公開できる。

Note

ICE により収集され RTCIceCandidate インスタンスとしてアプリケーションに渡されるアドレスは、 WebRTC 非対応ブラウザでユーザーが期待する以上の（例: 位置情報やローカルネットワークトポロジ）情報を デバイス・ユーザーについて漏らし得る。

これらのアドレスは常にアプリケーションおよび通信相手に公開され得るもので、 （データチャネルのみの接続や受信専用などにおいて）特別なユーザー同意無しに公開され得る。

これらのアドレスは一時的または永続的なクロスオリジン状態として利用され得、 デバイスのフィンガープリンティング面を増大させる。

通信相手にアドレスを公開しない（あるいは一時的に抑制する）ために、 アプリケーションは ICE Agent に リレー候補のみを iceTransportPolicy メンバを通じて強制することで可能であり、 これは RTCConfiguration の設定である。

アプリケーション自身に露出されるアドレスを制限するため、 ブラウザはユーザーにローカルアドレス共有ポリシーを選択できるようにでき、 これは [RFC8828] に定義される。

protocol 型 RTCIceProtocol、 readonly、nullable

候補のプロトコル ("udp"/"tcp")。これは candidate-attribute の transport フィールドに対応する。

port 型 unsigned short、readonly、nullable

候補のポート。

type 型 RTCIceCandidateType、 readonly、nullable

候補の種別。これは candidate-attribute の candidate-types フィールドに対応する。

tcpType 型 RTCIceTcpCandidateType、 readonly、nullable

protocol が "tcp" の場合、 tcpType は TCP 候補の種別を表す。 それ以外の場合 tcpType は null。 これは candidate-attribute の tcp-type フィールドに対応。

relatedAddress 型 DOMString、readonly、nullable

他の候補から導出された（例: relay や reflexive）候補において、 relatedAddress は元となる候補の IP アドレス。 host 候補では relatedAddress は null。これは candidate-attribute の rel-address フィールドに対応する。

relatedPort 型 unsigned short、readonly、nullable

他候補から導出された候補（relay / reflexive など）の場合、 relatedPort は元となる候補のポート。 host 候補では relatedPort は null。これは candidate-attribute の rel-port フィールドに対応。

usernameFragment 型 DOMString、readonly、nullable

これは [RFC5245] セクション 15.4 で定義される ufrag を保持する。

Candidate Addition 16:RTCIceCandidate.relayProtocol の追加 (PR #2763)

Show Current and Future Show CurrentShow Future

relayProtocol 型 RTCIceServerTransportProtocol、readonly、 nullable

ローカル候補が種別 "relay" の場合、 エンドポイントが TURN サーバと通信する際に使用したプロトコル。 それ以外の候補では null。

Candidate Addition 23:RTCIceCandidate.url の追加 (PR #2773)

Show Current and Future Show CurrentShow Future

url 型 DOMString、readonly、nullable

ローカル候補が種別 "srflx" または "relay" の場合、候補を取得した ICE サーバの URL。 それ以外の候補では null。

toJSON()

RTCIceCandidate インターフェイスの toJSON() 操作を呼び出すには、 次の手順を実行する。

1. jsonを新しい RTCIceCandidateInit 辞書とする。
2. «candidate, sdpMid, sdpMLineIndex, usernameFragment» 内の各属性識別子 attrについて、
   1. このRTCIceCandidate オブジェクトを与えて、 attrによって識別される属性の 基礎となる値を取得した結果をvalueとする。
   2. json[attr] をvalueに設定する。
3. jsonを返す。

candidate 型 DOMString、既定値 ""

これは [RFC5245] セクション 15.1 で定義される candidate-attribute を保持する。 end-of-candidates 指示を表す場合、 candidate は空文字列となる。

sdpMid 型 DOMString、nullable、既定値 null

null でない場合、 メディアストリーム "identification-tag" を保持する。

sdpMLineIndex 型 unsigned short、nullable、既定値 null

null でない場合、候補が対応する SDP 内の media description のインデックス（0 起算）を示す。

usernameFragment 型 DOMString、nullable、既定値 null

null でない場合、[RFC5245] セクション 15.4 で定義される ufrag を保持する。

RTCPeerConnectionIceEvent.constructor()

candidate 型 RTCIceCandidate、 readonly、nullable

candidate 属性はイベントを引き起こした新しい ICE 候補を持つ RTCIceCandidate オブジェクト。

候補収集終了を示すイベントでは、この属性は null に設定される。

Note

複数メディアコンポーネントがあっても、null 候補を含むイベントは一度だけ発火する。

url 型 DOMString、readonly、nullable

url 属性は、 その候補を収集した STUN または TURN サーバを識別する STUN/TURN URL。 STUN/TURN サーバから収集されていない候補では null。

Candidate Correction 23:RTCPeerConnectionIceEvent.url を非推奨化 (PR #2773)

Show Current and Future Show CurrentShow Future

この属性は非推奨であり、レガシー互換性のためだけに存在する。候補の url を利用すること。

candidate 型は RTCIceCandidate、 nullable

RTCPeerConnectionIceEvent インターフェイスの candidate 属性を参照。

url 型は DOMString、nullable

url 属性は、 この候補の収集に使用された STUN または TURN サーバーを識別する STUN または TURN URL である。

RTCPeerConnectionIceErrorEvent.constructor()

address 型 DOMString、readonly、nullable

address 属性は STUN または TURN サーバとの通信に用いられたローカル IP アドレスである。

マルチホーム環境では複数のインターフェイスがサーバ接続に使用され得るため、この属性によりどのインターフェイスで失敗が起きたかをアプリケーションが把握できる。

ローカル IP アドレス値がまだローカル候補の一部として公開されていない場合、 address 属性は null に設定される。

port 型 unsigned short、readonly、nullable

port 属性は STUN または TURN サーバとの通信に使用されたポートである。

address 属性が null の場合、 port 属性も null に設定される。

url 型 DOMString、readonly

url 属性は障害が発生した STUN または TURN サーバを識別する STUN/TURN URL である。

errorCode 型 unsigned short、readonly

errorCode 属性は STUN または TURN サーバから返された数値 STUN エラーコード [STUN-PARAMETERS] である。

いずれの host candidate もサーバに到達できない場合、 errorCode は STUN エラーコード範囲外の値 701 に設定される。このエラーは RTCIceGatheringState が "gathering" の間、サーバ URL ごとに一度だけ発火する。

errorText 型 USVString、readonly

errorText 属性は STUN または TURN サーバから返された STUN reason text [STUN-PARAMETERS] である。

サーバに到達できなかった場合、 errorText はエラーの詳細を示す実装依存の値に設定される。

address 型 DOMString、nullable

STUN または TURN サーバとの通信に使用されたローカルアドレス。あるいは null。

port 型 unsigned short、nullable

STUN または TURN サーバとの通信に使用されたローカルポート。あるいは null。

url 型 DOMString

障害が発生した STUN または TURN サーバを識別する STUN/TURN URL。

errorCode 型 unsigned short、required

STUN または TURN サーバから返された数値 STUN エラーコード。

errorText 型 USVString

STUN または TURN サーバから返された STUN reason text。