Class RTCPeerConnection
Represents a WebRTC connection between the local peer and remote peer.
Implements
Namespace: Unity.WebRTC
Assembly: Unity.WebRTC.dll
Syntax
public class RTCPeerConnection : IDisposable
Remarks
RTCPeerConnection
class represents a WebRTC connection between the local computer and a remote peer.
It provides methods to connect to a remote peer, maintain and monitor the connection, and close the connection once it's no longer needed.
Examples
RTCPeerConnection peerConnection = new RTCPeerConnection();
Constructors
RTCPeerConnection()
Creates an instance of peer connection with a default configuration.
Declaration
public RTCPeerConnection()
Remarks
RTCPeerConnection
constructor creates an instance of peer connection with a default configuration.
Examples
RTCPeerConnection peerConnection = new RTCPeerConnection();
See Also
RTCPeerConnection(ref RTCConfiguration)
Creates an instance of peer connection with a configuration provided by user.
Declaration
public RTCPeerConnection(ref RTCConfiguration configuration)
Parameters
Type | Name | Description |
---|---|---|
RTCConfiguration | configuration |
|
Remarks
RTCPeerConnection
constructor creates an instance of peer connection with a default configuration.
An RTCConfiguration object providing options to configure the new connection.
Examples
RTCPeerConnection peerConnection = new RTCPeerConnection(ref configuration);
See Also
Properties
CanTrickleIceCandidates
Boolean value that indicates whether the remote peer can accept trickled ICE candidates.
Declaration
public bool? CanTrickleIceCandidates { get; }
Property Value
Type | Description |
---|---|
bool? |
Remarks
When the value is true, the remote peer can accept trickled ICE candidates. When the value is false, the remote peer cannot accept trickled ICE candidates. When the value is null, the remote peer has not been established.
See Also
ConnectionState
The readonly property of the RTCPeerConnection indicates the current state of the peer connection by returning one of the RTCPeerConnectionState enum.
Declaration
public RTCPeerConnectionState ConnectionState { get; }
Property Value
Type | Description |
---|---|
RTCPeerConnectionState |
Examples
RTCPeerConnection peerConnection = new RTCPeerConnection(configuration);
RTCPeerConnectionState connectionState = peerConnection.ConnectionState;
See Also
CurrentLocalDescription
RTCSessionDescription object describing the local end of the connection from the last successful negotiation with a remote peer. It also includes ICE candidates generated by the ICE agent since the initial offer or answer was first created.
Declaration
public RTCSessionDescription CurrentLocalDescription { get; }
Property Value
Type | Description |
---|---|
RTCSessionDescription |
See Also
CurrentRemoteDescription
RTCSessionDescription object describing the remote end of the connection from the last successful negotiation with a remote peer. It also includes ICE candidates generated by the ICE agent since the initial offer or answer was first created.
Declaration
public RTCSessionDescription CurrentRemoteDescription { get; }
Property Value
Type | Description |
---|---|
RTCSessionDescription |
See Also
GatheringState
RTCIceGatheringState value that describes the overall ICE gathering state for the RTCPeerConnection.
Declaration
public RTCIceGatheringState GatheringState { get; }
Property Value
Type | Description |
---|---|
RTCIceGatheringState |
See Also
IceConnectionState
The readonly property of the RTCPeerConnection indicates the current state of the peer connection by returning one of the RTCIceConnectionState enum.
Declaration
public RTCIceConnectionState IceConnectionState { get; }
Property Value
Type | Description |
---|---|
RTCIceConnectionState |
Examples
RTCPeerConnection peerConnection = new RTCPeerConnection(configuration);
RTCIceConnectionState iceConnectionState = peerConnection.IceConnectionState;
See Also
LocalDescription
RTCSessionDescription object that describes the session for the local end of the RTCPeerConnection.
Declaration
public RTCSessionDescription LocalDescription { get; }
Property Value
Type | Description |
---|---|
RTCSessionDescription |
See Also
OnConnectionStateChange
Delegate to be called after a new track has been added to an RTCRtpReceiver which is part of the connection.
Declaration
public DelegateOnConnectionStateChange OnConnectionStateChange { get; set; }
Property Value
Type | Description |
---|---|
DelegateOnConnectionStateChange |
See Also
OnDataChannel
Delegate to be called when an RTCDataChannel has been added to the connection, as a result of the remote peer calling RTCPeerConnection.CreateDataChannel.
Declaration
public DelegateOnDataChannel OnDataChannel { get; set; }
Property Value
Type | Description |
---|---|
DelegateOnDataChannel |
See Also
OnIceCandidate
Delegate to be called when a new RTCIceCandidate is identified and added to the local peer, when all candidates for a specific generation are identified and added, and when the ICE gathering on all transports is complete.
Declaration
public DelegateOnIceCandidate OnIceCandidate { get; set; }
Property Value
Type | Description |
---|---|
DelegateOnIceCandidate |
See Also
OnIceConnectionChange
Delegate to be called when the IceConnectionState is changed.
Declaration
public DelegateOnIceConnectionChange OnIceConnectionChange { get; set; }
Property Value
Type | Description |
---|---|
DelegateOnIceConnectionChange | A delegate containing IceConnectionState. |
Examples
peerConnection.OnIceConnectionChange = iceConnectionState =>
{
...
};
See Also
OnIceGatheringStateChange
Delegate to be called when the state of the ICE candidate gathering process changes.
Declaration
public DelegateOnIceGatheringStateChange OnIceGatheringStateChange { get; set; }
Property Value
Type | Description |
---|---|
DelegateOnIceGatheringStateChange |
See Also
OnNegotiationNeeded
Delegate to be called when negotiation of the connection through the signaling channel is required.
Declaration
public DelegateOnNegotiationNeeded OnNegotiationNeeded { get; set; }
Property Value
Type | Description |
---|---|
DelegateOnNegotiationNeeded |
See Also
OnTrack
Delegate to be called after a new track has been added to an RTCRtpReceiver which is part of the connection.
Declaration
public DelegateOnTrack OnTrack { get; set; }
Property Value
Type | Description |
---|---|
DelegateOnTrack |
See Also
PendingLocalDescription
RTCSessionDescription object that describes a pending configuration change for the local end of the connection.
Declaration
public RTCSessionDescription PendingLocalDescription { get; }
Property Value
Type | Description |
---|---|
RTCSessionDescription |
See Also
PendingRemoteDescription
RTCSessionDescription object that describes a pending configuration change for the remote end of the connection.
Declaration
public RTCSessionDescription PendingRemoteDescription { get; }
Property Value
Type | Description |
---|---|
RTCSessionDescription |
See Also
RemoteDescription
RTCSessionDescription object that describes the session (which includes configuration and media information) for the remote end of the connection.
Declaration
public RTCSessionDescription RemoteDescription { get; }
Property Value
Type | Description |
---|---|
RTCSessionDescription |
See Also
SignalingState
The readonly property of the RTCPeerConnection indicates the current state of the peer connection by returning one of the RTCSignalingState enum.
Declaration
public RTCSignalingState SignalingState { get; }
Property Value
Type | Description |
---|---|
RTCSignalingState |
Examples
RTCPeerConnection peerConnection = new RTCPeerConnection(configuration);
RTCSignalingState signalingState = peerConnection.SignalingState;
See Also
Methods
AddIceCandidate(RTCIceCandidate)
Adds a new remote candidate to the connection's remote description.
Declaration
public bool AddIceCandidate(RTCIceCandidate candidate)
Parameters
Type | Name | Description |
---|---|---|
RTCIceCandidate | candidate |
|
Returns
Type | Description |
---|---|
bool |
|
Remarks
AddIceCandidate
method adds a new remote ICE candidate to the connection's remote description, which describes the current state of the remote end of the connection.
Examples
peerConnection.OnIceCandidate = candidate =>
{
bool result = otherPeerConnection.AddIceCandidate(candidate);
}
See Also
AddTrack(MediaStreamTrack, MediaStream)
Adds a new media track to the set of tracks which is transmitted to the other peer.
Declaration
public RTCRtpSender AddTrack(MediaStreamTrack track, MediaStream stream = null)
Parameters
Type | Name | Description |
---|---|---|
MediaStreamTrack | track |
|
MediaStream | stream | Local |
Returns
Type | Description |
---|---|
RTCRtpSender |
|
Remarks
AddTrack
method adds a new media track to the set of tracks which is transmitted to the other peer.
Adding a track to a connection triggers renegotiation by firing an OnNegotiationNeeded
event.
Examples
MediaStream sendStream = new MediaStream();
AudioStreamTrack audioTrack = new AudioStreamTrack(inputAudioSource)
RTCRtpSender sender = peerConnection.AddTrack(audioTrack, sendStream);
See Also
AddTransceiver(MediaStreamTrack, RTCRtpTransceiverInit)
Creates a new RTCRtpTransceiver and adds it to the set of transceivers associated with the RTCPeerConnection.
Declaration
public RTCRtpTransceiver AddTransceiver(MediaStreamTrack track, RTCRtpTransceiverInit init = null)
Parameters
Type | Name | Description |
---|---|---|
MediaStreamTrack | track |
|
RTCRtpTransceiverInit | init |
|
Returns
Type | Description |
---|---|
RTCRtpTransceiver |
|
Remarks
AddTransceiver
method creates a new RTCRtpTransceiver
instance and adds it to the set of transceivers associated with the RTCPeerConnection
.
Each transceiver represents a bidirectional stream, with both an RTCRtpSender
and an RTCRtpReceiver
associated with it.
Examples
RTCRtpTransceiverInit init = new RTCRtpTransceiverInit();
init.direction = RTCRtpTransceiverDirection.SendOnly;
RTCRtpTransceiver transceiver = peerConnection.AddTransceiver(videoStreamTrack, init);
See Also
AddTransceiver(TrackKind, RTCRtpTransceiverInit)
Creates a new RTCRtpTransceiver and adds it to the set of transceivers associated with the RTCPeerConnection.
Declaration
public RTCRtpTransceiver AddTransceiver(TrackKind kind, RTCRtpTransceiverInit init = null)
Parameters
Type | Name | Description |
---|---|---|
TrackKind | kind |
|
RTCRtpTransceiverInit | init |
|
Returns
Type | Description |
---|---|
RTCRtpTransceiver |
|
Remarks
AddTransceiver
method creates a new RTCRtpTransceiver
instance and adds it to the set of transceivers associated with the RTCPeerConnection
.
Each transceiver represents a bidirectional stream, with both an RTCRtpSender
and an RTCRtpReceiver
associated with it.
Examples
RTCRtpTransceiverInit init = new RTCRtpTransceiverInit();
init.direction = RTCRtpTransceiverDirection.RecvOnly;
RTCRtpTransceiver transceiver = peerConnection.AddTransceiver(TrackKind.Audio, init);
See Also
Close()
Closes the current peer connection.
Declaration
public void Close()
Remarks
Close
method closes the current peer connection.
Examples
peerConnection.Close();
See Also
CreateAnswer()
Create an SDP (Session Description Protocol) answer to start a new connection to a remote peer.
Declaration
public RTCSessionDescriptionAsyncOperation CreateAnswer()
Returns
Type | Description |
---|---|
RTCSessionDescriptionAsyncOperation |
|
Remarks
CreateAnswer
method creates an SDP answer to an offer received from a remote peer during the offer/answer negotiation of a WebRTC connection.
The SDP answer contains details about the session's media, supported codecs, and ICE candidates.
Examples
RTCSessionDescriptionAsyncOperation asyncOperation = peerConnection.CreateAnswer();
yield return asyncOperation;
if (!asyncOperation.IsError)
{
RTCSessionDescription description = asyncOperation.Desc;
RTCSetSessionDescriptionAsyncOperation asyncOperation = peerConnection.SetLocalDescription(ref description);
yield return asyncOperation;
}
See Also
CreateAnswer(ref RTCOfferAnswerOptions)
Create an SDP (Session Description Protocol) answer to start a new connection to a remote peer.
Declaration
public RTCSessionDescriptionAsyncOperation CreateAnswer(ref RTCOfferAnswerOptions options)
Parameters
Type | Name | Description |
---|---|---|
RTCOfferAnswerOptions | options |
|
Returns
Type | Description |
---|---|
RTCSessionDescriptionAsyncOperation |
|
Remarks
CreateAnswer
method creates an SDP answer to an offer received from a remote peer during the offer/answer negotiation of a WebRTC connection.
The SDP answer contains details about the session's media, supported codecs, and ICE candidates.
Examples
RTCSessionDescriptionAsyncOperation asyncOperation = peerConnection.CreateAnswer(ref options);
yield return asyncOperation;
if (!asyncOperation.IsError)
{
RTCSessionDescription description = asyncOperation.Desc;
RTCSetSessionDescriptionAsyncOperation asyncOperation = peerConnection.SetLocalDescription(ref description);
yield return asyncOperation;
}
See Also
CreateDataChannel(string, RTCDataChannelInit)
Creates a new data channel related the remote peer.
Declaration
public RTCDataChannel CreateDataChannel(string label, RTCDataChannelInit options = null)
Parameters
Type | Name | Description |
---|---|---|
string | label | A string for the data channel. This string may be checked by Label. |
RTCDataChannelInit | options | A struct provides configuration options for the data channel. |
Returns
Type | Description |
---|---|
RTCDataChannel | A new data channel. |
Remarks
CreateDataChannel
method creates a new data channel with the remote peer for transmitting any type of data.
Examples
var dataChannel = peerConnection.CreateDataChannel(label, options);
See Also
CreateOffer()
Create an SDP (Session Description Protocol) offer to start a new connection to a remote peer.
Declaration
public RTCSessionDescriptionAsyncOperation CreateOffer()
Returns
Type | Description |
---|---|
RTCSessionDescriptionAsyncOperation |
|
Remarks
CreateOffer
initiates the creation of an SDP offer for the purpose of starting a new WebRTC connection to a remote peer.
The SDP offer contains details about MediaStreamTrack
objects, supported codecs and options, and ICE candidates.
Examples
RTCSessionDescriptionAsyncOperation asyncOperation = peerConnection.CreateOffer();
yield return asyncOperation;
if (!asyncOperation.IsError)
{
RTCSessionDescription description = asyncOperation.Desc;
RTCSetSessionDescriptionAsyncOperation asyncOperation = peerConnection.SetLocalDescription(ref description);
yield return asyncOperation;
}
See Also
CreateOffer(ref RTCOfferAnswerOptions)
Create an SDP (Session Description Protocol) offer to start a new connection to a remote peer.
Declaration
public RTCSessionDescriptionAsyncOperation CreateOffer(ref RTCOfferAnswerOptions options)
Parameters
Type | Name | Description |
---|---|---|
RTCOfferAnswerOptions | options |
|
Returns
Type | Description |
---|---|
RTCSessionDescriptionAsyncOperation |
|
Remarks
CreateOffer
initiates the creation of an SDP offer for the purpose of starting a new WebRTC connection to a remote peer.
The SDP offer contains details about MediaStreamTrack
objects, supported codecs and options, and ICE candidates.
Examples
RTCSessionDescriptionAsyncOperation asyncOperation = peerConnection.CreateOffer(ref options);
yield return asyncOperation;
if (!asyncOperation.IsError)
{
RTCSessionDescription description = asyncOperation.Desc;
RTCSetSessionDescriptionAsyncOperation asyncOperation = peerConnection.SetLocalDescription(ref description);
yield return asyncOperation;
}
See Also
Dispose()
Disposes of RTCPeerConnection.
Declaration
public void Dispose()
Remarks
Dispose
method releases resources used by the RTCPeerConnection
.
This method closes the current peer connection and disposes of all transceivers.
Examples
peerConnection.Dispose();
See Also
~RTCPeerConnection()
Finalizer for RTCPeerConnection.
Declaration
protected ~RTCPeerConnection()
Remarks
Ensures that resources are released by calling the Dispose
method.
See Also
GetConfiguration()
Returns an object which indicates the current configuration of the RTCPeerConnection.
Declaration
public RTCConfiguration GetConfiguration()
Returns
Type | Description |
---|---|
RTCConfiguration | An object describing the RTCPeerConnection's current configuration. |
Remarks
GetConfiguration
method returns an object which indicates the current configuration of the RTCPeerConnection
.
Examples
RTCConfiguration configuration = myPeerConnection.GetConfiguration();
if(configuration.urls.length == 0)
{
configuration.urls = new[] {"stun:stun.l.google.com:19302"};
}
myPeerConnection.SetConfiguration(configuration);
See Also
GetReceivers()
Returns array of objects each of which represents one RTP receiver.
Declaration
public IEnumerable<RTCRtpReceiver> GetReceivers()
Returns
Type | Description |
---|---|
IEnumerable<RTCRtpReceiver> | An array of |
Remarks
GetReceivers
method returns an array of RTCRtpReceiver
objects, each of which represents one RTP receiver.
Examples
IEnumerable<RTCRtpReceiver> receivers = peerConnection.GetReceivers();
See Also
GetSenders()
Returns array of objects each of which represents one RTP sender.
Declaration
public IEnumerable<RTCRtpSender> GetSenders()
Returns
Type | Description |
---|---|
IEnumerable<RTCRtpSender> | An array of |
Remarks
GetSenders
method returns an array of RTCRtpSender
objects, each of which represents the RTP sender responsible for transmitting one track's data.
Examples
RTCRtpSender sender = peerConnection.GetSenders().First();
RTCRtpSendParameters parameters = sender.GetParameters();
parameters.encodings[0].maxBitrate = bandwidth * 1000;
RTCError error = sender.SetParameters(parameters);
if (error != RTCErrorType.None)
{
Debug.LogError($"Failed to set parameters: {error}");
}
See Also
GetStats()
Returns an AsyncOperation which resolves with data providing statistics.
Declaration
public RTCStatsReportAsyncOperation GetStats()
Returns
Type | Description |
---|---|
RTCStatsReportAsyncOperation | An AsyncOperation which resolves with an RTCStatsReport object providing connection statistics. |
Remarks
GetStats
method returns a promise which resolves with data providing statistics about either the overall connection or about the specified MediaStreamTrack
.
Examples
// Already instantiated peerConnection as RTCPeerConnection.
RTCStatsReportAsyncOperation operation = peerConnection.GetStats();
yield return operation;
if (!operation.IsError)
{
RTCStatsReport report = operation.Value;
foreach (RTCStats stat in report.Stats.Values)
{
Debug.Log(stat.Type.ToString());
}
}
See Also
GetTransceivers()
Returns array of objects each of which represents one RTP transceiver.
Declaration
public IEnumerable<RTCRtpTransceiver> GetTransceivers()
Returns
Type | Description |
---|---|
IEnumerable<RTCRtpTransceiver> | An array of the |
Remarks
GetTransceivers
method returns an array of the RTCRtpTransceiver
objects being used to send and receive data on the connection.
Examples
RTCRtpCapabilities capabilities = RTCRtpSender.GetCapabilities(TrackKind.Video);
RTCRtpTransceiver transceiver = peerConnection.GetTransceivers().First();
RTCErrorType error = transceiver.SetCodecPreferences(capabilities.codecs);
if (error.errorType != RTCErrorType.None)
{
Debug.LogError($"Failed to set codec preferences: {error.message}");
}
See Also
RemoveTrack(RTCRtpSender)
Tells the local end of the connection to stop sending media from the specified track.
Declaration
public RTCErrorType RemoveTrack(RTCRtpSender sender)
Parameters
Type | Name | Description |
---|---|---|
RTCRtpSender | sender |
|
Returns
Type | Description |
---|---|
RTCErrorType |
|
Remarks
RemoveTrack
method tells the local end of the connection to stop sending media from the specified track, without actually removing the corresponding RTCRtpSender
from the list of senders.
If the track is already stopped, or is not in the connection's senders list, this method has no effect.
Examples
RTCErrorType error = peerConnection.RemoveTrack(sender);
See Also
RestartIce()
Requests that ICE candidate gathering be redone on both ends of the connection.
Declaration
public void RestartIce()
Remarks
RestartIce
method requests that ICE candidate gathering be redone on both ends of the connection.
After RestartIce
is called, the offer returned by the next call to CreateOffer
automatically configured to trigger ICE restart on both the local and remote peers.
This method triggers an OnNegotiationNeeded
event.
Examples
peerConnection.RestartIce();
See Also
SetConfiguration(ref RTCConfiguration)
Sets the current configuration of the RTCPeerConnection.
Declaration
public RTCErrorType SetConfiguration(ref RTCConfiguration configuration)
Parameters
Type | Name | Description |
---|---|---|
RTCConfiguration | configuration |
|
Returns
Type | Description |
---|---|
RTCErrorType | Error code. |
Remarks
SetConfiguration
method sets the current configuration of the connection based on the values included in the specified object.
This lets you change the ICE servers used by the connection and which transport policies to use.
Examples
RTCConfiguration configuration = new RTCConfiguration
{
iceServers = new[]
{
new RTCIceServer
{
urls = new[] {"stun:stun.l.google.com:19302"},
username = "",
credential = "",
credentialType = RTCIceCredentialType.Password
}
}
};
RTCErrorType error = myPeerConnection.SetConfiguration(ref configuration);
if(error == RTCErrorType.None)
{
...
}
See Also
SetLocalDescription()
Changes the session description of the local connection to negotiate with other connections.
Declaration
public RTCSetSessionDescriptionAsyncOperation SetLocalDescription()
Returns
Type | Description |
---|---|
RTCSetSessionDescriptionAsyncOperation | An AsyncOperation which resolves with an RTCSessionDescription object providing a description of the session. |
Remarks
SetLocalDescription
method automatically adjusts the local description associated with the connection, specifying the properties of the local end of the connection, including the media format.
Examples
peerConnection.OnNegotiationNeeded = () =>
{
StartCoroutine(NegotiationProcess());
}
IEnumerator NegotiationProcess()
{
RTCSetSessionDescriptionAsyncOperation asyncOperation = peerConnection.SetLocalDescription(ref description);
yield return asyncOperation;
if (asyncOperation.IsError)
{
Debug.LogError("Failed to set local description: " + asyncOperation.Error.message);
}
}
See Also
SetLocalDescription(ref RTCSessionDescription)
Changes the session description of the local connection to negotiate with other connections.
Declaration
public RTCSetSessionDescriptionAsyncOperation SetLocalDescription(ref RTCSessionDescription desc)
Parameters
Type | Name | Description |
---|---|---|
RTCSessionDescription | desc |
|
Returns
Type | Description |
---|---|
RTCSetSessionDescriptionAsyncOperation | An AsyncOperation which resolves with an RTCSessionDescription object providing a description of the session. |
Remarks
SetLocalDescription
method changes the local description associated with the connection, specifying the properties of the local end of the connection, including the media format.
Examples
RTCSessionDescriptionAsyncOperation asyncOperation = peerConnection.CreateOffer();
yield return asyncOperation;
if (!asyncOperation.IsError)
{
RTCSessionDescription description = asyncOperation.Desc;
RTCSetSessionDescriptionAsyncOperation asyncOperation = peerConnection.SetLocalDescription(ref description);
yield return asyncOperation;
}
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown when an argument has an invalid value. For example, when passed the sdp which is null or empty. |
RTCErrorException | Thrown when an argument has an invalid value. For example, when passed the sdp which is not be able to parse. |
See Also
SetRemoteDescription(ref RTCSessionDescription)
This method changes the session description of the remote connection to negotiate with local connections.
Declaration
public RTCSetSessionDescriptionAsyncOperation SetRemoteDescription(ref RTCSessionDescription desc)
Parameters
Type | Name | Description |
---|---|---|
RTCSessionDescription | desc |
|
Returns
Type | Description |
---|---|
RTCSetSessionDescriptionAsyncOperation | An AsyncOperation which resolves with an RTCSessionDescription object providing a description of the session. |
Remarks
SetRemoteDescription
method changes the specified session description as the remote peer's current offer or answer, specifying the properties of the remote end of the connection, including the media format.
Examples
RTCSessionDescriptionAsyncOperation asyncOperation = peerConnection.CreateOffer();
yield return asyncOperation;
if (!asyncOperation.IsError)
{
RTCSessionDescription description = asyncOperation.Desc;
RTCSetSessionDescriptionAsyncOperation asyncOperation = otherPeerConnection.SetRemoteDescription(ref description);
yield return asyncOperation;
}
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown when an argument has an invalid value. For example, when passed the sdp which is null or empty. |
RTCErrorException | Thrown when an argument has an invalid value. For example, when passed the sdp which is not be able to parse. |