MediaCaptureSource Class

The media produced by a capture device started by MediaCaptureBackend.StartCapture: the video frames of a camera or a screen, or the audio samples of a microphone. The library pulls the media when a sink needs it (a video element paints a frame, ImageCapture.grabFrame(), a Web Audio graph renders a quantum...).

public abstract class MediaCaptureSource : IDisposable

Remarks

The methods are called on the thread of the event loop of the document that started the capture.

Implements

Constructors

NameDescription
MediaCaptureSource(MediaCaptureRequest)Initializes the source of a device.

MediaCaptureSource(MediaCaptureRequest)

MediaCaptureBackend.cs

Initializes the source of a device.

protected MediaCaptureSource(MediaCaptureRequest request)

Parameters

request MediaCaptureRequest
The request of MediaCaptureBackend.StartCapture.

Properties

NameDescription
DeviceGets the device.
IsEndedGets a value indicating whether the source ended (the device was removed): its tracks end.
IsMutedGets a value indicating whether the source is muted (it produces no media for now, e.g. the camera is covered or the operating system took the device).
SettingsGets the current settings of the device.

Gets the device.

public MediaCaptureDevice Device { get; }

Property value

MediaCaptureDevice

Gets a value indicating whether the source ended (the device was removed): its tracks end.

public bool IsEnded { get; }

Property value

bool

Gets a value indicating whether the source is muted (it produces no media for now, e.g. the camera is covered or the operating system took the device).

public bool IsMuted { get; }

Property value

bool

Gets the current settings of the device.

public MediaTrackSettings Settings { get; }

Property value

MediaTrackSettings

Methods

NameDescription
Dispose()Stops the capture: the device is released.
Dispose(bool)Releases the device.
End()Ends the source (e.g. the device was removed): its tracks end and get an ended event. Can be called from any thread.
GetVideoFrame(TimeSpan)Returns the video frame of a camera or a screen at a time, or null when there is no frame (an audio device, or a device that has not produced a frame yet). The size of the frame should be the one of the settings: a frame of another size is scaled.
OnSettingsChanged(MediaTrackSettings)Called when the settings of the device changed (see MediaCaptureSource.Settings).
ReadAudio(long, Span<float>)Reads the audio samples of a microphone: destination receives the interleaved samples (one per channel of the settings) of the frames from position, at the sample rate of the settings, as 32-bit floats between -1 and 1. The default implementation writes silence.
SetMuted(bool)Changes whether the source is muted: the tracks get a mute or an unmute event. Can be called from any thread.

Dispose overloads

Stops the capture: the device is released.

public void Dispose()

Releases the device.

protected virtual void Dispose(bool disposing)
Parameters
disposing bool
Whether the method is called by MediaCaptureSource.Dispose.

Ends the source (e.g. the device was removed): its tracks end and get an ended event. Can be called from any thread.

protected void End()

GetVideoFrame(TimeSpan)

MediaCaptureBackend.cs

Returns the video frame of a camera or a screen at a time, or null when there is no frame (an audio device, or a device that has not produced a frame yet). The size of the frame should be the one of the settings: a frame of another size is scaled.

public virtual MediaVideoFrame? GetVideoFrame(TimeSpan timestamp)

Parameters

timestamp TimeSpan
The time since the start of the capture, measured with the clock of the request.

Returns

MediaVideoFrame?

OnSettingsChanged(MediaTrackSettings)

MediaCaptureBackend.cs

Called when the settings of the device changed (see MediaCaptureSource.Settings).

protected virtual void OnSettingsChanged(MediaTrackSettings settings)

Parameters

settings MediaTrackSettings
The new settings.

ReadAudio(long, Span<float>)

MediaCaptureBackend.cs

Reads the audio samples of a microphone: destination receives the interleaved samples (one per channel of the settings) of the frames from position, at the sample rate of the settings, as 32-bit floats between -1 and 1. The default implementation writes silence.

public virtual void ReadAudio(long position, Span<float> destination)

Parameters

position long
The index of the first sample frame (the number of frames since the start of the capture).
destination Span<float>
The buffer to fill: a whole number of frames.

Changes whether the source is muted: the tracks get a mute or an unmute event. Can be called from any thread.

protected void SetMuted(bool muted)

Parameters

muted bool
Whether the source is muted.