RTCPeerConnection

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

La interfaz RTCPeerConnection representa una conexión WebRTC entre la computadora local y un par remoto. Proporciona métodos para conectarse a un par remoto, mantener y monitorear la conexión y cerrar la conexión una vez que ya no se necesita.

EventTarget RTCPeerConnection

Constructor

RTCPeerConnection()

Devuelve un RTCPeerConnection recién creado, que representa una conexión entre el dispositivo local y un par remoto.

Propiedades de instancia

También hereda propiedades de EventTarget.

canTrickleIceCandidates Read only

Devuelve un valor booleano que indica si el par remoto puede aceptar o no candidatos trickled ICE.

connectionState Read only

Indica el estado actual de la conexión entre pares devolviendo una de las cadenas new, connecting, connected, disconnected, failed o closed.

currentLocalDescription Read only

Devuelve un objeto RTCSessionDescription que describe el extremo local de la conexión tal como se negoció con éxito más recientemente desde la última vez que esta RTCPeerConnection terminó de negociar y conectarse a un par remoto. También se incluye una lista de los candidatos de ICE que ya puede haber generado el agente de ICE desde que se instanciaron por primera vez la oferta o respuesta representada por la descripción.

currentRemoteDescription Read only

Devuelve un objeto RTCSessionDescription que describe el extremo remoto de la conexión tal como se negoció con éxito más recientemente desde la última vez que RTCPeerConnection terminó de negociar y conectarse a un par remoto. También se incluye una lista de los candidatos de ICE que ya puede haber generado el agente de ICE desde que se instanciaron por primera vez la oferta o respuesta representada por la descripción.

iceConnectionState Read only

Devuelve una cadena cuyo estado del agente ICE asociado con este RTCPeerConnection. Puede ser uno de los siguientes valores: new, checking, connected, completed, failed, disconnected o closed.

iceGatheringState Read only

Devuelve una cadena que describe el estado de recopilación de ICE de la conexión. Esto le permite detectar, por ejemplo, cuándo finalizó la recopilación de candidatos de ICE. Los valores posibles son: new, gathering o complete.

localDescription Read only

Devuelve un RTCSessionDescription que describe la sesión para el extremo local de la conexión. Si aún no se ha configurado, devuelve null.

peerIdentity Read only.

Devuelve una Promesa que se resuelve en un RTCIdentityAssertion que contiene una cadena que identifica al par remoto. Una vez que esta promesa se resuelve con éxito, la identidad resultante es la identidad del par de destino y no cambiará durante la duración de la conexión.

pendingLocalDescription Read only

Devuelve un objeto RTCSessionDescription que describe un cambio de configuración pendiente para el extremo local de la conexión. Esto no describe la conexión tal como está actualmente, sino como puede existir en un futuro próximo.

pendingRemoteDescription Read only

Devuelve un objeto RTCSessionDescription que describe un cambio de configuración pendiente para el extremo remoto de la conexión. Esto no describe la conexión tal como está actualmente, sino como puede existir en un futuro próximo.

remoteDescription Read only

Devuelve un objeto RTCSessionDescription que describe la sesión, incluida la configuración y la información multimedia, para el extremo remoto de la conexión. Si aún no se ha establecido, devuelve null.

sctp Read only

Devuelve un objeto RTCSctpTransport que describe la capa de transporte SCTP sobre la que se envían y reciben los datos SCTP. Si no se ha negociado SCTP, este valor es null.

signalingState Read only

Devuelve una cadena que describe el estado del proceso de señalización en el extremo local de la conexión mientras se conecta o se vuelve a conectar a otro par. Es uno de los siguientes valores: stable, have-local-offer, have-remote-offer, have-local-pranswer, have-remote-pranswer o closed.

Métodos estáticos

generateCertificate()

Crea un certificado X.509 y su clave privada correspondiente, devolviendo una Promesa que se resuelve con el nuevo RTCCertificate una vez que se genera.

Métodos de instancia

También hereda métodos de EventTarget.

addIceCandidate()

Agrega un nuevo candidato remoto a la descripción remota de RTCPeerConnection, que describe el estado del extremo remoto de la conexión.

addTrack()

Agrega un nuevo MediaStreamTrack al conjunto de pistas que se transmitirán al otro par.

addTransceiver()

Crea un nuevo RTCRtpTransceiver y lo agrega al conjunto de transceptores asociados con la conexión. Cada transceptor representa un flujo bidireccional, con RTCRtpSender y RTCRtpReceiver asociados con él.

close()

Cierra la conexión de pares actual.

createAnswer()

Inicia la creación de una respuesta SDP a una oferta recibida de un par remoto durante la negociación de oferta/respuesta de una conexión WebRTC. La respuesta contiene información sobre cualquier medio ya adjunto a la sesión, códecs y opciones compatibles con el navegador, y cualquier candidato ICE ya recopilado.

createDataChannel()

Inicia la creación de un nuevo canal vinculado con el par remoto, sobre el cual se puede transmitir cualquier tipo de datos. Esto puede ser útil para contenido de canal secundario, como imágenes, transferencia de archivos, chat de texto, paquetes de actualización de juegos, etc.

createOffer()

Inicia la creación de una oferta de SDP con el fin de iniciar una nueva conexión WebRTC a un interlocutor remoto. La oferta de SDP incluye información sobre cualquier objeto MediaStreamTrack ya adjunto a la sesión, el códec y las opciones de WebRTC admitidos por el navegador, así como cualquier candidato ya recopilado por el agente ICE, con el fin de ser enviado por el canal de señalización a un posible par para solicitar una conexión o actualizar la configuración de una conexión existente.

getConfiguration()

Devuelve un objeto que indica la configuración actual de la conexión.

getIdentityAssertion()

Inicia la recopilación de una afirmación de identidad y devuelve una Promesa que se resuelve en una afirmación de identidad codificada como una cadena. Esto tiene efecto solo si signalingState no es closed.

getReceivers()

Devuelve un arreglo de objetos RTCRtpReceiver, cada uno de los cuales representa un receptor RTP.

getSenders()

Devuelve un arrreglo de objetos RTCRtpSender, cada uno de los cuales representa el remitente RTP responsable de transmitir los datos de una pista.

getStats()

Devuelve una Promesa que se resuelve con datos que proporcionan estadísticas sobre la conexión general o sobre el MediaStreamTrack especificado.

getTransceivers()

Devuelve una lista de todos los objetos RTCRtpTransceiver que se utilizan para enviar y recibir datos en la conexión.

removeTrack()

Le dice al extremo local de la conexión que deje de enviar medios desde la pista especificada, sin eliminar realmente el RTCRtpSender correspondiente de la lista de remitentes según lo informado por getSenders(). Si la pista ya está detenida o no está en la lista de remitentes de la conexión, este método no tiene efecto.

restartIce()

Permite solicitar fácilmente que la recopilación de candidatos ICE se rehaga en ambos extremos de la conexión. Esto simplifica el proceso al permitir que la persona que llama o el receptor utilicen el mismo método para activar un reinicio ICE.

setConfiguration()

Establece la configuración actual de la conexión en función de los valores incluidos en el objeto especificado. Esto le permite cambiar los servidores ICE utilizados por la conexión y qué políticas de transporte utilizar.

setIdentityProvider()

Establece el proveedor de identidad (IdP) en el triplete dado en el parámetro: su nombre, el protocolo utilizado para comunicarse con él y un nombre de usuario. El protocolo y el nombre de usuario son opcionales.

setLocalDescription()

Cambia la descripción local asociada con la conexión. Esta descripción especifica las propiedades del extremo local de la conexión, incluido el formato de medios. Devuelve una Promesa que se cumple una vez que se ha cambiado la descripción, de forma asíncrona.

setRemoteDescription()

Establece la descripción de la sesión especificada como la oferta o respuesta actual del interlocutor remoto. La descripción especifica las propiedades del extremo remoto de la conexión, incluido el formato de medios. Devuelve una Promesa que se cumple una vez que se ha cambiado la descripción, de forma asíncrona.

Métodos obsoletos

addStream() Obsoleto No estándar

Agrega un MediaStream como fuente local de audio o video. En lugar de usar este método obsoleto, debe usar addTrack() una vez por cada pista que desee enviar al interlocutor remoto.

createDTMFSender() Obsoleto

Crea un nuevo RTCDTMFSender, asociado a un MediaStreamTrack específico, que podrá enviar señalización telefónica DTMF a través de la conexión .

removeStream() Obsoleto No estándar

Elimina un MediaStream como fuente local de audio o video. Debido a que este método está obsoleto, en su lugar debe usar removeTrack().

Eventos

Detecte estos eventos usando addEventListener() o asignando un detector de eventos a la propiedad oneventname de esta interfaz.

connectionstatechange

Enviado cuando cambia el estado general de conectividad de RTCPeerConnection.

datachannel

Enviado cuando el par remoto agrega un RTCDataChannel a la conexión.

icecandidate

Enviado para solicitar que el candidato especificado se transmita al par remoto.

icecandidateerror

Enviado a la conexión si se produjo un error durante la recopilación de candidatos ICE. El evento describe el error.

iceconnectionstatechange

Se envía cuando cambia el estado de la conexión ICE, como cuando se desconecta.

icegatheringstatechange

Se envía cuando cambia el estado de recopilación de la capa ICE, reflejado por iceGatheringState. Esto indica si la negociación de ICE aún no ha comenzado (new), ha comenzado a reunir candidatos (gathering) o ha finalizado (complete).

negotiationneeded

Enviado cuando es necesario realizar la negociación o renegociación de la conexión ICE; esto puede suceder tanto cuando se abre una conexión por primera vez como cuando es necesario adaptarse a las condiciones cambiantes de la red. El receptor debe responder creando una oferta y enviándola al otro par.

signalingstatechange

Se envía cuando cambia el estado de señalización del ICE de la conexión.

track

Enviado después de que se haya agregado una nueva pista a una de las instancias RTCRtpReceiver que componen la conexión.

Eventos obsoletos

addstream Obsoleto No estándar

Enviado cuando se agrega un nuevo MediaStream a la conexión. En lugar de detectar este evento obsoleto, debe detectar los eventos track; se envía uno por cada MediaStreamTrack agregado a la conexión.

removestream Obsoleto No estándar

Enviado cuando se elimina un MediaStream de la conexión. En lugar de detectar este evento obsoleto, debe detectar los eventos removetrack en cada transmisión.

Especificaciones

Specification
WebRTC: Real-Time Communication in Browsers
# interface-definition

Compatibilidad con navegadores

BCD tables only load in the browser

Véase también