Class DeviceVideoTrackSource

Implementation of a video track source producing frames captured from a video capture device (webcam).

Inheritance

Object

VideoTrackSource

DeviceVideoTrackSource

Implements

IVideoSource

IDisposable

Inherited Members

VideoTrackSource.Name

VideoTrackSource.Tracks

VideoTrackSource.I420AVideoFrameReady

VideoTrackSource.Argb32VideoFrameReady

VideoTrackSource.Enabled

VideoTrackSource.Dispose()

Namespace: Microsoft.MixedReality.WebRTC

Assembly: Microsoft.MixedReality.WebRTC.dll

Syntax

public class DeviceVideoTrackSource : VideoTrackSource, IVideoSource

Properties

FrameEncoding

Video encoding indicating the kind of frames the source is producing.

Declaration

public override VideoEncoding FrameEncoding { get; }

Property Value

Type	Description
VideoEncoding

Overrides

VideoTrackSource.FrameEncoding

Methods

CreateAsync(LocalVideoDeviceInitConfig)

Create a video track source using a local video capture device (webcam).

The video track source produces raw video frames by capturing them from a capture device accessible from the local host machine, generally a USB webcam or built-in device camera. The video source initially starts in the capturing state, and will remain live for as long as the source is alive. Once the source is not live anymore (ended), it cannot be restarted. A new source must be created to use the same video capture device again.

The source can be used to create one or more local video tracks (LocalVideoTrack), which once added to a video transceiver allow the video frames to be sent to a remote peer. The source itself is not associated with any peer connection, and can be used to create local video tracks from multiple peer connections at once, thereby being shared amongst those peer connections.

The source is owned by the user, who must ensure it stays alive while being in use by at least one local video track. Once it is not used anymore, the user is in charge of disposing of the source. Disposing of a source still in use by a local video track is undefined behavior.

Declaration

public static Task<DeviceVideoTrackSource> CreateAsync(LocalVideoDeviceInitConfig initConfig = null)

Parameters

Type	Name	Description
LocalVideoDeviceInitConfig	initConfig	Optional configuration to initialize the video capture on the device.

Returns

Type	Description
Task<DeviceVideoTrackSource>	The newly create video track source.

Remarks

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

The video capture device may be accessed several times during the initializing process, generally once for listing and validating the capture format, and once for actually starting the video capture. This is a limitation of the OS and/or hardware.

Note that the capture device must support a capture format with the given constraints of profile ID or kind, capture resolution, and framerate, otherwise the call will fail. That is, there is no fallback mechanism selecting a closest match. Developers should use GetCaptureFormatsAsync(String) to list the supported formats ahead of calling CreateAsync(LocalVideoDeviceInitConfig), and can build their own fallback mechanism on top of this call if needed.

Examples

Create a video track source with Mixed Reality Capture (MRC) enabled. This assumes that the platform supports MRC. Note that if MRC is not available the call will still succeed, but will return a track without MRC enabled.

var initConfig = new LocalVideoDeviceInitConfig
{
    enableMrc = true
};
var videoSource = await VideoTrackSource.CreateFromDeviceAsync(initConfig);

Create a video track source from a local webcam, asking for a capture format suited for video conferencing, and a target framerate of 30 frames per second (FPS). The implementation will select an appropriate capture resolution. This assumes that the device supports video profiles, and has at least one capture format supporting exactly 30 FPS capture associated with the VideoConferencing profile. Otherwise the call will fail.

var initConfig = new LocalVideoDeviceInitConfig
{
    videoProfileKind = VideoProfileKind.VideoConferencing,
    framerate = 30.0
};
var videoSource = await VideoTrackSource.CreateFromDeviceAsync(initConfig);

See Also

CreateFromSource(VideoTrackSource, LocalVideoTrackInitConfig)

GetCaptureDevicesAsync()

Get the list of video capture devices available on the local host machine.

Declaration

public static Task<IReadOnlyList<VideoCaptureDevice>> GetCaptureDevicesAsync()

Returns

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

Remarks

Assign one of the returned VideoCaptureDevice to the videoDevice field to force a local video track to use that device when creating it with CreateAsync(LocalVideoDeviceInitConfig).

GetCaptureFormatsAsync(String)

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

Declaration

public static Task<IReadOnlyList<VideoCaptureFormat>> GetCaptureFormatsAsync(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 GetCaptureDevicesAsync().

Returns

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

GetCaptureFormatsAsync(String, VideoProfileKind)

Enumerate the video capture formats for the specified video capture device and video profile.

Declaration

public static Task<IReadOnlyList<VideoCaptureFormat>> GetCaptureFormatsAsync(string deviceId, VideoProfileKind profileKind)

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 GetCaptureDevicesAsync().
VideoProfileKind	profileKind	Kind of video profile to enumerate the capture formats of.

Returns

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

GetCaptureFormatsAsync(String, String)

Enumerate the video capture formats for the specified video capture device and video profile.

Declaration

public static Task<IReadOnlyList<VideoCaptureFormat>> GetCaptureFormatsAsync(string deviceId, string profileId)

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 GetCaptureDevicesAsync().
String	profileId	Unique identifier of the video profile to enumerate the capture formats of, as retrieved from id field of a capture device enumerated with GetCaptureDevicesAsync().

Returns

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

GetCaptureProfilesAsync(String)

Enumerate all the video profiles associated with the specified video capture device, if any.

Declaration

public static Task<IReadOnlyList<VideoProfile>> GetCaptureProfilesAsync(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 GetCaptureDevicesAsync().

Returns

Type	Description
Task<IReadOnlyList<VideoProfile>>	The list of available video profiles for the specified video capture device.

Remarks

If the video capture device does not support video profiles, the function succeeds and returns an empty list.

This is equivalent to:

GetCaptureProfilesAsync(deviceId, VideoProfileKind.Unspecified);

See Also

GetCaptureProfilesAsync(String, VideoProfileKind)

GetCaptureProfilesAsync(String, VideoProfileKind)

Enumerate the video profiles associated with the specified video capture device, if any, and restricted to the specified video profile kind.

Declaration

public static Task<IReadOnlyList<VideoProfile>> GetCaptureProfilesAsync(string deviceId, VideoProfileKind profileKind)

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 GetCaptureDevicesAsync().
VideoProfileKind	profileKind	Kind of video profile to enumerate. Specify Unspecified to enumerate all profiles.

Returns

Type	Description
Task<IReadOnlyList<VideoProfile>>	The list of available video profiles for the specified video capture device.

Remarks

If the video capture device does not support video profiles, the function succeeds and returns an empty list.

See Also

GetCaptureProfilesAsync(String)

ToString()

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

VideoTrackSource.ToString()

Implements

IVideoSource

IDisposable