RoomSession

A RoomSession allows you to start and control video sessions.

For example, the following code joins a video session and listens for new members joining:

const roomSession = new SignalWire.Video.RoomSession({
  token: '<YourRoomToken>',
  rootElement: document.getElementById('myVideoElement'),
  audio: true,
  video: true,
})

roomSession.on('member.joined', (e) => {
  console.log(`${e.member.name} joined`)
})

roomSession.join()

Events

Please see RoomSessionEvents for the list of events emitted by a RoomSession object.

Constructors

• new RoomSession(opts)

Creates a new RoomSession.

Parameters

Properties

• Readonly active: boolean

Whether the connection is currently active

---

• Readonly cameraId: null | string

The id of the video device, or null if not available

---

• Readonly cameraLabel: null | string

The label of the video device, or null if not available

---

• Readonly deviceList: RoomSessionDevice[]

Contains any additional devices added via addCamera, addMicrophone, or addDevice.

---

• Readonly localAudioTrack: null | MediaStreamTrack

Provides access to the local audio MediaStreamTrack.

---

• Readonly localStream: undefined | MediaStream

Provides access to the local MediaStream

---

• Readonly localVideoTrack: null | MediaStreamTrack

Provides access to the local video MediaStreamTrack.

---

• Readonly memberId: string

The id of the current member within the room

---

• Readonly microphoneId: null | string

The id of the audio input device, or null if not available

---

• Readonly microphoneLabel: null | string

The label of the audio input device, or null if not available

---

• Optional Readonly previewUrl: string

If the Room has been created with the property enable_room_previews set to true, this field contains the URL to the room preview.

---

• Readonly remoteStream: undefined | MediaStream

Provides access to the remote MediaStream

---

• Readonly roomId: string

The unique identifier for the room

---

• Readonly roomSessionId: string

The unique identifier for the room session

---

• Readonly screenShareList: RoomSessionScreenShare[]

Contains any local screen shares added to the room via startScreenShare.

Methods

▸ addCamera(opts): Promise<RoomSessionDevice>

Adds a camera device to the room. Using this method, a user can stream multiple video sources at the same time.

Parameters

Returns

Promise<RoomSessionDevice>

Examples

Adding any of the camera devices to the room (duplicate streams are possible):

await roomSession.addCamera()

Adding a specific camera:

await roomSession.addCamera({deviceId: "gOtMHwZdoA6wMlAnhbfTmeRgPAsqa7iw1OwgKYtbTLA="})

Adding a high-resolution camera, joining it manually:

const roomDev = await roomSession.addCamera({
  autoJoin: false,
  width: {min: 1280}
})
await roomDev.join()

---

▸ addDevice(opts): Promise<RoomSessionDevice>

Adds a device to the room. Using this method, a user can stream multiple sources at the same time. If you need to add a camera device or a microphone device, you can alternatively use the more specific methods addCamera and addMicrophone.

Parameters

Returns

Promise<RoomSessionDevice>

Example

Adding any of the microphone devices to the room (duplicate streams are possible):

await roomSession.addDevice({audio: true})

---

▸ addMicrophone(opts): Promise<RoomSessionDevice>

Adds a microphone device to the room. Using this method, a user can stream multiple video sources at the same time.

Parameters

Returns

Promise<RoomSessionDevice>

Examples

Adding any of the microphone devices to the room (duplicate streams are possible):

await roomSession.addMicrophone()

Adding a specific microphone:

await roomSession.addMicrophone({deviceId: "PIn/IIDDgBUHzJkhRncv1m85hX1gC67xYIgJvvThB3Q="})

Adding a microphone with specific constraints, joining it manually:

const roomDev = await roomSession.addMicrophone({
  autoJoin: false,
  noiseSuppression: true
})
await roomDev.join()

---

▸ audioMute(params?): Promise<void>

Puts the microphone on mute. The other participants will not hear audio from the muted participant anymore. You can use this method to mute either yourself or another participant in the room.

Parameters

Returns

Promise<void>

Permissions

• room.self.audio_mute: to mute a local device
• room.member.audio_mute: to mute a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Muting your own microphone:

await room.audioMute()

Muting the microphone of another participant:

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

---

▸ audioUnmute(params?): Promise<void>

Unmutes the microphone if it had been previously muted. You can use this method to unmute either yourself or another participant in the room.

Parameters

Returns

Promise<void>

Permissions

• room.self.audio_unmute: to unmute a local device
• room.member.audio_unmute: to unmute a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Unmuting your own microphone:

await room.audioUnmute()

Unmuting the microphone of another participant:

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

---

▸ createScreenShareObject(opts): Promise<RoomSessionScreenShare>

⚠

️ Deprecated

Use startScreenShare instead.

Adds a screen sharing instance to the room. You can create multiple screen sharing instances and add all of them to the room.

Parameters

Returns

Promise<RoomSessionScreenShare>

Example

Sharing the screen together with the associated audio:

await roomSession.createScreenShareObject({audio: true, video: true})

---

▸ deaf(params?): Promise<void>

Mutes the incoming audio. The affected participant will not hear audio from the other participants anymore. You can use this method to make deaf either yourself or another participant in the room.

Note that in addition to making a participant deaf, this will also automatically mute the microphone of the target participant (even if there is no audio_mute permission). If you want, you can then manually unmute it by calling audioUnmute.

Parameters

Returns

Promise<void>

Permissions

• room.self.deaf: to make yourself deaf
• room.member.deaf: to make deaf a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Making yourself deaf:

await room.deaf()

Making another participant deaf:

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

---

▸ destroy(): void

Destroys the room object. This only destroys the JavaScript object: it has no effect on the server-side room.

Returns

void

---

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

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

Returns

Promise<{ layouts: string[] }>

Permissions

• room.list_available_layouts

You need to specify the permissions when creating the Video Room Token on the server side.

Example

await room.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[] }>

Example

await room.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 recordings for the current room session.

Returns

Promise<GetPlaybacksOutput>

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

Permissions

• room.playback

You need to specify the permissions when creating the Video Room Token on the server side.

---

▸ getRecordings(): Promise<GetRecordingsOutput>

Obtains a list of recordings for the current room session. To download the actual mp4 file, please use the REST API.

Returns

Promise<GetRecordingsOutput>

Permissions

• room.recording

You need to specify the permissions when creating the Video Room Token on the server side.

Example

await room.getRecordings()
// returns:
{
  "recordings": [
    {
      "id": "94ec917c-ff9c-4d57-9111-7d93a8f6e3e8",
      "state": "completed",
      "duration": 4.66,
      "started_at": 1630681129.936,
      "ended_at": 1630681133.7655
    }
  ]
}

From your server, you can obtain the mp4 file using the REST API:

curl --request GET \
     --url https://<yourspace>.signalwire.com/api/video/room_recordings/<recording_id> \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic <your API token>'

---

▸ hideVideoMuted(): Promise<void>

⚠

️ Deprecated

Use setHideVideoMuted instead.

Do not show muted videos in the room layout.

Returns

Promise<void>

Permissions

• room.hide_video_muted

You need to specify the permissions when creating the Video Room Token on the server side.

Example

await room.hideVideoMuted()

---

▸ join(): Promise<RoomSession>

Joins the room session.

Returns

Promise<RoomSession>

---

▸ leave(): Promise<void>

Leaves the room. This detaches all the locally originating streams from the room.

Returns

Promise<void>

---

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

Type parameters

Parameters

Returns

EmitterContract<RoomSessionObjectEvents>

---

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

Type parameters

Parameters

Returns

EmitterContract<RoomSessionObjectEvents>

---

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

Type parameters

Parameters

Returns

EmitterContract<RoomSessionObjectEvents>

---

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

Permissions

• room.playback

You need to specify the permissions when creating the Video Room Token on the server side.

Example

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

---

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

Type parameters

Parameters

Returns

EmitterContract<RoomSessionObjectEvents>

---

▸ removeMember(params): Promise<void>

Removes a specific participant from the room.

Parameters

Returns

Promise<void>

Permissions

• room.member.remove: to remove a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Example

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await room.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>

Permissions

• room.hide_video_muted
• room.show_video_muted

You need to specify the permissions when creating the Video Room Token on the server side.

Example

await roomSession.setHideVideoMuted(false)

---

▸ setInputSensitivity(params): Promise<void>

Sets the input level at which the participant is identified as currently speaking. You can use this method to set the input sensitivity for either yourself or another participant in the room.

Parameters

Returns

Promise<void>

Permissions

• room.self.set_input_sensitivity: to set the sensitivity for a local
  device
• room.member.set_input_sensitivity: to set the sensitivity for a
  remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Setting your own input sensitivity:

await room.setInputSensitivity({value: 80})

Setting the input sensitivity of another participant:

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

---

▸ setInputVolume(params): Promise<void>

Sets the input volume level (e.g. for the microphone). You can use this method to set the input volume for either yourself or another participant in the room.

Parameters

Returns

Promise<void>

Permissions

• room.self.set_input_volume: to set the volume for a local device
• room.member.set_input_volume: to set the volume for a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Setting your own microphone volume:

await room.setInputVolume({volume: -10})

Setting the microphone volume of another participant:

const id = 'de550c0c-3fac-4efd-b06f-b5b8614b8966'  // you can get this from getMembers()
await room.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>

Permissions

• room.set_layout
• room.set_position (if you need to assign positions)

You need to specify the permissions when creating the Video Room Token on the server side.

Example

Set the 6x6 layout:

await room.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>

Permissions

• room.self.set_meta: to set the metadata for the local member
• room.member.set_meta: to set the metadata for a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Setting metadata for the current member:

await roomSession.setMemberMeta({
  meta: {
    email: '[email protected]'
  }
})

Setting metadata for another 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>

Permissions

• room.self.set_position: to set the position for the local member
• room.member.set_position: to set the position for a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

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>

Permissions

• room.set_meta

You need to specify the permissions when creating the Video Room Token on the server side.

Example

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

---

▸ setOutputVolume(params): Promise<void>

Sets the output volume level (e.g., for the speaker). You can use this method to set the output volume for either yourself or another participant in the room.

Parameters

Returns

Promise<void>

Permissions

• room.self.set_output_volume: to set the speaker volume for yourself
• room.member.set_output_volume: to set the speaker volume for a remote
  member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Setting your own output volume:

await room.setOutputVolume({volume: -10})

Setting the output volume of another participant:

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

---

▸ setPositions(params): Promise<void>

Assigns a position in the layout for multiple members.

Parameters

Returns

Promise<void>

Permissions

• room.set_position

You need to specify the permissions when creating the Video Room Token on the server side.

Example

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

---

▸ showVideoMuted(): Promise<void>

⚠

️ Deprecated

Use setHideVideoMuted instead.

Show muted videos in the room layout in addition to the unmuted ones. Members that have been muted via videoMute will display a mute image instead of the video.

Returns

Promise<void>

Permissions

• room.show_video_muted

You need to specify the permissions when creating the Video Room Token on the server side.

Example

await room.showVideoMuted()

---

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

Permissions

• room.recording

You need to specify the permissions when creating the Video Room Token on the server side.

Example

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

---

▸ startScreenShare(opts): Promise<RoomSessionScreenShare>

Adds a screen sharing instance to the room. You can create multiple screen sharing instances and add all of them to the room.

Parameters

Returns

Promise<RoomSessionScreenShare>

Examples

Sharing the screen together with the associated audio:

await roomSession.startScreenShare({ audio: true, video: true })

Sharing the screen while changing layout:

await roomSession.startScreenShare({
  audio: true,
  video: true,
  layout: "screen-share",
  positions: {
    "self": "reserved-1"
  }
})

---

▸ undeaf(params?): Promise<void>

Unmutes the incoming audio. The affected participant will start hearing audio from the other participants again. You can use this method to undeaf either yourself or another participant in the room.

Note that in addition to allowing a participants to hear the others, this will also automatically unmute the microphone of the target participant (even if there is no audio_unmute permission). If you want, you can then manually mute it by calling audioMute.

Parameters

Returns

Promise<void>

Permissions

• room.self.deaf: to make yourself deaf
• room.member.deaf: to make deaf a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Undeaf yourself:

await room.undeaf()

Undeaf another participant:

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

---

▸ updateCamera(constraints): Promise<void>

Replaces the current camera stream with the one coming from a different device.

Parameters

Returns

Promise<void>

Example

Replaces the current camera stream with the one coming from the specified deviceId:

await room.updateCamera({deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg="})

---

▸ updateMicrophone(constraints): Promise<void>

Replaces the current microphone stream with the one coming from a different device.

Parameters

Returns

Promise<void>

Example

Replaces the current microphone stream with the one coming from the specified deviceId:

await room.updateMicrophone({deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg="})

---

▸ updateSpeaker(opts): Promise<undefined>

Replaces the current speaker with a different one.

📘

Some browsers do not support output device selection. You can check by calling WebRTC.supportsMediaOutput.

Parameters

Returns

Promise<undefined>

Example

Replaces the current speaker:

await room.updateSpeaker({deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg="})

---

▸ videoMute(params?): Promise<void>

Puts the video on mute. Participants will see a mute image instead of the video stream. You can use this method to mute either yourself or another participant in the room.

Parameters

Returns

Promise<void>

Permissions

• room.self.video_mute: to unmute a local device
• room.member.video_mute: to unmute a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Muting your own video:

await room.videoMute()

Muting the video of another participant:

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

---

▸ videoUnmute(params?): Promise<void>

Unmutes the video if it had been previously muted. Participants will start seeing the video stream again. You can use this method to unmute either yourself or another participant in the room.

Parameters

Returns

Promise<void>

Permissions

• room.self.video_mute: to unmute a local device
• room.member.video_mute: to unmute a remote member

You need to specify the permissions when creating the Video Room Token on the server side.

Examples

Unmuting your own video:

await room.videoUnmute()

Unmuting the video of another participant:

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