Room Express
Single-step configuration based API for setting up a room - a solution for all your other streaming applications including Group Broadcast, Group Chat, and One to One Chat. The Room Express extends the lower-level Room Service API to provide easy solutions to:
- Join, create, and publish to a room
- Subscribe to streams of members in a room
Initializing
1import PhenixSdk23let backendEndpointUri = "https://example.yourdomain.com/phenix/"45let pcastExpressOptions = PhenixPCastExpressFactory.createPCastExpressOptionsBuilder()6 .withBackendUri(backendEndpointUri)7 .buildPCastExpressOptions()89let roomExpressOptions = PhenixRoomExpressFactory.createRoomExpressOptionsBuilder()10 .withPCastExpressOptions(pcastExpressOptions)11 .buildRoomExpressOptions()1213let roomExpress = PhenixRoomExpressFactory.createRoomExpress(roomExpressOptions)
PhenixRoomExpressOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withPCastExpressOptions (required) | PhenixPCastExpressOptions | See PhenixPCastExpressOptionsBuilder | |
buildRoomExpressOptions | none | Builds the PhenixRoomExpressOptions |
Join a Room
Join a room and optionally, automatically subscribe to member changes.
1import PhenixSdk23let roomExpress: PhenixRoomExpress = ... // previously obtained45let joinRoomOptions = PhenixRoomExpressFactory.createJoinRoomOptionsBuilder()6 .withRoomAlias("myRoom42")7 .withCapabilities(["streaming"])8 .buildJoinRoomOptions()910roomExpress.joinRoom(joinRoomOptions, { (status: PhenixRequestStatus, roomService: PhenixRoomService?) in11 if status == .ok {12 // Hold on to roomService reference for as long as you wish to stay in the room13 } else {14 // Handle error15 }16 })1718// With optional member update notification:19roomExpress.joinRoom(20 joinRoomOptions,21 { (status: PhenixRequestStatus, roomService: PhenixRoomService?) in22 if status == .ok {23 // Hold on to roomService reference for as long as you wish to stay in the room24 } else {25 // Handle error26 }27 },28 { (members: [PhenixMember]?) in29 // Do something with room members30 })
Express Join Room Parameters
Name | Type | Description |
---|---|---|
options (required) | PhenixJoinRoomOptions | Options to join room with |
joinRoomCallback (required) | Function | Function to call on success/failure of joining the room |
membersChangedCallback (optional) | Function | Function to call on when the participant members in the room changes. Returns array of Members. Callback is guaranteed to be called at least once when room is joined. |
PhenixJoinRoomOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withRoomId (required) | NSString | Id of channel to view | |
withRoomAlias (optional) | NSString | Alias, alternative to ID | |
withCapabilities (required) | NSArray of NSString | The list of all capabilities to subscribe with. | |
withRole (optional) | PhenixMemberRole | PhenixMemberRoleAudience | The Member Role to join with |
withScreenName (optional) | NSString | The member screen name to join with. A random string will be generated if not provided. | |
withStreams (optional) | NSArray of PhenixStream | [] | The member streams to join with. Empty if not provided |
buildJoinRoomOptions | none | Builds the PhenixJoinRoomOptions |
Express Join Room Callback Arguments
Name | Type | Description |
---|---|---|
status | PhenixRequestStatus | The status of the operation. |
roomService | PhenixRoomService | Phenix room service object |
Subscribe to a Member's Stream
Subscribe to a room member's stream and automatically handle audio and video state changes.
1import PhenixSdk23let roomExpress: PhenixRoomExpress = ... // previously obtained4let room: PhenixImmutableRoom = ... // previously obtained5let renderLayer: CALayer = ... // previously obtained67// Just an example showing how to get a stream from a member.8// In a real-world app you would want to subscribe to the room-members-observable on the room9// to receive updates when the list of members changes, and then subscribe to the streams-observable10// on each member to access their streams.11let member = room.getObservableMembers().getValue()[0] as! PhenixMember12let memberStream = member.getObservableStreams().getValue[0] as! PhenixStream1314let options = PhenixRoomExpressFactory.createSubscribeToMemberStreamOptionsBuilder()15 .withRenderer(renderLayer)16 .buildSubscribeToMemberStreamOptions()1718roomExpress.subscribe(19 toMemberStream: memberStream,20 options,21 { [weak self] (22 status: PhenixRequestStatus,23 subscriber: PhenixExpressSubscriber?,24 renderer: PhenixRenderer?) in25 guard status == .ok, let strongSelf = self else {26 // Handle subscribe error27 return28 }2930 // Important: Store subscriber reference, otherwise we will stop subscription immediately:31 strongSelf.currentSubscriber = subscriber32 })
Subscribe To Member Stream Parameters
Name | Type | Description |
---|---|---|
memberStream (required) | PhenixStream | The room member's stream to subscribe to |
options (required) | Subscribe to Member's Stream Options | PCast™ Express Subscribe Options to subscribe to member stream with |
callback (required) | Function | Function to call on success/failure of subscribing to the member stream |
PhenixSubscribeToMemberStreamOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withCapabilities (optional) | NSArray of NSString | [] | The list of all capabilities to subscribe with |
withRenderer (optional) | CALayer | none | Render layer on which to display stream. If none of the withRenderer... methods are called, no renderer will be instantiated. |
withRenderer (optional) | none | false | Will trigger instantiation of renderer. Useful for audio only type streams that do not require a render surface |
withRendererOptions (optional) | PhenixRendererOptions | none | Options passed to renderer. Will trigger instantiation of renderer |
withMonitor (optional) | PhenixMonitorSetupFailedCallback, PhenixMonitorStreamEndedCallback, PhenixMonitorOptions | none | Options for monitoring a subscriber for failure |
withConnectOptions (optional) | NSArray of NSStrings | [] | List of options for subscribing |
withTags (optional) | NSArray of NSStrings | [] | Tags for the stream |
buildSubscribeToMemberStreamOptions | none | Builds the PhenixSubscribeToMemberStreamOptions |
Subscribe To Member Stream Callback Arguments
Name | Type | Description |
---|---|---|
status | PhenixRequestStatus | The status of the operation. |
publisher | Subscriber | Phenix subscriber object |
renderer | Renderer | Optional renderer if renderer was enabled, else nil |
Publish to a Room
Publish local or remote media to a room. An error will be returned if a room corresponding to the Room Options passed does not exist. If you have not entered the room via joinRoom or publishToRoom methods then a model for Self will be created.
1import PhenixSdk23let roomExpress: PhenixRoomExpress = ... // previously obtained4let renderLayer: CALayer = ... // previously obtained56let mediaConstraints = PhenixUserMediaOptions()7// Customize constraints if needed89let localPublishOptions = PhenixPCastExpressFactory.createPublishOptionsBuilder()10 .withCapabilities(["hd", "streaming"])11 .withMediaConstraints(mediaConstraints)12 .withPreviewRenderer(renderLayer)13 .buildPublishOptions()1415let roomOptions = PhenixRoomServiceFactory.createRoomOptionsBuilder()16 .withName("MyAwesomeRoom")17 .buildRoomOptions()1819let localPublishToRoomOptions = PhenixRoomExpressFactory.createPublishToRoomOptionsBuilder()20 .withStreamType(.user)21 .withMemberRole(.participant)22 .withRoomOptions(roomOptions)23 .withPublishOptions(localPublishOptions)24 .buildPublishToRoomOptions()2526roomExpress.publish(27 toRoom: localPublishToRoomOptions,28 withCallback: { [weak self] (29 status: PhenixRequestStatus,30 roomService: PhenixRoomService?,31 publisher: PhenixExpressPublisher?) in32 guard status == .ok, let strongSelf = self else {33 // Handle publish error34 return35 }3637 // Important: Store publisher reference, otherwise we will stop publisher immediately:38 strongSelf.currentPublisher = publisher39 })404142// OR for a remote stream:43let remotePublishOptions = PhenixPCastExpressFactory.createPublishRemoteOptionsBuilder()44 .withStreamUri("http://example.com/mystream.mp4")45 .buildPublishRemoteOptions()4647let remotePublishToRoomOptions = PhenixRoomExpressFactory.createPublishToRoomOptionsBuilder()48 .withStreamType(.user)49 .withMemberRole(.participant)50 .withRoomOptions(roomOptions)51 .withPublishRemoteOptions(remotePublishOptions)52 .buildPublishToRoomOptions()5354// Remaining code is the same as for local stream
Publish To Room Parameters
Name | Type | Description |
---|---|---|
options (required) | Options | Options to publish to room with |
callback (required) | Function | Function to call on success/failure of publishing to the room |
PhenixPublishToRoomOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withRoomOptions (required) | PhenixRoomOptions | If omitted, then withRoomId needs to be provided. | |
withRoomId (required) | NSString | ID of room to publish to. If omitted, then withRoomOptions needs to be provided. | |
withPublishOptions (required) | PhenixPublishOptions | Either local or remote publish options are required | |
withPublishRemoteOptions (required) | PhenixPublishRemoteOptions | Either local or remote publish options are required | |
withMemberRole (required) | PhenixMemberRole | Role of member to join room as (used if not already in room). See Member Roles | |
withStreamType (required) | PhenixStreamType | Type of stream to publish. See Stream Types | |
withScreenName (optional) | NSString | automatically generated | Screen name of self member |
withViewerStreamSelectionStrategy (optional) | PhenixStreamSelectionStrategy | PhenixStreamSelectionStrategyMostRecent | Stream Selection Strategy |
buildPublishToRoomOptions | none | Builds the PhenixPublishToRoomOptions |
Publish To Room Callback Arguments
Name | Type | Description |
---|---|---|
status | PhenixRequestStatus | The status of the operation. |
roomService | RoomService | Phenix room service |
publisher | Publisher | Phenix publisher object |
previewRenderer | Renderer | Optional renderer if preview renderer was enabled |
Get PCast™ Express
Get the underlying instance of the PCast™ Express. This is preferred to creating another instance as this will introduce more overhead.
1import PhenixSdk23let roomExpress: PhenixRoomExpress = ... // previously obtained45let pcastExpress = roomExpress.pcastExpress
Clean Up
Underlying resources are kept alive for as long as you hold any references to any of the returned objects (room service, subscriber, renderer). Once those references as well as any reference to the room express instance itself have been released, all underlying resources will be automatically cleaned up and released.