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

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.

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.

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

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. Typically this happens when there is a disruption in 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 TwilioError

A TwilioError explaining why your application is reconnecting

Example
myRoom.on('reconnecting', error => {
  console.warn('Reconnecting!', error);
});

recordingStarted

The Room is now being recorded


recordingStopped

The Room is no longer being recorded


trackAdded

A RemoteTrack was added by a RemoteParticipant in the Room.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that was added

participant RemoteParticipant

The RemoteParticipant who added the RemoteTrack

Deprecated:
  • Use RemoteParticipant#trackSubscribed instead
Example
room.on('trackAdded', function(track, participant) {
  var participantView = document.getElementById('participant-view-' + participant.identity);
  participantView.appendChild(track.attach());
});

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
track RemoteTrack

The RemoteTrack that was disabled

participant RemoteParticipant

The RemoteParticipant who disabled the RemoteTrack


trackEnabled

A RemoteTrack was enabled by a RemoteParticipant in the Room.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that was enabled

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 RemoteVideoTrack

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

trackRemoved

A RemoteTrack was removed by a RemoteParticipant in the Room.

Parameters:
Name Type Description
track RemoteTrack

The RemoteTrack that was removed

participant RemoteParticipant

The RemoteParticipant who removed the RemoteTrack

Deprecated:
  • Use RemoteParticipant#trackUnsubscribed instead
Example
room.on('trackRemoved', function(track, participant) {
  track.detach().forEach(function(mediaElement) {
    mediaElement.remove();
  });
});

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

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack was subscribed

Example
room.on('trackSubscribed', function(track, 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


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

participant RemoteParticipant

The RemoteParticipant whose RemoteTrack was unsubscribed

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