Skip to main content
Version: Current

Room Actions

  • os.getRoomOptions(roomName: string): Promise<GetRoomOptionsResult>​

    Attempts to get the current options for the given chat room. Useful for determining the current state of the local video (camera), audio (microphone), and screen streams. Returns a promise that resolves with an object that contains the information.

    The first parameter is a string and is the name of the room that the options should be retrieved for.

    Examples
    Get the current options for a room
    const result = await os.getRoomOptions("myChat");
    if (result.success) {
        os.toast("Room options: " + JSON.stringify(result.options));
    } else {
        os.toast("Failed to get the options: " + result.errorMessage);
    }

  • os.getRoomRemoteOptions(roomName: string, remoteId: string): Promise<GetRoomRemoteOptionsResult>​

    Attempts to get the current options for the specified remote user in the specified room. Returns a promise that resolves with an object that contains information about the remote user.

    This function is useful for determining if the user is streaming audio or video and how good their network connection is.

    The first parameter is a string and is the name of the room.

    The second parameter is a string and is the ID of the remote user whose options should be retrieved. Remote IDs can be obtained via the @onRoomRemoteJoined listener.

    Examples
    Get the options for a remote user
    const result = await os.getRoomRemoteOptions("myChat", "myRemote");
    if (result.success) {
        os.toast("Remote options: " + JSON.stringify(result.options));
    } else {
        os.toast("Failed to get the options: " + result.errorMessage);
    }

  • os.getRoomTrackOptions(roomName: string, address: string): Promise<GetRoomTrackOptionsResult>​

    Attempts to get the current options for the specified audio/video track in the specified room. Returns a promise that resolves with an object that contains the information.

    This function is useful for getting basic information about a track, like the video aspect ratio or if it is sourced from a camera or the screen.

    The first parameter is a string and is the name of the room.

    The second parameter is a string and is the address of the audio/video track. Track addresses can be obtained via the @onRoomTrackSubscribed listener.

    Examples
    Get the options for a track
    const result = await os.getRoomTrackOptions("myChat", "myTrack");
    if (result.success) {
        os.toast("Track options: " + JSON.stringify(result.options));
    } else {
        os.toast("Failed to get the options: " + result.errorMessage);
    }

  • os.joinRoom(roomName: string, options?: RoomJoinOptions): Promise<JoinRoomResult>​

    Attempts to join the given meeting room using the given options. Returns a promise that resolves with an object that indicates whether the operation was successful.

    Triggers the @onRoomJoined listener once the room has been successfully joined.

    Additionally, the following listeners will be triggered when the relevent events occur in the chat room:

    The first parameter is a string and is the name of the room that should be joined. Any valid string can be used as a room name. Additionally, rooms are shared across instances.

    The second parameter is optional and is a RoomJoinOptions and is the additional options for joining the room.

    Examples
    Join the "myChat" room
    const result = await os.joinRoom("myChat");
    if (result.success) {
        os.toast("Joined the room!");
    } else {
        os.toast("Failed to join the room: " + result.errorMessage);
    }
    Join a room with the video stream disabled
    const result = await os.joinRoom("myChat", {
        video: false
    });
    if (result.success) {
        os.toast("Joined the room!");
    } else {
        os.toast("Failed to join the room: " + result.errorMessage);
    }

  • os.leaveRoom(roomName: string, options?: RecordActionOptions): Promise<LeaveRoomResult>​

    Attempts to exit the given room using the given options. Returns a promise that resolves with an object which indicates whether the operation was successful.

    Triggers the @onRoomLeave listener once the room has been left.

    The first parameter is a string and is the name of the room that should be exited.

    The second parameter is optional and is a RecordActionOptions and is the additional options for leaving the room.

    Examples
    Leave the "myChat" room
    const result = await os.leaveRoom("myChat");
    if (result.success) {
        os.toast("Left the room!");
    } else {
        os.toast("Failed to leave the room: " + result.errorMessage);
    }

  • os.setRoomOptions(roomName: string, options: Partial<RoomOptions>): Promise<SetRoomOptionsResult>​

    Attempts to set the options for the given chat room. Useful for enabling/disabling video, audio, and screensharing. Returns a promise that resolves with an object indicating if the operation was successful and what the current state of the room is.

    Triggers the @onRoomOptionsChanged and @onRoomTrackSubscribed/@onRoomTrackUnsubscribed listeners as needed for the specified changes.

    The first parameter is a string and is the name of the room that the options should be changed in.

    The second parameter is a Partial<RoomOptions> and is the options to set. Omitted properties remain unchanged.

    Examples
    Start screensharing
    const result = await os.setRoomOptions("myChat", {
        screen: true
    });
    if (result.success) {
        os.toast("Screensharing started!");
    } else {
        os.toast("Failed to start screensharing: " + result.errorMessage);
    }
    Mute the microphone
    const result = await os.setRoomOptions("myChat", {
        audio: false
    });
    if (result.success) {
        os.toast("Microphone muted!");
    } else {
        os.toast("Failed to mute microphone: " + result.errorMessage);
    }

  • os.setRoomTrackOptions(roomName: string, address: string, options: SetRoomTrackOptions): Promise<SetRoomTrackOptionsResult>​

    Attempts to set the current options for the specified audio/video track in the specified room. Returns a promise that resolves with an object that indicates whether the operation was successful.

    This function is useful for locally muting a track or setting the video quality you want it to stream at.

    The first parameter is a string and is the name of the room.

    The second parameter is a string and is the address of the audio/video track. Track addresses can be obtained via the @onRoomTrackSubscribed listener.

    The third parameter is a SetRoomTrackOptions and is the options that should be set for the track.

    Examples
    Stop streaming a track
    const result = await os.setRoomTrackOptions("myChat", "myTrack", {
        muted: true
    });
    if (result.success) {
        os.toast("Track muted!");
    } else {
        os.toast("Failed to mute the track: " + result.errorMessage);
    }
    Set the video quality on a track
    const result = await os.setRoomTrackOptions("myChat", "myTrack", {
        videoQuality: 'low'
    });
    if (result.success) {
        os.toast("Track video quality changed!");
    } else {
        os.toast("Failed to set video quality on the track: " + result.errorMessage);
    }