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
isMuted boolean

Whether or not the video source has stopped sending frames to the LocalVideoTrack; This can happen when the camera is taken over by another application, mainly on mobile devices; When this property toggles, then muted and unmuted events are fired appropriately
isStopped boolean

Whether or not the LocalVideoTrack is stopped
Fires:

Extends

Methods

addProcessor(processor [, options])

Add a VideoProcessor to allow for custom processing of video frames belonging to a VideoTrack.

Parameters:
Name Type Argument Description
processor VideoProcessor

The VideoProcessor to use.
options AddProcessorOptions <optional>

AddProcessorOptions to provide.
Overrides:
Returns:
Type
this
Example
class GrayScaleProcessor {
  constructor(percentage) {
    this.percentage = percentage;
  }
  processFrame(inputFrameBuffer, outputFrameBuffer) {
    const context = outputFrameBuffer.getContext('2d');
    context.filter = `grayscale(${this.percentage}%)`;
    context.drawImage(inputFrameBuffer, 0, 0, inputFrameBuffer.width, inputFrameBuffer.height);
  }
}

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 equivalent to pausing a video source. If a VideoProcessor is added, then processedTrack is also disabled.

Fires:
Returns:
Type
this

enable()

Enable the LocalVideoTrack. This is equivalent to unpausing the video source. If a VideoProcessor is added, then processedTrack is also enabled.

Fires:
Returns:
Type
this

enable( [enabled])

Enable or disable the LocalVideoTrack. This is equivalent to unpausing or pausing the video source respectively. If a VideoProcessor is added, then processedTrack is also enabled or disabled.

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

Specify false to disable 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.percentage = percentage;
  }
  processFrame(inputFrameBuffer, outputFrameBuffer) {
    const context = outputFrameBuffer.getContext('2d');
    context.filter = `grayscale(${this.percentage}%)`;
    context.drawImage(inputFrameBuffer, 0, 0, inputFrameBuffer.width, inputFrameBuffer.height);
  }
}

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. the video source was paused by the user.

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that was disabled
Overrides:

enabled

The LocalVideoTrack was enabled, i.e. the video source was unpaused by the user.

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that was enabled
Overrides:

muted

The LocalVideoTrack was muted because the video source stopped sending frames, most likely due to another application taking said video source, especially on mobile devices.

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that was muted

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

unmuted

The LocalVideoTrack was unmuted because the video source resumed sending frames, most likely due to the application that took over the said video source has released it back to the application, especially on mobile devices. This event is also fired when LocalVideoTrack#restart is called on a muted LocalVideoTrack with a new video source.

Parameters:
Name Type Description
track LocalVideoTrack

The LocalVideoTrack that was unmuted