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

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

PreferredAudioCodecExtraParams

Advanced use only. A semicolon-separated list of "key=value" pairs of arguments passed as extra parameters to the preferred audio codec during SDP filtering. This enables configuring codec-specific parameters. Arguments are passed as is, and there is no check on the validity of the parameter names nor their value. This is ignored if PreferredAudioCodec is an empty string, or is not a valid codec name found in the SDP message offer.

Declaration

public string PreferredAudioCodecExtraParams

Field Value

Type	Description
String

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

PreferredVideoCodecExtraParams

Advanced use only. A semicolon-separated list of "key=value" pairs of arguments passed as extra parameters to the preferred video codec during SDP filtering. This enables configuring codec-specific parameters. Arguments are passed as is, and there is no check on the validity of the parameter names nor their value. This is ignored if PreferredVideoCodec is an empty string, or is not a valid codec name found in the SDP message offer.

Declaration

public string PreferredVideoCodecExtraParams

Field Value

Type	Description
String

Properties

Initialized

Boolean property indicating whether the peer connection has been initialized.

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.

Methods

AddDataChannelAsync(String, Boolean, Boolean)

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

A data channel is negotiated 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 negotiated ID, and the ID will be returned on both sides to the user for information.

Compares to out-of-band messages, this requires exchanging some SDP messages, but avoids having to determine 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)

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).

Returns

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

AddDataChannelAsync(UInt16, String, Boolean, Boolean)

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

A data channel is negotiated 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.

Declaration

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

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).

Returns

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

AddIceCandidate(String, Int32, String)

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

Declaration

public void AddIceCandidate(string sdpMid, int sdpMlineindex, string candidate)

Parameters

Type	Name	Description
String	sdpMid
Int32	sdpMlineindex
String	candidate

AddLocalAudioTrackAsync()

Add to the current connection an audio track from a local audio capture device (microphone).

Declaration

public Task AddLocalAudioTrackAsync()

Returns

Type	Description
Task	Asynchronous task completed once the device is capturing and the track is added.

Remarks

On UWP this requires the "microphone" capability. See https://docs.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations for more details.

PeerConnection supports a single local audio track and a single local video track. In order to send/receive multiple tracks to/from a given remote device, developers need to use multiple PeerConnection instances.

AddLocalVideoTrackAsync(PeerConnection.LocalVideoTrackSettings)

Add to the current connection a video track from a local video capture device (webcam).

Declaration

public Task AddLocalVideoTrackAsync(PeerConnection.LocalVideoTrackSettings settings = null)

Parameters

Type	Name	Description
PeerConnection.LocalVideoTrackSettings	settings	Video capture settings for the local video track.

Returns

Type	Description
Task	Asynchronous task completed once the device is capturing and the track is added.

Remarks

On UWP this requires the "webcam" capability. See https://docs.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations for more details.

PeerConnection supports a single local audio track and a single local video track. In order to send/receive multiple tracks to/from a given remote device, developers need to use multiple PeerConnection instances.

Close()

Close the peer connection and destroy the underlying native resources.

Declaration

public void Close()

Remarks

This is equivalent to Dispose().

CreateAnswer()

Create an SDP answer message to a previously-received offer, to accept a connection.

Declaration

public bool CreateAnswer()

Returns

Type	Description
Boolean	true if the offer was created successfully.

CreateOffer()

Create an SDP offer message as an attempt to establish a connection.

Declaration

public bool CreateOffer()

Returns

Type	Description
Boolean	true if the offer was created successfully.

Dispose()

Dispose of native resources by closing the peer connection.

Declaration

public void Dispose()

Remarks

This is equivalent to Close().

GetVideoCaptureDevicesAsync()

Get the list of available video capture devices.

Declaration

public static Task<List<VideoCaptureDevice>> GetVideoCaptureDevicesAsync()

Returns

Type	Description
Task<List<VideoCaptureDevice>>	The list of available video capture devices.

GetVideoCaptureFormatsAsync(String)

Enumerate the video capture formats for the specified video captur device.

Declaration

public static Task<List<VideoCaptureFormat>> GetVideoCaptureFormatsAsync(string deviceId)

Parameters

Type	Name	Description
String	deviceId	Unique identifier of the video capture device to enumerate the capture formats of, as retrieved from the id field of a capture device enumerated with GetVideoCaptureDevicesAsync().

Returns

Type	Description
Task<List<VideoCaptureFormat>>	The list of available video capture formats for the specified video capture device.

InitializeAsync(PeerConnectionConfiguration, CancellationToken)

Initialize the current peer connection object asynchronously.

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.

IsLocalAudioTrackEnabled()

Check if the local audio track associated with this peer connection is enabled. Disable audio tracks are still active, but are silent.

Declaration

public bool IsLocalAudioTrackEnabled()

Returns

Type	Description
Boolean	true if the track is enabled, or false otherwise

IsLocalVideoTrackEnabled()

Check if the local video track associated with this peer connection is enabled. Disable video tracks are still active, but emit only black frames.

Declaration

public bool IsLocalVideoTrackEnabled()

Returns

Type	Description
Boolean	true if the track is enabled, or false otherwise

RemoveLocalAudioTrack()

Remove from the current connection the local audio track added with AddLocalAudioTrackAsync().

Declaration

public void RemoveLocalAudioTrack()

RemoveLocalVideoTrack()

Remove from the current connection the local video track added with AddLocalAudioTrackAsync().

Declaration

public void RemoveLocalVideoTrack()

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 should be cropped, padded or left unchanged. Default is Crop to avoid severe artifacts produced by the H.264 hardware encoder on HoloLens 1. 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.

SetLocalAudioTrackEnabled(Boolean)

Enable or disable the local audio track associated with this peer connection. Disable audio tracks are still active, but are silent.

Declaration

public void SetLocalAudioTrackEnabled(bool enabled = true)

Parameters

Type	Name	Description
Boolean	enabled	true to enable the track, or false to disable it

SetLocalVideoTrackEnabled(Boolean)

Enable or disable the local video track associated with this peer connection. Disable video tracks are still active, but emit only black frames.

Declaration

public void SetLocalVideoTrackEnabled(bool enabled = true)

Parameters

Type	Name	Description
Boolean	enabled	true to enable the track, or false to disable it

SetRemoteDescription(String, String)

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.

Declaration

public void SetRemoteDescription(string type, string sdp)

Parameters

Type	Name	Description
String	type	The type of SDP message ("offer", "answer", "ice")
String	sdp	The content of the SDP message

Events

ARGBLocalVideoFrameReady

Event that occurs when a video frame from a local track has been produced locally and is available for render.

Declaration

public event ARGBVideoFrameDelegate ARGBLocalVideoFrameReady

Event Type

Type	Description
ARGBVideoFrameDelegate

ARGBRemoteVideoFrameReady

Event that occurs when a video frame from a remote peer has been received and is available for render.

Declaration

public event ARGBVideoFrameDelegate ARGBRemoteVideoFrameReady

Event Type

Type	Description
ARGBVideoFrameDelegate

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

I420LocalVideoFrameReady

Event that occurs when a video frame from a local track has been produced locally and is available for render.

Declaration

public event I420VideoFrameDelegate I420LocalVideoFrameReady

Event Type

Type	Description
I420VideoFrameDelegate

I420RemoteVideoFrameReady

Event that occurs when a video frame from a remote peer has been received and is available for render.

Declaration

public event I420VideoFrameDelegate I420RemoteVideoFrameReady

Event Type

Type	Description
I420VideoFrameDelegate

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

IceStateChanged

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

Declaration

public event PeerConnection.IceStateChangedDelegate IceStateChanged

Event Type

Type	Description
PeerConnection.IceStateChangedDelegate

LocalAudioFrameReady

Event that occurs when an audio frame from a local track has been produced locally and is available for render.

Declaration

public event AudioFrameDelegate LocalAudioFrameReady

Event Type

Type	Description
AudioFrameDelegate

Remarks

WARNING -- This is currently not implemented in the underlying WebRTC implementation, so THIS EVENT IS NEVER FIRED.

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

RemoteAudioFrameReady

Event that occurs when an audio frame from a remote peer has been received and is available for render.

Declaration

public event AudioFrameDelegate RemoteAudioFrameReady

Event Type

Type	Description
AudioFrameDelegate

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

TrackAdded

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

Declaration

public event Action<PeerConnection.TrackKind> TrackAdded

Event Type

Type	Description
Action<PeerConnection.TrackKind>

TrackRemoved

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

Declaration

public event Action<PeerConnection.TrackKind> TrackRemoved

Event Type

Type	Description
Action<PeerConnection.TrackKind>