• 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: PhenixPCast must be initialized and started when invoking createRoomService so that a valid session ID is present.

Swift
1import PhenixSdk
2
3let pcast: PhenixPCast = ... // previously obtained
4let roomService = PhenixRoomServiceFactory.createRoomService(pcast)!

Initializing Parameters

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

PhenixRoomService

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

Instantiate Self Member Model

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

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.

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4let selfMember = roomService.getSelf()
5
6selfMember.getObservableScreenName().setValue("My New Screen Name")
7selfMember.getObservableRole().setValue(NSNumber.init(value: PhenixMemberRole.audience.rawValue))
8
9// Commit changes to self if already in a room
10selfMember.commitChanges({ (status: PhenixRequestStatus, message: String?) in
11 if status == .ok {
12 // Successfully updated self
13 } else {
14 // Handle error
15 }
16 })

To undo uncommitted local changes, use reload:

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4let selfMember = roomService.getSelf()
5
6selfMember.getObservableScreenName().setValue("My New Screen Name")
7selfMember.getObservableRole().setValue(NSNumber.init(value: PhenixMemberRole.audience.rawValue))
8
9// Decided to undo changes
10selfMember.reload()

Update Self Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe 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.

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4let selfMember = roomService.getSelf()
5
6let selfStream = roomService.createStream("http://myuri.stream", .user, .enabled, .enabled)
7
8selfMember.getObservableStreams().setValue([selfStream!])
9
10// Now commit changes

Set Self Streams Parameters

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

Get Room Info

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

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4
5// Either provide alias or roomId, other can be nil or empty
6let roomId = "us-central#demo#exampleRoomId"
7let alias: String? = nil
8
9roomService.getRoomInfo(
10 roomId,
11 alias,
12 { (roomService: PhenixRoomService?, status: PhenixRequestStatus, room: PhenixRoom?) in
13 if status == .ok {
14 // Do something with room
15 } else {
16 // Handle error
17 }
18 })

Get Room Info Parameters

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

Get Room Info Callback Arguments

NameTypeDescription
roomServicePhenixRoomServiceThe room service making the callback
statusPhenixRequestStatusThe status of the operation
roomPhenixRoomImmutable 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

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4
5let roomName = "My Room Name"
6let description = "Deep thoughts only"
7
8let roomOptions = PhenixRoomServiceFactory.createRoomOptionsBuilder()
9 .withName(roomName)
10 .withDescription(description)
11 .withType(.multiPartyChat)
12 .buildRoomOptions()
13
14roomService.createRoom(
15 roomOptions,
16 { (roomService: PhenixRoomService?, status: PhenixRequestStatus, room: PhenixRoom?) in
17 if status == .ok {
18 // Do something with room
19 } else {
20 // Handle error
21 }
22 })

Create Room Parameters

NameTypeDescription
options (required)PhenixRoomOptionsRoom creation options
callback (required)FunctionCallback with the status of the request and the room model

Create Room Callback Arguments

NameTypeDescription
roomServicePhenixRoomServiceThe room service making the callback
statusPhenixRequestStatusThe status of the operation
roomPhenixRoomImmutable room object

Create Room Callback Status Codes

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

PhenixRoomOptionsBuilder

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

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.

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4
5// Need to provide either room ID or alias (other can be nil)
6let roomId: String? = nil
7let alias = "exampleRoom"
8
9roomService.joinRoom(
10 roomId,
11 alias,
12 { (roomService: PhenixRoomService?, status: PhenixRequestStatus, room: PhenixRoom?) in
13 if status == .ok {
14 // Do something with room
15 } else {
16 // Handle error
17 }
18 })

Join Room Parameters

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

Join Room Callback Arguments

NameTypeDescription
roomServicePhenixRoomServiceThe room service making the callback
statusPhenixRequestStatusThe status of the operation
roomPhenixRoomImmutable 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.

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4
5let observableActiveRoom = roomService.getObservableActiveRoom()!
6
7// For this simple example, we assume that there is an active room, hence we can force un-wrap.
8// In a production environment, this can return nil if we have not currently joined a room. In that case
9// you would want to listen as a subscriber on the 'observableActiveRoom' for updates
10let activeRoom = observableActiveRoom.getValue()!
11let observableMembers = activeRoom.getObservableMembers()!
12
13let 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 // Now do something with this member's streams
18 }
19})
20
21// The subscription will remain active for as long as 'subscription' is kept alive

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.

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4
5let room = roomService.getObservableActiveRoom().getValue()!
6
7room.getObservableDescription().setValue("My New Room Description")
8room.commitChanges({ (status: PhenixRequestStatus, message: String?) in
9 if status == .ok {
10 // Successfully updated room
11 } else {
12 // Handle error
13 }
14 })

Update Room Parameters

NameTypeDescription
callback (required)FunctionCallback with the status of the request

Update Room Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe 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.

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4
5roomService.leaveRoom({ (roomService: PhenixRoomService?, status: PhenixRequestStatus) in
6 if status == .ok {
7 // Successfully left room, no action required
8 } else {
9 // Handle error
10 }
11 })

Leave Room Parameters

NameTypeDescription
callback (required)FunctionCallback with the status of the request

Leave Room Callback Arguments

NameTypeDescription
roomServicePhenixRoomServiceThe room service making the callback
statusPhenixRequestStatusThe 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.

Swift
1import PhenixSdk
2
3let roomService: PhenixRoomService = ... // previously obtained
4
5roomService.destroyRoom({ (roomService: PhenixRoomService?, status: PhenixRequestStatus) in
6 if status == .ok {
7 // Successfully destroyed room, no action required
8 } else {
9 // Handle error
10 }
11 })

Destroy Room Parameters

NameTypeDescription
callback (required)FunctionCallback with the status of the request

Destroy Room Callback Arguments

NameTypeDescription
roomServicePhenixRoomServiceThe room service making the callback
statusPhenixRequestStatusThe 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.

Swift
1import PhenixSdk
2
3let room: PhenixImmutableRoom = ... // previously obtained
4
5let disposable = room.getObservableEstimatedSize().subscribe(
6 { (change: PhenixObservableChange<NSNumber>?) in
7 let currentEstimatedRoomSize = change?.value.uintValue
8 // E.g. update UI
9 })

Room Model

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

PhenixImmutableRoom

NameSignatureReturnsDescription
getRoomId()NSStringThe 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

PhenixRoom extends PhenixImmutableRoom

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

Room Types

TypeDescription
PhenixRoomTypeDirectChatOne to one chat
PhenixRoomTypeMultiPartyChatMany to many or few to many chat
PhenixRoomTypeModeratedChatModerated chat with integrated SIP Bridge for conferencing abilities (join by phone).
PhenixRoomTypeTownHallChat with a few active participants or presenters and many audience or inactive participants
PhenixRoomTypeChannelView only room with a single active member at a time. Broadcast content to many viewers.

PhenixMember

NameSignatureReturnsDescription
getSessionId()NSStringThe 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)voidAttempts to update server member model with any changes made locally
reload()voidReverts all local changes to the server member model

Member Roles

RoleDescription
PhenixMemberRoleParticipantMember with streams and is visible to all members
PhenixMemberRoleAudienceMember with no streams and is not visible to other members
PhenixMemberRolePresenterPresenter participant member
PhenixMemberRoleModeratorPrivileged participant member

Member States

RoleDescription
PhenixMemberStateActiveMember is active
PhenixMemberStatePassiveMember is not active
PhenixMemberStateHandRaisedMember is requesting to become active
PhenixMemberStateInactiveMember is not away
PhenixMemberStateOfflineMember has left the room

PhenixStream

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

NameSignatureReturnsDescription
getUri()NSStringThe stream uri (may or may not be associated with phenix stream id)
getType()PhenixStreamTypeThe stream type
getObservableAudioState()Observable(of PhenixTrackState via NSNumber)Observable of stream video state
getObservableVideoState()Observable(of PhenixTrackState via NSNumber)Observable of stream audio state

Stream Types

TypeDescription
PhenixStreamTypeUserGeneral purpose stream
PhenixStreamTypePresentationPrivileged stream
PhenixStreamTypeAudioAudio-only stream

Stream Track States

StateDescription
PhenixTrackStateEnabledTrack is enabled
PhenixTrackStateDisabledTrack is disabled
PhenixTrackStateEndedTrack has ended
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10