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

Swift
import PhenixSdk

let backendEndpointUri = "https://example.yourdomain.com/phenix/"

let pcastExpressOptions = PhenixPCastExpressFactory.createPCastExpressOptionsBuilder()
    .withBackendUri(backendEndpointUri)
    .buildPCastExpressOptions()

let roomExpressOptions = PhenixRoomExpressFactory.createRoomExpressOptionsBuilder()
    .withPCastExpressOptions(pcastExpressOptions)
    .buildRoomExpressOptions()

let 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.

Swift
import PhenixSdk

let roomExpress: PhenixRoomExpress = ...  // previously obtained

let joinRoomOptions = PhenixRoomExpressFactory.createJoinRoomOptionsBuilder()
    .withRoomAlias("myRoom42")
    .withCapabilities(["streaming"])
    .buildJoinRoomOptions()

roomExpress.joinRoom(joinRoomOptions, { (status: PhenixRequestStatus, roomService: PhenixRoomService?) in
    if status == .ok {
      // Hold on to roomService reference for as long as you wish to stay in the room
    } else {
      // Handle error
    }
  })

// With optional member update notification:
roomExpress.joinRoom(
    joinRoomOptions,
    { (status: PhenixRequestStatus, roomService: PhenixRoomService?) in
      if status == .ok {
        // Hold on to roomService reference for as long as you wish to stay in the room
      } else {
        // Handle error
      }
    },
    { (members: [PhenixMember]?) in
      // Do something with room members
    })

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 room member's stream and automatically handle audio and video state changes.

Swift
import PhenixSdk

let roomExpress: PhenixRoomExpress = ... // previously obtained
let room: PhenixImmutableRoom = ...  // previously obtained
let renderLayer: CALayer = ...  // previously obtained

// Just an example showing how to get a stream from a member.
// In a real-world app you would want to subscribe to the room-members-observable on the room
// to receive updates when the list of members changes, and then subscribe to the streams-observable
// on each member to access their streams.
let member = room.getObservableMembers().getValue()[0] as! PhenixMember
let memberStream = member.getObservableStreams().getValue[0] as! PhenixStream

let options = PhenixRoomExpressFactory.createSubscribeToMemberStreamOptionsBuilder()
    .withRenderer(renderLayer)
    .buildSubscribeToMemberStreamOptions()

roomExpress.subscribe(
    toMemberStream: memberStream,
    options,
    { [weak self] (
        status: PhenixRequestStatus,
        subscriber: PhenixExpressSubscriber?,
        renderer: PhenixRenderer?) in
      guard status == .ok, let strongSelf = self else {
        // Handle subscribe error
        return
      }

      // Important: Store subscriber reference, otherwise we will stop subscription immediately:
      strongSelf.currentSubscriber = subscriber
    })

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`

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.

Swift
import PhenixSdk

let roomExpress: PhenixRoomExpress = ... // previously obtained
let renderLayer: CALayer = ...  // previously obtained

let mediaConstraints = PhenixUserMediaOptions()
// Customize constraints if needed

let localPublishOptions = PhenixPCastExpressFactory.createPublishOptionsBuilder()
    .withCapabilities(["hd", "streaming"])
    .withMediaConstraints(mediaConstraints)
    .withPreviewRenderer(renderLayer)
    .buildPublishOptions()

let roomOptions = PhenixRoomServiceFactory.createRoomOptionsBuilder()
    .withName("MyAwesomeRoom")
    .buildRoomOptions()

let localPublishToRoomOptions = PhenixRoomExpressFactory.createPublishToRoomOptionsBuilder()
    .withStreamType(.user)
    .withMemberRole(.participant)
    .withRoomOptions(roomOptions)
    .withPublishOptions(localPublishOptions)
    .buildPublishToRoomOptions()

roomExpress.publish(
    toRoom: localPublishToRoomOptions,
    withCallback: { [weak self] (
        status: PhenixRequestStatus,
        roomService: PhenixRoomService?,
        publisher: PhenixExpressPublisher?) in
      guard status == .ok, let strongSelf = self else {
        // Handle publish error
        return
      }

      // Important: Store publisher reference, otherwise we will stop publisher immediately:
      strongSelf.currentPublisher = publisher
    })


// OR for a remote stream:
let remotePublishOptions = PhenixPCastExpressFactory.createPublishRemoteOptionsBuilder()
    .withStreamUri("http://example.com/mystream.mp4")
    .buildPublishRemoteOptions()

let remotePublishToRoomOptions = PhenixRoomExpressFactory.createPublishToRoomOptionsBuilder()
    .withStreamType(.user)
    .withMemberRole(.participant)
    .withRoomOptions(roomOptions)
    .withPublishRemoteOptions(remotePublishOptions)
    .buildPublishToRoomOptions()

// 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.

Swift
import PhenixSdk

let roomExpress: PhenixRoomExpress = ...  // previously obtained

let 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.

Page Content

v2023-01-31T21:25:10