Skip to main content

RoomSession

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

Example

const video = new Video.Client({
project: "<project-id>",
token: "<project-token>",
});

video.on("room.started", async (roomSession) => {
console.log("This is my RoomSession object:", roomSession);
});

Properties

displayName

displayName: string

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


hideVideoMuted

hideVideoMuted: boolean

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


id

id: string

Unique id for this room session


layoutName

layoutName: string

Current layout name used in the room.


meta

meta: [Record][record-type]<string, unknown>

Metadata associated to this room session.


name

name: string

Name of this room


previewUrl

Optional previewUrl: string

URL to the room preview.


layoutName

Optional layoutName: string

Current layout name used in the room.


recording

recording: boolean

Whether recording is active


recordings

Optional recordings: any[]

Deprecated

Please use getRecordings instead.

List of active recordings in the room


roomId

roomId: string

Id of the room associated to this room session

Methods

audioMute

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

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

Returns

Promise<void>

Example

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

audioUnmute

audioUnmute(params): Promise<void>

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

Parameters

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

Returns

Promise<void>

Example

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

deaf

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

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

Returns

Promise<void>

Example

const id = "de550c0c-3fac-4efd-b06f-b5b8614b8966"; // you can get this from getMembers()
await roomSession.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 default device in the local client.
params.keysstring[]The keys to remove.

Returns

Promise<void>

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>

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

demote

demote(params): Promise<void>

Demotes a participant from "member" to "audience". See promote.

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the member to affect.
params.mediaAllowed?"all" | "audio-only" | "video-only"Specifies the media that the client will be allowed to receive. An audience participant cannot send any media.

Returns

Promise<void>

Example

await roomSession.demote({
memberId: "de550c0c-3fac-4efd-b06f-b5b8614b8966",
mediaAllowed: "all",
});

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[] }>

Example

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

an object with type: Promise<{ members: VideoMemberEntity[] }>

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,
"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
paramsObject-
params.memberIdstringId of the member for which to obtain the metadata.

Returns

Promise<{ meta: Object }>

Example

const { meta } = await roomSession.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 roomSession.getMeta();
console.log(meta);

getPlaybacks

getPlaybacks(): Promise<{ playbacks: RoomSessionPlayback }> - See RoomSessionPlayback for more details.

Obtains a list of playbacks for the current room session.

Returns

Promise<{ playbacks: RoomSessionPlayback }> - See RoomSessionPlayback for more details.

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 }> - See RoomSessionRecording for more details.

Obtains a list of recordings for the current room session.

Returns

Promise<{ recordings: RoomSessionRecording }> - See RoomSessionRecording for more details.

Example

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

getStreams

getStreams(): Promise<{ streams: RoomSessionStream }> - See RoomSessionStream for more details.

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 }> - See RoomSessionStream for more details.

Example

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

lock

lock(params): Promise<void>

Locks the room. This prevents new participants from joining the room.

Returns

Promise<void>

Example

await roomSession.lock();

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> - See RoomSessionPlayback for more details.

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.seekPosition?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> - See RoomSessionPlayback for more details.

Example

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

promote

promote(params): Promise<void>

Promotes a participant from "audience" to "member". See demote.

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the audience participant to promote.
params.joinAudioMuted?booleanForce the member's audio to be muted right after the promotion.
params.joinVideoMuted?booleanForce the member's video to be muted right after the promotion.
params.mediaAllowed?"all" | "audio-only" | "video-only"Specifies the media that the client will be allowed to send. A member participant can always receive all media.
params.meta?[Record][record-type]<string, unknown>Metadata to assign to the member.
params.permissions?string[]List of [permissions][permissions] to grant when the Audience participant will become a Member.

Returns

Promise<void>

Example

await roomSession.promote({
memberId: "de550c0c-3fac-4efd-b06f-b5b8614b8966",
mediaAllowed: "all",
permissions: [
"room.self.audio_mute",
"room.self.audio_unmute",
"room.self.video_mute",
"room.self.video_unmute",
"room.list_available_layouts",
],
});

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>

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>

Example

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

setHideVideoMuted

setHideVideoMuted(value): Promise<void>

Show or hide muted videos in the room layout. Members that have been muted via videoMute 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>

Example

await roomSession.setHideVideoMuted(false);

setInputSensitivity

setInputSensitivity(params): Promise<void>

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

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the member to affect.
params.valuenumberDesired sensitivity from 0 (lowest sensitivity, essentially muted) to 100 (highest sensitivity). The default value is 30.

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

setInputVolume(params): Promise<void>

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

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the member to affect.
params.volumenumberDesired volume. Values range from -50 to 50, with a default of 0.

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

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>

Example

Set the 6x6 layout:

await roomSession.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.memberIdstringId of the member to affect.
params.meta[Record][record-type]<string, unknown>The medatada object to assign to the member.

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

setMemberPosition

setMemberPosition(params): Promise<void>

Assigns a position in the layout to the specified member.

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the member to affect.
params.positionVideoPositionPosition to assign in the layout.

Returns

Promise<void>

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
meta[Record][record-type]<string, unknown>The metadata object to assign to the RoomSession.

Returns

Promise<void>

Example

await roomSession.setMeta({ foo: "bar" });

setMicrophoneVolume

setMicrophoneVolume(params): Promise<void>

⚠️ Deprecated. Use setInputVolume instead. setMicrophoneVolume will be removed in v4.0.0

Parameters

NameType
paramsObject
params.memberIdstring
params.volumenumber

Returns

Promise<void>


setOutputVolume

setOutputVolume(params): Promise<void>

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

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the member to affect.
params.volumenumberDesired volume. Values range from -50 to 50, with a default of 0.

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

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>

Example

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

setPrioritizeHandraise

setPrioritizeHandraise(params): Promise<boolean>

Set whether to prioritize hand-raise or not. Users with raised hands will be shown in the main video area over other participants who don't have their hand raised.

Parameters

NameTypeDescription
parambooleanWhether to prioritize participants on the canvas with their hand-raised. Default: true. If omitted, the hand status is toggled to the opposite of the current status.

Permissions

  • video.prioritize_handraise

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

Returns

Promise<boolean>

Example

await room.setPrioritizeHandraise(false)

setRaisedHand

setRaisedHand(params): Promise<void>

Sets the raised hand status for the current member.

Parameters

NameTypeDescription
paramsObject-
params.memberIdstringId of the member to affect.
params.raised?booleanWhether to raise or lower the hand. Default: true. If omitted, the hand status is toggled to the opposite of the current status.

Returns

Promise<void>

Permissions

  • video.member.raisehand: to raise a hand
  • video.member.lowerhand: to lower a hand

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

Example

await room.setRaisedHand({
memberId: "de550c0c-3fac-4efd-b06f-b5b86...",
raised: false
});

setSpeakerVolume

setSpeakerVolume(params): Promise<void>

⚠️ Deprecated. Use setOutputVolume instead. setSpeakerVolume will be removed in v4.0.0

Parameters

NameType
paramsObject
params.memberIdstring
params.volumenumber

Returns

Promise<void>


startRecording

startRecording(): Promise<RoomSessionRecording> - See RoomSessionRecording for more details.

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> - See RoomSessionRecording for more details.

Example

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

startStream

startStream(): Promise<RoomSessionStream> - See RoomSessionStream for more details.

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> - See RoomSessionStream for more details.

Example

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

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

subscribe

subscribe(): Promise<RoomSessionFullState> - See RoomSessionFullState for more details.

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> - See RoomSessionFullState for more details.

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

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

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

Returns

Promise<void>

Example

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

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.meta[Record][record-type]<string, unknown>The update to the metadata.

Returns

Promise<void>

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
meta[Record][record-type]<string, unknown>The update to the metadata.

Returns

Promise<void>

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

unlock

unlock(params): Promise<void>

Unlocks the room if it had been previously locked. This allows new participants to join the room.

Returns

Promise<void>

Example

await roomSession.unlock();

videoMute

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

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

Returns

Promise<void>

Example

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

videoUnmute

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

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

Returns

Promise<void>

Example

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

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:

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


room.audience_count

room.audience_count(e)

This event is received periodically, and contains a total count of audience members.

Audience members joining and leaving trigger this event.

Parameters

NameTypeDescription
eObject-
e.room_session_idstringId of the room session.
e.room_idstringId of the room.
e.totalnumberTotal number of audience members.

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