• Skip to Search
  • Skip to Content
  • Skip to Side Navigation
Getting StartedSDK ReferenceGlossary
  • Home
  • Getting Started
  • SDK Reference
  • Portal
  • How-To
  • Troubleshooting
  • FAQs
  • Reference
  • Glossary
REST API
Web SDK
Android SDK
iOS SDK
Unity SDK
React Native SDK
EdgeAuth SDK
  • Overview
  • Express API
    • Channel
    • Room
    • PCast™
  • Low-Level API
    • Room
    • Chat
    • PCast™
  • Examples
  • Release Notes

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.

Note: PCast™ must be initialized and started when invoking createRoomService so that a valid session ID is present.

Java
1import android.content.Context;
2
3import com.phenixrts.environment.android.AndroidContext;
4import com.phenixrts.pcast.PCast;
5import com.phenixrts.room.RoomService;
6import com.phenixrts.room.RoomServiceFactory;
7
8// IMPORTANT: Before accessing any of the static factories, make sure the context is passed to Phenix:
9final Context context = ...; // e.g. Activity.getApplication();
10AndroidContext.setContext(context);
11
12final PCast pcast = ...; // previously obtained
13final RoomService roomService = RoomServiceFactory.createRoomService(pcast);

Initializing Parameters

NameTypeDescription
pcast (required)PCastInstantiated PCast™ object. Must already be authenticated

RoomService

NameSignatureReturnsDescription
getRoomInfo(roomId, alias, callback)RoomSee Get Room Info
createRoom(room, callback)RoomSee Create a Room
joinRoom(roomId, alias, callback)RoomSee Join a Room
leaveRoom(callback)voidSee Leave a Room
destroyRoom(callback)voidSee Destroy a Room
getSelf()Observable of Member)Observable of self member
getObservableActiveRoom()Observable of Room)Observable of the active room

Instantiate Self Member Model

Before entering a room the RoomService must have a valid model of the Self member. The Self member model may be updated at any time by changing observable values and calling commitChanges. See Update Self Model.

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. This works whether or not you are currently in a room.

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.room.Member;
3import com.phenixrts.room.MemberRole;
4import com.phenixrts.room.RoomService;
5
6final RoomService roomService = ...; // previously obtained
7final Member selfMember = roomService.getSelf();
8
9selfMember.getObservableScreenName().setValue("My New Screen Name");
10selfMember.getObservableRole().setValue(MemberRole.AUDIENCE);
11
12// Commit changes to self if already in a room
13selfMember.commitChanges((RequestStatus status, String message) -> {
14 if (status == RequestStatus.OK) {
15 // Successfully updated self
16 } else {
17 // Handle error
18 }
19});

To undo uncommitted local changes, use reload:

Java
1import com.phenixrts.room.Member;
2import com.phenixrts.room.MemberRole;
3import com.phenixrts.room.RoomService;
4
5final RoomService roomService = ...; // previously obtained
6final Member selfMember = roomService.getSelf();
7
8selfMember.getObservableScreenName().setValue("My New Screen Name");
9selfMember.getObservableRole().setValue(MemberRole.AUDIENCE);
10
11// Decided to undo changes
12selfMember.reload();

Update Self Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation
messageStringError message, if applicable

Set Self Streams

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

Java
1import com.phenixrts.room.Member;
2import com.phenixrts.room.RoomService;
3import com.phenixrts.room.Stream;
4import com.phenixrts.room.StreamType;
5import com.phenixrts.room.TrackState;
6
7final RoomService roomService = ...; // previously obtained
8final Member selfMember = roomService.getSelf();
9
10final Stream selfStream = roomService.createStream(
11 "http://myuri.stream", StreamType.USER, TrackState.ENABLED, TrackState.ENABLED);
12
13selfMember.getObservableStreams().setValue(new Stream[] {selfStream});
14
15// Now commit changes

Set Self Streams Parameters

NameTypeDescription
uri (required)StringUnique identifier for stream.
type (required)StreamTypeType of stream - see Stream Types
audioState (required)TrackStateState of the audio track - see Stream Track States
videoState (required)TrackStateState of the video track - see Stream Track States

Get Room Info

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

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.room.Room;
3import com.phenixrts.room.RoomService;
4
5final RoomService roomService = ...; // previously obtained
6
7// Either provide alias or roomId, other can be null or empty
8final String roomId = "us-central#demo#exampleRoomId";
9final String alias = null;
10
11roomService.getRoomInfo(roomId, alias, (RoomService roomService, RequestStatus status, Room room) -> {
12 if (status == RequestStatus.OK) {
13 // Do something with room
14 } else {
15 // Handle error
16 }
17});

Get Room Info Parameters

NameTypeDescription
roomId (required)StringID of the room
alias (optional)StringAlternative to roomId - alias of the room
getRoomInfoCallback (required)RoomService.GetRoomInfoCallbackCallback with the status of the request and the room model

Get Room Info Callback Arguments

NameTypeDescription
roomServiceRoomServiceThe room service making the callback
statusRequestStatusThe status of the operation
roomRoomImmutable room object

Get Room Info Callback Status Codes

StatusDescription
okGet room info succeeded
not-foundGet room info failed. Room does not exist - verify room data or create the room
variesGet room info failed for other reasons

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.

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.room.Room;
3import com.phenixrts.room.RoomOptions;
4import com.phenixrts.room.RoomService;
5import com.phenixrts.room.RoomServiceFactory;
6import com.phenixrts.room.RoomType;
7
8final RoomService roomService = ...; // previously obtained
9
10final String roomName = "My Room Name";
11final String description = "Deep thoughts only";
12
13final RoomOptions roomOptions = RoomServiceFactory.createRoomOptionsBuilder()
14 .withName(roomName)
15 .withDescription(description)
16 .withType(RoomType.MULTI_PARTY_CHAT)
17 .buildRoomOptions();
18
19roomService.createRoom(
20 roomOptions,
21 (RoomService service, RequestStatus status, Room room) -> {
22 if (status == RequestStatus.OK) {
23 // Do something with room
24 } else {
25 // Handle error
26 }
27 });

Create Room Parameters

NameTypeDescription
options (required)RoomOptionsRoom creation options
callback (required)RoomService.CreateRoomCallbackCallback with the status of the request and the room model

Create Room Callback Arguments

NameTypeDescription
roomServiceRoomServiceThe room service making the callback
statusRequestStatusThe status of the operation
roomRoomImmutable room object

Create Room Callback Status Codes

StatusDescription
okCreate room succeeded. This can also mean that the room already existed
variesCreate room failed for other reasons

RoomOptionsBuilder

NameTypeDefaultDescription
withName (required)StringName of room
withType (required)RoomTypeRoom type
withAlias (optional)StringgeneratedRoom Alias
withDescription (optional)StringemptyRoom description
buildRoomOptionsnoneBuilds the RoomOptions

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.

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.room.Room;
3import com.phenixrts.room.RoomService;
4
5final RoomService roomService = ...; // previously obtained
6
7// Either provide alias or roomId, other can be null or empty
8final String roomId = null;
9final String alias = "exampleRoom";
10
11roomService.joinRoom(roomId, alias, (RoomService roomService, RequestStatus status, Room room) -> {
12 if (status == RequestStatus.OK) {
13 // Do something with room
14 } else {
15 // Handle error
16 }
17});

Join Room Parameters

NameTypeDescription
roomId (required)StringID of the room
alias (optional)StringAlternative to roomId - alias of the room
callback (required)RoomService.JoinRoomCallbackCallback with the status of the request and the room model

Join Room Callback Arguments

NameTypeDescription
roomServiceRoomServiceThe room service making the callback
statusRequestStatusThe status of the operation
roomRoomImmutable room object

Join Room Callback Status Codes

StatusDescription
okJoin room succeeded
not-foundJoin room failed. Room does not exist - create room first
variesJoin 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 accessing each member's streams whenever the list of members is updated. Remember: Since each observable behaves like a Behavior Rx Subject, your subscriber will always get called back immediately with the current value (in this case the list of members), see Observable.

Java
1import com.phenixrts.common.Disposable;
2import com.phenixrts.common.Observable;
3import com.phenixrts.common.RequestStatus;
4import com.phenixrts.room.Member;
5import com.phenixrts.room.Room;
6import com.phenixrts.room.RoomService;
7import com.phenixrts.room.Stream;
8
9final RoomService roomService = ...; // previously obtained
10
11final Observable<Room> observableActiveRoom = roomService.getObservableActiveRoom();
12
13// For this simple example, we assume that there is an active room.
14// In a production environment, this can return null if we have not currently joined a room. In that case
15// you would want to listen as a subscriber on the 'observableActiveRoom' for updates
16final Room activeRoom = observableActiveRoom.getValue();
17final Observable<Member[]> observableMembers = activeRoom.getObservableMembers();
18
19final Disposable subscription = observableMembers.subscribe((change) -> {
20 final Member[] currentMembers = (Member[])change;
21 for (Member member : currentMembers) {
22 final Stream[] currentStreams = member.getObservableStreams().getValue();
23 // Now do something with this member's streams
24 }
25});
26
27// The subscription will remain active for as long as 'subscription' is kept alive or not closed

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.

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.room.Room;
3import com.phenixrts.room.RoomService;
4
5final RoomService roomService = ...; // previously obtained
6
7final Room room = roomService.getObservableActiveRoom().getValue();
8
9room.getObservableDescription().setValue("My New Room Description");
10room.commitChanges((RequestStatus status, String message) -> {
11 if (status == RequestStatus.OK) {
12 // Successfully updated room
13 } else {
14 // Handle error (`message` may provide more information about what went wrong)
15 }
16});

Update Room Parameters

NameTypeDescription
callback (required)Room.CommitCallbackCallback with the status of the request

Update Room Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation
messageStringError message, if applicable

Update Room Callback Status Codes

StatusDescription
okUpdate room succeeded
variesUpdate room failed for other reasons

Leave a Room

Leave the current active room. Self is not modified.

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.room.Room;
3import com.phenixrts.room.RoomService;
4
5final RoomService roomService = ...; // previously obtained
6
7roomService.leaveRoom((RoomService roomService, RequestStatus status) -> {
8 if (status == RequestStatus.OK) {
9 // Successfully left room, no action required
10 } else {
11 // Handle error
12 }
13});

Leave Room Parameters

NameTypeDescription
callback (required)RoomService.LeaveRoomCallbackCallback with the status of the request

Leave Room Callback Arguments

NameTypeDescription
roomServiceRoomServiceThe room service making the callback
statusRequestStatusThe status of the operation

Leave Room Callback Status Codes

StatusDescription
okLeave room succeeded
variesLeave room failed for other reasons

Destroy a Room

Destroys the current active room assuming your self member has the permissions.

Java
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.room.Room;
3import com.phenixrts.room.RoomService;
4
5final RoomService roomService = ...; // previously obtained
6
7roomService.destroyRoom((RoomService roomService, RequestStatus status) -> {
8 if (status == RequestStatus.OK) {
9 // Successfully destroyed room, no action required
10 } else {
11 // Handle error
12 }
13});

Destroy Room Parameters

NameTypeDescription
callback (required)RoomService.DestroyRoomCallbackCallback with the status of the request

Destroy Room Callback Arguments

NameTypeDescription
roomServiceRoomServiceThe room service making the callback
statusRequestStatusThe status of the operation

Destroy Room Callback Status Codes

StatusDescription
okDestroy room succeeded
variesDestroy room failed for other reasons

Observe Room size

Subscribe to observable to receive periodic room size updates. The room size corresponds to the total number of members currently in the room, which does include audience members.

This is a so called cold observable, which means that you may not immediately receive an update. It also means that both getValue and setValue methods will cause a failure.

Updates will be provided for as long as the disposable reference is kept alive.

Java
1import com.phenixrts.common.Disposable;
2import com.phenixrts.room.ImmutableRoom;
3
4final ImmutableRoom room = ... // previously obtained
5
6final Disposable disposable = room.getObservableEstimatedSize().subscribe((change) -> {
7 final Long currentEstimatedRoomSize = (Long) change;
8 // E.g. update UI
9});

Room Model

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

ImmutableRoom

NameSignatureReturnsDescription
getRoomId()StringThe room ID
getObservableAlias()Observable(of String)Observable of room alias
getObservableName()Observable(of String)Observable of room name
getObservableDescription()Observable(of String)Observable of room description
getObservableType()Observable(of RoomType)Observable of room type
getObservableMembers()Observable(of Member[])Observable of array of visible members in the room
getObservableBridgeId()Observable(of String)Observable of room bridgeId
getObservablePin()Observable(of String)Observable of room pin
getObservableEstimatedSize()Observable(of Long)Observable of estimated room size. This is a cumulative count of all members in the room, including audience members

Room

Room extends ImmutableRoom

NameSignatureReturnsDescription
commitChanges(Room.CommitCallback)voidAttempts to update server room model with any changes made locally
reload()voidReverts all local changes to the server room model

Room Types

TypeDescription
RoomType.DIRECT_CHATOne to one chat
RoomType.MULTI_PARTY_CHATMany to many or few to many chat
RoomType.MODERATED_CHATModerated chat with integrated SIP Bridge for conferencing abilities (join by phone).
RoomType.TOWN_HALLChat with a few active participants or presenters and many audience or inactive participants
RoomType.CHANNELView only room with a single active member at a time. Broadcast content to many viewers.

Member

NameSignatureReturnsDescription
getSessionId()StringThe session ID of the member in the room
getObservableRole()Observable(of MemberRole)Observable of member role
getObservableState()Observable(of MemberState)Observable of member state
getObservableScreenName()Observable(of String)Observable of member screen name
getObservableStreams()Observable(of Stream[])Observable of array of streams belonging to the member
getObservableLastUpdate()Observable(of Date)Observable of utc timestamp
commitChanges(Member.CommitCallback)voidAttempts to update server member model with any changes made locally
reload()voidReverts all local changes to the server member model

Member Roles

RoleDescription
MemberRole.PARTICIPANTMember with streams and is visible to all members
MemberRole.AUDIENCEMember with no streams and is not visible to other members
MemberRole.PRESENTERPresenter participant member
MemberRole.MODERATORPrivileged participant member

Member States

RoleDescription
MemberState.ACTIVEMember is active
MemberState.PASSIVEMember is not active
MemberState.HAND_RAISEDMember is requesting to become active
MemberState.INACTIVEMember is not away
MemberState.OFFLINEMember has left the room

Stream

The stream object may be used to represent any value that will be shared between all members.

NameSignatureReturnsDescription
getUri()StringThe stream uri (may or may not be associated with phenix stream ID)
getType()StreamTypeThe stream type
getObservableAudioState()Observable(of TrackState)Observable of stream video state
getObservableVideoState()Observable(of TrackState)Observable of stream audio state

Stream Types

TypeDescription
StreamType.USERGeneral purpose stream
StreamType.PRESENTATIONPrivileged stream
StreamType.AUDIOAudio-only stream

Stream Track States

StateDescription
TrackState.ENABLEDTrack is enabled
TrackState.DISABLEDTrack is disabled
TrackState.ENDEDTrack has ended
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10