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:

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.local.on('videoUpdated', (result) => {

});

Parameters:

NameTypeDescription
resultMediaStreamTrackThe updated 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 an error. 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 an error.

Parameters:

NameTypeDescription
constraints?MediaTrackConstraintsA set of specifications for controlling and customizing the behavior of media streams.

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 an error.


setProcessor

setProcessor(processor: VideoProcessor | VideoProcessorOptions ): Promise<void>

📘

Note

This method requires using 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

For the best experience, we recommend using Opus and either Chrome or Edge browser.

❗️

Note

Using video processor requires downloading and hosting additional SDK package files. For more information, see the Initializing the SDK guide.

Sets video processing. If the processor is enabled via one of the start methods, the setProcessor method allows changing the processor. Not providing the processor parameter results in disabling video processing. For more information about using this method, see the Video Processing guide.

var processorOptions = {
    virtualBackground: 'bokeh',
};
await VoxeetSDK.video.local.setProcessor(processorOptions);

Parameters:

NameTypeDescription
processorVideoProcessorOptionsThe video processor configuration, either VideoProcessor in SDK 3.10 and earlier or VideoProcessorOptions in SDK 3.11 and later.

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 an error.


start

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

📘

Note

If you want to use the processor parameter, make sure that you use 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

For the best experience, we recommend using Opus and either Chrome or Edge browser.

❗️

Note

Using video processor requires downloading and hosting additional SDK package files. For more information, see the Initializing the SDK guide.

Starts a video stream transmission:

  • When the local participant calls the method before a conference, the SDK starts a camera stream that will be added to the conference after joining, so the participant can see the video preview.
  • When the participant calls the method in a conference when their video is disabled, the method starts sending the participant's video stream to the conference.
  • When the participant calls this method in a conference when their video is enabled, the SDK stops the existing video stream and starts a new one with new constraints.

The constraints and processor parameters are optional. If you choose not to provide constraints, the SDK will use the default ones. For more information about using video processing, see the Video Processing guide.

// If you want to specify constraints:
const videoConstraints = {
  width: {
    min: "320",
    max: "1280",
  },
  height: {
    min: "240",
    max: "720",
  },
}
;
 
await VoxeetSDK.video.local.start(videoConstraints);

// If you want to use the default constraints:
await VoxeetSDK.video.local.start();

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

Before using this method, initialize the SDK and open a session. Otherwise, the SDK triggers the SessionError exception. The method is not available for listeners and triggers the UnsupportedError.

Parameters:

NameTypeDescription
constraints?MediaTrackConstraintsA set of specifications for controlling and customizing the behavior of media streams. When constrains are not specified, the SDK uses 720p (1280 x 720) resolution at 25fps to capture video.
processor?VideoProcessorOptionsThe video processor configuration, either VideoProcessor in SDK 3.10 and earlier or VideoProcessorOptions in SDK 3.11 and later.

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

start

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

📘

Note

If you want to use the processor parameter, make sure that you use 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

For the best experience, we recommend using Opus and either Chrome or Edge browser.

❗️

Note

Using video processor requires downloading and hosting additional SDK package files. For more information, see the Initializing the SDK guide.

Starts a video stream transmission from a custom track:

  • When the local participant calls the method before a conference, the SDK starts a camera stream that will be added to the conference after joining, so the participant can see the video preview.
  • When the participant calls the method in a conference when their video is disabled, the method starts sending the participant's video stream to the conference.
  • When the participant calls this method in a conference when their video is 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.

Before using this method, initialize the SDK and open a session. Otherwise, the SDK triggers the SessionError exception. The method is not available for listeners and triggers the UnsupportedError.

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

Parameters:

NameTypeDescription
customTrackMediaStreamTrackThe MediaStreamTrack object that represents a single media track within a stream.
processor?VideoProcessorOptionsThe video processor configuration, either VideoProcessor in SDK 3.10 and earlier or VideoProcessorOptions in SDK 3.11 and later.

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


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 an error.