Class: Room

Room

A Room represents communication between you and one or more RemoteParticipants sharing AudioTracks and VideoTracks.

You can connect to a Room by calling module:twilio-video.connect.

Extends

  • EventEmitter

Methods


disconnect()

Disconnect from the Room.

Returns:
Type
this

getStats()

Get the Room's media statistics. This is not supported in Safari 12.0 or below due to this bug : https://bugs.webkit.org/show_bug.cgi?id=192601

Returns:
Type
Promise.<Array.<StatsReport>>

refreshInactiveMedia()

Restart the muted local media Tracks and play inadvertently paused HTMLMediaElements that are attached to local and remote media Tracks. This method is useful mainly on mobile browsers (Safari and Chrome on iOS), where there is a possibility that the muted local media Tracks are never unmuted and inadvertently paused HTMLMediaElements are never played again, especially after handling an incoming phone call.

Returns:
Type
this

Type Definitions


SID

A Room.SID is a 34-character string starting with "RM" that uniquely identifies a Room.

Type:
  • string

Events


disconnected

Your LocalParticipant was disconnected from the Room and all other RemoteParticipants.

Parameters:
Name Type Argument Description
room Room

The Room your LocalParticipant was disconnected from

error TwilioError <nullable>

Present when the LocalParticipant got disconnected from the Room unexpectedly

Example
myRoom.on('disconnected', function(room, error) {
  if (error) {
    console.log('Unexpectedly disconnected:', error);
  }
  myRoom.localParticipant.tracks.forEach(function(track) {
    track.stop();
    track.detach();
  });
});

dominantSpeakerChanged

The Dominant Speaker in the Room changed. Either the Dominant Speaker is a new RemoteParticipant or the Dominant Speaker has been reset and is now null.

Parameters:
Name Type Argument Description
dominantSpeaker RemoteParticipant <nullable>

The Dominant Speaker in the Room, if any


participantConnected

A RemoteParticipant joined the Room. In Large Group Rooms (Maximum Participants greater than 50), this event is raised only when a RemoteParticipant publishes at least one LocalTrack.

Parameters:
Name Type Description
participant RemoteParticipant

The RemoteParticipant who joined

Example
myRoom.on('participantConnected', function(participant) {
  console.log(participant.identity + ' joined the Room');
});

participantDisconnected

A RemoteParticipant left the Room. In Large Group Rooms (Maximum Participants greater than 50), this event is raised only when a RemoteParticipant unpublishes all its LocalTracks.

Parameters:
Name Type Description
participant RemoteParticipant

The RemoteParticipant who left

Example
myRoom.on('participantDisconnected', function(participant) {
  console.log(participant.identity + ' left the Room');
  participant.tracks.forEach(function(track) {
    track.detach().forEach(function(mediaElement) {
      mediaElement.remove();
    });
  });
});

participantReconnected

A RemoteParticipant has reconnected to the Room after a signaling connection disruption.

Parameters:
Name Type Description
participant RemoteParticipant

The RemoteParticipant that has reconnected.

Example
myRoom.on('participantReconnected', participant => {
  console.log(participant.identity + ' reconnected to the Room');
});

participantReconnecting

A RemoteParticipant is reconnecting to the Room after a signaling connection disruption.

Parameters:
Name Type Description
participant RemoteParticipant

The RemoteParticipant that is reconnecting.

Example
myRoom.on('participantReconnecting', participant => {
  console.log(participant.identity + ' is reconnecting to the Room');
});

reconnected

Your application successfully reconnected to the Room. When this event is emitted, the Room is in state "connected".

Example
myRoom.on('reconnected', () => {
  console.log('Reconnected!');
});

reconnecting

Your application is reconnecting to the Room. This happens when there is a disruption in your signaling connection and/or your media connection. When this event is emitted, the Room is in state "reconnecting". If reconnecting succeeds, the Room will emit a "reconnected" event.

Parameters:
Name Type Description
error MediaConnectionError | SignalingConnectionDisconnectedError

A MediaConnectionError if your application is reconnecting due to a disruption in your media connection, or a SignalingConnectionDisconnectedError if your application is reconnecting due to a disruption in your signaling connection

Example
myRoom.on('reconnecting', error => {
  if (error.code === 53001) {
    console.log('Reconnecting your signaling connection!', error.message);
  } else if (error.code === 53405) {
    console.log('Reconnecting your media connection!', error.message);
  }
});

recordingStarted

The Room is now being recorded


recordingStopped

The Room is no longer being recorded


trackDimensionsChanged

One of the RemoteParticipant's VideoTrack's dimensions changed.

Parameters:
Name Type Description
track RemoteVideoTrack

The RemoteVideoTrack whose dimensions changed

participant RemoteParticipant

The RemoteParticipant whose RemoteVideoTrack's dimensions changed


trackDisabled

A RemoteTrack was disabled by a RemoteParticipant in the Room.

Parameters:
Name Type Description
publication RemoteTrackPublication

The RemoteTrackPublication that represents disabled RemoteTrack

participant RemoteParticipant

The RemoteParticipant who disabled the RemoteTrack


trackEnabled

A RemoteTrack was enabled by a RemoteParticipant in the Room.

Parameters:
Name Type Description
publication RemoteTrackPublication

The RemoteTrackPublication that represents enabled RemoteTrack

participant RemoteParticipant

The RemoteParticipant who enabled the RemoteTrack


trackMessage

A message was received over one of the RemoteParticipant's RemoteDataTrack's.

Parameters:
Name Type Description
data string | ArrayBuffer
track RemoteDataTrack

The RemoteDataTrack over which the message was received

participant RemoteParticipant

The RemoteParticipant whose RemoteDataTrack received the message


trackPublished

A RemoteTrack was published by a RemoteParticipant after connecting to the Room. This event is not emitted for RemoteTracks that were published while the RemoteParticipant was connecting to the Room.

Parameters:
Name Type Description
publication RemoteTrackPublication

The RemoteTrackPublication which represents the published RemoteTrack

participant RemoteParticipant

The RemoteParticipant who published the RemoteTrack

Example
function trackPublished(publication, participant) {
  console.log(`RemoteParticipant ${participant.sid} published Track ${publication.trackSid}`);
}

// Handle RemoteTracks published after connecting to the Room.
room.on('trackPublished', trackPublished);

room.on('participantConnected', participant => {
  // Handle RemoteTracks published while connecting to the Room.
  participant.trackPublications.forEach(publication => trackPublished(publication, participant));
});

trackPublishPriorityChanged

The RemoteTrack's publish Track.Priority was changed by the RemoteParticipant.

Parameters:
Name Type Description
priority Track.Priority

the RemoteTrack's new publish Track.Priority;

publication RemoteTrackPublication

The RemoteTrackPublication for the RemoteTrack that changed priority

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack changed priority


trackStarted

One of a RemoteParticipant's RemoteTracks in the Room started.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that started

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack started


trackSubscribed

A RemoteParticipant's RemoteTrack was subscribed to.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that was subscribed

publication RemoteTrackPublication

The RemoteTrackPublication for the RemoteTrack that was subscribed to

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack was subscribed

Example
room.on('trackSubscribed', function(track, publication, participant) {
  var participantView = document.getElementById('participant-view-' + participant.identity);
  participantView.appendChild(track.attach());
});

trackSubscriptionFailed

A RemoteParticipant's RemoteTrack could not be subscribed to.

Parameters:
Name Type Description
error TwilioError

The reason the RemoteTrack could not be subscribed to

publication RemoteTrackPublication

The RemoteTrackPublication for the RemoteTrack that could not be subscribed to

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack could not be subscribed to


trackSwitchedOff

A RemoteParticipant's RemoteTrack was switched off.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that was switched off

publication RemoteTrackPublication

The RemoteTrackPublication for the RemoteTrack that was subscribed to

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack was switched off


trackSwitchedOn

A RemoteParticipant's RemoteTrack was switched on.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that was switched on

publication RemoteTrackPublication

The RemoteTrackPublication for the RemoteTrack that was subscribed to

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack was switched on


trackUnpublished

A RemoteTrack was unpublished by a RemoteParticipant to the Room.

Parameters:
Name Type Description
publication RemoteTrackPublication

The RemoteTrackPublication which represents the unpublished RemoteTrack

participant RemoteParticipant

The RemoteParticipant who unpublished the RemoteTrack


trackUnsubscribed

A RemoteParticipant's RemoteTrack was unsubscribed from.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that was unsubscribed

publication RemoteTrackPublication

The RemoteTrackPublication for the RemoteTrack that was unsubscribed from

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack was unsubscribed

Example
room.on('trackUnsubscribed', function(track, publication, participant) {
  track.detach().forEach(function(mediaElement) {
    mediaElement.remove();
  });
});

trackWarning

One of the LocalParticipant's LocalTrackPublications in the Room encountered a warning. This event is only raised if you enabled warnings using notifyWarnings in ConnectOptions.

Parameters:
Name Type Description
name string

The warning that was raised.

publication LocalTrackPublication

The LocalTrackPublication that encountered the warning.

participant LocalParticipant

The LocalParticipant

Example
room.on('trackWarning', (name, publication, participant) => {
  if (name === 'recording-media-lost') {
    log(`LocalTrack ${publication.track.name} is not recording media.`,
      name, publication, participant);

    // Wait a reasonable amount of time to clear the warning.
    const timer = setTimeout(() => {
      // If the warning is not cleared, you can manually
      // reconnect to the room, or show a dialog to the user
    }, 5000);

    room.once('trackWarningsCleared', (publication, participant) => {
      log('LocalTrack warnings have cleared!',
        publication, participant);
      clearTimeout(timer);
    });
  }
});

trackWarningsCleared

One of the LocalParticipant's LocalTrackPublications in the Room cleared all warnings. This event is only raised if you enabled warnings using notifyWarnings in ConnectOptions.

Parameters:
Name Type Description
publication LocalTrackPublication

The LocalTrackPublication that cleared all warnings.

participant LocalParticipant

The LocalParticipant