Skip to main content

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

Obtaining a token

Please refer to the Simple Video Demo guide to learn how to obtain Video Room tokens.

Constructors

constructor

new RoomSession(opts)

Creates a new RoomSession. Note that the room will not be joined until join has been called.

Parameters

NameTypeDescription
optsObject-
opts.tokenstringSignalWire video room token (get one from the REST APIs)
opts.applyLocalVideoOverlay?booleanWhether to apply the local-overlay on top of your video. Default: true.
opts.audio?boolean | MediaTrackConstraintsAudio constraints to use when joining the room. Default: true.
opts.iceServers?RTCIceServer[]List of ICE servers.
opts.logLevel?"trace" | "debug" | "info" | "warn" | "error" | "silent"Logging level.
opts.rootElement?HTMLElementHTML element in which to display the video stream.
opts.speakerId?stringId of the speaker device to use for audio output. If undefined, picks a default speaker.
opts.stopCameraWhileMuted?booleanWhether to stop the camera when the member is muted. Default: true.
opts.stopMicrophoneWhileMuted?booleanWhether to stop the microphone when the member is muted. Default: true.
opts.video?boolean | MediaTrackConstraintsVideo constraints to use when joining the room. Default: true.

Example

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

Properties

active

Readonly active: boolean

Whether the connection is currently active.


cameraId

Readonly cameraId: null | string

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


cameraLabel

Readonly cameraLabel: null | string

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


deviceList

Readonly deviceList: RoomSessionDevice[]

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


localAudioTrack

Readonly localAudioTrack: null | MediaStreamTrack

Provides access to the local audio MediaStreamTrack.


localStream

Readonly localStream: undefined | MediaStream

Provides access to the local MediaStream.


localVideoTrack

Readonly localVideoTrack: null | MediaStreamTrack

Provides access to the local video MediaStreamTrack.


memberId

Readonly memberId: string

The id of the current member within the room.


microphoneId

Readonly microphoneId: null | string

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


microphoneLabel

Readonly microphoneLabel: null | string

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


previewUrl

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.


remoteStream

Readonly remoteStream: undefined | MediaStream

Provides access to the remote MediaStream.


roomId

Readonly roomId: string

The unique identifier for the room.


roomSessionId

Readonly roomSessionId: string

The unique identifier for the room session.


screenShareList

Readonly screenShareList: RoomSessionScreenShare[]

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

Methods

addCamera

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

NameTypeDescription
optsMediaTrackConstraints & { autoJoin?: boolean }Specify the constraints for the device. In addition, you can add the autoJoin key to specify whether the device should immediately join the room or joining will be performed manually later.

Returns

Promise<RoomSessionDevice>

Permissions

  • room.self.additional_source

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

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

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

NameTypeDescription
optsObjectSpecify the constraints for the device. In addition, you can add the autoJoin key to specify whether the device should immediately join the room or joining will be performed manually later.
opts.audio?boolean | MediaTrackConstraintsAudio constraints.
opts.autoJoin?booleanWhether the device should automatically join the room. Default: true.
opts.video?boolean | MediaTrackConstraintsVideo constraints.

Returns

Promise<RoomSessionDevice>

Permissions

  • room.self.additional_source

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

Example

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

await roomSession.addDevice({ audio: true });

addMicrophone

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

NameTypeDescription
optsMediaTrackConstraints & { autoJoin?: boolean }Specify the constraints for the device. In addition, you can add the autoJoin key to specify whether the device should immediately join the room or joining will be performed manually later.

Returns

Promise<RoomSessionDevice>

Permissions

  • room.self.additional_source

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

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

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

NameTypeDescription
params?Object-
params.memberId?stringId of the member to mute. If omitted, mutes the default device in the local client.

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

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

NameTypeDescription
params?Object-
params.memberId?stringId of the member to unmute. If omitted, unmutes the default device in the local client.

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

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

NameTypeDescription
optsObject-
opts.audio?boolean | MediaTrackConstraintsAudio constraints to use when joining the room. Default: true.
opts.autoJoin?booleanWhether the screen share object should automatically join the room.
opts.video?boolean | MediaTrackConstraintsVideo constraints to use when joining the room. Default: true.

Returns

Promise<RoomSessionScreenShare>

Permissions

  • room.self.screenshare

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

Example

Sharing the screen together with the associated audio:

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

deaf

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

NameTypeDescription
params?Object-
params.memberId?stringId of the member to affect. If omitted, affects the default device in the local client.

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

deleteMemberMeta

deleteMemberMeta(params): Promise<void>

Deletes the specified keys from the metadata for the specified member.

Parameters

NameTypeDescription
paramsObject-
params.memberId?stringId of the member to affect. If omitted, affects the current member.
params.keysstring[]The keys to remove.

Returns

Promise<void>

Permissions

  • room.set_meta

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

Example

roomSession.on("member.updated", (e) => {
// We can set an event listener to log changes to the metadata.
console.log(e.member.meta);
});

await roomSession.setMemberMeta({
memberId: "...",
meta: { foo: "bar", baz: true },
});
// The logger will now print `{ foo: "bar", baz: true }`

await roomSession.deleteMemberMeta({ memberId: "...", keys: ["foo"] });
// The logger will now print `{ baz: true }`

deleteMeta

deleteMeta(keys): Promise<void>

Deletes the specified keys from the metadata for this RoomSession.

Parameters

NameTypeDescription
keysstring[]The keys to remove.

Returns

Promise<void>

Permissions

  • room.set_meta

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

Example

roomSession.on("room.updated", (e) => {
// We can set an event listener to log changes to the metadata.
console.log(e.room.meta);
});

await roomSession.setMeta({ foo: "bar", baz: true });
// The logger will now print `{ foo: "bar", baz: true }`

await roomSession.deleteMeta(["foo"]);
// The logger will now print `{ baz: true }`

destroy

destroy(): void

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

Returns

void


getLayouts

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

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,
"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,
"name": "David",
"deaf": false,
"video_muted": false,
"room_id": "aae25822-892c-4832-b0b3-34aac3a0e8d1",
"type": "member"
}
]
}

getMemberMeta

getMemberMeta(): Promise<{ meta: Object }>

Returns the metadata assigned to the specified member.

Parameters

NameTypeDescription
params?Object-
params.memberId?stringId of the member for which to obtain the metadata. If omitted, refers to the current member.

Returns

Promise<{ meta: Object }>

Example

const { meta } = await room.getMemberMeta();
console.log(meta);

getMeta

getMeta(): Promise<{ meta: Object }>

Returns the metadata assigned to this Room Session.

Returns

Promise<{ meta: Object }>

Example

const { meta } = await room.getMeta();
console.log(meta);

getPlaybacks

getPlaybacks(): Promise<{ playbacks: RoomSessionPlayback }>

Obtains a list of recordings for the current room session.

Returns

Promise<{ playbacks: RoomSessionPlayback }>

Permissions

  • room.playback

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

Example

const pl = await roomSession.getPlaybacks();
if (pl.playbacks.length > 0) {
console.log(rec.playbacks[0].id, recs.playbacks[0].state);
}

getRecordings

getRecordings(): Promise<{ recordings: RoomSessionRecording }>

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

Returns

Promise<{ recordings: RoomSessionRecording }>

Permissions

  • room.recording

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

Example

const recs = await room.getRecordings();
if (recs.recordings.length > 0) {
console.log(rec.recordings[0].id, recs.recordings[0].duration);
}

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

getStreams

getStreams(): Promise<{ streams: RoomSessionStream }>

Obtains a list of active streams for this RoomSession. These are RTMP streams of the audio/video content of this room, which will be sent to an external party (e.g., to YouTube).

Returns

Promise<{ streams: RoomSessionStream }>

Permissions

  • room.stream

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

Example

const s = await room.getStreams();
for (const stream of s.streams) {
console.log(stream.id, stream.url);
}

hideVideoMuted

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

join(): Promise<RoomSession>

Joins the room session.

Returns

Promise<RoomSession>


leave

leave(): Promise<void>

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

Returns

Promise<void>


off

off(event, fn?)

Remove an event handler.

Parameters

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fn?FunctionAn event handler which had been previously attached.

on

on(event, fn)

Attaches an event handler to the specified event.

Parameters

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fnFunctionAn event handler.

once

once(event, fn)

Attaches an event handler to the specified event. The handler will fire only once.

Parameters

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fnFunctionAn event handler.

play

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

NameTypeDescription
paramsObject-
params.urlstringThe url (http, https, rtmp, rtmps) of the stream to reproduce.
params.volume?numberThe audio volume at which to play the stream. Values range from -50 to 50, with a default of 0.
params.currentTimecode?numberThe starting timecode in milliseconds for playback. Defaults to 0.
params.positions?VideoPositionsPositions to assign as soon as the playback starts. You can use the special keyword "self" to refer to the id of the playback.
params.layout?stringLayout to change to when the playback starts.

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

removeAllListeners(event?)

Detaches all event listeners for the specified event.

Parameters

NameTypeDescription
event?stringName of the event (leave this undefined to detach listeners for all events). See Events for the list of available events.

removeAllMembers

removeAllMembers(): Promise<void>

Removes all the members from this room session. The room session will end.

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

await roomSession.removeAllMembers();

removeMember

removeMember(params): Promise<void>

Removes a specific participant from the room.

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the member to remove.

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

setHideVideoMuted(value): Promise<void>

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

Muted videos are shown by default.

Parameters

NameTypeDescription
valuebooleanWhether to hide muted videos in the room layout.

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

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

NameTypeDescription
paramsObject-
params.memberId?stringId of the member to affect. If omitted, affects the default device in the local client.
params.valuenumberDesired sensitivity from 0 (lowest sensitivity, essentially muted) to 100 (highest sensitivity). The default value is 30.

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

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

NameTypeDescription
paramsObject-
params.memberId?stringId of the member for which to set input volume. If omitted, sets the volume of the default device in the local client.
params.volumenumberDesired volume. Values range from -50 to 50, with a default of 0.

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

setLayout(params): Promise<void>

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

Parameters

NameTypeDescription
paramsObject-
params.namestringName of the layout.
params.positions?VideoPositionsPositions to assign as soon as the new layout is set.

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

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

NameTypeDescription
paramsObject-
params.memberId?stringId of the member to affect. If omitted, affects the default device in the local client.
params.metaRecord<string, unknown>The medatada object to assign to the member.

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: "joe@example.com",
},
});

Setting metadata for another member:

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

setMemberPosition

setMemberPosition(params): Promise<void>

Assigns a position in the layout to the specified member.

Parameters

NameTypeDescription
paramsObject-
params.memberId?stringId of the member to affect. If omitted, affects the current member.
params.positionVideoPositionPosition to assign in the layout.

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

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

NameTypeDescription
metaRecord<string, unknown>The medatada object to assign to the RoomSession.

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

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

NameTypeDescription
paramsObject-
params.memberId?stringId of the member to affect. If omitted, affects the default device in the local client.
params.volumenumberDesired volume. Values range from -50 to 50, with a default of 0.

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

setPositions(params): Promise<void>

Assigns a position in the layout for multiple members.

Parameters

NameTypeDescription
paramsObject-
params.positionsVideoPositionsMapping of member IDs and positions to assign.

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

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

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

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

NameTypeDescription
optsObject-
opts.audio?boolean | MediaTrackConstraintsAudio constraints to use when joining the room. Default: false.
opts.autoJoin?booleanWhether the screen share object should automatically join the room. Default: true.
opts.layout?stringLayout to switch to as soon as the screen share joins the room.
opts.positions?VideoPositionsLayout positions to assign as soon as the screen share joins the room.
opts.video?boolean | MediaTrackConstraintsVideo constraints to use when joining the room. Default: true.

Returns

Promise<RoomSessionScreenShare>

Permissions

  • room.self.screenshare

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

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

startStream

startStream(): Promise<RoomSessionStream>

Starts streaming the audio/video of this room to an external service. You can use the returned RoomSessionStream object to interact with the stream.

Parameters

NameTypeDescription
paramsObject
params.urlstringRTMP or RTMPS url. This must be the address of a server accepting incoming RTMP/RTMPS streams.

Returns

Promise<RoomSessionStream>

Permissions

  • room.stream (or the more specific room.stream.start)

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

Example

const stream = await room.startStream({ url: "rtmp://example.com" });

// Stop the stream after 60 seconds
setTimeout(() => stream.stop(), 60000);

undeaf

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

NameTypeDescription
params?Object
params.memberId?stringId of the member to affect. If omitted, affects the default device in the local client.

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

updateCamera(constraints): Promise<void>

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

Parameters

NameTypeDescription
constraintsMediaTrackConstraintsSpecify the constraints that the device should satisfy. See MediaTrackConstraints.

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=",
});

updateMemberMeta

updateMemberMeta(params): Promise<void>

Updates a member's metadata in only the specified fields. This is different from setMemberMeta, which replaces the whole metadata object.

Parameters

NameTypeDescription
paramsObject-
params.memberId?stringId of the member to affect. If omitted, affects the current member.
params.metaRecord<string, unknown>The update to the metadata.

Returns

Promise<void>

Permissions

  • room.set_meta

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

Example

roomSession.on("member.updated", (e) => {
// We can set an event listener to log changes to the metadata.
console.log(e.member.meta);
});

await roomSession.setMemberMeta({
memberId: "...",
meta: { foo: "bar", baz: true },
});
// The logger will now print `{ foo: "bar", baz: true }`

await roomSession.updateMemberMeta({
memberId: "...",
meta: { baz: false, t: 10 },
});
// The logger will now print `{ foo: "bar", baz: false, t: 10 }`

updateMeta

updateMeta(meta): Promise<void>

Updates the RoomSession metadata by only setting the specified fields. This is different from setMeta, which replaces the whole metadata object.

Parameters

NameTypeDescription
metaRecord<string, unknown>The update to the metadata.

Returns

Promise<void>

Permissions

  • room.set_meta

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

Example

roomSession.on("room.updated", (e) => {
// We can set an event listener to log changes to the metadata.
console.log(e.room.meta);
});

await roomSession.setMeta({ foo: "bar", baz: true });
// The logger will now print `{ foo: "bar", baz: true }`

await roomSession.updateMeta({ baz: false, t: 10 });
// The logger will now print `{ foo: "bar", baz: false, t: 10 }`

updateMicrophone

updateMicrophone(constraints): Promise<void>

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

Parameters

NameTypeDescription
constraintsMediaTrackConstraintsSpecify the constraints that the device should satisfy. See MediaTrackConstraints.

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

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

NameTypeDescription
optsObject
opts.deviceIdstringId of the new speaker device.

Returns

Promise<undefined>

Example

Replaces the current speaker:

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

videoMute

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

NameTypeDescription
params?Object-
params.memberId?stringId of the member to mute. If omitted, mutes the default device in the local client.

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

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

NameTypeDescription
params?Object-
params.memberId?stringId of the member to unmute. If omitted, unmutes the default device in the local client.

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

Events

List of events emitted by a RoomSession object.

layout.changed

layout.changed(e)

The layout of the room has changed. This event is not limited to changes associated to the grid layout of the room: it also includes for example changes in the position of the participants within the grid of the room.

Parameters

NameTypeDescription
eObject-
e.room_session_idstringId of the room session.
e.room_idstringId of the room.
e.layoutObjectInformation on the current layout.
e.layout.namestringName of the current layout.
e.layout.room_session_idstringId of the room session.
e.layout.room_idstringId of the room.
e.layout.layersVideoLayoutLayer[]Array containing information on all the layers in the current layout.

member.joined

member.joined

A member has joined the room. The event handler receives objects of type:

type _ = {
room_session_id: string;
room_id: string;
member: {
visible: boolean;
room_session_id: string;
input_volume: number;
id: string;
scope_id: string;
input_sensitivity: number;
output_volume: number;
audio_muted: boolean;
name: string;
deaf: boolean;
video_muted: boolean;
room_id: string;
type: string;
};
};

member.left

member.left

A member has left the room. The event handler receives objects of type:

type _ = {
room_session_id: string;
room_id: string;
member: {
room_session_id: string;
id: string;
room_id: string;
type: string;
};
};

member.talking

member.talking

A member is talking or has stopped talking. The event handler receives objects of type:

type _ = {
room_session_id: string;
room_id: string;
member: {
id: string;
room_session_id: string;
room_id: string;
talking: boolean;
};
};

member.updated

member.updated

A property of a member of the room has been updated. The event handler receives objects of type:

type _ = {
room_session_id: string;
room_id: string;
member: {
updated: Array<string>;
room_session_id: string;
id: string;
room_id: string;
type: string;
};
};

In particular, in the field member.updated you find an array of all the properties that have been updated. The new values for those properties are available as additional fields of member.

For example, say visible and video_muted have been updated. The received object will be:

{
"room_session_id": "35e85417-09cf-4b07-8f21-d3c16809e5a8",
"room_id": "aae25822-892c-4832-b0b3-34aac3a0e8d1",
"member": {
"updated": ["visible", "video_muted"],
"room_session_id": "35e85417-09cf-4b07-8f21-d3c16809e5a8",
"visible": false,
"video_muted": true,
"id": "4a829c9f-812c-49d7-b272-e3077213c55e",
"room_id": "aae25822-892c-4832-b0b3-34aac3a0e8d1",
"type": "member"
}
}

memberList.updated

memberList.updated

The set of members or one or more properties of a member have changed. The event handler receives an object e with the updated, full list of members in the room as e.members.


playback.ended

playback.ended

A playback has ended. You only receive this event if your token has the room.playback permission. The event handler receives a RoomSessionPlayback object.


playback.started

playback.started

A playback has been started. You only receive this event if your token has the room.playback permission. The event handler receives a RoomSessionPlayback object.


playback.updated

playback.updated

A playback has been updated. You only receive this event if your token has the room.playback permission. The event handler receives a RoomSessionPlayback object.


recording.ended

recording.ended

An active recording has been stopped. You only receive this event if your token has the room.recording permission. The event handler receives a RoomSessionRecording object.


recording.started

recording.started

A recording has been started in the room. You only receive this event if your token has the room.recording permission. The event handler receives a RoomSessionRecording object.


recording.updated

recording.updated

An active recording has been updated. You only receive this event if your token has the room.recording permission. The event handler receives a RoomSessionRecording object.


room.joined

room.joined

The current client joined the room session. The event handler receives objects that contain information about the room and all its members (including the current client). The objects received by the event handler have the following type:

type _ = {
room_session: {
room_session_id: string;
logos_visible: boolean;
members: Array<{
visible: boolean;
room_session_id: string;
input_volume: number;
id: string;
input_sensitivity: number;
output_volume: number;
audio_muted: boolean;
name: string;
deaf: boolean;
video_muted: boolean;
room_id: string;
type: string;
}>;
blind_mode: boolean;
recording: boolean;
silent_mode: boolean;
name: string;
hide_video_muted: boolean;
locked: boolean;
meeting_mode: boolean;
room_id: string;
event_channel: string;
layout_name: string;
};
call_id: string;
member_id: string;
};

room.left

room.left()

The current client left the room session.


room.updated

room.updated

The properties of the room have been updated. The event handler receives objects of type:

type _ = {
room_session_id: string;
room_id: string;
room: {
updated: Array<string>;
room_session_id: string;
room_id: string;
};
};

In particular, in the field room.updated you find an array of all the properties that have been updated. The new values for those properties are available as additional fields of room.

For example, say hide_video_muted has been updated. The received object will be:

{
"room_session_id": "fc695445-7f93-4597-b705-c0db6c21096a",
"room_id": "aae25822-892c-4832-b0b3-34aac3a0e8d1",
"room": {
"updated": [ "hide_video_muted" ],
"room_session_id": "fc695445-7f93-4597-b705-c0db6c21096a",
"room_id": "aae25822-892c-4832-b0b3-34aac3a0e8d1",
"hide_video_muted": true
}
}

stream.ended

stream.ended(stream)

A stream ended (e.g., it was stopped).

Parameters

NameType
streamRoomSessionStream

stream.started

stream.started(stream)

A new stream started.

Parameters

NameType
streamRoomSessionStream

Type Aliases

VideoLayoutLayer

Ƭ VideoLayoutLayer: Object

An object that represents a layer in a video layout. It contains the following keys.

NameTypeDescription
memberId?stringId of the member in this layer, if any.
ynumberY position of this layer.
xnumberX position of this layer.
heightnumberHeight of this layer.
widthnumberWidth of this layer.
layerIndexnumberIndex of this layer.
zIndexnumberZ order of this layer.
reservationstringReservation name for this layer.
positionVideoPositionVideo position associated to this layer.
playingFilebooleanWhether there is a file playing in this layer.
visiblebooleanWhether this layer is visible.

VideoPosition

Ƭ VideoPosition: "auto" | `reserved-${number}` | `standard-${number}` | "off-canvas"

Each video layout has a number of positions which members can be assigned to. This type enumerates all the available position names. Note that not all these position names may be available within a given layout.

  • auto: the position of the member in the layout is determined automatically.
  • reserved-n: the n-th reserved position in the layout (e.g. reserved-3).
  • standard-n: the n-th standard position in the layout (e.g. standard-3).
  • off-canvas: the member is hidden outside the layout.

VideoPositions

Ƭ VideoPositions: Record<string, VideoPosition>

An object whose keys represent member IDs, and values are chosen from VideoPosition. Instead of a member ID, in some contexts you can use the special keyword self if you don't know yet the ID of the member which is going to be created.

For example:

{
"1bf4d4fb-a3e4-4d46-80a8-3ebfdceb2a60": "reserved-1",
"e0c5be44-d6c7-438f-8cda-f859a1a0b1e7": "auto"
}

Or:

{
"self": "reserved-1"
}