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.
JavaScript
varroomService=newsdk.RoomService(pcast);
Initializing Parameters
Name
Type
Description
pcast (required)
[object PCast]
Instantiated PCast™ object. Must already be authenticated
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.
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.
JavaScript
varself=roomService.getSelf();self.getObservableScreenName.setValue('My New Screen Name');// Commit changes to self if already in a roomself.commitChanges(functioncommitChangesCallback(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
Name
Type
Description
status
String
The status of the operation
Update Self Callback Status Codes
Status
Description
ok
Update self succeeded
not-in-room
Update self failed. Not currently in a room - Join a room and changes will automatically be committed
varies
Update self failed for other reasons
Set Self Streams
The self model must have at least one stream when joining the room as any member role besides Audience.
Create room failed. Room already exists - verify room data and either join or create a different room
varies
Create room failed for other reasons
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.
JavaScript
roomService.enterRoom(roomId,alias,functionenterRoomCallback(error, response) {if (error) {// Handle error }if (response.status==='not-found') {// Handle room not found - createRoom }if (response.status!=='ok') {// Handle error }// Successfully entered roomif (response.status==='ok'&&response.room) {// Do something with room model - now the active room } });
Join Room Parameters
Name
Type
Description
roomId (required)
String
ID of the room
alias (optional)
String
Alternative to roomId - alias of the room
enterRoomCallback (required)
Function
Callback with the status of the request and the room model
Join room failed. Room does not exist - create room first
varies
Join room failed for other reasons
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.
JavaScript
varobservableActiveRoom=roomService.getObservableActiveRoom();varactiveRoom=observableActiveRoom.getValue();varmembersObservable=activeRoom.getObservableMembers();varpcastStreamURIPrefix='pcast://phenixp2p.com/';membersObservable.subscribe(function (members) {members.forEach(function (member) {varmemberStreams=member.getObservableStreams().getValue();memberStreams.forEach(function (stream) {// Subscribe if its a PCast streamif (stream.uri.indexOf(pcastStreamURIPrefix) ===0) {varstreamId=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.
JavaScript
varroom=roomService.getObservableActiveRoom().getValue();room.getObservableDescription().setValue('My New Room Description');// Commit changes to self if already in a roomroom.commitChanges(functioncommitChangesCallback(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
Name
Type
Description
commitChangesCallback (required)
Function
Callback with the status of the request
Update Room Callback Arguments
Name
Type
Description
status
String
The status of the operation
Update Room Callback Status Codes
Status
Description
ok
Update room succeeded
not-in-room
Update room failed. Not currently in a room - Join a room first
varies
Update room failed for other reasons
Leave a Room
Leave the current active room. Self is not modified.
JavaScript
roomService.leaveRoom(functionleaveRoomCallback(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.
JavaScript
constdoNotForcefullyLeaveRoom=false;roomService.leaveRoom(functionleaveRoomCallback(error, response) {if (error) {// Handle error }if (response.status==='not-in-room') {// Do nothing }if (response.status!=='ok') {// Handle error }// Successfully left roomif (response.status==='ok') {// No action required }}, doNotForcefullyLeaveRoom);
Leave Room Parameters
Name
Type
Description
leaveRoomCallback (required)
Function
Callback with the status of the request
isForceLeaveRoom (optional)
Boolean
Indicates whether to skip waiting for confirmation. If isForceLeaveRoom is true then the leave request is sent and no response from backend is waited upon. By default isForceLeaveRoom is true.
Leave Room Callback Arguments
Name
Type
Description
status
String
The status of the operation
Update Room Callback Status Codes
Status
Description
ok
Leave room succeeded
not-in-room
Leave room failed. Not currently in a room. Do nothing
varies
Leave room failed for other reasons
Room Model
The following details technical specifications for the Room, Members, and Streams.
Observable of array of streams belonging to the member
getObservableLastUpdate
()
Observable(of number)
Observable of utc timestamp
getLastUpdate
()
Number
Current last update value of the member
setStreams
(streams)
void
Set member streams. To be used only on self member model
toJson
()
object
Returns member object with current observable values
commitChanges
()
void
Attempts to update server member model with any changes made locally
reload
()
void
Reverts all local changes to the server member model
Member Roles
Role
Description
Participant
Member with streams and is visible to all members
Audience
Member with no streams and is not visible to other members
Presenter
Presenter participant member
Moderator
Privileged participant member
Member States
Role
Description
Active
Member is active
Passive
Member is not active
HandRaised
Member is requesting to become active
Inactive
Member is not active
Offline
Member has left the room
[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.
Name
Signature
Returns
Description
getUri
()
string
The stream uri (may or may not be associated with phenix stream ID)