RTCPeerConnection

Borrador

Esta página no está completa.

La interfaz RTCPeerConnection representa una conexión WebRTC entre un computador local y un par remoto (otro computador). Esta interfaz provee métodos para: conectar un equipo remoto (remote peer), mantener y monitorear esa coneexión y cerrar la conexión una vez que no se necesite más.

RTCPeerConnection y RTCSessionDescription (en-US) aún están prefijados en algunos navegadores. Se recomienda encarecidamente usar una librería de ajuste (shim) como la excelente y ampliamente soportada Adapter.js, para asegurar la compatibilidad más amplia posible de su sitio o aplicación web. Vale la pena señalar que Adapter.js va más allá del manejo de prefijos, esta librería implementa ajustes (shims) para asegurar la compatibilidad entre las distintas implementaciones de WebRTC de los distintos navegadores.

Método obsoleto

El siguiente método fue declarado obsoleto ya hace un tiempo, admás, nunca fue implementado en los navegadores más importantes.

RTCPeerConnection.createDTMFSender() This is an obsolete API and is no longer guaranteed to work.
Crea un nuevo RTCDTMFSender (en-US), que se asocia a un MediaStreamTrack específico, that will be able to send DTMF (en-US) phone signaling over the connection.

Constantes

RTCBundlePolicy enum

The RTCBundlePolicy enum defines string constants which are used to request a specific policy for gathering ICE candidates if the remote peer isn't compatible with the SDP BUNDLE standard for bundling multiple media streams on a single transport link.

In technical terms, a BUNDLE lets all media flow between two peers flow across a single 5-tuple; that is, from the same IP and port on one peer to the same IP and port on the other peer, using the same transport protocol.

Constant Description
"balanced" On BUNDLE-aware connections, the ICE agent should gather candidates for all of the media types in use (audio, video, and data). Otherwise, the ICE agent should only negotiate one audio and video track on separate transports.
"max-compat" The ICE agent should gather candidates for each track, using separate transports to negotiate all media tracks for connections which aren't BUNDLE-compatible.
"max-bundle" The ICE agent should gather candidates for just one track. If the connection isn't BUNDLE-compatible, then the ICE agent should negotiate just one media track.

RTCIceConnectionState enum

The RTCIceConnectionState enum defines the string constants used to describe the current state of the ICE agent and its connection to the ICE server (that is, the STUN (en-US) or TURN (en-US) server).

Constant Description
"new" The ICE agent is gathering addresses or is waiting to be given remote candidates through calls to RTCPeerConnection.addIceCandidate() (en-US) (or both).
"checking" The ICE agent has been given one or more remote candidates and is checking pairs of local and remote candidates against one another to try to find a compatible match, but has not yet found a pair which will allow the peer connection to be made. It's possible that gathering of candidates is also still underway.
"connected" A usable pairing of local and remote candidates has been found for all components of the connection, and the connection has been established. It's possible that gathering is still underway, and it's also possible that the ICE agent is still checking candidates against one another looking for a better connection to use.
"completed" The ICE agent has finished gathering candidates, has checked all pairs against one another, and has found a connection for all components.
"failed" The ICE candidate has checked all candidates pairs against one another and has failed to find compatible matches for all components of the connection. It is, however, possible that the ICE agent did find compatible connections for some components.
"disconnected" Checks to ensure that components are still connected failed for at least one component of the RTCPeerConnection. This is a less stringent test than "failed" and may trigger intermittently and resolve just as spontaneously on less reliable networks, or during temporary disconnections. When the problem resolves, the connection may return to the "connected" state.
"closed" The ICE agent for this RTCPeerConnection has shut down and is no longer handling requests.

RTCIceGatheringState enum

The RTCIceGatheringState enum defines string constants which reflect the current status of ICE gathering, as returned using the RTCPeerConnection.iceGatheringState (en-US) property. You can detect when this value changes by watching for an event of type icegatheringstatechange.

Constant Description
"new" The peer connection was just created and hasn't done any networking yet.
"gathering" The ICE agent is in the process of gathering candidates for the connection.
"complete" The ICE agent has finished gathering candidates. If something happens that requires collecting new candidates, such as a new interface being added or the addition of a new ICE server, the state will revert to "gathering" to gather those candidates.

RTCIceTransportPolicy enum

The RTCIceTransportPolicy enum defines string constants which can be used to limit the transport policies of the ICE candidates to be considered during the connection process.

Constant Description
"all" All ICE candidates will be considered.
"public" This is an obsolete API and is no longer guaranteed to work. Only ICE candidates with public IP addresses will be considered. Removed from the specification's May 13, 2016 working draft.
"relay" Only ICE candidates whose IP addresses are being relayed, such as those being passed through a TURN server, will be considered.

RTCPeerConnectionState enum

The RTCPeerConnectionState enum defines string constants which describe states in which the RTCPeerConnection may be. These values are returned by the connectionState (en-US) property. This state essentially represents the aggregate state of all ICE transports (which are of type RTCIceTransport (en-US) or RTCDtlsTransport (en-US)) being used by the connection.

Constant Description
"new" At least one of the connection's ICE transports (RTCIceTransport (en-US)s or RTCDtlsTransport (en-US)s) are in the "new" state, and none of them are in one of the following states: "connecting", "checking", "failed", or "disconnected", or all of the connection's transports are in the "closed" state.
"connecting" One or more of the ICE transports are currently in the process of establishing a connection; that is, their RTCIceConnectionState is either "checking" or "connected", and no transports are in the "failed" state. <<< Make this a link once I know where that will be documented
"connected" Every ICE transport used by the connection is either in use (state "connected" or "completed") or is closed (state "closed"); in addition, at least one transport is either "connected" or "completed".
"disconnected" At least one of the ICE transports for the connection is in the "disconnected" state and none of the other transports are in the state "failed", "connecting", or "checking".
"failed" One or more of the ICE transports on the connection is in the "failed" state.
"closed"

The RTCPeerConnection is closed.

This value was in the RTCSignalingState enum (and therefore found by reading the value of the signalingState (en-US)) property until the May 13, 2016 draft of the specification.

RTCRtcpMuxPolicy enum

The RTCRtcpMuxPolicy enum defines string constants which specify what ICE candidates are gathered to support non-multiplexed RTCP. <<<add a link to info about multiplexed RTCP.

Constant Description
"negotiate" Instructs the ICE agent to gather both RTP (en-US) and RTCP (en-US) candidates. If the remote peer can multiplex RTCP, then RTCP candidates are multiplexed atop the corresponding RTP candidates. Otherwise, both the RTP and RTCP candidates are returned, separately.
"require" Tells the ICE agent to gather ICE candidates for only RTP, and to multiplex RTCP atop them. If the remote peer doesn't support RTCP multiplexing, then session negotiation fails.

RTCSignalingState enum

The RTCSignalingState enum specifies the possible values of RTCPeerConnection.signalingState (en-US), which indicates where in the process of signaling the exchange of offer and answer the connection currently is.

Constant Description
"stable" There is no ongoing exchange of offer and answer underway. This may mean that the RTCPeerConnection object is new, in which case both the localDescription (en-US) and remoteDescription (en-US) are null; it may also mean that negotiation is complete and a connection has been established.
"have-local-offer" The local peer has called RTCPeerConnection.setLocalDescription() (en-US), passing in SDP representing an offer (usually created by calling RTCPeerConnection.createOffer() (en-US)), and the offer has been applied successfully.
"have-remote-offer" The remote peer has created an offer and used the signaling server to deliver it to the local peer, which has set the offer as the remote description by calling RTCPeerConnection.setRemoteDescription() (en-US).
"have-local-pranswer" The offer sent by the remote peer has been applied and an answer has been created (usually by calling RTCPeerConnection.createAnswer() (en-US)) and applied by calling RTCPeerConnection.setLocalDescription() (en-US). This provisional answer describes the supported media formats and so forth, but may not have a complete set of ICE candidates included. Further candidates will be delivered separately later.
"have-remote-pranswer" A provisional answer has been received and successfully applied in response to an offer previously sent and established by calling setLocalDescription().
"closed" This is an obsolete API and is no longer guaranteed to work.

The connection is closed.

This value moved into the RTCPeerConnectionState enum in the May 13, 2016 draft of the specification, as it reflects the state of the RTCPeerConnection, not the signaling connection. You now detect a closed connection by checking for connectionState (en-US) to be "closed" instead.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
La definición de 'RTCPeerConnection' en esta especificación.
Candidate Recommendation Initial definition.

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help! (en-US)
Feature Chrome Edge Firefox (Gecko) Internet Explorer Microsoft Edge Opera Safari (WebKit)
Basic support (Yes)-webkit (en-US)
56 (unprefixed)
(Yes) 22 (22)
-moz (en-US) until Firefox 44
? ? ? ?
addTrack() Sin soporte ? 45 (45) [1] ? ? ? ?
iceConnectionState: disconnected 48 ? 52 (52) ? ? ? ?
onicegatheringstatechange 59 ? ? ? ? ? ?
removeTrack() Sin soporte ? (Yes)[2] ? ? ? ?
Feature Android Webview Chrome for Android Edge Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support (Yes)-webkit (en-US)
56 (unprefixed)
(Yes)-webkit (en-US)
56 (unprefixed)
(Yes) 22 (22)
-moz (en-US) until Firefox 44
22 ? ? ?
addTrack() Sin soporte Sin soporte ? 45 (45) ? ? ?  
iceConnectionState: disconnected 48 48 ? 52 (52) Sin soporte ? ? ?
onicegatheringstatechange 59 59 ? ? ? ? ? ?
removeTrack() Sin soporte Sin soporte ? ? ? ? ?  

[1] Prior to Firefox 49, the specified track was required to be component of all passed MediaStream (en-US)s. Starting in Firefox 49, this is no longer the case. See error 1271669 for specifics.

[2] Firefox currently removes the RTCRtpSender (en-US) from the list of senders as reported by RTCPeerConnection.getSenders() (en-US). This was correct in earlier versions of the specification, but no longer is. See error 1290949.

See also