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: PhenixPCast must be initialized and started when invoking createRoomService
so that a valid session ID is present.
1 import PhenixSdk
2
3 let pcast : PhenixPCast = ...
4 let roomService = PhenixRoomServiceFactory . createRoomService ( pcast ) !
Initializing Parameters Copied URL Name Type Description pcast (required) PhenixPCast Instantiated PCast™ object. Must already be authenticated
PhenixRoomService Copied URL Instantiate Self Member Model Copied URL Before entering a room the PhenixRoomService 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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4 let selfMember = roomService . getSelf ( )
5
6 selfMember . getObservableScreenName ( ) . setValue ( "My New Screen Name" )
7 selfMember . getObservableRole ( ) . setValue ( NSNumber . init ( value : PhenixMemberRole . audience . rawValue ) )
8
9
10 selfMember . commitChanges ( { ( status : PhenixRequestStatus , message : String ? ) in
11 if status == . ok {
12
13 } else {
14
15 }
16 } )
To undo uncommitted local changes, use reload:
1 import PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4 let selfMember = roomService . getSelf ( )
5
6 selfMember . getObservableScreenName ( ) . setValue ( "My New Screen Name" )
7 selfMember . getObservableRole ( ) . setValue ( NSNumber . init ( value : PhenixMemberRole . audience . rawValue ) )
8
9
10 selfMember . reload ( )
Update Self Callback Arguments Copied URL Name Type Description status PhenixRequestStatus 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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4 let selfMember = roomService . getSelf ( )
5
6 let selfStream = roomService . createStream ( "http://myuri.stream" , . user , . enabled , . enabled )
7
8 selfMember . getObservableStreams ( ) . setValue ( [ selfStream ! ] )
9
10
Set Self Streams Parameters Copied URL Name Type Description uri (required) String Unique identifier for stream. type (required) PhenixStreamType Type of stream - see Stream Types audioState (required) PhenixTrackState State of the audio track - see Stream Track States videoState (required) PhenixTrackState State of the video track - see Stream Track States
Get room info with the provided room details without joining the room.
1 import PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4
5
6 let roomId = "us-central#demo#exampleRoomId"
7 let alias : String ? = nil
8
9 roomService . getRoomInfo (
10 roomId ,
11 alias ,
12 { ( roomService : PhenixRoomService ? , status : PhenixRequestStatus , room : PhenixRoom ? ) in
13 if status == . ok {
14
15 } else {
16
17 }
18 } )
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) Function Callback with the status of the request and the room model
Get Room Info Callback Arguments Copied URL Name Type Description roomService PhenixRoomService The room service making the callback status PhenixRequestStatus The status of the operation room PhenixRoom 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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4
5 let roomName = "My Room Name"
6 let description = "Deep thoughts only"
7
8 let roomOptions = PhenixRoomServiceFactory . createRoomOptionsBuilder ( )
9 . withName ( roomName )
10 . withDescription ( description )
11 . withType ( . multiPartyChat )
12 . buildRoomOptions ( )
13
14 roomService . createRoom (
15 roomOptions ,
16 { ( roomService : PhenixRoomService ? , status : PhenixRequestStatus , room : PhenixRoom ? ) in
17 if status == . ok {
18
19 } else {
20
21 }
22 } )
Create Room Parameters Copied URL Name Type Description options (required) PhenixRoomOptions Room creation options callback (required) Function Callback with the status of the request and the room model
Create Room Callback Arguments Copied URL Name Type Description roomService PhenixRoomService The room service making the callback status PhenixRequestStatus The status of the operation room PhenixRoom Immutable room object
Create Room Callback Status Codes Copied URL Status Description PhenixRequestStatusOk Create room succeeded. This can also mean that the room already existed varies Create room failed for other reasons
PhenixRoomOptionsBuilder Copied URL Name Type Default Description withName (required) String Name of room withType (required) PhenixRoomType Room type withAlias (optional) String generated Room Alias withDescription (optional) String empty Room description buildRoomOptions none Builds the PhenixRoomOptions
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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4
5
6 let roomId : String ? = nil
7 let alias = "exampleRoom"
8
9 roomService . joinRoom (
10 roomId ,
11 alias ,
12 { ( roomService : PhenixRoomService ? , status : PhenixRequestStatus , room : PhenixRoom ? ) in
13 if status == . ok {
14
15 } else {
16
17 }
18 } )
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) Function Callback with the status of the request and the room model
Join Room Callback Arguments Copied URL Name Type Description roomService PhenixRoomService The room service making the callback status PhenixRequestStatus The status of the operation room PhenixRoom 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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4
5 let observableActiveRoom = roomService . getObservableActiveRoom ( ) !
6
7
8
9
10 let activeRoom = observableActiveRoom . getValue ( ) !
11 let observableMembers = activeRoom . getObservableMembers ( ) !
12
13 let subscription = observableMembers . subscribe ( { ( change ) in
14 let currentMembers = change ? . value as ! [ PhenixMember ]
15 for member in currentMembers {
16 let currentStreams = member . getObservableStreams ( ) . getValue ( ) as ! [ PhenixStream ]
17
18 }
19 } )
20
21
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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4
5 let room = roomService . getObservableActiveRoom ( ) . getValue ( ) !
6
7 room . getObservableDescription ( ) . setValue ( "My New Room Description" )
8 room . commitChanges ( { ( status : PhenixRequestStatus , message : String ? ) in
9 if status == . ok {
10
11 } else {
12
13 }
14 } )
Update Room Parameters Copied URL Name Type Description callback (required) Function Callback with the status of the request
Update Room Callback Arguments Copied URL Name Type Description status PhenixRequestStatus 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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4
5 roomService . leaveRoom ( { ( roomService : PhenixRoomService ? , status : PhenixRequestStatus ) in
6 if status == . ok {
7
8 } else {
9
10 }
11 } )
Leave Room Parameters Copied URL Name Type Description callback (required) Function Callback with the status of the request
Leave Room Callback Arguments Copied URL Name Type Description roomService PhenixRoomService The room service making the callback status PhenixRequestStatus 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 PhenixSdk
2
3 let roomService : PhenixRoomService = ...
4
5 roomService . destroyRoom ( { ( roomService : PhenixRoomService ? , status : PhenixRequestStatus ) in
6 if status == . ok {
7
8 } else {
9
10 }
11 } )
Destroy Room Parameters Copied URL Name Type Description callback (required) Function Callback with the status of the request
Destroy Room Callback Arguments Copied URL Name Type Description roomService PhenixRoomService The room service making the callback status PhenixRequestStatus 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 PhenixSdk
2
3 let room : PhenixImmutableRoom = ...
4
5 let disposable = room . getObservableEstimatedSize ( ) . subscribe (
6 { ( change : PhenixObservableChange < NSNumber >? ) in
7 let currentEstimatedRoomSize = change ? . value . uintValue
8
9 } )
The following details technical specifications for the Room, Members, and Streams.
PhenixImmutableRoom Copied URL Name Signature Returns Description getRoomId () NSString The room ID getObservableAlias () Observable(of NSString) Observable of room alias getObservableName () Observable(of NSString) Observable of room name getObservableDescription () Observable(of NSString) Observable of room description getObservableType () Observable(of PhenixRoomType via NSNumber) Observable of room type getObservableMembers () Observable(of NSArray of PhenixMember) Observable of array of visible members in the room getObservableBridgeId () Observable(of NSString) Observable of room bridgeId getObservablePin () Observable(of NSString) Observable of room pin getObservableEstimatedSize () Observable(of size_t) Observable of estimated room size. This is a cumulative count of all members in the room, including audience members
PhenixRoom extends PhenixImmutableRoom
Name Signature Returns Description commitChanges (RoomCommitCallback) 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 PhenixRoomTypeDirectChat One to one chat PhenixRoomTypeMultiPartyChat Many to many or few to many chat PhenixRoomTypeModeratedChat Moderated chat with integrated SIP Bridge for conferencing abilities (join by phone). PhenixRoomTypeTownHall Chat with a few active participants or presenters and many audience or inactive participants PhenixRoomTypeChannel View only room with a single active member at a time. Broadcast content to many viewers.
Name Signature Returns Description getSessionId () NSString The session ID of the member in the room getObservableRole () Observable(of PhenixMemberRole via NSNumber) Observable of member role getObservableState () Observable(of PhenixMemberState via NSNumber) Observable of member state getObservableScreenName () Observable(of NSString) Observable of member screen name getObservableStreams () Observable(of NSArray of PhenixStream) Observable of array of streams belonging to the member getObservableLastUpdate () Observable(of NSDate) Observable of utc timestamp commitChanges (MemberCommitCallback) 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 PhenixMemberRoleParticipant Member with streams and is visible to all members PhenixMemberRoleAudience Member with no streams and is not visible to other members PhenixMemberRolePresenter Presenter participant member PhenixMemberRoleModerator Privileged participant member
Role Description PhenixMemberStateActive Member is active PhenixMemberStatePassive Member is not active PhenixMemberStateHandRaised Member is requesting to become active PhenixMemberStateInactive Member is not away PhenixMemberStateOffline 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 () NSString The stream uri (may or may not be associated with phenix stream id) getType () PhenixStreamType The stream type getObservableAudioState () Observable(of PhenixTrackState via NSNumber) Observable of stream video state getObservableVideoState () Observable(of PhenixTrackState via NSNumber) Observable of stream audio state
Type Description PhenixStreamTypeUser General purpose stream PhenixStreamTypePresentation Privileged stream PhenixStreamTypeAudio Audio-only stream
Stream Track States Copied URL State Description PhenixTrackStateEnabled Track is enabled PhenixTrackStateDisabled Track is disabled PhenixTrackStateEnded Track has ended