LocalVideo

The LocalVideo model allows enabling and disabling the local participant's video and video processor.

An example of using the model:

  1. Before a conference, the local participant calls one of the start methods to start video transmission from either a camera or a custom track. The participant can also use the processor parameter to blur or change their background. This allows the participant to preview their video before joining.

  2. The participant receives the videoStarted event.

  3. To disable the video preview, the participant can call the stop method that triggers the videoStopped event.

  4. The participant joins a conference.

  5. When the participant's video stream is successfully sent to the conference, the participant receives the streamAdded or streamUpdated event.

  6. The participant can change the video setting while being in the conference by:

To ensure the proper work of the video processor, the vsl_impl.wasm and vsl_impl.pkgwvsl files need to be accessible for download at URL that can be configured using the packageUrlPrefix accessor.

This model is supported only in SDK 3.7 and later.

Events

videoStarted

videoStarted(result: MediaStreamTrack): void

Emitted when the local participant's camera or a custom video has been enabled.

Example:

VoxeetSDK.video.local.on('videoStarted', (result) => {

});

Parameters:

NameTypeDescription
resultMediaStreamTrackA new MediaStreamTrack object.

Returns: void


videoStopped

videoStopped(result: MediaStreamTrack): void

Emitted when the local participant's camera or a custom video has been disabled.

Example:

VoxeetSDK.video.local.on('videoStopped', (result) => {

});

Parameters:

NameTypeDescription
resultMediaStreamTrackThe stopped MediaStreamTrack object.

Returns: void


videoUpdated

videoUpdated(result: MediaStreamTrack): void

Emitted whenever a video captured by the local participant's camera or a custom video is updated.

The event is emitted in the following situations:

  • A video input device is changed successfully when the local participant's video is enabled.
  • A video processing is enabled or disabled when the local participant's video is enabled.

Example:

VoxeetSDK.video.on('videoUpdated', (result) => {

});

Parameters:

NameTypeDescription
resultMediaStreamTrackThe stopped MediaStreamTrack object.

Returns: void

Methods

applyConstraints

applyConstraints(constraints: MediaTrackConstraints): Promise

Applies a set of constraints to a video track to allow setting ideal values and acceptable value ranges of constrainable properties of the track, such as frame rate or dimensions. The method does not allow setting the deviceId and groupId constraints. If the required constraints are too strict to find a match during a track configuration attempt, the promise is rejected with the VideoServiceError. We recommend using this method for applying constraints, especially when video processing is enabled; MediaStreamTrack.applyconstraints() may not work as expected when the video processor is enabled.

Calling this method when the local video is not started causes a promise rejection with the VideoServiceError.

Parameters:

NameTypeDescription
constraints?MediaTrackConstraints-

Returns: Promise


disableProcessing

disableProcessing(): Promise<void>

Disables video processing.

Returns: Promise<void> A Promise that resolves when the processor is successfully disabled. If the processor cannot be disabled, the promise is rejected with the VideoServiceError.


setProcessor

setProcessor(processor: VideoProcessor): Promise<void>

Enables video processing and adds a video processor to the existing local participant's video stream to blur the participant's background or replace the background with an image. If the processor is enabled via one of the start methods, the setProcessor method allows changing the processor.

📘

Note

This method requires using Chrome or Edge on a desktop operating system with Graphics Processing Unit (GPU) acceleration enabled and the following minimum hardware requirements:

  • i5 dual-core CPU
  • 8GB of RAM
  • 64-bit operating system

❗️

Note

If you use two different URLs for serving your application and hosting the SDK through a Content Delivery Network (CDN), you have to enable cross-origin resource sharing (CORS) to use this method. To enable CORS, see the Install the SDK instruction.

For more information about using this method, see the Enable Video Processing guide.

Parameters:

NameTypeDescription
processorVideoProcessorThe video processor configuration.

Returns: Promise<void> A Promise that resolves when the processor is successfully enabled and set. If the processor cannot be enabled, the promise is rejected with the VideoServiceError.


start

start(constraints?: MediaTrackConstraints, processor?: VideoProcessor): Promise<MediaStreamTrack>

Enables the local participant's camera and starts a video stream transmission. If the local participant calls this method before a conference, the SDK starts a camera stream that will be added to the conference after joining and the participant can see the video preview. If the participant calls this method in a conference, the method starts sending the participant's video stream to the conference.

If the participant calls this method when their video is already enabled, the SDK stops the existing video stream and starts a new one with new constraints.

The method triggers the videoStarted event. Adding a new video stream to a conference additionally triggers the streamAdded or streamUpdated events.

This method is not available for listeners and triggers the UnsupportedError.

📘

Note

This method requires using Chrome or Edge with Graphics Processing Unit (GPU) acceleration enabled and the following minimum hardware requirements:

  • i5 dual-core CPU
  • 8GB of RAM
  • 64-bit operating system

Example:

const videoConstraints = {
  width: {
    min: "320",
    max: "1280",
  },
  height: {
    min: "240",
    max: "720",
  },
;
 
await VoxeetSDK.video.local.start(videoConstraints);

For more information about using video processing, see the Enable Video Processing guide.

Parameters:

NameTypeDescription
constraints?MediaTrackConstraints-
processor?VideoProcessorThe video processor configuration.

Returns: Promise<MediaStreamTrack> A Promise which handler receives a MediaStreamTrack object. If the track cannot be created, the promise is rejected with the VideoServiceError.

start

start(customTrack: MediaStreamTrack, processor?: VideoProcessor): Promise<MediaStreamTrack>

Starts transmission of the local participant's video from a custom track. If the local participant calls this method before a conference, the SDK starts a new stream that will be added to the conference after joining and the participant can see the video preview. If the participant calls this method in a conference, the method starts sending the participant's video stream to the conference.

If the participant calls this method when their video is already enabled, the SDK stops the existing video stream and starts a new one with new constraints.

The method triggers the videoStarted event. Adding a new video stream to a conference additionally triggers the streamAdded or streamUpdated events.

This method is not available for listeners and triggers the UnsupportedError.

📘

Note

This method requires using Chrome or Edge with Graphics Processing Unit (GPU) acceleration enabled and the following minimum hardware requirements:

  • i5 dual-core CPU
  • 8GB of RAM
  • 64-bit operating system

Parameters:

NameTypeDescription
customTrackMediaStreamTrackThe MediaStreamTrack object
processor?VideoProcessorThe video processor configuration.

Returns: Promise<MediaStreamTrack> A Promise whose fulfilment handler receives a MediaStreamTrack object. If the track cannot be created, the promise is rejected with the VideoServiceError.


stop

stop(): Promise<void>

Stops the local participant's video stream transmission. Disabling video before a conference triggers the SDK to emit the videoStopped event. Calling this method in a conference additionally triggers the streamAdded or streamUpdated event.

Example:

await VoxeetSDK.video.local.stop();

Returns: Promise<void> A Promise which resolves when the video is successfully stopped. If the video cannot be stopped, the promise is rejected with the VideoServiceError.