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 メソッドは SDP のブロブを生成し、そこにはサポートされているセッション構成 (この RTCPeerConnection にアタッチされたローカル MediaStreamTrack の記述、実装がサポートする codec/RTP/RTCP 能力、 さらに ICE agent と DTLS 接続のパラメータを含む) を持つ RFC 3264 の offer が含まれる。 options 引数を与えて生成される offer を追加制御できる。

システムが限られたリソース (例: デコーダ数が有限) の場合、 createOffer はシステムの現在の状態を反映する offer を返す必要がある。これは setLocalDescription がそれらのリソース取得を試みる際に成功するためである。セッション記述は、返された Promise の fulfillment コールバックの終了時点までは setLocalDescription でエラーを引き起こすことなく使用可能でなければならない (MUST)。

SDP の生成は [RFC9429] に記述された offer 生成手順に従わなければならない (MUST)。 ただし、このケースではユーザーエージェントは stopping トランシーバを RFC9429 の目的において stopped とみなさなければならない (MUST)。

offer であるため、生成された SDP はセッションがサポートまたは優先する codec/RTP/RTCP 能力の完全な集合を含む (answer は使用する特定のネゴシエート済みサブセットのみを含むのとは対照)。セッション確立後に createOffer が呼び出された場合、 createOffer は現在のセッションと互換性のある offer を生成し、トラックの追加や削除など最後の完全な offer-answer 交換以降に行われた変更を取り込む。 変更がない場合、offer には現在のローカル記述の能力と、更新された offer でネゴシエート可能な追加の能力が含まれる。

生成された SDP には ICE agent の usernameFragment、 password および ICE オプション ([RFC5245] セクション 14 で定義) が含まれ、さらにエージェントによって収集済みのローカル candidate が含まれる場合がある。

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

SDP を生成する過程は基盤となるシステムのメディア能力のサブセットを公開し、デバイス上の一般に持続的でクロスオリジンな情報を提供する。 これはアプリケーションのフィンガープリンティング表面を増やす。プライバシー重視の文脈では、ブラウザは共通サブセットの能力にのみ一致する SDP を生成するなどの緩和策を検討できる。

メソッドが呼ばれたとき、ユーザーエージェントは次の手順を実行しなければならない (MUST):

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

2. もし connection.[[IsClosed]] が true なら、Promise を新規に rejected 状態で返し、 新たに 作成された InvalidStateError を与える。

3. chaining の結果を、 creating an offer を connection で行った結果と connection の operations chain に対して実行したものとして返す。

connection を与えて create an offer するには次の手順を行う:

1. もし connection.[[SignalingState]] が "stable" でも "have-local-offer" でもないなら、 新たに 作成された InvalidStateError で Promise を rejected にして返す。

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

3. 並行して (In parallel)、 in-parallel steps to create an offer を connection と p を与えて開始する。

4. p を返す。

connection と Promise p を与えた in-parallel steps to create an offer は次の通り:

1. もし connection が証明書集合なしで構築され、かつ証明書がまだ生成されていないなら、 生成されるまで待機する。

2. オファラーのシステム状態 を検査し、 offer 生成に必要な現在利用可能なリソースを確定する。 これは [RFC9429] (セクション 4.1.8.) に記述されている。

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

4. タスクをキューし、connection と p を与えて final steps to create an offer を実行する。

connection と Promise p を与えた final steps to create an offer は次の通り:

1. もし connection.[[IsClosed]] が true なら、これらの手順を中止する。

2. もし connection が変更され、その結果として オファラーのシステム状態 の追加検査が必要になったなら、 並行して 再び in-parallel steps to create an offer を connection と p を与えて開始し、これらの手順を中止する。

   Note

   例えば、createOffer が audio のみの RTCRtpTransceiver だけが connection に追加された状態で呼ばれたが、 in-parallel steps to create an offer の実行中に video RTCRtpTransceiver が追加され、追加のビデオリソース検査が必要になる場合が該当する。

3. 以前の検査で得た情報、connection の現在の状態、およびその RTCRtpTransceiver 群の状態を用いて、 [RFC9429] (セクション 5.2.) に記述されるように SDP offer sdpString を生成する。

   1. [RFC8843] (セクション 7) に記載のとおり、バンドル ( RTCBundlePolicy 参照) が使用される場合、 BUNDLE グループをネゴシエートするために offerer tagged m= セクションを選択する必要がある。 ユーザーエージェントは MUST、 set of transceivers における最初の非 stopped トランシーバに対応する m= セクションを offerer tagged m= セクションとして選ぶ。 これによりリモートエンドポイントは SDP をパースせずにどのトランシーバが offerer tagged m= セクションか予測できる。

   2. filteredCodecs を、 transceiver.[[PreferredCodecs]] に以下のフィルタを適用した結果とする。フィルタはコーデックの順序を変更してはならない (MUST NOT)。

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

      3. もし transceiver.direction が "sendonly" または "sendrecv" の場合、 kind の list of implemented send codecs に含まれていないコーデックを除外する。 その際 codec dictionary match アルゴリズムを ignoreLevels を true に設定して使用する。

      4. もし transceiver.direction が "recvonly" または "sendrecv" の場合、 kind の list of implemented receive codecs に含まれていないコーデックを除外する。 その際 codec dictionary match アルゴリズムを ignoreLevels を true に設定して使用する。

      media description の associated なトランシーバ transceiver の codec preferences は、 filteredCodecs が空でない場合その値であり、 空の場合は未設定 (unset) とされる。

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

      Note

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

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

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

6. Resolve p を offer で行う。

createAnswer

createAnswer メソッドは、リモート構成内のパラメータと互換性があり、セッションに対してサポートされる構成を持つ [SDP] の answer を生成する。 createOffer と同様に、 返される SDP のブロブには、この RTCPeerConnection にアタッチされたローカル MediaStreamTrack の記述、 このセッションについてネゴシエートされた codec/RTP/RTCP オプション、 そして ICE Agent によって収集済みのあらゆる candidate が含まれる。 options 引数を与えることで生成される answer への追加制御を行える。

createOffer と同様に、 返される記述はシステムの現在の状態を反映することが望ましい (SHOULD)。 セッション記述は、返された Promise の fulfillment コールバックの終了時点までは エラーを引き起こすことなく setLocalDescription で使用可能でなければならない (MUST)。

answer であるため、生成された SDP には、対応する offer と共にメディアプレーンをどのように確立するかを指定する 特定の codec/RTP/RTCP 構成が含まれる。SDP の生成は [RFC9429] に記述された answer 生成の適切な手順に従わなければならない (MUST)。

生成された SDP にはまた、ICE agent の usernameFragment、 password、および ICE オプション ([RFC5245] セクション 14) が含まれ、 さらにエージェントが収集したローカル candidate を含む場合がある。

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

answer は [RFC9429] (section 4.1.10.1.) に記述されるように、 type を "pranswer" に設定することで 暫定 (provisional) としてマークできる。

メソッドが呼ばれたとき、ユーザーエージェントは以下の手順を実行しなければならない (MUST):

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

2. もし connection.[[IsClosed]] が true なら、新規に 作成された InvalidStateError で rejected された Promise を返す。

3. chaining の結果を返す。 これは creating an answer を connection で実行した結果を connection の operations chain に連結したものである。

connection を与えた create an answer の手順:

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

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

3. 並行して (In parallel)、 in-parallel steps to create an answer を connection と p を与えて開始する。

4. p を返す。

connection と Promise p を与えた in-parallel steps to create an answer は次の通り:

1. もし connection が証明書集合なしで構築され、証明書がまだ生成されていなければ、 生成されるまで待機する。

2. アンサラーのシステム状態 を検査し、 answer 生成に必要な現在利用可能なリソースを特定する。 これは [RFC9429] (section 4.1.9.) に記述される。

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

4. タスクをキューし、 final steps to create an answer を p を与えて実行する。

Promise p を与えた final steps to create an answer は次の通り:

1. もし connection.[[IsClosed]] が true なら、これらの手順を中止する。

2. もし connection が変更され、 アンサラーのシステム状態 の追加検査が必要になった場合、 並行して in-parallel steps to create an answer を connection と p を与えて再実行し、これらの手順を中止する。

   Note

   例えば createAnswer が、ある RTCRtpTransceiver の direction が "recvonly" のときに呼ばれたが、 in-parallel steps to create an answer の実行中にその direction が "sendrecv" に変更され、 追加のビデオエンコードリソース検査が必要になった場合などが該当する。

3. 以前の検査で得られた情報、および connection とその RTCRtpTransceiver 群の現在の状態から、 [RFC9429] (section 5.3.) に記述されるように SDP answer sdpString を生成する。

   Candidate Correction 26:createAnswer() の encodings と SendEncodings を sLD(answer) で刈り込む。 (PR #2801)

   Candidate Correction 27:RID のカンマ区切り代替を無視する。 (PR #2813)

   現行と将来を表示 現行を表示将来を表示

   1. m= セクションの関連付けられたトランシーバの codec preferences は、 RTCRtpTransceiver.[[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. もし [[SendEncodings]] スロットの長さが RTCRtpSender で 1 より大きいなら、[[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 の list of implemented send codecs に含まれないコーデックを除外する。 その際 codec dictionary match アルゴリズムを ignoreLevels を true に設定して使用する。

      3. もし transceiver.direction が "recvonly" または "sendrecv" の場合、 kind の list of implemented receive codecs に含まれないコーデックを除外する。 その際 codec dictionary match アルゴリズムを ignoreLevels を true に設定して使用する。

      media description の associated なトランシーバ transceiver の codec preferences は、 filteredCodecs が空でない場合その値、 空の場合は未設定 (unset) とされる。

   4. これが受信側 simulcast を提案する offer に対する answer である場合、 simulcast の受信を要求する各メディアセクションについて次を実行する:

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

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

      3. 対応するトランシーバの [[Sender]].[[SendEncodings]] に存在しない RID を、 answer のメディアセクションから除外する。

      Note

      setRemoteDescription(offer) が sender の proposed envelope を確立すると、 sender の [[SendEncodings]] は "have-remote-offer" で更新され、 rollback へ曝される。しかし一度 sender の simulcast envelope が確立されると、 その後の sender の [[SendEncodings]] の刈り込み (pruning) は、 この answer が setLocalDescription により設定されたときに行われる。

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

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

6. Resolve p を answer で行う。

setLocalDescription

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

この API はローカルメディア状態を変更する。アプリケーションがあるメディアフォーマットから互換性のない別のフォーマットへ変更する提案を行いたいシナリオを正常に扱うために、 RTCPeerConnection は、最終的な answer を受信するまで現在と pending の両方のローカル記述（例: 両方の記述に存在するコーデックのサポート）を同時に利用可能な形で保持できなければならない (MUST)。最終的な answer を受信した時点で、 RTCPeerConnection は pending のローカル記述を完全に採用するか、リモート側が変更を拒否した場合は現在の記述へロールバックできる。

description を引数に渡すことは任意である。省略された場合、 setLocalDescription は必要に応じて暗黙的に create an offer または create an answer を行う。 [RFC9429] (section 5.4.) に記載されているように、SDP を含む記述が渡された場合、その SDP は createOffer または createAnswer から返された時点から変更されていてはならない。

メソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければならない (MUST):

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

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

3. sdp を description.sdp とする。

4. 次の手順を connection の operations chain に対して chaining した結果を返す:

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

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

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

   4. もし sdp が空文字列かつ type が "offer" なら、次のサブ手順を実行する:

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

      2. もし sdp が空文字列であるか、またはもはや offerer's system state を正確に表していないなら、 p を creating an offer を connection で実行した結果とし、 p への reacting の結果を返す。その fulfillment 手順では最初の引数が示す sets the local session description を行う。

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

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

      2. もし sdp が空文字列であるか、またはもはや answerer's system state を正確に表していないなら、 p を creating an answer を connection で実行した結果とし、 p への reacting の結果を次の fulfillment 手順で返す:

         1. answer をこれらの fulfillment 手順への最初の引数とする。

         2. setting the local session description を {type, answer.sdp} で示されるものについて実行した結果を返す。

   6. {type, sdp} で示される setting the local session description の結果を返す。

Note

[RFC9429] (section 5.9.) に記載されているように、このメソッドを呼び出すことは ICE Agent による ICE candidate 収集プロセスをトリガーする場合がある。

setRemoteDescription

setRemoteDescription メソッドは RTCPeerConnection に対し、与えられた RTCSessionDescriptionInit をリモートの offer または answer として適用するよう指示する。この API はローカルのメディア状態を変更する。

メソッドが呼ばれたとき、ユーザーエージェントは以下の手順を実行しなければならない (MUST):

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

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

3. 以下の手順を connection の operations chain に chaining した結果を返す:

   1. もし description.type が "offer" であり、 現在の connection.[[SignalingState]] に対して [RFC9429] (section 5.5. および section 5.6.) に記述される通り不正である場合、次のサブ手順を実行する:

      1. p を setting the local session description を {type: "rollback"} で示した結果とする。

      2. p への reacting の結果を返す。fulfillment 手順では description を sets the remote session description として設定し、これらの手順を中止する。

   2. setting the remote session description description の結果を返す。

addIceCandidate

addIceCandidate メソッドはリモート candidate を ICE Agent に提供する。このメソッドは candidate メンバに空文字列を渡して呼び出すことで、リモート candidate の終端を示すためにも使用できる。 このメソッドが利用する引数のメンバは candidate、 sdpMid、 sdpMLineIndex、 および usernameFragment のみであり、他は無視される。 メソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければならない (MUST):

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

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

3. もし candidate.candidate が空文字列でなく、かつ candidate.sdpMid と candidate.sdpMLineIndex の両方が null なら、新たに 作成された TypeError で Promise を rejected にして返す。

4. 以下の手順を connection の operations chain に chaining した結果を返す:

   1. もし remoteDescription が null なら、新たに 作成された InvalidStateError で Promise を rejected にして返す。

   2. もし candidate.sdpMid が null でないなら、以下の手順を実行する:

      1. もし candidate.sdpMid が remoteDescription 内のいずれのメディア記述の mid とも一致しないなら、新たに 作成された OperationError で Promise を rejected にして返す。

   3. そうでなく、candidate.sdpMLineIndex が null でないなら、以下の手順を実行する:

      1. もし candidate.sdpMLineIndex が remoteDescription 内のメディア記述数以上であるなら、新たに 作成された OperationError で Promise を rejected にして返す。

   4. もし candidate.sdpMid または candidate.sdpMLineIndex が remoteDescription 内の、対応するトランシーバが stopped であるメディア記述を指しているなら、 undefined で resolved された Promise を返す。

   5. もし candidate.usernameFragment が null でなく、適用済みリモート記述の対応する media description 内に存在する任意の username fragment と一致しないなら、新たに 作成された OperationError で Promise を rejected にして返す。

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

   7. 並行して、candidate が administratively prohibited でない場合、[RFC9429] (section 4.1.19.) に記述される通り ICE candidate candidate を追加する。 candidate.usernameFragment を用いて ICE の generation を識別する。 もし usernameFragment が null なら、最新の ICE generation に対して candidate を処理する。

      もし candidate.candidate が空文字列である場合、candidate を対応する media description および ICE candidate generation の end-of-candidates 指示として処理する。 もし candidate.sdpMid と candidate.sdpMLineIndex が両方とも null の場合、この end-of-candidates 指示はすべての media description に適用される。

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

         1. もし connection.[[IsClosed]] が true なら、これらの手順を中止する。

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

      2. もし candidate が正常に適用されたか、または candidate が administratively prohibited であった場合、ユーザーエージェントは次の手順を実行するタスクをキューしなければならない (MUST):

         1. もし connection.[[IsClosed]] が true なら、これらの手順を中止する。

         2. もし connection.[[PendingRemoteDescription]] が null でなく、 candidate が処理された ICE generation を表すなら、 candidate を connection.[[PendingRemoteDescription]].sdp に追加する。

         3. もし connection.[[CurrentRemoteDescription]] が null でなく、 candidate が処理された ICE generation を表すなら、 candidate を connection.[[CurrentRemoteDescription]].sdp に追加する。

         4. Resolve p を undefined で行う。

   8. p を返す。

candidate は、UA がそのアドレスへの接続試行を許可しないと判断した場合、 administratively prohibited である。

プライバシー上の理由から、アドレス / ポートがブロックされているかどうかについて開発者には何の手掛かりも与えられず、 そのアドレスから応答がない場合と全く同じ挙動となる。

UA は [Fetch] の block bad port リスト上のアドレスへの接続を禁止しなければならない (MUST)。 また他のアドレスへの接続を禁止することもできる (MAY)。

もし iceTransportPolicy メンバが relay である RTCConfiguration の場合、 mDNS candidate や DNS candidate のような外部解決を要する candidate は禁止されなければならない (MUST)。

Note

WebIDL の処理上、 addIceCandidate(null) はデフォルト辞書が存在する呼び出しとして解釈され、上記アルゴリズムではすべてのメディア記述および ICE candidate generation に対する end-of-candidates を示す。 これはレガシー上の理由による設計である。

restartIce

restartIce メソッドは、RTCPeerConnection に ICE をリスタートすべきであることを指示する。続く createOffer の呼び出しは、[RFC5245] セクション 9.1.1.1 に記述されるように ICE をリスタートする記述を生成する。

このメソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければならない (MUST):

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

2. connection.[[LocalIceCredentialsToReplace]] を空にし、[RFC5245] セクション 15.4 で定義されるすべての ICE 資格情報 (ice-ufrag と ice-pwd) のうち、 connection.[[CurrentLocalDescription]] に存在するもの、ならびに connection.[[PendingLocalDescription]] に存在するものをすべて追加して埋める。

3. connection について negotitation-needed フラグを更新する。

getConfiguration

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

このメソッドが呼び出されたとき、ユーザーエージェントは RTCConfiguration オブジェクトで、 [[Configuration]] 内部スロットに格納されているものを返さなければならない (MUST)。

setConfiguration

setConfiguration メソッドはこの RTCPeerConnection オブジェクトの構成を更新する。これには ICE Agent の構成変更が含まれる。 [RFC9429] (section 3.5.1.) に記載されるように、ICE 構成が新たな収集フェーズを必要とする形で変化した場合、ICE リスタートが必要となる。

setConfiguration メソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければならない (MUST):

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

2. もし connection.[[IsClosed]] が true なら、 throw InvalidStateError を投げる。

3. 指定された構成を設定 (引数 configuration) する。

close

close メソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければならない (MUST):

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

2. close the connection を connection と値 false で実行する。

close the connection アルゴリズム (引数: connection, 真偽値 disappear) は次の通り:

1. もし connection.[[IsClosed]] が true なら、これらの手順を中止する。

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

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

4. transceivers を CollectTransceivers アルゴリズムの実行結果とする。各 RTCRtpTransceiver transceiver について以下の手順を実行する:

   1. もし transceiver.[[Stopped]] が true なら、これらのサブ手順を中止する。

   2. Stop the RTCRtpTransceiver を transceiver と disappear を与えて実行する。

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

   Note

   RTCDataChannel は即座に閉じられ、closing 手順は呼び出されない。

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

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

8. connection の ICE Agent を破棄し、進行中の ICE 処理を即座に終了し関連リソース (例: TURN permission) を解放する。

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 の場合、throw で TypeError を投げる。

2. RTCIceCandidate の作成 を candidateInitDict で行った結果を返す。

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 を candidate 辞書メンバとし、candidate が空文字列でない場合以下を実行する:
   1. candidate を candidate-attribute 文法でパースする。
   2. candidate-attribute のパースに失敗した場合、これらの手順を中止する。
   3. パース結果内の任意のフィールドが iceCandidate の対応属性に対し不正な値を表す場合、これらの手順を中止する。
   4. iceCandidate の対応する内部スロットをパース結果の値に設定する。
5. iceCandidate を返す。

Note

RTCIceCandidate のコンストラクタは candidateInitDict 内辞書メンバに対して基本的な構文解析と型確認のみを行う。 candidate, sdpMid, sdpMLineIndex, usernameFragment の整形式性に関する詳細な検証は、 RTCIceCandidate オブジェクトを addIceCandidate() に渡す際に行われる。

後方互換性維持のため、candidate 属性のパースエラーは無視される。 その場合 candidate 属性には candidateInitDict で与えられた生の文字列が保持され、 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 する。 ウェブアプリが addIceCandidate を使ってアドレスを学習した後は、 ユーザーエージェントはそのアドレスを持つリモート候補を表す いずれの 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()

toJSON() 操作を呼び出すため、以下の手順を実行する:

1. json を新しい RTCIceCandidateInit 辞書とする。
2. 属性識別子 attr を «candidate, sdpMid, sdpMLineIndex, usernameFragment» それぞれについて:
   1. attr で識別される属性の基礎値を、この RTCIceCandidate オブジェクトに対して取得し 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

candidate 属性を参照。

url 型 DOMString、nullable

候補を収集した 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。