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.
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.
1 import android . content . Context ;
2
3 import com . phenixrts . environment . android . AndroidContext ;
4 import com . phenixrts . pcast . PCast ;
5 import com . phenixrts . room . RoomService ;
6 import com . phenixrts . room . RoomServiceFactory ;
7
8
9 final Context context = . . . ;
10 AndroidContext . setContext ( context ) ;
11
12 final PCast pcast = . . . ;
13 final RoomService roomService = RoomServiceFactory . createRoomService ( pcast ) ;
Initializing Parameters Copied URL Name Type Description pcast (required) PCast Instantiated PCast™ object. Must already be authenticated
Instantiate Self Member Model Copied URL 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 Copied URL 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.
1 import com . phenixrts . common . RequestStatus ;
2 import com . phenixrts . room . Member ;
3 import com . phenixrts . room . MemberRole ;
4 import com . phenixrts . room . RoomService ;
5
6 final RoomService roomService = . . . ;
7 final Member selfMember = roomService . getSelf ( ) ;
8
9 selfMember . getObservableScreenName ( ) . setValue ( "My New Screen Name" ) ;
10 selfMember . getObservableRole ( ) . setValue ( MemberRole . AUDIENCE ) ;
11
12
13 selfMember . commitChanges ( ( RequestStatus status , String message ) -> {
14 if ( status == RequestStatus . OK ) {
15
16 } else {
17
18 }
19 } ) ;
To undo uncommitted local changes, use reload:
1 import com . phenixrts . room . Member ;
2 import com . phenixrts . room . MemberRole ;
3 import com . phenixrts . room . RoomService ;
4
5 final RoomService roomService = . . . ;
6 final Member selfMember = roomService . getSelf ( ) ;
7
8 selfMember . getObservableScreenName ( ) . setValue ( "My New Screen Name" ) ;
9 selfMember . getObservableRole ( ) . setValue ( MemberRole . AUDIENCE ) ;
10
11
12 selfMember . reload ( ) ;
Update Self Callback Arguments Copied URL Name Type Description status RequestStatus The status of the operation message String Error message, if applicable
Set Self Streams Copied URL The self model must have at least one stream when joining the room as any member role besides Audience.
1 import com . phenixrts . room . Member ;
2 import com . phenixrts . room . RoomService ;
3 import com . phenixrts . room . Stream ;
4 import com . phenixrts . room . StreamType ;
5 import com . phenixrts . room . TrackState ;
6
7 final RoomService roomService = . . . ;
8 final Member selfMember = roomService . getSelf ( ) ;
9
10 final Stream selfStream = roomService . createStream (
11 "http://myuri.stream" , StreamType . USER , TrackState . ENABLED , TrackState . ENABLED ) ;
12
13 selfMember . getObservableStreams ( ) . setValue ( new Stream [ ] { selfStream } ) ;
14
15
Set Self Streams Parameters Copied URL Name Type Description uri (required) String Unique identifier for stream. type (required) StreamType Type of stream - see Stream Types audioState (required) TrackState State of the audio track - see Stream Track States videoState (required) TrackState State of the video track - see Stream Track States
Get room info with the provided room details without joining the room.
1 import com . phenixrts . common . RequestStatus ;
2 import com . phenixrts . room . Room ;
3 import com . phenixrts . room . RoomService ;
4
5 final RoomService roomService = . . . ;
6
7
8 final String roomId = "us-central#demo#exampleRoomId" ;
9 final String alias = null ;
10
11 roomService . getRoomInfo ( roomId , alias , ( RoomService roomService , RequestStatus status , Room room ) -> {
12 if ( status == RequestStatus . OK ) {
13
14 } else {
15
16 }
17 } ) ;
Get Room Info Parameters Copied URL Name Type Description roomId (required) String ID of the room alias (optional) String Alternative to roomId - alias of the room getRoomInfoCallback (required) RoomService.GetRoomInfoCallback Callback with the status of the request and the room model
Get Room Info Callback Arguments Copied URL Name Type Description roomService RoomService The room service making the callback status RequestStatus The status of the operation room Room Immutable room object
Get Room Info Callback Status Codes Copied URL Status Description ok Get room info succeeded not-found Get room info failed. Room does not exist - verify room data or create the room varies Get room info failed for other reasons
Create a Room (deprecated) Copied URL 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.
1 import com . phenixrts . common . RequestStatus ;
2 import com . phenixrts . room . Room ;
3 import com . phenixrts . room . RoomOptions ;
4 import com . phenixrts . room . RoomService ;
5 import com . phenixrts . room . RoomServiceFactory ;
6 import com . phenixrts . room . RoomType ;
7
8 final RoomService roomService = . . . ;
9
10 final String roomName = "My Room Name" ;
11 final String description = "Deep thoughts only" ;
12
13 final RoomOptions roomOptions = RoomServiceFactory . createRoomOptionsBuilder ( )
14 . withName ( roomName )
15 . withDescription ( description )
16 . withType ( RoomType . MULTI_PARTY_CHAT )
17 . buildRoomOptions ( ) ;
18
19 roomService . createRoom (
20 roomOptions ,
21 ( RoomService service , RequestStatus status , Room room ) -> {
22 if ( status == RequestStatus . OK ) {
23
24 } else {
25
26 }
27 } ) ;
Create Room Parameters Copied URL Name Type Description options (required) RoomOptions Room creation options callback (required) RoomService.CreateRoomCallback Callback with the status of the request and the room model
Create Room Callback Arguments Copied URL Name Type Description roomService RoomService The room service making the callback status RequestStatus The status of the operation room Room Immutable room object
Create Room Callback Status Codes Copied URL Status Description ok Create room succeeded. This can also mean that the room already existed varies Create room failed for other reasons
RoomOptionsBuilder Copied URL Name Type Default Description withName (required) String Name of room withType (required) RoomType Room type withAlias (optional) String generated Room Alias withDescription (optional) String empty Room description buildRoomOptions none Builds the RoomOptions
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.
1 import com . phenixrts . common . RequestStatus ;
2 import com . phenixrts . room . Room ;
3 import com . phenixrts . room . RoomService ;
4
5 final RoomService roomService = . . . ;
6
7
8 final String roomId = null ;
9 final String alias = "exampleRoom" ;
10
11 roomService . joinRoom ( roomId , alias , ( RoomService roomService , RequestStatus status , Room room ) -> {
12 if ( status == RequestStatus . OK ) {
13
14 } else {
15
16 }
17 } ) ;
Join Room Parameters Copied URL Name Type Description roomId (required) String ID of the room alias (optional) String Alternative to roomId - alias of the room callback (required) RoomService.JoinRoomCallback Callback with the status of the request and the room model
Join Room Callback Arguments Copied URL Name Type Description roomService RoomService The room service making the callback status RequestStatus The status of the operation room Room Immutable room object
Join Room Callback Status Codes Copied URL Status Description ok Join room succeeded not-found Join room failed. Room does not exist - create room first varies Join room failed for other reasons
Subscribe to Room Member Streams Copied URL 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 .
1 import com . phenixrts . common . Disposable ;
2 import com . phenixrts . common . Observable ;
3 import com . phenixrts . common . RequestStatus ;
4 import com . phenixrts . room . Member ;
5 import com . phenixrts . room . Room ;
6 import com . phenixrts . room . RoomService ;
7 import com . phenixrts . room . Stream ;
8
9 final RoomService roomService = . . . ;
10
11 final Observable < Room > observableActiveRoom = roomService . getObservableActiveRoom ( ) ;
12
13
14
15
16 final Room activeRoom = observableActiveRoom . getValue ( ) ;
17 final Observable < Member [ ] > observableMembers = activeRoom . getObservableMembers ( ) ;
18
19 final Disposable subscription = observableMembers . subscribe ( ( change ) -> {
20 final Member [ ] currentMembers = ( Member [ ] ) change ;
21 for ( Member member : currentMembers ) {
22 final Stream [ ] currentStreams = member . getObservableStreams ( ) . getValue ( ) ;
23
24 }
25 } ) ;
26
27
Update Room Model Copied URL 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.
1 import com . phenixrts . common . RequestStatus ;
2 import com . phenixrts . room . Room ;
3 import com . phenixrts . room . RoomService ;
4
5 final RoomService roomService = . . . ;
6
7 final Room room = roomService . getObservableActiveRoom ( ) . getValue ( ) ;
8
9 room . getObservableDescription ( ) . setValue ( "My New Room Description" ) ;
10 room . commitChanges ( ( RequestStatus status , String message ) -> {
11 if ( status == RequestStatus . OK ) {
12
13 } else {
14
15 }
16 } ) ;
Update Room Parameters Copied URL Name Type Description callback (required) Room.CommitCallback Callback with the status of the request
Update Room Callback Arguments Copied URL Name Type Description status RequestStatus The status of the operation message String Error message, if applicable
Update Room Callback Status Codes Copied URL Status Description ok Update room succeeded varies Update room failed for other reasons
Leave the current active room. Self is not modified.
1 import com . phenixrts . common . RequestStatus ;
2 import com . phenixrts . room . Room ;
3 import com . phenixrts . room . RoomService ;
4
5 final RoomService roomService = . . . ;
6
7 roomService . leaveRoom ( ( RoomService roomService , RequestStatus status ) -> {
8 if ( status == RequestStatus . OK ) {
9
10 } else {
11
12 }
13 } ) ;
Leave Room Parameters Copied URL Name Type Description callback (required) RoomService.LeaveRoomCallback Callback with the status of the request
Leave Room Callback Arguments Copied URL Name Type Description roomService RoomService The room service making the callback status RequestStatus The status of the operation
Leave Room Callback Status Codes Copied URL Status Description ok Leave room succeeded varies Leave room failed for other reasons
Destroys the current active room assuming your self member has the permissions.
1 import com . phenixrts . common . RequestStatus ;
2 import com . phenixrts . room . Room ;
3 import com . phenixrts . room . RoomService ;
4
5 final RoomService roomService = . . . ;
6
7 roomService . destroyRoom ( ( RoomService roomService , RequestStatus status ) -> {
8 if ( status == RequestStatus . OK ) {
9
10 } else {
11
12 }
13 } ) ;
Destroy Room Parameters Copied URL Name Type Description callback (required) RoomService.DestroyRoomCallback Callback with the status of the request
Destroy Room Callback Arguments Copied URL Name Type Description roomService RoomService The room service making the callback status RequestStatus The status of the operation
Destroy Room Callback Status Codes Copied URL Status Description ok Destroy room succeeded varies Destroy room failed for other reasons
Observe Room size Copied URL 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.
1 import com . phenixrts . common . Disposable ;
2 import com . phenixrts . room . ImmutableRoom ;
3
4 final ImmutableRoom room = . . .
5
6 final Disposable disposable = room . getObservableEstimatedSize ( ) . subscribe ( ( change ) -> {
7 final Long currentEstimatedRoomSize = ( Long ) change ;
8
9 } ) ;
The following details technical specifications for the Room, Members, and Streams.
Name Signature Returns Description getRoomId () String The 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 extends ImmutableRoom
Name Signature Returns Description commitChanges (Room.CommitCallback) void Attempts to update server room model with any changes made locally reload () void Reverts all local changes to the server room model
Type Description RoomType.DIRECT_CHAT One to one chat RoomType.MULTI_PARTY_CHAT Many to many or few to many chat RoomType.MODERATED_CHAT Moderated chat with integrated SIP Bridge for conferencing abilities (join by phone). RoomType.TOWN_HALL Chat with a few active participants or presenters and many audience or inactive participants RoomType.CHANNEL View only room with a single active member at a time. Broadcast content to many viewers.
Name Signature Returns Description getSessionId () String The 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) void Attempts to update server member model with any changes made locally reload () void Reverts all local changes to the server member model
Role Description MemberRole.PARTICIPANT Member with streams and is visible to all members MemberRole.AUDIENCE Member with no streams and is not visible to other members MemberRole.PRESENTER Presenter participant member MemberRole.MODERATOR Privileged participant member
Role Description MemberState.ACTIVE Member is active MemberState.PASSIVE Member is not active MemberState.HAND_RAISED Member is requesting to become active MemberState.INACTIVE Member is not away MemberState.OFFLINE Member has left the room
The stream object may be used to represent any value that will be shared between all members.
Name Signature Returns Description getUri () String The stream uri (may or may not be associated with phenix stream ID) getType () StreamType The stream type getObservableAudioState () Observable(of TrackState) Observable of stream video state getObservableVideoState () Observable(of TrackState) Observable of stream audio state
Type Description StreamType.USER General purpose stream StreamType.PRESENTATION Privileged stream StreamType.AUDIO Audio-only stream
Stream Track States Copied URL State Description TrackState.ENABLED Track is enabled TrackState.DISABLED Track is disabled TrackState.ENDED Track has ended