Class PeerConnection
The WebRTC peer connection object is the entry point to using WebRTC.
Namespace: Microsoft.MixedReality.WebRTC
Assembly: Microsoft.MixedReality.WebRTC.dll
Syntax
public class PeerConnection : IDisposable
Fields
| Improve this Doc View SourcePreferredAudioCodec
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
| Improve this Doc View SourceInitialized
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
| Improve this Doc View SourceAddDataChannelAsync(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 |
|
CreateOffer()
Create an SDP offer message as an attempt to establish a connection.
Declaration
public bool CreateOffer()
Returns
Type | Description |
---|---|
Boolean |
|
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 |
|
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 |
|
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 |
|
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 |
|
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
| Improve this Doc View SourceARGBLocalVideoFrameReady
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> |