Migrating from 1.x to 2.x

• API docs
• Getting started
• QuickStart App

In twilio-video.js 2.x, you can now determine how your downlink bandwidth will be distributed among your subscribed RemoteVideoTracks in a Group Room using the Network Bandwidth Profile API. You can also use the Track Priority API to prioritize certain VideoTracks over others in order to protect audio and higher priority video qualities in times of network congestion.

In twilio-video.js 1.x, you would be disconnected from the Room if you experienced network disruption or handoff. twilio-video.js 2.x will instead attempt to re-establish your signaling and media connections to the Room. You can use the Reconnection States and Events to update your application's user interface accordingly. For more details, please refer to this guide.

NOTE: Please make the following changes to your AccessToken generation logic:

• A valid AccessToken is necessary for reconnection attempts to be successful. Therefore, we recommend that you set its Time-To-Live (TTL) to the maximum allowed session duration, which is currently 14,400 seconds (4 hours).
• Ensure that the AccessToken does not contain a configuration profile sid. Configuration profiles were deprecated when we announced the general availability of twilio-video.js 1.x. They are not supported in twilio-video.js 2.x.

In twilio-video.js 2.x, your Participant will connect to the nearest region as determined by latency based routing. If you want your signaling traffic to originate and terminate in a specific region, you can do so using a new ConnectOptions flag region:

1
const { connect } = require('twilio-video');
2
const room = await connect(token, {
3
  region: 'de1'
4
});

In twilio-video.js 2.x, you can choose not to subscribe to any Tracks published by other Participants in a Group or Small Group Room by setting a new ConnectOptions flag automaticSubscription to false:

1
  const { connect } = require('twilio-video');
2
  const room = await connect(token, {
3
    automaticSubscription: false
4
  });

In twilio-video.js 1.x, developers primarily interacted with the LocalParticipant's and RemoteParticipants' media using Tracks. In twilio-video.js 2.x, developers will interact with TrackPublications, which basically represent Tracks that are published to the Room by its Participants. LocalTracks that are published by the LocalParticipant are represented by LocalTrackPublications, and RemoteTracks that are published by RemoteParticipants are represented by RemoteTrackPublications.

A LocalTrackPublication is created when a LocalParticipant successfully publishes a LocalTrack, whether by adding it to the ConnectOptions' tracks array, or by using the LocalParticipant's publishTrack() or publishTracks() methods.

Publish a LocalTrack while connecting to a Room

1
const { connect, createLocalVideoTrack } = require('twilio-video');
2

3
const videoTrack = await createLocalVideoTrack();
4

5
const room = await connect('$TOKEN', {
6
  name: 'my-room',
7
  tracks: [videoTrack]
8
});
9

10
function trackPublished(publication) {
11
  console.log(`Published LocalTrack: ${publication.track}`);
12
}
13

14
// Access the already published LocalTracks.
15
room.localParticipant.tracks.forEach(trackPublished);

Publish a LocalTrack after connecting to a Room

1
// Access LocalTracks that are published after connecting to the Room.
2
room.localParticipant.on('trackPublished', trackPublished);
3

4
const audioTrack = await createLocalVideoTrack();
5

6
// publishTrack() resolves with a LocalTrackPublication when the LocalTrack is
7
// successfully published.
8
const audioTrackPublication = await room.localParticipant.publishTrack(audioTrack);
9

10
trackPublished(audioTrackPublication);

In order to unpublish the LocalTrack, the developer can either use the LocalTrackPublication's unpublish() method, or the LocalParticipant's unpublishTrack() method. The LocalTrackPublication maintains a reference to the published LocalTrack through its track property.

Unpublish a LocalTrack using LocalTrackPublication#unpublish

audioTrackPublication.unpublish();

Unpublish a LocalTrack using LocalParticipant#unpublishTrack

room.localParticipant.unpublishTrack(videoTrack);

A RemoteTrackPublication is created when a RemoteParticipant successfully publishes a RemoteTrack. In twilio-video.js 1.x, the LocalParticipant always subscribed to each published RemoteTrack. In 2.x, we are moving towards the LocalParticipant being able to subscribe to only the desired RemoteTracks. In this regard, RemoteTracks that are not yet subscribed to will have their RemoteTrackPublications' isSubscribed property set to false, and their track property set to null. A subscribed RemoteTrack will have its RemoteTrackPublication's isSubscribed property set to true, and the track property will be set to the subscribed RemoteTrack. When a RemoteTrack is subscribed to, a "subscribed" event is emitted on the RemoteTrackPublication. When a RemoteTrack is unsubscribed from, an "unsubscribed" event is emitted on the RemoteTrackPublication.

1
const { connect } = require('twilio-video');
2

3
const room = await connect('$TOKEN', {
4
  name: 'my-room'
5
});
6

7
function trackPublished(publication, participant) {
8
  console.log(`RemoteParticipant ${participant.identity} published a RemoteTrack: ${publication}`);
9
  assert(!publication.isSubscribed);
10
  assert.equal(publication.track, null);
11

12
  publication.on('subscribed', track => {
13
    console.log(`LocalParticipant subscribed to a RemoteTrack: ${track}`);
14
    assert(publication.isSubscribed);
15
    assert(publication.track, track);
16
  });
17

18
  publication.on('unsubscribed', track => {
19
    console.log(`LocalParticipant unsubscribed from a RemoteTrack: ${track}`);
20
    assert(!publication.isSubscribed);
21
    assert.equal(publication.track, null);
22
  });
23
}
24

25
function participantConnected(participant) {
26
  participant.tracks.forEach(publication => {
27
    trackPublished(publication, participant);
28
  });
29

30
  participant.on('trackPublished', publication => {
31
    trackPublished(publication, participant);
32
  });
33

34
  participant.on('trackUnpublished', publication => {
35
    console.log(`RemoteParticipant ${participant.identity} unpublished a RemoteTrack: ${publication}`);
36
  });
37
}
38

39
room.participants.forEach(participantConnected);
40
room.on('participantConnected', participantConnected);

NOTE: We do not have support for Track subscriptions yet. So each LocalParticipant will subscribe to all the published RemoteTracks. The only way a LocalParticipant unsubscribes from a RemoteTrack is if the RemoteParticipant unpublishes it. So:

• When a RemoteParticipant publishes a RemoteTrack, the following events are emitted in the given order:

  • "trackPublished" event on the RemoteParticipant
  • "subscribed" event on the RemoteTrackPublication
  • "trackSubscribed" event on the RemoteParticipant

• When a RemoteParticipant unpublishes a RemoteTrack, the following events are emitted in the given order:

  • "unsubscribed" event on the RemoteTrackPublication
  • "trackUnsubscribed" event on the RemoteParticipant
  • "trackUnpublished" event on the RemoteParticipant

• dscpTagging has been deprecated and renamed to enableDscp.

• "trackPublished" event is emitted when a RemoteParticipant publishes a RemoteTrack.
• "trackUnpublished" event is emitted when a RemoteParticipant unpublishes a RemoteTrack.
• "trackSubscribed" event is emitted when the LocalParticipant subscribes to a RemoteTrack published by a RemoteParticipant.
• "trackUnsubscribed" event is emitted when the LocalParticipant unsubscribes from a RemoteTrack published by a RemoteParticipant.
• "trackAdded" event is no longer emitted.
• "trackRemoved" event is no longer emitted.

• tracks is now a collection of LocalTrackPublications instead of a collection of LocalTracks.
• audioTracks is now a collection of LocalAudioTrackPublications instead of a collection of LocalAudioTracks.
• dataTracks is now a collection of LocalDataTrackPublications instead of a collection of LocalDataTracks.
• videoTracks is now a collection of LocalVideoTrackPublications instead of a collection of LocalVideoTracks.
• addTrack() is now replaced by publishTrack().
• addTracks() is now replaced by publishTracks().
• removeTrack() is now replaced by unpublishTrack().
• removeTracks() is now replaced by unpublishTracks().
• "trackPublished" event is emitted when a LocalTrack has been successfully published to the Room.
• "trackPublicationFailed" event is emitted when the LocalParticipant failed to publish a LocalTrack to the Room.
• "trackAdded" event is no longer emitted.
• "trackRemoved" event is no longer emitted.

• tracks is now a collection of RemoteTrackPublications instead of a collection of RemoteTracks.
• audioTracks is now a collection of RemoteAudioTrackPublications instead of a collection of RemoteAudioTracks.
• dataTracks is now a collection of RemoteDataTrackPublications instead of a collection of RemoteDataTracks.
• videoTracks is now a collection of RemoteVideoTrackPublications instead of a collection of RemoteVideoTracks.
• "trackPublished" event is emitted when the RemoteParticipant publishes a RemoteTrack.
• "trackUnpublished" event is emitted when the RemoteParticipant unpublishes a RemoteTrack.
• "trackSubscribed" event is emitted when the LocalParticipant subscribes to a RemoteTrack published by a RemoteParticipant.
• "trackUnsubscribed" event is emitted when the LocalParticipant unsubscribes from a RemoteTrack published by a RemoteParticipant.
• "trackAdded" event is no longer emitted.
• "trackRemoved" event is no longer emitted.

• id is no longer available. Use sid or name instead.
• isSubscribed is no longer available. Use the corresponding RemoteTrackPublication's isSubscribed instead.
• "unsubscribed" event is now emitted on the corresponding RemoteTrackPublication instead of the RemoteTrack.