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
import PhenixSdk

let pcast: PhenixPCast = ...  // previously obtained
let roomService = PhenixRoomServiceFactory.createRoomService(pcast)!

Initializing Parameters

Name	Type	Description
pcast (required)	PhenixPCast	Instantiated PCast™ object. Must already be authenticated

PhenixRoomService

Name	Signature	Returns	Description
getRoomInfo	(roomId, alias, callback)	PhenixRoom	See Get Room Info
createRoom	(room, callback)	PhenixRoom	See Create a Room
joinRoom	(roomId, alias, callback)	PhenixRoom	See Join a Room
leaveRoom	(callback)	void	See Leave a Room
destroyRoom	(callback)	void	See Destroy a Room
getSelf	()	Observable of PhenixMember	Observable of self member
getObservableActiveRoom	()	Observable of PhenixRoom	Observable 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
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained
let selfMember = roomService.getSelf()

selfMember.getObservableScreenName().setValue("My New Screen Name")
selfMember.getObservableRole().setValue(NSNumber.init(value: PhenixMemberRole.audience.rawValue))

// Commit changes to self if already in a room
selfMember.commitChanges({ (status: PhenixRequestStatus, message: String?) in
    if status == .ok {
      // Successfully updated self
    } else {
      // Handle error
    }
  })

To undo uncommitted local changes, use reload:

Swift
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained
let selfMember = roomService.getSelf()

selfMember.getObservableScreenName().setValue("My New Screen Name")
selfMember.getObservableRole().setValue(NSNumber.init(value: PhenixMemberRole.audience.rawValue))

// Decided to undo changes
selfMember.reload()

Update Self Callback Arguments

Name	Type	Description
status	PhenixRequestStatus	The status of the operation
message	String	Error 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
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained
let selfMember = roomService.getSelf()

let selfStream = roomService.createStream("http://myuri.stream", .user, .enabled, .enabled)

selfMember.getObservableStreams().setValue([selfStream!])

// Now commit changes

Set Self Streams Parameters

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

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

Swift
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained

// Either provide alias or roomId, other can be nil or empty
let roomId = "us-central#demo#exampleRoomId"
let alias: String? = nil

roomService.getRoomInfo(
    roomId,
    alias,
    { (roomService: PhenixRoomService?, status: PhenixRequestStatus, room: PhenixRoom?) in
      if status == .ok {
        // Do something with room
      } else {
        // Handle error
      }
    })

Get Room Info Parameters

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

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

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)

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
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained

let roomName = "My Room Name"
let description = "Deep thoughts only"

let roomOptions = PhenixRoomServiceFactory.createRoomOptionsBuilder()
    .withName(roomName)
    .withDescription(description)
    .withType(.multiPartyChat)
    .buildRoomOptions()

roomService.createRoom(
    roomOptions,
    { (roomService: PhenixRoomService?, status: PhenixRequestStatus, room: PhenixRoom?) in
      if status == .ok {
        // Do something with room
      } else {
        // Handle error
      }
    })

Create Room Parameters

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

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

Status	Description
PhenixRequestStatusOk	Create room succeeded. This can also mean that the room already existed
varies	Create room failed for other reasons

PhenixRoomOptionsBuilder

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

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
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained

// Need to provide either room ID or alias (other can be nil)
let roomId: String? = nil
let alias = "exampleRoom"

roomService.joinRoom(
    roomId,
    alias,
    { (roomService: PhenixRoomService?, status: PhenixRequestStatus, room: PhenixRoom?) in
      if status == .ok {
        // Do something with room
      } else {
        // Handle error
      }
    })

Join Room Parameters

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

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

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

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
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained

let observableActiveRoom = roomService.getObservableActiveRoom()!

// For this simple example, we assume that there is an active room, hence we can force un-wrap.
// In a production environment, this can return nil if we have not currently joined a room. In that case
// you would want to listen as a subscriber on the 'observableActiveRoom' for updates
let activeRoom = observableActiveRoom.getValue()!
let observableMembers = activeRoom.getObservableMembers()!

let subscription = observableMembers.subscribe({ (change) in
  let currentMembers = change?.value as! [PhenixMember]
  for member in currentMembers {
    let currentStreams = member.getObservableStreams().getValue() as! [PhenixStream]
    // Now do something with this member's streams
  }
})

// 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
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained

let room = roomService.getObservableActiveRoom().getValue()!

room.getObservableDescription().setValue("My New Room Description")
room.commitChanges({ (status: PhenixRequestStatus, message: String?) in
    if status == .ok {
      // Successfully updated room
    } else {
      // Handle error
    }
  })

Update Room Parameters

Name	Type	Description
callback (required)	Function	Callback with the status of the request

Update Room Callback Arguments

Name	Type	Description
status	PhenixRequestStatus	The status of the operation
message	String	Error message, if applicable

Update Room Callback Status Codes

Status	Description
ok	Update room succeeded
varies	Update room failed for other reasons

Leave a Room

Leave the current active room. Self is not modified.

Swift
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained

roomService.leaveRoom({ (roomService: PhenixRoomService?, status: PhenixRequestStatus) in
    if status == .ok {
      // Successfully left room, no action required
    } else {
      // Handle error
    }
  })

Leave Room Parameters

Name	Type	Description
callback (required)	Function	Callback with the status of the request

Leave Room Callback Arguments

Name	Type	Description
roomService	PhenixRoomService	The room service making the callback
status	PhenixRequestStatus	The status of the operation

Leave Room Callback Status Codes

Status	Description
ok	Leave room succeeded
varies	Leave room failed for other reasons

Destroy a Room

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

Swift
import PhenixSdk

let roomService: PhenixRoomService = ...  // previously obtained

roomService.destroyRoom({ (roomService: PhenixRoomService?, status: PhenixRequestStatus) in
    if status == .ok {
      // Successfully destroyed room, no action required
    } else {
      // Handle error
    }
  })

Destroy Room Parameters

Name	Type	Description
callback (required)	Function	Callback with the status of the request

Destroy Room Callback Arguments

Name	Type	Description
roomService	PhenixRoomService	The room service making the callback
status	PhenixRequestStatus	The status of the operation

Destroy Room Callback Status Codes

Status	Description
ok	Destroy room succeeded
varies	Destroy 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
import PhenixSdk

let room: PhenixImmutableRoom = ...  // previously obtained

let disposable = room.getObservableEstimatedSize().subscribe(
    { (change: PhenixObservableChange<NSNumber>?) in
      let currentEstimatedRoomSize =  change?.value.uintValue
      // E.g. update UI
    })

Room Model

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

PhenixImmutableRoom

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

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

Room Types

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.

PhenixMember

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

Member Roles

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

Member States

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

PhenixStream

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

Stream Types

Type	Description
PhenixStreamTypeUser	General purpose stream
PhenixStreamTypePresentation	Privileged stream
PhenixStreamTypeAudio	Audio-only stream

Stream Track States

State	Description
PhenixTrackStateEnabled	Track is enabled
PhenixTrackStateDisabled	Track is disabled
PhenixTrackStateEnded	Track has ended

Page Content

v2023-01-31T21:25:10