Video

Fresh

Overview

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

The Browser SDK gives you a Call object for every active conversation, inbound or outbound, audio-only or video, 1-on-1 or room. Once you have one, every aspect of the call (status, media streams, participants, layout, recording state, network quality) is reachable through observables and a small set of imperative methods.

This section is the practical guide to building with that object. Pages are roughly ordered from “first call” to “advanced call-center features,” but each is self-contained.

Reading order

If you’re starting from zero:

Outbound Calls, the simplest thing that works: client.dial(), attach streams, listen for status, hang up.
Call Controls, the muscle of any call UI: mute, deaf, hand raise, hangup, DTMF.
Device Management, pick a microphone and camera; reactively rebind when the user plugs in a headset mid-call.
Inbound Calls, register() and subscribe to session.incomingCalls$; answer or reject.

When you need more:

Screen Sharing, self.startScreenShare() and the matching screenShareStatus$.
Layouts, setLayout(), layoutLayers$, picking room layouts at runtime.
Messaging & Chat, in-call text messages via address.sendText and textMessages$.

Every page in this section assumes you’ve read the RxJS Primer, the SDK is observables all the way down. See the Call reference for the full property and method list; the guides here teach how to use it, not which fields exist.

Two patterns the SDK relies on

These show up in every example below, calling them out once here so they don’t surprise you:

call.audioMuted doesn’t exist. Mute / deaf / hand raise / video state all live on the SelfParticipant:

call.self$.subscribe((self) => {
  if (!self) return;
  self.audioMuted$.subscribe((muted) => updateMuteButton(muted));
});

You wait for self$ to emit (it’s null until the local member joins) and then bind to the participant’s own observables.

Most observables on Call and Participant are BehaviorSubjects: late subscribers receive the current value immediately. You don’t need to remember “did I subscribe before the call connected”, you’ll get the cached state on first emission.

// This works even if you subscribe well after the call is connected:
call.status$.subscribe((status) => console.log(status));
// → logs the current status immediately, then any future changes.

A real reference app

Everything in this section is faithful to the kitchen-sink demo in signalwire-typescript-web/playground/kitchen-sink-demo, a vanilla TypeScript app that exercises every public API. When in doubt about how a feature fits together with the rest of the SDK, check playground/kitchen-sink-demo/src/main.ts in the SDK repo for the exact wiring.

Reference

SignalWire, top-level client
Call (interface) / WebRTCCall (concrete), the active call
Participant / SelfParticipant, members
Address, directory entries
SelfCapabilities, per-call permission flags
SessionState, client.session surface (incl. inbound calls)

autoMuteVideoOnHidden

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get autoMuteVideoOnHidden(): boolean
set autoMuteVideoOnHidden(value: boolean)

Whether to auto-mute video when the tab becomes hidden.

Parameters

value

booleanRequired

If true, auto-mutes video when the tab or window becomes hidden.

Examples

// Read
console.log(client.preferences.autoMuteVideoOnHidden);

// Write
client.preferences.autoMuteVideoOnHidden = true;

defaultVideoConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get defaultVideoConstraints(): MediaTrackConstraints | undefined
set defaultVideoConstraints(value: MediaTrackConstraints | undefined)

Default video track constraints applied when video is enabled without explicit constraints.

Parameters

value

MediaTrackConstraints | undefined

Default constraints applied when capturing video input. Pass undefined to clear. See MediaTrackConstraints.

Examples

// Read
console.log(client.preferences.defaultVideoConstraints);

// Write
client.preferences.defaultVideoConstraints = { width: { ideal: 1280 }, height: { ideal: 720 } };

inputVideoConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get inputVideoConstraints(): MediaTrackConstraints | undefined
set inputVideoConstraints(value): void

Default video input track constraints.

Parameters

value

MediaTrackConstraints | undefined

Constraints applied when acquiring video input. Pass undefined to clear. See MediaTrackConstraints.

Examples

console.log(client.preferences.inputVideoConstraints);

preferredVideoCodecs

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get preferredVideoCodecs(): string[]
set preferredVideoCodecs(value): void

Preferred video codecs in priority order.

Parameters

value

string[]

Ordered list of preferred video codec names, e.g. ["VP9", "H264"].

Examples

console.log(client.preferences.preferredVideoCodecs);

preferredVideoInput

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get preferredVideoInput(): MediaDeviceInfo | null
set preferredVideoInput(value): void

Preferred video input device for new calls.

Parameters

value

MediaDeviceInfo | null

Preferred video input device, or null to clear. See MediaDeviceInfo.

Examples

console.log(client.preferences.preferredVideoInput);

receiveVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get receiveVideo(): boolean
set receiveVideo(value): void

Whether to receive remote video by default.

Parameters

value

boolean

If true, the local peer accepts incoming video.

Examples

console.log(client.preferences.receiveVideo);

muteVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

muteVideo(): Promise<void>

Mutes the participant’s video.

Examples

await participant.muteVideo();

See

videoMuted$, reactive state pair.
toggleMuteVideo / unmuteVideo.

toggleMuteVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleMuteVideo(): Promise<void>

Toggles the participant’s video mute state.

Returns

Promise<void>

Examples

await participant.toggleMuteVideo();

See

videoMuted$, reactive state pair.
muteVideo / unmuteVideo, force a specific state.
Gated by SelfCapabilities.self.muteVideo.

unmuteVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

unmuteVideo(): Promise<void>

Unmutes the participant’s video.

Returns

Promise<void>

Examples

await participant.unmuteVideo();

See

videoMuted$, reactive state pair.
toggleMuteVideo / muteVideo.

videoMuted$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get videoMuted$(): Observable<boolean | undefined>

Observable indicating whether the participant’s video is muted.

videoMuted

get videoMuted(): boolean

Whether the participant’s video is muted.

Examples

participant.videoMuted$.subscribe((videoMuted) => {
  console.log('videoMuted:', videoMuted);
});

addVideoInputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

addVideoInputDevice(__namedParameters?): Promise<void>

Adds or replaces the primary video input device with optional constraints or stream.

Parameters

__namedParameters

{ constraints?: MediaTrackConstraints; stream?: MediaStream; }

Capture options: either explicit constraints or a pre-acquired stream. See MediaTrackConstraints and MediaStream.

Returns

Promise<void>

Examples

await selfParticipant.addVideoInputDevice(__namedParameters);

muteVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

muteVideo(): Promise<void>

Mutes local video. Falls back to local device mute if the server RPC fails.

Returns

Promise<void>

Examples

await selfParticipant.muteVideo();

selectVideoInputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

selectVideoInputDevice(device, options?): void

Selects the video input device for future calls. Optionally saves as a preference.

Parameters

device

MediaDeviceInfoRequired

Device to select. See MediaDeviceInfo.

options

SelectDeviceOptions

Selection options, including whether to persist the choice. See SelectDeviceOptions.

Returns

void

Examples

selfParticipant.selectVideoInputDevice(device, options);

setVideoInputDeviceConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setVideoInputDeviceConstraints(constraints): Promise<void>

Updates the video input track constraints for the active call.

Parameters

constraints

MediaTrackConstraintsRequired

Media-track constraints to apply to the current video input. See MediaTrackConstraints.

Returns

Promise<void>

Examples

await selfParticipant.setVideoInputDeviceConstraints(constraints);

toggleMuteVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleMuteVideo(): Promise<void>

Toggles the participant’s video mute state.

Returns

Promise<void>

Inherited from

Participant. toggleMuteVideo

Examples

await selfParticipant.toggleMuteVideo();

unmuteVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

unmuteVideo(): Promise<void>

Unmutes local video. Falls back to local device unmute if the server RPC fails.

Returns

Promise<void>

Examples

await selfParticipant.unmuteVideo();

videoMuted$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get videoMuted$(): Observable<boolean | undefined>

Observable indicating whether the participant’s video is muted.

Inherited from

Participant. videoMuted$

videoMuted

get videoMuted(): boolean

Whether the participant’s video is muted.

Inherited from

Participant. videoMuted

Examples

selfParticipant.videoMuted$.subscribe((videoMuted) => {
  console.log('videoMuted:', videoMuted);
});

disableVideoInput

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

disableVideoInput(): void

Disables video input (receive-only mode). No video track will be acquired.

Examples

client.disableVideoInput();

enableVideoInput

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

enableVideoInput(): void

Re-enables video input, restoring the last selection or auto-selecting.

Examples

client.enableVideoInput();

selectVideoInputDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

selectVideoInputDevice(device): void

Sets the preferred video input device.

Parameters

device

MediaDeviceInfo | nullRequired

Device to select. Pass null to clear the current selection. See MediaDeviceInfo.

Returns

void

Examples

client.selectVideoInputDevice(device);

See

videoInputDevices$, list of available cameras.
selectedVideoInputDevice$, reactive state.
deviceRecovered$, auto-switch events.

selectedVideoInputDevice$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get selectedVideoInputDevice$(): Observable<MediaDeviceInfo | null>

Observable of the currently selected video input device.

selectedVideoInputDevice

get selectedVideoInputDevice(): MediaDeviceInfo | null

Currently selected video input device, or null if none.

Examples

client.selectedVideoInputDevice$.subscribe((selectedVideoInputDevice) => {
  console.log('selectedVideoInputDevice:', selectedVideoInputDevice);
});

selectedVideoInputDeviceConstraints

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get selectedVideoInputDeviceConstraints(): boolean | MediaTrackConstraints

Media track constraints for the selected video input device. Returns false when disabled.

Examples

console.log(client.selectedVideoInputDeviceConstraints);

videoInputDevices$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get videoInputDevices$(): Observable<MediaDeviceInfo[]>

Observable list of available video input (camera) devices.

videoInputDevices

get videoInputDevices(): MediaDeviceInfo[]

Current snapshot of available video input devices.

Examples

client.videoInputDevices$.subscribe((videoInputDevices) => {
  console.log('videoInputDevices:', videoInputDevices);
});

videoInputDisabled$

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

get videoInputDisabled$(): Observable<boolean>

Observable that emits true when video input is disabled (receive-only).

videoInputDisabled

get videoInputDisabled(): boolean

Whether video input is currently disabled.

Examples

client.videoInputDisabled$.subscribe((videoInputDisabled) => {
  console.log('videoInputDisabled:', videoInputDisabled);
});

VideoPosition

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

type VideoPosition = "auto" | `reserved-${number}` | `standard-${number}` | "off-canvas" | "playback" | "full-screen"

Position of a participant’s video within the layout canvas.

'auto', Automatically positioned by the layout engine.
reserved-${number}, A reserved slot in the layout (e.g., 'reserved-0').
standard-${number}, A standard slot in the layout (e.g., 'standard-1').
'off-canvas', Participant is not visible in the layout.
'playback', Playback position for media streams.
'full-screen', Participant occupies the entire canvas.

toggleIncomingVideo

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

toggleIncomingVideo(): Promise<void>

Toggles whether the local peer receives incoming video from the call. When disabled, the remote video stream is discarded; the local participant continues to send video (if not muted).

Not yet implemented in v4. This method is on the API surface and will throw when called.

Returns

Promise<void>, once implemented, resolves after the server has acknowledged the state change.

Throws

Throws unconditionally, implementation pending.

See

toggleIncomingAudio, the parallel audio toggle.

Build a video calling application with the Browser SDK

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

SignalWire’s Video API allows you to host real-time video calls and conferences on your website or app. In this guide, we will use SignalWire APIs in three steps to create a minimal full-stack video-calling website.

This is what we will cover:

Registering with SignalWire to obtain your API key and Project ID
Writing a minimal backend server in Node.js. This is a simple proxy server, so if you prefer you can use any platform such as PHP or Python.
Developing a simple frontend web app in JavaScript. The SignalWire Browser SDK will do most of the work for us.

When the site is finished, it will look something like this:

a video call with two participants and a button labeled 'Hang up' beneath the video.

The end result of this tutorial.

Obtaining your API key and Project ID

First, we will need access to the SignalWire APIs. If you already have a SignalWire account, can sign in to the SignalWire website. If you’re not already registered, you can sign up in trial mode, which comes with a $5 credit. This will be plenty to follow along with this guide.

Once you’ve signed up and verified your email, create a new project. Next, navigate to the API Credentials page page of your SignalWire Dashboard.

The API page shows the active Project ID and Space URL, and a list of API tokens organized by Name, Token, and Last Used.

Two important pieces of information about our project are displayed there:

Space URL: You’ll use this URL to access SignalWire APIs
Project ID: You’ll use this UUID to specify your project to the API

There is one more piece of information that we need from our new project. We need to generate an API token to access SignalWire’s APIs from our own code.

To generate an API token, click on the New Token button. Give it an easily identifiable name, and make sure that the “Video” scope is enabled. Then hit “Save”.

It is important that the API tokens are not publically exposed. They can be used to make API requests on your behalf. Take extreme care to make sure that the tokens are not pushed to GitHub or exposed in frontend code. For Node.js backends, you can use dotenv files or similar mechanisms to safely store confidential constants.

Now that we have collected the Project ID, the Space URL, and the API token, we can start writing our application.

Backend

Why do I need my own backend?

As mentioned in the previous section, API tokens must be kept confidential. When you build a web application or any application that runs on a user’s device, the code running on the device should be considered untrusted (secrets can be stolen). S ince you must use the API token from a trusted environment, you do so in your own server. Having your own backend server also allows you to build custom authorization policies instead of giving every client admin access.

The figure below illustrates the typical network interaction we are building. Your server can directly access the SignalWire servers (for example, to get a list of active rooms). However, for a client to interact with SignalWire servers, it must first ask your server to provide a limited-scope token (we call this the Video Room Token).

A diagram showing the relationship between SignalWire Servers, Your Server, and the Client, such as a browser or app. The SignalWire Servers communicate a list of rooms and the requested Video Room Token to Your Server. The Client interfaces with SignalWire Servers to join the room, transmit WebRTC video stream and events, and perform room actions like changing room layout, muting audio, and leaving the room.

The API token gives full access to SignalWire APIs. Whoever owns the API token can, for example, delete any room, mute or unmute any participant, and so on without limitations. You may only use the API token in your server to communicate with SignalWire.

The Video Room Token is a limited-scope token that clients can use to access SignalWire APIs without knowing the API token. Clients must ask your proxy server for a Video Room Token. Your server will obtain it from SignalWire servers and pass it back to the client. Video Room Tokens are associated with a given <_user_, _room_> pair, so you can think of them as a personal key for a given user to access a given room. Your server sets the permissions for each Video Room Token, for example, whether they are allowed to mute other users.

Getting a Video Room Token using cURL

Let’s take a look at how our backend will use the API token to get a Video Room Token. To get a token from the REST API for a user with name “john” and a room “office” with only video muting permissions, we can use this call:

curl --request POST \
     --url 'https://your_space_url.signalwire.com/api/video/room_tokens' \
     --user 'project_id:api_token' \
     --header 'Content-Type: application/json' \
     --data '{"user_name": "john", "room_name": "office", "permissions": ["room.self.video_mute"]}'

You can see a complete list of possible permissions and video token parameters in our documentation.

The JSON response from the API will look like this and can be safely sent to the client:

{
  "token": "eyJ0eXAiOiJWUlQiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MzI0OTE3ODAsImp0aSI6ImM2NmU3ODlkLTJmMjItMTIzNC1hNzMzLThlZjA2MzdmNWI2YiIsInN1YiI6ImExNmQ4ZjllLTIxNjYtNGU4Mi01Njc4LWE0ODQwZjIxN2JjMyIsInUiOiJqb2huIiwiciI6Im9mZmljZSIsInMiOlsicm9vbS5yZWNvcmRpbmciXSwiYWNyIjp0cnVlfQ.qYQwQ1PEnzGbAIb1RoVuYLf0mlqApi15wSC2n7QMCFP4M7jOjOIb_Ia_BhKnbnTHb7sI78d2jS7f_qsFV2OHLw"
}

Getting a Video Room Token using your own server

Instead of using curl, and to allow for more granular control over permissions alongside user authentication, we’ll create a server to accept an incoming request for a Video Room Token, obtain the Video Room Token, and send it back to the client. Our server only needs to expose a single endpoint, which we will call /get_token (but it can be anything you want).

// Auth constants to be stored in a dotenv file (or equivalent) with gitignore
const auth = {
  username: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx", // Project ID
  password: "PTxxx...xxx", // API token
};

const apiurl = "https://<your_space_url>/api/video";

// Endpoint to request Video Room Token for video call
app.post("/get_token", async (req, res) => {
  let { user_name, room_name } = req.body;

  console.log("Received name", user_name);

  try {
    // get the Video Room Token from SignalWire
    let token = await axios.post(
      apiurl + "/room_tokens",
      {
        user_name: user_name,
        room_name: room_name,
        permissions: [\
          "room.list_available_layouts",\
          "room.set_layout",\
          "room.self.audio_mute",\
          "room.self.audio_unmute",\
          "room.self.video_mute",\
          "room.self.video_unmute",\
        ],
      },
      { auth }
    );
    console.log(token.data.token);

    // send the Video Room Token back to the client
    return res.json({ token: token.data.token });
  } catch (e) {
    console.log(e);
    return res.sendStatus(500);
  }
});

Let’s break this piece of code down.

The user’s user_name will be used to identify them in the video call, so the frontend will send this information when making a request to our /get_token endpoint. Likewise, the room_name determines the name of the room to join. If the room doesn’t exist, it will be created automatically.
We send a post request to the room_tokens endpoint of SignalWire REST APIs. The room_tokens endpoint sends back a Video Room Token that we can forward to our client.

Now we have everything we need to start building the frontend.

Frontend

The SignalWire Browser SDK makes it surprisingly easy to integrate video calling into any web application. It only takes a few minutes to set up the basics. First, we need to include the SDK in our HTML.

<!-- Import SignalWire library -->
<script src="https://cdn.signalwire.com/@signalwire/js"></script>

Then you can interact with the SDK using the global variable SignalWire. We’ll mainly be interested in the SignalWire.Video.RoomSession class for this guide, but if you’d like to explore this API, please browse the SDK documentation.

Before a user can join a room, we need to make a POST request for a Video Room Token to the backend server endpoint we just created.

const backendurl = ""; // Your backend server. If you server and frontend are in the same directory, you can leave this string empty
let token = await axios.post(backendurl + "/get_token", {
  user_name: username,
  room_name: roomname,
});
console.log(token.data);
token = token.data.token;

Then, to start the video session, we instantiate a new RoomSession object and then we join it:

roomSession = new SignalWire.Video.RoomSession({
  token,
  rootElement: document.getElementById("root"), // The HTML element in which to display the video
});

try {
  await roomSession.join();
} catch (error) {
  console.error("Error", error);
}

The other important key-value parameter to pass is a rootElement. The root element is an empty HTML element in your DOM (for example, a “). It will serve as the container for the video stream. When roomSession.join is called, the SDK will join the room, and the video will appear in rootElement.

These pieces are all you need to get the video up and running. However, we can polish our application by using the Events included on the Room Session object.

Using Events

The Room Session object supports the standard .on() method to attach event listeners and the corresponding .off() method to detach them. You should subscribe to events after the room is created but before joining the room. Some of the events you might subscribe to are:

room.joined: you have joined the room
room.updated: a room property has been updated
room.ended: the room has ended
member.updated: a member property has changed (e.g., video muted)
member.updated.audio_muted: the audio_muted state has changed for a member
member.updated.video_muted: the video_muted state has changed for a member
member.updated.visible: the member is now visible in the video layout
member.left: a member left the room
layout.changed: the layout of the room has changed

Find the complete list in our API reference.

Here’s how we can use some these events in our example program:

roomSession.on("room.joined", (e) => logevent("You joined the room"));
roomSession.on("member.joined", (e) => logevent(e.member.name + " has joined the room"));
roomSession.on("member.left", (e) => logevent(e.member.id + " has left the room"));

Putting it All Together

All the above ideas can be combined to create the following function, which we’ll use (with minor variations) in the frontend.

async function join() {
  const username = $("usernameinput").value.trim();
  const roomname = $("roomnameinput").value.trim();
  gotopage("loading");

  try {
    token = await axios.post(backendurl + "/get_token", {
      user_name: username,
      room_name: roomname,
    });
    console.log(token.data);
    token = token.data.token;

    try {
      try {
        roomSession = new SignalWire.Video.RoomSession({
          token,
          rootElement: document.getElementById("root"),
        });
      } catch (e) {
        console.log(e);
      }

      roomSession.on("room.joined", (e) => logevent("You joined the room"));
      roomSession.on("member.joined", (e) =>
        logevent(e.member.name + " has joined the room")
      );
      roomSession.on("member.left", (e) => logevent(e.member.id + " has left the room"));

      await roomSession.join();
    } catch (error) {
      console.error("Something went wrong", error);
    }

    gotopage("videoroom");
  } catch (e) {
    console.log(e);
    alert("Error encountered. Please try again.");
    gotopage("getusername");
  }
}

Please visit our GitHub page to see complete code or fork the repository.

Conclusion

Here is the final result of our development with a preview of some added features:

SignalWire video call with controls for screen share, layout, audio, and video.

The most noteworthy thing about SignalWire Video technology is that it only streams a single video stream no matter how many participants there are. The video is composited on powerful SignalWire servers by stitching all of the individual video streams together. So you can invite as many people as you like to your virtual video party. Your app will run without a hitch.

What now? If you would like a custom approach that adds to what we developed here, visit one of our guides below. If you prefer a guide to build a standard, polished video application from scratch, you can see our Zoom like application Guide.

Video

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

The Video namespace contains the classes and functions that you need to create a video conferencing application.

The RoomSession class is the main interface for managing video room sessions.

Classes

RoomSession\ \ The main interface for managing video room sessions

RoomSessionDevice\ \ Control devices within a room session RoomSessionPlayback\ \ Manage media playback in a room session RoomSessionRecording\ \ Handle recording functionality RoomSessionScreenShare\ \ Manage screen sharing in a room session ~~RoomDevice~~\ \ Use RoomSessionDevice instead. ~~RoomScreenShare~~\ \ Use RoomSessionScreenShare instead.

Functions

~~Functions~~

createRoomObject

Const createRoomObject(roomOptions): Promise<Room>

Deprecated

Use RoomSession instead.

Using Video.createRoomObject() you can create a RoomObject to join a room.

Parameters

Name	Type	Description
`applyLocalVideoOverlay?`	`boolean`	Whether to apply the local-overlay on top of your video. Default: `true`.
`audio?`	`boolean` \| `MediaTrackConstraints`	Audio constraints to use when joining the room. Default: `true`.
`autoJoin?`	`boolean`	Whether to automatically join the room session.
`iceServers?`	`RTCIceServer[]`	List of ICE servers.
`logLevel?`	`"trace"` \| `"debug"` \| `"info"` \| `"warn"` \| `"error"` \| `"silent"`	Logging level.
`project`	`string`	SignalWire project id, e.g. `a10d8a9f-2166-4e82-56ff-118bc3a4840f`.
`rootElementId?`	`string`	Id of the HTML element in which to display the video stream.
`speakerId?`	`string`	Id of the speaker device to use for audio output. If undefined, picks a default speaker.
`stopCameraWhileMuted?`	`boolean`	Whether to stop the camera when the member is muted. Default: `true`.
`stopMicrophoneWhileMuted?`	`boolean`	Whether to stop the microphone when the member is muted. Default: `true`.
`token`	`string`	SignalWire project token, e.g. `PT9e5660c101cd140a1c93a0197640a369cf5f16975a0079c9`.
`video?`	`boolean` \| `MediaTrackConstraints`	Video constraints to use when joining the room. Default: `true`.

Returns

Promise<Room>

Example

With an HTMLDivElement with id=“root” in the DOM.

// <div id="root"></div>

try {
  const roomObj = await Video.createRoomObject({
    token: "<YourJWT>",
    rootElementId: "root"
  });

  roomObj.join();
} catch (error) {
  console.error("Error", error);
}

joinRoom

Const joinRoom(roomOptions): Promise<Room>

Deprecated

Use RoomSession instead.

Using Video.joinRoom() you can automatically join a room.

Parameters

Name	Type	Description
`applyLocalVideoOverlay?`	`boolean`	Whether to apply the local-overlay on top of your video. Default: `true`.
`audio?`	`boolean` \| `MediaTrackConstraints`	Audio constraints to use when joining the room. Default: `true`.
`autoJoin?`	`boolean`	Whether to automatically join the room session.
`iceServers?`	`RTCIceServer[]`	List of ICE servers.
`logLevel?`	`"trace"` \| `"debug"` \| `"info"` \| `"warn"` \| `"error"` \| `"silent"`	Logging level.
`project`	`string`	SignalWire project id, e.g. `a10d8a9f-2166-4e82-56ff-118bc3a4840f`.
`rootElementId?`	`string`	Id of the HTML element in which to display the video stream.
`speakerId?`	`string`	Id of the speaker device to use for audio output. If undefined, picks a default speaker.
`stopCameraWhileMuted?`	`boolean`	Whether to stop the camera when the member is muted. Default: `true`.
`stopMicrophoneWhileMuted?`	`boolean`	Whether to stop the microphone when the member is muted. Default: `true`.
`token`	`string`	SignalWire project token, e.g. `PT9e5660c101cd140a1c93a0197640a369cf5f16975a0079c9`.
`video?`	`boolean` \| `MediaTrackConstraints`	Video constraints to use when joining the room. Default: `true`.

Returns

Promise<Room>

Example

With an HTMLDivElement with id=“root” in the DOM.

// <div id="root"></div>

try {
  const roomObj = await Video.joinRoom({
    token: "<YourJWT>",
    rootElementId: "root",
  });

  // You have joined the room..
} catch (error) {
  console.error("Error", error);
}

LocalOverlay

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Represents the local overlay, which displays the user’s local camera feed.

Properties

mirrored

booleanRequired

Whether the local video overlay is mirrored.

Methods

setMirrored

▸ setMirrored(): void

Mirror the local video overlay when true. The mirrored stream is sent to the SignalWire server and is visible to all participants.

Parameters

mirror

booleanRequired

Whether to mirror the local video overlay.

Returns

void

Example

await roomSession.localOverlay.setMirrored(true);

RoomDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Deprecated

Use RoomSessionDevice instead.

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.

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.

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.

Methods

audioMute

▸ audioMute(): Promise<void>

Puts the microphone on mute. The other participants will not hear audio from the muted device anymore.

Returns

Promise<void>

Permissions

room.self.audio_mute

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

Example

Muting the microphone:

await roomdevice.audioMute();

audioUnmute

▸ audioUnmute(): Promise<void>

Unmutes the microphone if it had been previously muted.

Returns

Promise<void>

Permissions

room.self.audio_unmute

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

Example

Unmuting the microphone:

await roomdevice.audioUnmute();

join

▸ join(): Promise<void>

Joins this device to the room session.

Returns

Promise<void>

leave

▸ leave(): Promise<void>

Detaches this device from the room session.

Returns

Promise<void>

setInputSensitivity

▸ setInputSensitivity(params): Promise<void>

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

Parameters

Name	Type	Description
`params`	`Object`
`params.value`	`number`	Desired 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

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

Example

await roomdevice.setInputSensitivity({ value: 80 });

setInputVolume

▸ setInputVolume(params): Promise<void>

Sets the input volume level (e.g. for the microphone).

Parameters

Name	Type	Description
`params`	`Object`	-
`params.volume`	`number`	Desired volume. Values range from -50 to 50, with a default of 0.

Returns

Promise<void>

Permissions

room.self.set_input_volume

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

Example

await roomdevice.setMicrophoneVolume({ volume: -10 });

setMicrophoneVolume

▸ setMicrophoneVolume(params): Promise<void>

Deprecated. Use setInputVolume instead.

Parameters

Name	Type
`params`	`Object`
`params.volume`	`number`

Returns

Promise<void>

updateCamera

▸ updateCamera(constraints): Promise<void>

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

Parameters

Name	Type	Description
`constraints`	`MediaTrackConstraints`	Specify 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 roomDevice.updateCamera({
  deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg=",
});

updateMicrophone

▸ updateMicrophone(constraints): Promise<void>

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

Parameters

Name	Type	Description
`constraints`	`MediaTrackConstraints`	Specify 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 roomDevice.updateMicrophone({
  deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg=",
});

videoMute

▸ videoMute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_mute

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

Example

Muting the camera:

await roomdevice.videoMute();

videoUnmute

▸ videoUnmute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_unmute

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

Example

Unmuting the camera:

await roomdevice.videoUnmute();

RoomScreenShare

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Deprecated

Use RoomSessionDevice instead.

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.

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.

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.

Methods

audioMute

▸ audioMute(): Promise<void>

Puts the microphone on mute. The other participants will not hear audio from the muted device anymore.

Returns

Promise<void>

Permissions

room.self.audio_mute

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

Example

Muting the microphone:

await roomdevice.audioMute();

audioUnmute

▸ audioUnmute(): Promise<void>

Unmutes the microphone if it had been previously muted.

Returns

Promise<void>

Permissions

room.self.audio_unmute

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

Example

Unmuting the microphone:

await roomdevice.audioUnmute();

join

▸ join(): Promise<void>

Joins this device to the room session.

Returns

Promise<void>

leave

▸ leave(): Promise<void>

Detaches this device from the room session.

Returns

Promise<void>

setInputSensitivity

▸ setInputSensitivity(params): Promise<void>

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

Parameters

Name	Type	Description
`params`	`Object`
`params.value`	`number`	Desired 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

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

Example

await roomdevice.setInputSensitivity({ value: 80 });

setInputVolume

▸ setInputVolume(params): Promise<void>

Sets the input volume level (e.g. for the microphone).

Parameters

Name	Type	Description
`params`	`Object`	-
`params.volume`	`number`	Desired volume. Values range from -50 to 50, with a default of 0.

Returns

Promise<void>

Permissions

room.self.set_input_volume

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

Example

await roomdevice.setMicrophoneVolume({ volume: -10 });

setMicrophoneVolume

▸ setMicrophoneVolume(params): Promise<void>

Deprecated. Use setInputVolume instead.

Parameters

Name	Type
`params`	`Object`
`params.volume`	`number`

Returns

Promise<void>

updateCamera

▸ updateCamera(constraints): Promise<void>

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

Parameters

Name	Type	Description
`constraints`	`MediaTrackConstraints`	Specify 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 screenShareObj.updateCamera({
  deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg=",
});

updateMicrophone

▸ updateMicrophone(constraints): Promise<void>

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

Parameters

Name	Type	Description
`constraints`	`MediaTrackConstraints`	Specify 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 screenShareObj.updateMicrophone({
  deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg=",
});

videoMute

▸ videoMute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_mute

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

Example

Muting the camera:

await roomdevice.videoMute();

videoUnmute

▸ videoUnmute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_unmute

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

Example

Unmuting the camera:

await roomdevice.videoUnmute();

RoomSession

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

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

roomSession.join();

Obtaining a token

The room token is obtained from the REST API from your backend server.

POST

/api/video/room_tokens

cURL

curl -X POST https://{your_space_name}.signalwire.com/api/video/room_tokens \
     -H "Content-Type: application/json" \
     -u "<project_id>:<api_token>" \
     -d '{
  "room_name": "my_room"
}'

Try it

Please refer to the build a video application guide to learn how to obtain Video Room tokens.

Constructor

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

const roomSession = new SignalWire.Video.RoomSession({
  token: "<YourRoomToken>",
  // ...
});

Parameters

The RoomSession constructor accepts the following parameters:

token

stringRequired

SignalWire video room token (get one from the REST APIs)

rootElement

HTMLElement

HTML element in which to display the video stream.

applyLocalVideoOverlay

booleanDefaults to true

Whether to apply the local-overlay on top of your video.

iceServers

RTCIceServer[]

List of ICE servers.

localStream

MediaStream

A custom media stream to use in place of a camera.

logLevel

Logging level.

speakerId

string

Id of the speaker device to use for audio output. If undefined, picks a default speaker.

stopCameraWhileMuted

booleanDefaults to true

Whether to stop the camera when the member is muted.

stopMicrophoneWhileMuted

booleanDefaults to true

Whether to stop the microphone when the member is muted.

audio

boolean | MediaTrackConstraintsDefaults to trueDeprecated

Audio constraints to use when joining the room. Deprecated: please use the equivalent parameter in join.

video

boolean | MediaTrackConstraintsDefaults to trueDeprecated

Video constraints to use when joining the room. Deprecated: please use the equivalent parameter in join.

Properties

The RoomSession class has the following properties:

active

boolean

Whether the connection is currently active. Read-only.

cameraId

string | null

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

cameraLabel

string | null

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

deviceList

RoomSessionDevice[]

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

interactivityMode

roomSessionId

string

The unique identifier for the room session. Read-only.

screenShareList

RoomSessionScreenShare[]

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

Methods

join\ \ Join the room session leave\ \ Leave the room session destroy\ \ Destroy the room session addCamera\ \ Add a camera device to the room addMicrophone\ \ Add a microphone device to the room addDevice\ \ Add a media device to the room updateCamera\ \ Update the camera device updateMicrophone\ \ Update the microphone device updateSpeaker\ \ Update the speaker device audioMute\ \ Mute the microphone audioUnmute\ \ Unmute the microphone videoMute\ \ Mute the video videoUnmute\ \ Unmute the video deaf\ \ Stop receiving audio from the room undeaf\ \ Resume receiving audio from the room getMembers\ \ Get list of members in the room removeMember\ \ Remove a member from the room removeAllMembers\ \ Remove all members from the room hangupAll\ \ Disconnect all members from the room promote\ \ Promote audience member to member demote\ \ Demote member to audience startRecording\ \ Start recording the room getRecordings\ \ Get list of active recordings startStream\ \ Start streaming the room getStreams\ \ Get list of active streams play\ \ Play media in the room getPlaybacks\ \ Get list of active playbacks startScreenShare\ \ Start screen sharing setLayout\ \ Set the room layout getLayouts\ \ Get available room layouts setMemberPosition\ \ Set position for a member in the layout setPositions\ \ Set positions for multiple members getMeta\ \ Get room metadata setMeta\ \ Set room metadata updateMeta\ \ Update room metadata deleteMeta\ \ Delete room metadata getMemberMeta\ \ Get member metadata setMemberMeta\ \ Set member metadata updateMemberMeta\ \ Update member metadata deleteMemberMeta\ \ Delete member metadata setInputVolume\ \ Set input volume level setOutputVolume\ \ Set output volume level setInputSensitivity\ \ Set input sensitivity level setHideVideoMuted\ \ Hide video for muted members setPrioritizeHandraise\ \ Prioritize members with raised hands setRaisedHand\ \ Raise or lower hand setLocalStream\ \ Set local media stream lock\ \ Lock the room unlock\ \ Unlock the room sendDigits\ \ Send DTMF digits on\ \ Subscribe to an event once\ \ Subscribe to an event once off\ \ Unsubscribe from an event removeAllListeners\ \ Remove all event listeners ~~createScreenShareObject~~\ \ Create screen share object ~~hideVideoMuted~~\ \ Hide muted video ~~showVideoMuted~~\ \ Show muted video

Events

Events\ \ Events emitted by the RoomSession class.

RoomSessionDevice

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

string

The unique identifier for the room session.

Methods

join\ \ Join the room session leave\ \ Leave the room session audioMute\ \ Mute the microphone audioUnmute\ \ Unmute the microphone videoMute\ \ Mute the video videoUnmute\ \ Unmute the video updateCamera\ \ Switch to a different camera updateMicrophone\ \ Switch to a different microphone setInputVolume\ \ Set the input volume level setInputSensitivity\ \ Set the input sensitivity level ~~setMicrophoneVolume~~\ \ Set microphone volume (deprecated)

audioMute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

audioMute

▸ audioMute(): Promise<void>

Puts the microphone on mute. The other participants will not hear audio from the muted device anymore.

Returns

Promise<void>

Permissions

room.self.audio_mute

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

Example

await roomdevice.audioMute();

audioUnmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

audioUnmute

▸ audioUnmute(): Promise<void>

Unmutes the microphone if it had been previously muted.

Returns

Promise<void>

Permissions

room.self.audio_unmute

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

Example

await roomdevice.audioUnmute();

join

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

join

▸ join(): Promise<void>

Joins this device to the room session.

Returns

Promise<void>

leave

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

leave

▸ leave(): Promise<void>

Detaches this device from the room session.

Returns

Promise<void>

setInputSensitivity

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setInputSensitivity

▸ setInputSensitivity(params): Promise<void>

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

Parameters

params

objectRequired

Configuration object for input sensitivity

params.value

numberRequired

Desired 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

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

Example

await roomdevice.setInputSensitivity({ value: 80 });

setInputVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setInputVolume

▸ setInputVolume(params): Promise<void>

Sets the input volume level (e.g. for the microphone).

Parameters

params

objectRequired

Configuration object for input volume

params.volume

numberRequired

Desired volume. Values range from -50 to 50, with a default of 0.

Returns

Promise<void>

Permissions

room.self.set_input_volume

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

Example

await roomdevice.setMicrophoneVolume({ volume: -10 });

setMicrophoneVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setMicrophoneVolume

▸ setMicrophoneVolume(params): Promise<void>

Deprecated. Use setInputVolume instead.

Parameters

params

objectRequired

Configuration object

params.volume

numberRequired

Volume value

Returns

Promise<void>

updateCamera

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateCamera

▸ updateCamera(constraints): Promise<void>

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

Parameters

constraints

MediaTrackConstraintsRequired

Specify the constraints that the device should satisfy. See MediaTrackConstraints.

Returns

Promise<void>

Example

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

updateMicrophone

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateMicrophone

▸ updateMicrophone(constraints): Promise<void>

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

Parameters

constraints

MediaTrackConstraintsRequired

Specify the constraints that the device should satisfy. See MediaTrackConstraints.

Returns

Promise<void>

Example

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

videoMute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

videoMute

▸ videoMute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_mute

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

Example

await roomdevice.videoMute();

videoUnmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

videoUnmute

▸ videoUnmute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_unmute

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

Example

await roomdevice.videoUnmute();

RoomSessionPlayback

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

numberRequired

Audio volume at which the playback file is reproduced.

Methods

forward

▸ forward(offset): Promise<void>

Seeks the current playback forward by the specified offset.

Parameters

offset

number

Relative number of milliseconds to seek forward from the current position. Defaults to 5000 (5 seconds).

Returns

Promise<void>

Permissions

room.playback.seek or the more permissive 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.forward(5000); // 5 seconds

pause

▸ pause(): Promise<void>

Pauses the playback.

Returns

Promise<void>

resume

▸ resume(): Promise<void>

Resumes the playback.

Returns

Promise<void>

rewind

▸ rewind(offset): Promise<void>

Seeks the current playback backwards by the specified offset.

Parameters

offset

number

Relative number of milliseconds to seek backwards from the current position. Defaults to 5000 (5 seconds).

Returns

Promise<void>

Permissions

room.playback.seek or the more permissive 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.rewind(5000); // 5 seconds

seek

▸ seek(timecode): Promise<void>

Seeks the current playback to the specified absolute position.

Parameters

timecode

numberRequired

The absolute position in milliseconds to seek to in the playback.

Returns

Promise<void>

Permissions

room.playback.seek or the more permissive 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.seek(30_000); // 30th second

setVolume

▸ setVolume(volume): Promise<void>

Sets the audio volume for the playback.

Parameters

volume

numberRequired

The desired volume. Values range from -50 to 50, with a default of 0.

Returns

Promise<void>

stop

▸ stop(): Promise<void>

Stops the playback.

Returns

Promise<void>

RoomSessionRecording

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Represents a specific recording of a room session.

Properties

duration

number

Duration, if available.

endedAt

Date

End time, if available.

id

stringRequired

The unique id of this recording.

roomSessionId

stringRequired

The id of the room session associated to this recording.

startedAt

Date

Start time, if available.

state

"recording" | "paused" | "completed"Required

Current state.

Methods

pause

▸ pause(): Promise<void>

Pauses the recording.

Returns

Promise<void>

resume

▸ resume(): Promise<void>

Resumes the recording.

Returns

Promise<void>

stop

▸ stop(): Promise<void>

Stops the recording.

Returns

Promise<void>

RoomSessionScreenShare

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

string

The unique identifier for the room session.

Methods

audioMute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

audioMute

▸ audioMute(): Promise<void>

Puts the microphone on mute. The other participants will not hear audio from the muted device anymore.

Returns

Promise<void>

Permissions

room.self.audio_mute

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

Example

await roomdevice.audioMute();

audioUnmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

audioUnmute

▸ audioUnmute(): Promise<void>

Unmutes the microphone if it had been previously muted.

Returns

Promise<void>

Permissions

room.self.audio_unmute

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

Example

await roomdevice.audioUnmute();

join

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

join

▸ join(): Promise<void>

Joins this device to the room session.

Returns

Promise<void>

leave

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

leave

▸ leave(): Promise<void>

Detaches this device from the room session.

Returns

Promise<void>

setInputSensitivity

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setInputSensitivity

▸ setInputSensitivity(params): Promise<void>

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

Parameters

params

objectRequired

Configuration object for input sensitivity

params.value

numberRequired

Desired sensitivity. The default value is 30 and the scale goes from 0 (lowest sensitivity, essentially muted) to 100 (highest sensitivity).

Returns

Promise<void>

Permissions

room.self.set_input_sensitivity

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

Example

await roomdevice.setInputSensitivity({ value: 80 });

setInputVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setInputVolume

▸ setInputVolume(params): Promise<void>

Sets the input volume level (e.g. for the microphone).

Parameters

params

objectRequired

Configuration object for input volume

params.volume

numberRequired

Desired volume. Values range from -50 to 50, with a default of 0.

Returns

Promise<void>

Permissions

room.self.set_input_volume

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

Example

await roomdevice.setMicrophoneVolume({ volume: -10 });

setMicrophoneVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setMicrophoneVolume

▸ setMicrophoneVolume(params): Promise<void>

Deprecated. Use setInputVolume instead.

Parameters

params

objectRequired

Configuration object

params.volume

numberRequired

Volume value

Returns

Promise<void>

updateCamera

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateCamera

▸ updateCamera(constraints): Promise<void>

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

Parameters

constraints

MediaTrackConstraintsRequired

Specify the constraints that the device should satisfy. See MediaTrackConstraints.

Returns

Promise<void>

Example

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

updateMicrophone

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateMicrophone

▸ updateMicrophone(constraints): Promise<void>

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

Parameters

constraints

MediaTrackConstraintsRequired

Specify the constraints that the device should satisfy. See MediaTrackConstraints.

Returns

Promise<void>

Example

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

videoMute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

videoMute

▸ videoMute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_mute

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

Example

await roomdevice.videoMute();

videoUnmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

videoUnmute

▸ videoUnmute(): Promise<void>

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

Returns

Promise<void>

Permissions

room.self.video_unmute

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

Example

await roomdevice.videoUnmute();

RoomSessionStream

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

Represents a specific stream of a room session. This is an RTMP stream of the audio/video content of the room, which will be sent to an external party (e.g., to YouTube).

You can start a stream with RoomSession.startStream.

Properties

duration

number

Total seconds of time spent streaming, if available. This is equal to (endedAt - startedAt).

endedAt

Date

End time, if available.

id

stringRequired

The unique id of this stream.

roomSessionId

stringRequired

The id of the room session associated to this stream.

startedAt

DateRequired

Start time, if available.

state

"streaming" | "completed"Required

Current state of the stream.

url

stringRequired

The RTMP URL of the stream.

Methods

stop

stop(): Promise<void>

Stops the stream.

Returns

Promise<void>

Example

await stream.stop();

addCamera

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

addCamera

addCamera(opts): Promise<RoomSessionDevice> - See RoomSessionDevice documentation for more details.

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

Parameters

opts

MediaTrackConstraints & { 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> - See RoomSessionDevice documentation for more details.

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

addDevice

addDevice(opts): Promise<RoomSessionDevice> - See RoomSessionDevice documentation for more details.

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

opts

object

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.

audio

boolean | MediaTrackConstraints

Audio constraints.

autoJoin

boolean

Whether the device should automatically join the room. Default: true.

video

boolean | MediaTrackConstraints

Video constraints.

Returns

Promise<RoomSessionDevice> - See RoomSessionDevice documentation for more details.

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

addMicrophone

addMicrophone(opts): Promise<RoomSessionDevice> - See RoomSessionDevice documentation for more details.

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

Parameters

opts

MediaTrackConstraints & { 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> - See RoomSessionDevice documentation for more details.

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id 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 roomSession.audioMute();

Muting the microphone of another participant:

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

audioUnmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id 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 roomSession.audioUnmute();

Unmuting the microphone of another participant:

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

createScreenShareObject

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

createScreenShareObject(opts): Promise<RoomSessionScreenShare> - See RoomSessionScreenShare documentation for more details.

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

opts

object

Object containing the parameters of the method.

audio

boolean | MediaTrackConstraints

Audio constraints to use when joining the room. Default: true.

autoJoin

boolean

Whether the screen share object should automatically join the room.

video

boolean | MediaTrackConstraints

Video constraints to use when joining the room. Default: true.

Returns

Promise<RoomSessionScreenShare> - See RoomSessionScreenShare documentation for more details.

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id 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 roomSession.deaf();

Making another participant deaf:

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

deleteMemberMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

deleteMemberMeta

deleteMemberMeta(params): Promise<void>

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

Parameters

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the current member.

keys

string[]

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

deleteMeta

deleteMeta(keys): Promise<void>

Deletes the specified keys from the metadata for this RoomSession.

Parameters

keys

string[]

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

demote

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

demote

demote(params): Promise<void>

Demotes a participant from “member” to “audience”. See join and promote.

Parameters

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the current member.

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>

Permissions

room.member.demote

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

Example

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

destroy

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

destroy

destroy(): void

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

Returns

void

Events

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

The RoomSession object emits the events listed below. You can work with these events using the following methods:

on\ \ Subscribe to an event once\ \ Subscribe to an event once off\ \ Unsubscribe from an event removeAllListeners\ \ Remove all event listeners

Events

camera.disconnected

camera.disconnected(event)

A camera device was disconnected.

Properties

event

object

Event object

event.label

string

Label for the camera that was disconnected.

event.deviceId

string

Device Id for the camera that was disconnected.

camera.updated

camera.updated(event)

layout.changed(event)

VideoLayoutLayer[]

Array containing information on all the layers in the current layout.

media.connected

media.connected

New media has been connected. There is no payload, as this event is used to troubleshoot advanced use cases when hooking into the media connection.

media.disconnected

media.disconnected

Media has been disconnected from the session. There is no payload, as this event is used to troubleshoot advanced use cases when hooking into the media connection.

media.reconnecting

media.reconnecting

Media is attempting to reconnect to the session. There is no payload, as this event is used to troubleshoot advanced use cases when hooking into the media connection.

member.demoted

member.demoted(event)

A member has been demoted to audience, for example using demote.

member.joined(event)

member.left(event)

string

The member type, either audience or member.

member.promoted

member.promoted(event)

An audience participant has been promoted to member, for example using promote.

member.talking(event)

boolean

Whether the member is speaking. A true value indicates the member has started speaking, while a false value indicates the member has stopped.

member.updated

member.updated(event)

string

Id for the room that the updated member is in.

event.member.type

string

The member type, either audience or member.

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

The set of members or one or more properties of a member have changed.

Properties

event

object

Event object

event.members

object[]

A list of current members with the current values of their updatable properties as listed in the getMembers method.

microphone.disconnected

microphone.disconnected(event)

A microphone device was disconnected.

Properties

event

object

Event object

event.label

string

Label for the microphone that was disconnected.

event.deviceId

string

Device Id for the microphone that was disconnected.

microphone.updated

microphone.updated(event)

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

room.audience_count(event)

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

Audience members joining and leaving trigger this event.

Properties

event

object

Event object

event.room_session_id

string

Id of the room session.

event.room_id

string

Id of the room.

event.total

number

Total number of audience members.

room.joined

room.joined(event)

boolean

Whether logos are visible in participant name banners.

event.room_session.members

object[]

A list of current members with the current values of their updatable properties as listed in the getMembers method.

room.left(event)

The current client left the room session.

Properties

event

object

Event object

event.reason

string

Reason client left the session. Possible values are RECONNECTION_ATTEMPT_TIMEOUT and undefined.

room.updated

room.updated(event)

The properties of the room have been updated.

Properties

event

object

Event object

event.room_session_id

string

Id for the room session that was updated.

event.room_id

string

Id for the room that was updated.

event.room

object

Information on the room that was updated.

event.room.updated

string[]

Which room properties were updated.

event.room.room_session_id

string

Id for the room session that was updated.

event.room.room_id

string

Id for the room that was updated.

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, if 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
  }
}

speaker.disconnected

speaker.disconnected(event)

A speaker device was disconnected.

Properties

event

object

Event object

event.label

string

Label for the speaker that was disconnected.

event.deviceId

string

Device Id for the speaker that was disconnected.

speaker.updated

speaker.updated(event)

stream.ended(stream)

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

Properties

stream

RoomSessionStream

The stream object. See RoomSessionStream.

stream.started

stream.started(stream)

A new stream started.

Properties

stream

RoomSessionStream

The stream object. See RoomSessionStream.

getLayouts

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getLayouts

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

Returns a list of available layouts for the room.

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

getMemberMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getMemberMeta

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

Returns the metadata assigned to the specified member.

Parameters

params

object

Object containing the parameters of the method.

memberId

string

Id of the member for which to obtain the metadata. If omitted, refers to the current member.

Returns

Promise<{ meta: Object }>

Example

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

getMembers

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getMembers

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

Returns a list of members currently in the room.

Returns

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"\
  }\
]
}

getMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getPlaybacks

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

Obtains a list of recordings for the current room session.

Returns

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

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getRecordings

getRecordings(): Promise<{ recordings: RoomSessionRecording}> - See RoomSessionRecording documentation for more details.

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

Permissions

room.recording

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

Example

const recs = await roomSession.getRecordings();
if (recs.recordings.length > 0) {
  console.log(recs.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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

getStreams

getStreams(): Promise<{ streams: RoomSessionStream}> - See RoomSessionStream documentation 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 documentation for more details.

Permissions

room.stream

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

Example

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

hangupAll

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

hangupAll

hangupAll(): Promise<void>

Hangs up the active calls in the RoomSession and will send a REJECT_ALL message to the rejected participant(s).

REJECT_ALL message

When a participant is rejected, the causeCode will be 825 and the cause will be REJECT_ALL. Below is an example of the JSON response when a participant is rejected:

{
  "jsonrpc": "2.0",
  "id": "cbcbe519-39db-4585-9a89-f0e1fdf036e9",
  "result": {
    "node_id": "105f2e4f-69a7-4907-bc01-36399fe34bdd@west-us",
    "result": {
      "jsonrpc": "2.0",
      "id": "f4a9c207-e1de-49bb-98bf-e8f4b243c4e0",
      "result": {
        "callID": "fc456094-6f0e-44b5-8209-7a474cac7ef7",
        "message": "CALL ENDED",
        "causeCode": 825,
        "cause": "REJECT_ALL"
      }
    },
    "code": "200"
  }
}

Returns

Promise<void>

Example

await roomSession.hangupAll();

hideVideoMuted

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

hideVideoMuted(): Promise<void>

Deprecated. Use setHideVideoMuted instead.

Do not show muted videos in the room layout.

Returns

Promise<void>

Permissions

room.hide_video_muted: to set the hand raise priority

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

Example

await roomSession.hideVideoMuted();

join

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

join

join(): Promise<RoomSession>

Joins the room session.

Promise<RoomSession>

leave

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

leave

leave(): Promise<void>

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

Returns

Promise<void>

lock

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

lock

lock(params): Promise<void>

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

Returns

Promise<void>

Example

await roomSession.lock();

off

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

off

off(event, fn?)

Remove an event handler.

Parameters

Name	Type	Description
`event`	`string`	Name of the event. See the list of events.
`fn?`	Function	An event handler which had been previously attached.

on

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

on

on(event, fn)

Attaches an event handler to the specified event.

Parameters

Name	Type	Description
`event`	`string`	Name of the event. See the list of events.
`fn`	Function	An event handler.

Example

In the below example, we are listening for the call.state event and logging the current call state to the console. This means this will be triggered every time the call state changes.

call.on("call.state", (call) => {
    console.log("call state changed:", call.state);
});

once

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

once

once(event, fn)

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

Parameters

Name	Type	Description
`event`	`string`	Name of the event. See the list of events.
`fn`	Function	An event handler.

play

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

play

play(params): Promise<RoomSessionPlayback> - See RoomSessionPlayback documentation 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

params

object

Object containing the parameters of the method.

url

string

The url (http, https, rtmp, rtmps) of the stream to reproduce.

volume

number

The audio volume at which to play the stream. Values range from -50 to 50, with a default of 0.

seekPosition

number

The starting timecode in milliseconds for playback. Defaults to 0.

positions

VideoPositions

Positions to assign as soon as the playback starts. You can use the special keyword "self" to refer to the id of the playback.

layout

string

Layout to change to when the playback starts.

Returns

Promise<RoomSessionPlayback> - See RoomSessionPlayback documentation for more details.

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

promote

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

promote

promote(params): Promise<void>

Promotes a participant from “audience” to “member”. See join and demote.

Parameters

params

object

Object containing the parameters of the method.

memberId

string

Id of the audience participant to promote.

joinAudioMuted

boolean

Force the member’s audio to be muted right after the promotion.

joinVideoMuted

boolean

Force the member’s video to be muted right after the promotion.

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.

meta

Record<string, unknown toc={true}>

Metadata to assign to the member.

permissions

string[]

List of permissions to grant when the Audience participant will become a Member.

Returns

Promise<void>

Permissions

room.member.promote

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

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

removeAllListeners

removeAllListeners(event?)

Detaches all event listeners for the specified event.

Parameters

Name	Type	Description
`event?`	`string`	Name of the event (leave this undefined to detach listeners for all events). See the list of events.

removeAllMembers

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

removeMember

removeMember(params): Promise<void>

Removes a specific participant from the room.

Parameters

params

object

Object containing the parameters of the method.

memberId

string

Id 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 roomSession.removeMember({ memberId: id });

sendDigits

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

sendDigits

sendDigits(string): Promise<void>

Sends DTMF digits to the room. The digits will be sent to the RoomSession.

Parameters

dtmf

string

The digits to send. Only the characters 0-9, A-D``*, and # are allowed.

Returns

Promise<void>

Example

await roomSession.sendDigits("1");

setHideVideoMuted

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

value

boolean

Whether 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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the default device in the local client.

value

number

Desired 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 roomSession.setInputSensitivity({ value: 80 });

Setting the input sensitivity of another participant:

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

setInputVolume

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id of the member for which to set input volume. If omitted, sets the volume of the default device in the local client.

volume

number

Desired 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 roomSession.setInputVolume({ volume: -10 });

Setting the microphone volume of another participant:

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

setLayout

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setLayout

setLayout(params): Promise<void>

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

Parameters

params

object

Object containing the parameters of the method.

name

string

Name of the layout.

positions

VideoPositions

Positions 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 roomSession.setLayout({ name: "6x6" });

setLocalStream

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setLocalStream

setLocalStream(stream): void

Replaces the current local media stream with the one specified as a parameter.

Parameters

stream

MediaStream

The media stream to use.

Returns

void

Example

Drawing and streaming the picture of a face:

const canvas = document.createElement("canvas");
const ctx = canvas.getContext("2d");

// Set canvas size
canvas.width = 400;
canvas.height = 400;

// Draw circle
ctx.beginPath();
ctx.arc(200, 200, 150, 0, 2 * Math.PI);
ctx.fillStyle = "lightblue";
ctx.fill();

// Draw eyes
ctx.beginPath();
ctx.arc(150, 150, 30, 0, 2 * Math.PI);
ctx.arc(250, 150, 30, 0, 2 * Math.PI);
ctx.fillStyle = "black";
ctx.fill();

// Get the media stream
const stream = canvas.captureStream(25); // 25 FPS

// Stream the canvas
await roomSession.setLocalStream(stream);

setMemberMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the default device in the local client.

meta

Record<string, unknown toc={true}>

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setMemberPosition

setMemberPosition(params): Promise<void>

Assigns a position in the layout to the specified member.

Parameters

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the current member.

position

VideoPosition

Position 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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

meta

Record<string, unknown toc={true}>

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the default device in the local client.

volume

number

Desired 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 roomSession.setOutputVolume({ volume: -10 });

Setting the output volume of another participant:

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

setPositions

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setPositions

setPositions(params): Promise<void>

Assigns a position in the layout for multiple members.

Parameters

params

object

Object containing the parameters of the method.

positions

VideoPositions

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

setPrioritizeHandraise

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setPrioritizeHandraise

setPrioritizeHandraise(params): Promise<boolean>

Sets whether to prioritize hand-raise’s or not.

Parameters

param

boolean

Whether to raise or lower the hand. 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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

setRaisedHand

setRaisedHand(params): Promise<void>

Sets the raised hand status for the current member.

Parameters

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the current member.

raised

boolean

Whether 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 roomSession.setRaisedHand({
  memberId: "de550c0c-3fac-4efd-b06f-b5b86...",
  raised: false
});

showVideoMuted

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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 roomSession.showVideoMuted();

startRecording

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

startRecording

startRecording(): Promise<RoomSessionRecording> - See RoomSessionRecording documentation 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 documentation for more details.

Permissions

room.recording

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

Example

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

startScreenShare

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

startScreenShare

startScreenShare(opts): Promise<RoomSessionScreenShare> - See RoomSessionScreenShare documentation for more details.

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

Parameters

opts

object

Object containing the parameters of the method.

audio

boolean | MediaTrackConstraints

Audio constraints to use when joining the room. Default: false.

autoJoin

boolean

Whether the screen share object should automatically join the room. Default: true.

layout

string

Layout to switch to as soon as the screen share joins the room.

positions

VideoPositions

Layout positions to assign as soon as the screen share joins the room.

video

boolean | MediaTrackConstraints

Video constraints to use when joining the room. Default: true.

Returns

Promise<RoomSessionScreenShare> - See RoomSessionScreenShare documentation for more details.

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

startStream

startStream(): Promise<RoomSessionStream> - See RoomSessionStream documentation 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

params

object

Object containing the parameters of the method.

url

string

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

Returns

Promise<RoomSessionStream> - See RoomSessionStream documentation for more details.

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 roomSession.startStream({ url: "rtmp://example.com" });

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

undeaf

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id 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 roomSession.undeaf();

Undeaf another participant:

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

unlock

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

updateCamera

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateCamera

updateCamera(constraints): Promise<void>

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

Parameters

constraints

MediaTrackConstraints

Specify 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 roomSession.updateCamera({
  deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg=",
});

updateMemberMeta

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id of the member to affect. If omitted, affects the current member.

meta

Record<string, unknown toc={true}>

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

meta

Record<string, unknown toc={true}>

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

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

updateMicrophone

updateMicrophone(constraints): Promise<void>

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

Parameters

constraints

MediaTrackConstraints

Specify 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 roomSession.updateMicrophone({
  deviceId: "/o4ZeWzroh+8q0Ds/CFfmn9XpqaHzmW3L/5ZBC22CRg=",
});

updateSpeaker

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

opts

object

Object containing the parameters of the method.

deviceId

string

Id of the new speaker device.

Returns

Promise<undefined>

Example

Replaces the current speaker:

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

videoMute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id 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 roomSession.videoMute();

Muting the video of another participant:

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

videoUnmute

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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

params

object

Object containing the parameters of the method.

memberId

string

Id 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 roomSession.videoUnmute();

Unmuting the video of another participant:

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

Video ​

Overview ​

Reading order ​

Two patterns the SDK relies on ​

1. Subscribe to the participant, not the call, for member state ​

2. BehaviorSubjects emit synchronously on subscribe ​

A real reference app ​

Reference ​

autoMuteVideoOnHidden ​

Parameters ​

value ​

Examples ​

defaultVideoConstraints ​

Parameters ​

value ​

Examples ​

inputVideoConstraints ​

Parameters ​

value ​

Examples ​

preferredVideoCodecs ​

Parameters ​

value ​

Examples ​

preferredVideoInput ​

Parameters ​

value ​

Examples ​

receiveVideo ​

Parameters ​

value ​

Examples ​

muteVideo ​

Examples ​

See ​

toggleMuteVideo ​

Returns ​

Examples ​

See ​

unmuteVideo ​

Returns ​

Examples ​

See ​

videoMuted$ ​

videoMuted ​

Examples ​

addVideoInputDevice ​

Parameters ​

__namedParameters ​

Returns ​

Examples ​

muteVideo ​

Returns ​

Examples ​

selectVideoInputDevice ​

Parameters ​

device ​

options ​

Returns ​

Examples ​

setVideoInputDeviceConstraints ​

Parameters ​

constraints ​

Returns ​

Examples ​

toggleMuteVideo ​

Returns ​

Inherited from ​

Examples ​

unmuteVideo ​

Returns ​

Examples ​

videoMuted$ ​

Inherited from ​

videoMuted ​

Inherited from ​

Examples ​

disableVideoInput ​

Examples ​

enableVideoInput ​

Video

Overview

Reading order

Two patterns the SDK relies on

1. Subscribe to the participant, not the call, for member state

2. BehaviorSubjects emit synchronously on subscribe

A real reference app

Reference

autoMuteVideoOnHidden

Parameters

value

Examples

defaultVideoConstraints

Parameters

value

Examples

inputVideoConstraints

Parameters

value

Examples

preferredVideoCodecs

Parameters

value

Examples

preferredVideoInput

Parameters

value

Examples

receiveVideo

Parameters

value

Examples

muteVideo

Examples

See

toggleMuteVideo

Returns

Examples

See

unmuteVideo

Returns

Examples

See

videoMuted$

videoMuted

Examples

addVideoInputDevice

Parameters

__namedParameters

Returns

Examples

muteVideo

Returns

Examples

selectVideoInputDevice

Parameters

device

options

Returns

Examples

setVideoInputDeviceConstraints

Parameters

constraints

Returns

Examples

toggleMuteVideo

Returns

Inherited from

Examples

unmuteVideo

Returns

Examples

videoMuted$

Inherited from

videoMuted

Inherited from

Examples

disableVideoInput

Examples

enableVideoInput