Documentation

Class: LocalVideoTrack

LocalVideoTrack

A LocalVideoTrack is a VideoTrack representing video that your LocalParticipant can publish to a Room. It can be enabled and disabled with LocalVideoTrack#enable and LocalVideoTrack#disable or stopped completely with LocalVideoTrack#stop.

new Twilio.Video.LocalVideoTrack(mediaStreamTrack [, options])

Construct a LocalVideoTrack from a MediaStreamTrack.

Parameters:
Name Type Argument Description
mediaStreamTrack MediaStreamTrack

The underlying MediaStreamTrack
options LocalTrackOptions <optional>

LocalTrack options
Properties:
Name Type Description
id Track.ID

The LocalVideoTrack's ID
isStopped boolean

Whether or not the LocalVideoTrack is stopped
Fires:

Extends

Methods

addProcessor(processor)

Add a VideoProcessor to allow for custom processing of video frames belonging to a VideoTrack. Only Chrome supports this as of now. Calling this API from a non-supported browser will result in a log warning.

Parameters:
Name Type Description
processor VideoProcessor

The VideoProcessor to use.
Overrides:
Returns:
Type
this
Example
class GrayScaleProcessor {
  constructor(percentage) {
    this.outputFrame = new OffscreenCanvas(0, 0);
    this.percentage = percentage;
  }
  processFrame(inputFrame) {
    this.outputFrame.width = inputFrame.width;
    this.outputFrame.height = inputFrame.height;

    const context = this.outputFrame.getContext('2d');
    context.filter = `grayscale(${this.percentage}%)`;
    context.drawImage(inputFrame, 0, 0, inputFrame.width, inputFrame.height);
    return this.outputFrame;
  }
}

const localVideoTrack = Array.from(room.localParticipant.videoTracks.values())[0].track;
localVideoTrack.addProcessor(new GrayScaleProcessor(100));

attach()

Create an HTMLVideoElement and attach the VideoTrack to it.

The HTMLVideoElement's srcObject will be set to a new MediaStream containing the VideoTrack's MediaStreamTrack.

Inherited From:
Overrides:
Returns:

videoElement

Type
HTMLVideoElement
Example
const Video = require('twilio-video');

Video.createLocalVideoTrack().then(function(videoTrack) {
  const videoElement = videoTrack.attach();
  document.body.appendChild(videoElement);
});

detach()

Detach the VideoTrack from all previously attached HTMLMediaElements.

Inherited From:
Overrides:
Returns:

mediaElements

Type
Array.<HTMLMediaElement>
Example
const mediaElements = videoTrack.detach();
mediaElements.forEach(mediaElement => mediaElement.remove());

disable()

Disable the LocalVideoTrack. This is effectively "pause". If a VideoProcessor is added, then processedTrack is disabled as well.

Fires:
Returns:
Type
this

enable()

Enable the LocalVideoTrack. This is effectively "unpause". If a VideoProcessor is added, then processedTrack is enabled as well.

Fires:
Returns:
Type
this

enable( [enabled])

Enable or disable the LocalVideoTrack. This is effectively "unpause" or "pause". If a VideoProcessor is added, then processedTrack is enabled or disabled as well.

Parameters:
Name Type Argument Default Description
enabled boolean <optional>
 true

Specify false to pause the LocalVideoTrack
Fires:
Returns:
Type
this

removeProcessor(processor)

Remove the previously added VideoProcessor using addProcessor API.

Parameters:
Name Type Description
processor VideoProcessor

The VideoProcessor to remove.
Overrides:
Returns:
Type
this
Example
class GrayScaleProcessor {
  constructor(percentage) {
    this.outputFrame = new OffscreenCanvas(0, 0);
    this.percentage = percentage;
  }
  processFrame(inputFrame) {
    this.outputFrame.width = inputFrame.width;
    this.outputFrame.height = inputFrame.height;

    const context = this.outputFrame.getContext('2d');
    context.filter = `grayscale(${this.percentage}%)`;
    context.drawImage(inputFrame, 0, 0, inputFrame.width, inputFrame.height);
    return this.outputFrame;
  }
}

const localVideoTrack = Array.from(room.localParticipant.videoTracks.values())[0].track;
const grayScaleProcessor = new GrayScaleProcessor(100);
localVideoTrack.addProcessor(grayScaleProcessor);

document.getElementById('remove-button').onclick = () => localVideoTrack.removeProcessor(grayScaleProcessor);

restart( [constraints])

Restart the LocalVideoTrack. This stops the existing MediaStreamTrack and creates a new MediaStreamTrack. If the LocalVideoTrack is being published to a Room, then all the RemoteParticipants will start receiving media from the newly created MediaStreamTrack. You can access the new MediaStreamTrack via the mediaStreamTrack property. If you want to listen to events on the MediaStreamTrack directly, please do so in the "started" event handler. Also, the LocalVideoTrack's ID is no longer guaranteed to be the same as the underlying MediaStreamTrack's ID.

Parameters:
Name Type Argument Description
constraints MediaTrackConstraints <optional>

The optional MediaTrackConstraints for restarting the LocalVideoTrack; If not specified, then the current MediaTrackConstraints will be used; If {} (empty object) is specified, then the default MediaTrackConstraints will be used
Fires:
Returns:

Rejects with a TypeError if the LocalVideoTrack was not created using an one of createLocalVideoTrack, createLocalTracks or connect; Also rejects with the DOMException raised by getUserMedia when it fails

Type
Promise.<void>
Example
const { connect, createLocalVideoTrack } = require('twilio-video');

// Create a LocalVideoTrack that captures video from the front-facing camera.
createLocalVideoTrack({ facingMode: 'user' }).then(function(localVideoTrack) {
  return connect('token', {
    name: 'my-cool-room',
    tracks: [localVideoTrack]
  });
}).then(function(room) {
  // Restart the LocalVideoTrack to capture video from the back-facing camera.
  const localVideoTrack = Array.from(room.localParticipant.videoTracks.values())[0].track;
  return localVideoTrack.restart({ facingMode: 'environment' });
});

stop()

Calls stop on the underlying MediaStreamTrack. If you choose to stop a LocalVideoTrack, you should unpublish it after stopping.

Fires:
Returns:
Type
this

Events

dimensionsChanged

The VideoTrack's dimensions changed.

Parameters:
Name Type Description
track VideoTrack

The VideoTrack whose dimensions changed
Inherited From:
Overrides:

disabled

The LocalVideoTrack was disabled, i.e. "muted".

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that was disabled
Overrides:

enabled

The LocalVideoTrack was enabled, i.e. "unmuted".

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that was enabled
Overrides:

started

The LocalVideoTrack started. This means there is enough video data to begin playback.

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that started
Overrides:

stopped

The LocalVideoTrack stopped, either because LocalVideoTrack#stop or LocalVideoTrack#restart was called or because the underlying MediaStreamTrack ended.

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that stopped