Room Service

Set up a room and manage members, streams, and chat. Some typical uses for rooms include:

• Broadcast video chats between multiple people - few to many
• Large-scale video chat
• Conference calls with integrated video chat
• Real-time web channels for hosting media content. See View a Channel with the Express API
• Town hall meetings

To get started, create a room of the type associated with your need.

Initializing

First you will need to initialize a room service object. This object is used for creating, joining, and leaving a room. As well, use this object for managing the room you enter (active room), members, and the model of your Self.

var roomService = new sdk.RoomService(pcast);

Initializing Parameters

[object RoomService]

Instantiate Self Member Model

Before entering a room the [object RoomService] must have a model of the member you would like to join as, or Self. The Self member model may be updated at any time by changing observable values and calling commitChanges. See Updating Self Model.

roomService.start(role, screenName);

Instantiate Self Parameters

Update Self Model

Broadcast local changes of the Self model to all the members in the room. These changes are sent to our server which forwards the changes to all members in the room.

var self = roomService.getSelf();

self.getObservableScreenName.setValue('My New Screen Name');

// Commit changes to self if already in a room
self.commitChanges(function commitChangesCallback(error, response) {
  if (error) {
    // Handle error
  }

if (response.status !== 'ok' && response.status !== 'not-in-room') {
    // Handle error
  }

if (response.status === 'not-in-room') {
    // Changes not committed. Enter a room and the self model will automatically be committed.
  }

if (response.status === 'ok') {
    // Successfully updated self
  }
});

Update Self Callback Arguments

Update Self Callback Status Codes

Set Self Streams

The self model must have at least one stream when joining the room as any member role besides Audience.

var self = roomService.getSelf();
var selfStream = {
  uri: publisher.getStreamId(),
  type: 'User',
  audioState: 'TrackEnabled',
  videoState: 'TrackEnabled',
};

self.setStreams([selfStream]);

Set Self Parameters

Get Room Info

Get room info with the provided room details without joining the room.

roomService.getRoomInfo(
  roomId,
  alias,
  function getRoomInfoCallback(error, response) {
    if (error) {
      // Handle error
    }

if (response.status !== 'ok') {
      // Handle error
    }

// Successfully got room info
    if (response.status === 'ok' && response.room) {
      // Do something with room
    }
  }
);

Get Room Info Parameters

Get Room Info Callback Arguments

Get Room Info Callback Status Codes

Create a Room (deprecated)

Creation of Rooms from client SDKs is deprecated. Rooms should be created by the backend using the REST API.

Create a room with the provided details.

roomService.createRoom(room, function createRoomCallback(error, response) {
  if (error) {
    // Handle error
  }

if (response.status === 'already-exists') {
    // No action required
  }

if (response.status !== 'ok') {
    // Handle error
  }

// Successfully created room
  if (response.status === 'ok' && response.room) {
    // Do something with room
  }
});

Create Room Parameters

Room Options

Create Room Callback Arguments

Create Room Callback Status Codes

Join a Room

Join a room with the Self model. After successfully joining a room that room becomes the active room and can be returned via the getObservableActiveRoom method.

roomService.enterRoom(
  roomId,
  alias,
  function enterRoomCallback(error, response) {
    if (error) {
      // Handle error
    }

if (response.status === 'not-found') {
      // Handle room not found - createRoom
    }

if (response.status !== 'ok') {
      // Handle error
    }

// Successfully entered room
    if (response.status === 'ok' && response.room) {
      // Do something with room model - now the active room
    }
  }
);

Join Room Parameters

Join Room Callback Arguments

Join Room Callback Status Codes

Subscribe to Room Member Streams

After entering a room you may use the active room to get the observable members and associated metadata. Here we provide an example for parsing the stream ID associated with the member stream's uri.

var observableActiveRoom = roomService.getObservableActiveRoom();
var activeRoom = observableActiveRoom.getValue();
var membersObservable = activeRoom.getObservableMembers();
var pcastStreamURIPrefix = 'pcast://phenixp2p.com/';

membersObservable.subscribe(function (members) {
  members.forEach(function (member) {
    var memberStreams = member.getObservableStreams().getValue();

memberStreams.forEach(function (stream) {
      // Subscribe if its a PCast stream
      if (stream.uri.indexOf(pcastStreamURIPrefix) === 0) {
        var streamId = stream.uri.substring(
          pcastStreamURIPrefix.length,
          stream.uri.length
        );

// subscribe with pcast.subscribe
      }
    });
  });
});

Update Room Model

Broadcast local changes of the Room model to all the members in the room. These changes are sent to our server which forwards the changes to all members in the room.

var room = roomService.getObservableActiveRoom().getValue();

room.getObservableDescription().setValue('My New Room Description');

// Commit changes to self if already in a room
room.commitChanges(function commitChangesCallback(error, response) {
  if (error) {
    // Handle error
  }

if (response.status !== 'ok' && response.status !== 'not-in-room') {
    // Handle error
  }

if (response.status === 'not-in-room') {
    // Changes not committed. Enter the room and then re-submit
  }

if (response.status === 'ok') {
    // Successfully updated room
  }
});

Update Room Parameters

Update Room Callback Arguments

Update Room Callback Status Codes

Leave a Room

Leave the current active room. Self is not modified.

roomService.leaveRoom(function leaveRoomCallback(error, response) {
  // No action required
});

Setting isForceLeaveRoom to false will delay the response to the callback until the backend confirms that the client has left the room.

const doNotForcefullyLeaveRoom = false;

roomService.leaveRoom(function leaveRoomCallback(error, response) {
  if (error) {
    // Handle error
  }

if (response.status === 'not-in-room') {
    // Do nothing
  }

if (response.status !== 'ok') {
    // Handle error
  }

// Successfully left room
  if (response.status === 'ok') {
    // No action required
  }
}, doNotForcefullyLeaveRoom);

Leave Room Parameters

Leave Room Callback Arguments

Update Room Callback Status Codes

Room Model

The following details technical specifications for the Room, Members, and Streams.

[object Room]

Room Types

[object Member]

Member Roles

Member States

[object Stream]

The stream object represent any stream resource that will be shared between all members. The simplest configuration would be to use a PCast™ StreamId as the streamUri. This associates streams published locally to the member and enables other room members to subscribe to that stream. See Subscribe to Room Member Streams.

Stream Types

Stream Track States