Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Migrating from 1.x to 2.x


(warning)

Warning

This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024(link takes you to an external page).
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.

This guide provides an introduction to the 2.x Programmable Video JavaScript SDK (twilio-video.js) and a set of guidelines to migrate an application from 1.x to 2.x.


Resources

resources page anchor

Track Priority and Network Bandwidth Profiles (Group Rooms only)

track-priority-and-network-bandwidth-profiles-group-rooms-only page anchor

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.

Reconnection States and Events

reconnection-states-and-events page anchor

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(link takes you to an external page) 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:


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

Connect without Subscribing to Tracks

connect-without-subscribing-to-tracks page anchor

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:


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


TrackPublication

trackpublication page anchor

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.

LocalTrackPublication
localtrackpublication page anchor

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


_15
const { connect, createLocalVideoTrack } = require('twilio-video');
_15
_15
const videoTrack = await createLocalVideoTrack();
_15
_15
const room = await connect('$TOKEN', {
_15
name: 'my-room',
_15
tracks: [videoTrack]
_15
});
_15
_15
function trackPublished(publication) {
_15
console.log(`Published LocalTrack: ${publication.track}`);
_15
}
_15
_15
// Access the already published LocalTracks.
_15
room.localParticipant.tracks.forEach(trackPublished);

Publish a LocalTrack after connecting to a Room


_10
// Access LocalTracks that are published after connecting to the Room.
_10
room.localParticipant.on('trackPublished', trackPublished);
_10
_10
const audioTrack = await createLocalVideoTrack();
_10
_10
// publishTrack() resolves with a LocalTrackPublication when the LocalTrack is
_10
// successfully published.
_10
const audioTrackPublication = await room.localParticipant.publishTrack(audioTrack);
_10
_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


_10
audioTrackPublication.unpublish();

Unpublish a LocalTrack using LocalParticipant#unpublishTrack


_10
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.


_40
const { connect } = require('twilio-video');
_40
_40
const room = await connect('$TOKEN', {
_40
name: 'my-room'
_40
});
_40
_40
function trackPublished(publication, participant) {
_40
console.log(`RemoteParticipant ${participant.identity} published a RemoteTrack: ${publication}`);
_40
assert(!publication.isSubscribed);
_40
assert.equal(publication.track, null);
_40
_40
publication.on('subscribed', track => {
_40
console.log(`LocalParticipant subscribed to a RemoteTrack: ${track}`);
_40
assert(publication.isSubscribed);
_40
assert(publication.track, track);
_40
});
_40
_40
publication.on('unsubscribed', track => {
_40
console.log(`LocalParticipant unsubscribed from a RemoteTrack: ${track}`);
_40
assert(!publication.isSubscribed);
_40
assert.equal(publication.track, null);
_40
});
_40
}
_40
_40
function participantConnected(participant) {
_40
participant.tracks.forEach(publication => {
_40
trackPublished(publication, participant);
_40
});
_40
_40
participant.on('trackPublished', publication => {
_40
trackPublished(publication, participant);
_40
});
_40
_40
participant.on('trackUnpublished', publication => {
_40
console.log(`RemoteParticipant ${participant.identity} unpublished a RemoteTrack: ${publication}`);
_40
});
_40
}
_40
_40
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.

Rate this page: