Class PeerConnection

The WebRTC peer connection object is the entry point to using WebRTC.

Inheritance

Object

PeerConnection

Namespace: Microsoft.MixedReality.WebRTC

Assembly: Microsoft.MixedReality.WebRTC.dll

Syntax

public class PeerConnection : IDisposable

Constructors

PeerConnection()

Create a new peer connection object. The object is initially created empty, and cannot be used until InitializeAsync(PeerConnectionConfiguration, CancellationToken) has completed successfully.

Declaration

public PeerConnection()

Fields

PreferredAudioCodec

Name of the preferred audio codec, or empty to let WebRTC decide. See https://en.wikipedia.org/wiki/RTP_audio_video_profile for the standard SDP names.

Declaration

public string PreferredAudioCodec

Field Value

Type	Description
String

PreferredAudioCodecExtraParamsLocal

Advanced use only. List of additional codec-specific arguments set on the local endpoint.

Declaration

public string PreferredAudioCodecExtraParamsLocal

Field Value

Type	Description
String

Remarks

This must be a semicolon-separated list of "key=value" pairs. Arguments are passed as is, and there is no check on the validity of the parameter names nor their value. Arguments are set locally by adding them to the audio codec section of SDP messages received from the remote endpoint.

This is ignored if PreferredAudioCodec is an empty string, or is not a valid codec name found in the SDP message offer.

PreferredAudioCodecExtraParamsRemote

Advanced use only. List of additional codec-specific arguments requested to the remote endpoint.

Declaration

public string PreferredAudioCodecExtraParamsRemote

Field Value

Type	Description
String

Remarks

This must be a semicolon-separated list of "key=value" pairs. Arguments are passed as is, and there is no check on the validity of the parameter names nor their value. Arguments are added to the audio codec section of SDP messages sent to the remote endpoint.

This is ignored if PreferredAudioCodec is an empty string, or is not a valid codec name found in the SDP message offer.

PreferredVideoCodec

Name of the preferred video codec, or empty to let WebRTC decide. See https://en.wikipedia.org/wiki/RTP_audio_video_profile for the standard SDP names.

Declaration

public string PreferredVideoCodec

Field Value

Type	Description
String

PreferredVideoCodecExtraParamsLocal

Advanced use only. List of additional codec-specific arguments set on the local endpoint.

Declaration

public string PreferredVideoCodecExtraParamsLocal

Field Value

Type	Description
String

Remarks

This must be a semicolon-separated list of "key=value" pairs. Arguments are passed as is, and there is no check on the validity of the parameter names nor their value. Arguments are set locally by adding them to the video codec section of SDP messages received from the remote endpoint.

This is ignored if PreferredVideoCodec is an empty string, or is not a valid codec name found in the SDP message offer.

PreferredVideoCodecExtraParamsRemote

Advanced use only. List of additional codec-specific arguments requested to the remote endpoint.

Declaration

public string PreferredVideoCodecExtraParamsRemote

Field Value

Type	Description
String

Remarks

This must be a semicolon-separated list of "key=value" pairs. Arguments are passed as is, and there is no check on the validity of the parameter names nor their value. Arguments are added to the video codec section of SDP messages sent to the remote endpoint.

This is ignored if PreferredVideoCodec is an empty string, or is not a valid codec name found in the SDP message offer.

Properties

AssociatedTransceivers

Collection of transceivers which have already been associated with a media line.

A transceiver is associated with a media line when a local or remote offer is applied to the peer connection, respectively during CreateOffer() and SetRemoteDescriptionAsync(SdpMessage).

Declaration

public IEnumerable<Transceiver> AssociatedTransceivers { get; }

Property Value

Type	Description
IEnumerable<Transceiver>

DataChannels

Collection of data channels for the peer connection.

Data channels are either manually added by calling AddDataChannelAsync(String, Boolean, Boolean, CancellationToken) or AddDataChannelAsync(UInt16, String, Boolean, Boolean, CancellationToken), or are created by the implementation while applying a remote offer when the remote peer created a new in-band data channel.

Declaration

public List<DataChannel> DataChannels { get; }

Property Value

Type	Description
List<DataChannel>

Initialized

Boolean property indicating whether the peer connection has been initialized.

Warning

This property will be deprecated and later removed in future versions.

The value of this property is undefined while the asynchronous task resulting from a call to InitializeAsync(PeerConnectionConfiguration, CancellationToken) is pending. This means its value is only relevant before the call (and then it is false) or after the asynchronous call completed (and then it is true), but not while the initialization is underway. For this reason, it is recommended NOT to use this property, and instead to rely on logic around InitializeAsync(PeerConnectionConfiguration, CancellationToken) and Close() alone. Generally this means awaiting the initialize call (await operator) before using the peer connection object for anything else.

Declaration

public bool Initialized { get; }

Property Value

Type	Description
Boolean

IsConnected

Indicates whether the peer connection is established and can exchange some track content (audio/video/data) with the remote peer.

Declaration

public bool IsConnected { get; }

Property Value

Type	Description
Boolean

Remarks

This does not indicate whether the ICE exchange is done, as it may continue after the peer connection negotiated a first session. For ICE connection status, see the IceStateChanged event.

LocalAudioTracks

Collection of local audio tracks attached to the peer connection.

Declaration

public IEnumerable<LocalAudioTrack> LocalAudioTracks { get; }

Property Value

Type	Description
IEnumerable<LocalAudioTrack>

LocalVideoTracks

Collection of local video tracks attached to the peer connection.

Declaration

public IEnumerable<LocalVideoTrack> LocalVideoTracks { get; }

Property Value

Type	Description
IEnumerable<LocalVideoTrack>

Name

A name for the peer connection, used for logging and debugging.

Declaration

public string Name { get; set; }

Property Value

Type	Description
String

RemoteAudioTracks

Collection of remote audio tracks attached to the peer connection.

Declaration

public IEnumerable<RemoteAudioTrack> RemoteAudioTracks { get; }

Property Value

Type	Description
IEnumerable<RemoteAudioTrack>

RemoteVideoTracks

Collection of remote video tracks attached to the peer connection.

Declaration

public IEnumerable<RemoteVideoTrack> RemoteVideoTracks { get; }

Property Value

Type	Description
IEnumerable<RemoteVideoTrack>

Transceivers

Collection of transceivers for the peer connection. Once a transceiver is added to the peer connection, it cannot be removed, but its tracks can be changed. Adding a transceiver or changing its direction require some new session negotiation.

Declaration

public List<Transceiver> Transceivers { get; }

Property Value

Type	Description
List<Transceiver>

Methods

AddDataChannelAsync(String, Boolean, Boolean, CancellationToken)

Add a new in-band data channel whose ID will be determined by the implementation.

A data channel is branded in-band when one peer requests its creation to the WebRTC core, and the implementation negotiates with the remote peer an appropriate ID by sending some SDP offer message. In that case once accepted the other peer will automatically create the appropriate data channel on its side with that same ID, and the ID will be returned on both sides to the user for information.

Compared to out-of-band messages, this requires exchanging some SDP messages, but avoids having to agree on a common unused ID and having to explicitly open the data channel on both sides.

Declaration

public Task<DataChannel> AddDataChannelAsync(string label, bool ordered, bool reliable, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
String	label	The data channel name.
Boolean	ordered	Indicates whether data channel messages are ordered (see Ordered).
Boolean	reliable	Indicates whether data channel messages are reliably delivered (see Reliable).
CancellationToken	cancellationToken	Cancellation token for the task returned.

Returns

Type	Description
Task<DataChannel>	Returns a task which completes once the data channel is created.

Remarks

See the critical remark about SCTP handshake in AddDataChannelAsync(UInt16, String, Boolean, Boolean, CancellationToken).

Exceptions

Type	Condition
SctpNotNegotiatedException	SCTP not negotiated. Call CreateOffer() first.

AddDataChannelAsync(UInt16, String, Boolean, Boolean, CancellationToken)

Add a new out-of-band data channel with the given ID.

A data channel is branded out-of-band when the peers agree on an identifier by any mean not known to WebRTC, and both open a data channel with that ID. The WebRTC will match the incoming and outgoing pipes by this ID to allow sending and receiving through that channel.

This requires some external mechanism to agree on an available identifier not otherwise taken by another channel, and also requires to ensure that both peers explicitly open that channel. The advantage of in-band data channels is that no SDP session renegotiation is needed, except for the very first data channel added (in-band or out-of-band) which requires a negotiation for the SCTP handshake (see remarks).

Declaration

public Task<DataChannel> AddDataChannelAsync(ushort id, string label, bool ordered, bool reliable, CancellationToken cancellationToken = null)

Parameters

Type	Name	Description
UInt16	id	The unique data channel identifier to use.
String	label	The data channel name.
Boolean	ordered	Indicates whether data channel messages are ordered (see Ordered).
Boolean	reliable	Indicates whether data channel messages are reliably delivered (see Reliable).
CancellationToken	cancellationToken	Cancellation token for the task returned.

Returns

Type	Description
Task<DataChannel>	Returns a task which completes once the data channel is created.

Remarks

Data channels use DTLS over SCTP, which ensure in particular that messages are encrypted. To that end, while establishing a connection with the remote peer, some specific SCTP handshake must occur. This handshake is only performed if at least one data channel was added to the peer connection when the connection starts its negotiation with CreateOffer(). Therefore, if the user wants to use a data channel at any point during the lifetime of this peer connection, it is critical to add at least one data channel before CreateOffer() is called. Otherwise all calls will fail with an SctpNotNegotiatedException exception.

Exceptions

Type	Condition
SctpNotNegotiatedException	SCTP not negotiated. Call CreateOffer() first.

AddIceCandidate(IceCandidate)

Inform the WebRTC peer connection of a newly received ICE candidate.

Declaration

public void AddIceCandidate(IceCandidate candidate)

Parameters

Type	Name	Description
IceCandidate	candidate	The ICE candidate received from the remote peer.

AddTransceiver(MediaKind, TransceiverInitSettings)

Add to the current connection a new media transceiver.

A transceiver is a container for a pair of media tracks, one local sending to the remote peer, and one remote receiving from the remote peer. Both are optional, and the transceiver can be in receive-only mode (no local track), in send-only mode (no remote track), or inactive (neither local nor remote track).

Once a transceiver is added to the peer connection, it cannot be removed, but its tracks can be changed (this requires some renegotiation).

Declaration

public Transceiver AddTransceiver(MediaKind mediaKind, TransceiverInitSettings settings = null)

Parameters

Type	Name	Description
MediaKind	mediaKind	Kind of media the transeiver is transporting.
TransceiverInitSettings	settings	Settings to initialize the new transceiver.

Returns

Type	Description
Transceiver	The newly created transceiver.

Close()

Close the peer connection and destroy the underlying native resources.

Declaration

public void Close()

Remarks

This is equivalent to Dispose().

See Also

Dispose()

CreateAnswer()

Create an SDP answer message to a previously-received offer, to accept a connection. Once the message is ready to be sent, the LocalSdpReadytoSend event is fired to allow the user to send that message to the remote peer via its selected signaling solution. Note that this cannot be called before SetRemoteDescriptionAsync(SdpMessage) successfully completed and applied the remote offer.

Declaration

public bool CreateAnswer()

Returns

Type	Description
Boolean	true if the answer creation task was successfully submitted.

Remarks

The SDP answer message is not successfully created until the LocalSdpReadytoSend event is triggered, and may still fail even if this method returns true, for example if the peer connection is not in a valid state to create an answer.

CreateOffer()

Create an SDP offer message as an attempt to establish a connection. Once the message is ready to be sent, the LocalSdpReadytoSend event is fired to allow the user to send that message to the remote peer via its selected signaling solution.

Declaration

public bool CreateOffer()

Returns

Type	Description
Boolean	true if the offer creation task was successfully submitted.

Remarks

The SDP offer message is not successfully created until the LocalSdpReadytoSend event is triggered, and may still fail even if this method returns true, for example if the peer connection is not in a valid state to create an offer.

Dispose()

Dispose of native resources by closing the peer connection.

Declaration

public void Dispose()

Remarks

This is equivalent to Close().

See Also

Close()

GetSimpleStatsAsync()

Get a snapshot of the statistics relative to the peer connection.

Declaration

public Task<PeerConnection.StatsReport> GetSimpleStatsAsync()

Returns

Type	Description
Task<PeerConnection.StatsReport>

InitializeAsync(PeerConnectionConfiguration, CancellationToken)

Initialize the current peer connection object asynchronously.

Most other methods will fail unless this call completes successfully, as it initializes the underlying native implementation object required to create and manipulate the peer connection.

Once this call asynchronously completed, the Initialized property is true.

Declaration

public Task InitializeAsync(PeerConnectionConfiguration config = null, CancellationToken token = null)

Parameters

Type	Name	Description
PeerConnectionConfiguration	config	Configuration for initializing the peer connection.
CancellationToken	token	Optional cancellation token for the initialize task. This is only used if the singleton task was created by this call, and not a prior call.

Returns

Type	Description
Task	The singleton task used to initialize the underlying native peer connection.

Remarks

This method is multi-thread safe, and will always return the same task object from the first call to it until the peer connection object is deinitialized. This allows multiple callers to all execute some action following the initialization, without the need to force a single caller and to synchronize with it.

RemoveDataChannel(DataChannel)

Remove an existing data channel from the peer connection and destroy its native implementation.

Declaration

public void RemoveDataChannel(DataChannel dataChannel)

Parameters

Type	Name	Description
DataChannel	dataChannel	The data channel to remove and destroy.

SetBitrate(Nullable<UInt32>, Nullable<UInt32>, Nullable<UInt32>)

Set the bitrate allocated to all RTP streams sent by this connection. Other limitations might affect these limits and are respected (for example "b=AS" in SDP).

Declaration

public void SetBitrate(uint? minBitrateBps = null, uint? startBitrateBps = null, uint? maxBitrateBps = null)

Parameters

Type	Name	Description
Nullable<UInt32>	minBitrateBps	Minimum bitrate in bits per second.
Nullable<UInt32>	startBitrateBps	Start/current target bitrate in bits per second.
Nullable<UInt32>	maxBitrateBps	Maximum bitrate in bits per second.

SetFrameHeightRoundMode(PeerConnection.FrameHeightRoundMode)

[HoloLens 1 only] Use this function to select whether resolutions where height is not multiple of 16 pixels should be cropped, padded, or left unchanged.

Default is Crop to avoid severe artifacts produced by the H.264 hardware encoder on HoloLens 1 due to a bug with the encoder. This is the recommended value, and should be used unless cropping discards valuable data in the top and bottom rows for a given usage, in which case Pad can be used as a replacement but may still produce some mild artifacts.

This has no effect on other platforms.

Declaration

public static void SetFrameHeightRoundMode(PeerConnection.FrameHeightRoundMode value)

Parameters

Type	Name	Description
PeerConnection.FrameHeightRoundMode	value	The rounding mode for video frames.

SetH264Config(PeerConnection.H264Config)

Set the configuration used by the H.264 encoder. The passed value will apply to all tracks that start streaming, from any PeerConnection created by the application, after the call to this function.

Declaration

public static void SetH264Config(PeerConnection.H264Config config)

Parameters

Type	Name	Description
PeerConnection.H264Config	config

SetRemoteDescriptionAsync(SdpMessage)

Pass the given SDP description received from the remote peer via signaling to the underlying WebRTC implementation, which will parse and use it.

This must be called by the signaler when receiving a message. Once this operation has completed, it is safe to call CreateAnswer().

Declaration

public Task SetRemoteDescriptionAsync(SdpMessage message)

Parameters

Type	Name	Description
SdpMessage	message	The SDP message

Returns

Type	Description
Task	Returns a task which completes once the remote description has been applied and transceivers have been updated.

ToString()

Declaration

public override string ToString()

Returns

Type	Description
String

Events

AudioTrackAdded

Event that occurs when a remote audio track is added to the current connection.

Declaration

public event PeerConnection.AudioTrackAddedDelegate AudioTrackAdded

Event Type

Type	Description
PeerConnection.AudioTrackAddedDelegate

AudioTrackRemoved

Event that occurs when a remote audio track is removed from the current connection.

Declaration

public event PeerConnection.AudioTrackRemovedDelegate AudioTrackRemoved

Event Type

Type	Description
PeerConnection.AudioTrackRemovedDelegate

Connected

Event fired when a connection is established.

Declaration

public event Action Connected

Event Type

Type	Description
Action

DataChannelAdded

Event fired when a data channel is added to the peer connection. This event is always fired, whether the data channel is created by the local peer or the remote peer, and is negotiated (out-of-band) or not (in-band). If an in-band data channel is created by the local peer, the ID field is not yet available when this event is fired, because the ID has not been agreed upon with the remote peer yet.

Declaration

public event PeerConnection.DataChannelAddedDelegate DataChannelAdded

Event Type

Type	Description
PeerConnection.DataChannelAddedDelegate

DataChannelRemoved

Event fired when a data channel is removed from the peer connection. This event is always fired, whatever its creation method (negotiated or not) and original creator (local or remote peer).

Declaration

public event PeerConnection.DataChannelRemovedDelegate DataChannelRemoved

Event Type

Type	Description
PeerConnection.DataChannelRemovedDelegate

IceCandidateReadytoSend

Event that occurs when a local ICE candidate is ready to be transmitted.

Declaration

public event PeerConnection.IceCandidateReadytoSendDelegate IceCandidateReadytoSend

Event Type

Type	Description
PeerConnection.IceCandidateReadytoSendDelegate

IceGatheringStateChanged

Event that occurs when the state of the ICE gathering changed.

Declaration

public event PeerConnection.IceGatheringStateChangedDelegate IceGatheringStateChanged

Event Type

Type	Description
PeerConnection.IceGatheringStateChangedDelegate

IceStateChanged

Event that occurs when the state of the ICE connection changed.

Declaration

public event PeerConnection.IceStateChangedDelegate IceStateChanged

Event Type

Type	Description
PeerConnection.IceStateChangedDelegate

LocalSdpReadytoSend

Event that occurs when a local SDP message is ready to be transmitted.

Declaration

public event PeerConnection.LocalSdpReadyToSendDelegate LocalSdpReadytoSend

Event Type

Type	Description
PeerConnection.LocalSdpReadyToSendDelegate

RenegotiationNeeded

Event that occurs when a renegotiation of the session is needed. This generally occurs as a result of adding or removing tracks, and the user should call CreateOffer() to actually start a renegotiation.

Declaration

public event Action RenegotiationNeeded

Event Type

Type	Description
Action

TransceiverAdded

Event that occurs when a transceiver is added to the peer connection, either manually using AddTransceiver(MediaKind, TransceiverInitSettings), or automatically as a result of a new session negotiation.

Declaration

public event PeerConnection.TransceiverAddedDelegate TransceiverAdded

Event Type

Type	Description
PeerConnection.TransceiverAddedDelegate

Remarks

Transceivers cannot be removed from the peer connection, so there is no TransceiverRemoved event.

VideoTrackAdded

Event that occurs when a remote video track is added to the current connection.

Declaration

public event PeerConnection.VideoTrackAddedDelegate VideoTrackAdded

Event Type

Type	Description
PeerConnection.VideoTrackAddedDelegate

VideoTrackRemoved

Event that occurs when a remote video track is removed from the current connection.

Declaration

public event PeerConnection.VideoTrackRemovedDelegate VideoTrackRemoved

Event Type

Type	Description
PeerConnection.VideoTrackRemovedDelegate