Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Migrating from 1.x to 2.x

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

What's New

TrackPublication

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

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

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

const videoTrack = await createLocalVideoTrack();

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

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

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

Publish a LocalTrack after connecting to a Room

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

const audioTrack = await createLocalVideoTrack();

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

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);

RemoteTrackPublication

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.

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

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

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

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

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

function participantConnected(participant) {
  participant.tracks.forEach(publication => {
    trackPublished(publication, participant);
  });

  participant.on('trackPublished', publication => {
    trackPublished(publication, participant);
  });

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

room.participants.forEach(participantConnected);
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

What's Changed

Room

  • "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.

LocalParticipant

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

RemoteParticipant

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

RemoteTrack

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

Object Model

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Loading Code Sample...