RoomSession

Represents a room session. You can obtain instances of this class by subscribing to the appropriate events from Video.

Events

You can use this object to subscribe to the following events.

Room events:

• room.started,
• room.updated,
• room.ended:

Emitted when the room session is, respectively, started, updated, or ended. Your event handler receives an object which is an instance of RoomSession.

• recording.started,
• recording.updated,
• recording.ended:

Emitted when a recording is, respectively, started, updated, or ended. Your event handler receives an object which is an instance of RoomSessionRecording.

• playback.started,
• playback.updated,
• playback.ended:

Emitted when a playback is, respectively, started, updated, or ended. Your event handler receives an object which is an instance of RoomSessionPlayback.

• layout.changed:

Emitted when the layout of the room changes.

Member events:

• member.joined:

Emitted when a member joins the room. Your event handler receives an object of type RoomSessionMember.

• member.left:

Emitted when a member leaves the room. Your event handler receives an object of type RoomSessionMember.

• member.talking:

Emitted when a member starts or stops talking. Your event handler receives an object of type RoomSessionMember.

• member.talking.started:

Emitted when a member starts talking. Your event handler receives an object of type RoomSessionMember.

• member.talking.ended:

Emitted when a member stops talking. Your event handler receives an object of type RoomSessionMember.

• member.updated:

Emitted when any property of one of the members is updated. Your event handler receives an object member of type RoomSessionMember. Use
member.updated to access the list of updated properties. Example:

room.on('member.updated', (member) => {
    console.log(member.updated)
    // [ 'audioMuted' ]
}

• member.updated.audioMuted,
• member.updated.videoMuted,
• member.updated.deaf,
• member.updated.onHold,
• member.updated.visible,
• member.updated.inputVolume,
• member.updated.outputVolume,
• member.updated.inputSensitivity:

Each of the above events is emitted when the associated property changes. Your event handler receives an object member of type RoomSessionMember.

Properties

• displayName: string

Display name for this room. Defaults to the value of name

---

• hideVideoMuted: boolean

Whether muted videos are shown in the room layout. See setHideVideoMuted

---

• id: string

Unique id for this room session

---

• meta: Record<string, unknown>

Metadata associated to this room session.

---

• name: string

Name of this room

---

• Optional previewUrl: string

URL to the room preview.

---

• recording: boolean

Whether recording is active

---

• Optional recordings: any[]

List of active recordings in the room

---

• roomId: string

Id of the room associated to this room session

Methods

▸ audioMute(params): Promise<void>

Puts the microphone of a given member on mute. The other participants will not hear audio from the muted participant anymore.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.audioMute({memberId: id})

---

▸ audioUnmute(params): Promise<void>

Unmutes the microphone of a given member if it had been previously muted.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.audioUnmute({memberId: id})

---

▸ deaf(params): Promise<void>

Mutes the incoming audio for a given member. The affected participant will not hear audio from the other participants anymore.

Note that in addition to making a participant deaf, this will also automatically mute the microphone of the target participant. If you want, you can then manually unmute it by calling audioUnmute.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.deaf({memberId: id})

---

▸ getLayouts(): Promise<{ layouts: string[] }>

Returns a list of available layouts for the room. To set a room layout, use setLayout.

Returns

Promise<{ layouts: string[] }>

Example

await roomSession.getLayouts()
// returns:
{
  "layouts": [
    "8x8", "2x1", "1x1", "5up", "5x5",
    "4x4", "10x10", "2x2", "6x6", "3x3",
    "grid-responsive", "highlight-1-responsive"
  ]
}

---

▸ getMembers(): Promise<{ members: VideoMemberEntity[] }>

Returns a list of members currently in the room.

Returns

Promise<{ members: VideoMemberEntity[] }>

an object with type: Promise<{members: {@link VideoMember}[]}>

Example

await roomSession.getMembers()
// returns:
{
"members": [
    {
         "visible": true,
         "room_session_id": "fde15619-13c1-4cb5-899d-96afaca2c52a",
         "input_volume": 0,
         "id": "1bf4d4fb-a3e4-4d46-80a8-3ebfdceb2a60",
         "input_sensitivity": 50,
         "output_volume": 0,
         "audio_muted": false,
         "on_hold": false,
         "name": "Mark",
         "deaf": false,
         "video_muted": false,
         "room_id": "aae25822-892c-4832-b0b3-34aac3a0e8d1",
         "type": "member"
    },
    {
         "visible": true,
         "room_session_id": "fde15619-13c1-4cb5-899d-96afaca2c52a",
         "input_volume": 0,
         "id": "e0c5be44-d6c7-438f-8cda-f859a1a0b1e7",
         "input_sensitivity": 50,
         "output_volume": 0,
         "audio_muted": false,
         "on_hold": false,
         "name": "David",
         "deaf": false,
         "video_muted": false,
         "room_id": "aae25822-892c-4832-b0b3-34aac3a0e8d1",
         "type": "member"
    }
]
}

---

▸ getPlaybacks(): Promise<GetPlaybacksOutput>

Obtains a list of playbacks for the current room session.

Returns

Promise<GetPlaybacksOutput>

The returned objects contain all the properties of a RoomSessionPlayback, but no methods.

Example

const pl = await roomSession.startRecording()
pl.playbacks[0].id
pl.playbacks[0].state

---

▸ getRecordings(): Promise<GetRecordingsOutput>

Obtains a list of recordings for the current room session.

Returns

Promise<GetRecordingsOutput>

The returned objects contain all the properties of a RoomSessionRecording, but no methods.

Example

const rec = await roomSession.getRecordings()
rec.recordings[0].id
rec.recordings[0].state

---

▸ off<T>(event, fn?): EmitterContract<RealTimeRoomApiEvents>

Type parameters

Parameters

Returns

EmitterContract<RealTimeRoomApiEvents>

---

▸ on<T>(event, fn): EmitterContract<RealTimeRoomApiEvents>

Type parameters

Parameters

Returns

EmitterContract<RealTimeRoomApiEvents>

---

▸ once<T>(event, fn): EmitterContract<RealTimeRoomApiEvents>

Type parameters

Parameters

Returns

EmitterContract<RealTimeRoomApiEvents>

---

▸ play(params): Promise<RoomSessionPlayback>

Starts a playback in the room. You can use the returned RoomSessionPlayback object to control the playback (e.g., pause, resume, setVolume and stop).

Parameters

Returns

Promise<RoomSessionPlayback>

Example

const playback = await roomSession.play({ url: 'rtmp://example.com/foo' })
await playback.stop()

---

▸ removeAllListeners<T>(event?): EmitterContract<RealTimeRoomApiEvents>

Type parameters

Parameters

Returns

EmitterContract<RealTimeRoomApiEvents>

---

▸ removeMember(params): Promise<void>

Removes a specific participant from the room.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.removeMember({memberId: id})

---

▸ setHideVideoMuted(value): Promise<void>

Show or hide muted videos in the room layout. Members that have been muted via videoMute will display a mute image instead of the video, if this setting is enabled.

Parameters

Returns

Promise<void>

Example

await roomSession.setHideVideoMuted(false)

---

▸ setInputSensitivity(params): Promise<void>

Sets the input level at which the participant is identified as currently speaking.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.setInputSensitivity({memberId: id, value: 80})

---

▸ setInputVolume(params): Promise<void>

Sets the input volume for a given member (e.g., the microphone input level).

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.setInputVolume({memberId: id, volume: -10})

---

▸ setLayout(params): Promise<void>

Sets a layout for the room. You can obtain a list of available layouts with getLayouts.

Parameters

Returns

Promise<void>

Example

Set the 6x6 layout:

await roomSession.setLayout({name: "6x6"})

---

▸ setMemberMeta(params): Promise<void>

Assigns custom metadata to the specified RoomSession member. You can use this to store metadata whose meaning is entirely defined by your application.

Note that calling this method overwrites any metadata that had been previously set on the specified member.

Parameters

Returns

Promise<void>

Example

Setting metadata for a member:

await roomSession.setMemberMeta({
  memberId: 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
  meta: {
    email: '[email protected]'
  }
})

---

▸ setMemberPosition(params): Promise<void>

Assigns a position in the layout to the specified member.

Parameters

Returns

Promise<void>

Example

await roomSession.setMemberPosition({
  memberId: "1bf4d4fb-a3e4-4d46-80a8-3ebfdceb2a60",
  position: "off-canvas"
})

---

▸ setMeta(meta): Promise<void>

Assigns custom metadata to the RoomSession. You can use this to store metadata whose meaning is entirely defined by your application.

Note that calling this method overwrites any metadata that had been previously set on this RoomSession.

Parameters

Returns

Promise<void>

Example

await roomSession.setMeta({ foo: 'bar' })

---

▸ setMicrophoneVolume(params): Promise<void>

⚠

️ Deprecated

Use setInputVolume instead.
setMicrophoneVolume will be removed in v4.0.0

Parameters

Returns

Promise<void>

---

▸ setOutputVolume(params): Promise<void>

Sets the output volume for the member (e.g., the speaker output level).

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.setOutputVolume({memberId: id, volume: -10})

---

▸ setPositions(params): Promise<void>

Assigns a position in the layout for multiple members.

Parameters

Returns

Promise<void>

Example

await roomSession.setPositions({
  positions: {
    "1bf4d4fb-a3e4-4d46-80a8-3ebfdceb2a60": "reserved-1",
    "e0c5be44-d6c7-438f-8cda-f859a1a0b1e7": "auto"
  }
})

---

▸ setSpeakerVolume(params): Promise<void>

⚠

️ Deprecated

Use setOutputVolume instead.
setSpeakerVolume will be removed in v4.0.0

Parameters

Returns

Promise<void>

---

▸ startRecording(): Promise<RoomSessionRecording>

Starts the recording of the room. You can use the returned RoomSessionRecording object to control the recording (e.g., pause, resume, stop).

Returns

Promise<RoomSessionRecording>

Example

const rec = await roomSession.startRecording()
await rec.stop()

---

▸ subscribe(): Promise<RoomSessionFullState>

Listens for the events for which you have provided event handlers and returns the RoomSessionFullState that contains the full state of the room session.

Note that you don't need to manually call this method to start listening to events, since they are listened automatically.

Returns

Promise<RoomSessionFullState>

Example

const client = ...  // get a client with createClient()

client.video.on('room.started', async (roomSession) => {
  // attach event listeners...
  // roomSession.on(...)

  // This gives you the full state of the room session!
  const roomSessionState = await roomSession.subscribe()
  console.log('room name:', roomSessionState.name)
  console.log('members:', roomSessionState.members)
}

---

▸ undeaf(params): Promise<void>

Unmutes the incoming audio for a given member. The affected participant will start hearing audio from the other participants again.

Note that in addition to allowing a participants to hear the others, this will also automatically unmute the microphone of the target participant. If you want, you can then manually mute it by calling audioMute.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.undeaf({memberId: id})

---

▸ videoMute(params): Promise<void>

Puts the video of a given member on mute. Participants will see a mute image instead of the video stream.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.videoMute({memberId: id})

---

▸ videoUnmute(params): Promise<void>

Unmutes the video of a given member if it had been previously muted. Participants will start seeing the video stream again.

Parameters

Returns

Promise<void>

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await roomSession.videoUnmute({memberId: id})