• 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 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
1import PhenixSdk
2
3let backendEndpointUri = "https://example.yourdomain.com/phenix/"
4
5let pcastExpressOptions = PhenixPCastExpressFactory.createPCastExpressOptionsBuilder()
6 .withBackendUri(backendEndpointUri)
7 .buildPCastExpressOptions()
8
9let roomExpressOptions = PhenixRoomExpressFactory.createRoomExpressOptionsBuilder()
10 .withPCastExpressOptions(pcastExpressOptions)
11 .buildRoomExpressOptions()
12
13let roomExpress = PhenixRoomExpressFactory.createRoomExpress(roomExpressOptions)

PhenixRoomExpressOptionsBuilder

NameTypeDefaultDescription
withPCastExpressOptions (required)PhenixPCastExpressOptionsSee PhenixPCastExpressOptionsBuilder
buildRoomExpressOptionsnoneBuilds the PhenixRoomExpressOptions

Join a Room

Join a room and optionally, automatically subscribe to member changes.

Swift
1import PhenixSdk
2
3let roomExpress: PhenixRoomExpress = ... // previously obtained
4
5let joinRoomOptions = PhenixRoomExpressFactory.createJoinRoomOptionsBuilder()
6 .withRoomAlias("myRoom42")
7 .withCapabilities(["streaming"])
8 .buildJoinRoomOptions()
9
10roomExpress.joinRoom(joinRoomOptions, { (status: PhenixRequestStatus, roomService: PhenixRoomService?) in
11 if status == .ok {
12 // Hold on to roomService reference for as long as you wish to stay in the room
13 } else {
14 // Handle error
15 }
16 })
17
18// With optional member update notification:
19roomExpress.joinRoom(
20 joinRoomOptions,
21 { (status: PhenixRequestStatus, roomService: PhenixRoomService?) in
22 if status == .ok {
23 // Hold on to roomService reference for as long as you wish to stay in the room
24 } else {
25 // Handle error
26 }
27 },
28 { (members: [PhenixMember]?) in
29 // Do something with room members
30 })

Express Join Room Parameters

NameTypeDescription
options (required)PhenixJoinRoomOptionsOptions to join room with
joinRoomCallback (required)FunctionFunction to call on success/failure of joining the room
membersChangedCallback (optional)FunctionFunction 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

NameTypeDefaultDescription
withRoomId (required)NSStringId of channel to view
withRoomAlias (optional)NSStringAlias, alternative to ID
withCapabilities (required)NSArray of NSStringThe list of all capabilities to subscribe with.
withRole (optional)PhenixMemberRolePhenixMemberRoleAudienceThe Member Role to join with
withScreenName (optional)NSStringThe 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
buildJoinRoomOptionsnoneBuilds the PhenixJoinRoomOptions

Express Join Room Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe status of the operation.
roomServicePhenixRoomServicePhenix room service object

Subscribe to a Member's Stream

Subscribe to a room member's stream and automatically handle audio and video state changes.

Swift
1import PhenixSdk
2
3let roomExpress: PhenixRoomExpress = ... // previously obtained
4let room: PhenixImmutableRoom = ... // previously obtained
5let renderLayer: CALayer = ... // previously obtained
6
7// 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 room
9// to receive updates when the list of members changes, and then subscribe to the streams-observable
10// on each member to access their streams.
11let member = room.getObservableMembers().getValue()[0] as! PhenixMember
12let memberStream = member.getObservableStreams().getValue[0] as! PhenixStream
13
14let options = PhenixRoomExpressFactory.createSubscribeToMemberStreamOptionsBuilder()
15 .withRenderer(renderLayer)
16 .buildSubscribeToMemberStreamOptions()
17
18roomExpress.subscribe(
19 toMemberStream: memberStream,
20 options,
21 { [weak self] (
22 status: PhenixRequestStatus,
23 subscriber: PhenixExpressSubscriber?,
24 renderer: PhenixRenderer?) in
25 guard status == .ok, let strongSelf = self else {
26 // Handle subscribe error
27 return
28 }
29
30 // Important: Store subscriber reference, otherwise we will stop subscription immediately:
31 strongSelf.currentSubscriber = subscriber
32 })

Subscribe To Member Stream Parameters

NameTypeDescription
memberStream (required)PhenixStreamThe room member's stream to subscribe to
options (required)Subscribe to Member's Stream OptionsPCast™ Express Subscribe Options to subscribe to member stream with
callback (required)FunctionFunction to call on success/failure of subscribing to the member stream

PhenixSubscribeToMemberStreamOptionsBuilder

NameTypeDefaultDescription
withCapabilities (optional)NSArray of NSString[]The list of all capabilities to subscribe with
withRenderer (optional)CALayernoneRender layer on which to display stream. If none of the withRenderer... methods are called, no renderer will be instantiated.
withRenderer (optional)nonefalseWill trigger instantiation of renderer. Useful for audio only type streams that do not require a render surface
withRendererOptions (optional)PhenixRendererOptionsnoneOptions passed to renderer. Will trigger instantiation of renderer
withMonitor (optional)PhenixMonitorSetupFailedCallback, PhenixMonitorStreamEndedCallback, PhenixMonitorOptionsnoneOptions 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
buildSubscribeToMemberStreamOptionsnoneBuilds the PhenixSubscribeToMemberStreamOptions

Subscribe To Member Stream Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe status of the operation.
publisherSubscriberPhenix subscriber object
rendererRendererOptional 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
1import PhenixSdk
2
3let roomExpress: PhenixRoomExpress = ... // previously obtained
4let renderLayer: CALayer = ... // previously obtained
5
6let mediaConstraints = PhenixUserMediaOptions()
7// Customize constraints if needed
8
9let localPublishOptions = PhenixPCastExpressFactory.createPublishOptionsBuilder()
10 .withCapabilities(["hd", "streaming"])
11 .withMediaConstraints(mediaConstraints)
12 .withPreviewRenderer(renderLayer)
13 .buildPublishOptions()
14
15let roomOptions = PhenixRoomServiceFactory.createRoomOptionsBuilder()
16 .withName("MyAwesomeRoom")
17 .buildRoomOptions()
18
19let localPublishToRoomOptions = PhenixRoomExpressFactory.createPublishToRoomOptionsBuilder()
20 .withStreamType(.user)
21 .withMemberRole(.participant)
22 .withRoomOptions(roomOptions)
23 .withPublishOptions(localPublishOptions)
24 .buildPublishToRoomOptions()
25
26roomExpress.publish(
27 toRoom: localPublishToRoomOptions,
28 withCallback: { [weak self] (
29 status: PhenixRequestStatus,
30 roomService: PhenixRoomService?,
31 publisher: PhenixExpressPublisher?) in
32 guard status == .ok, let strongSelf = self else {
33 // Handle publish error
34 return
35 }
36
37 // Important: Store publisher reference, otherwise we will stop publisher immediately:
38 strongSelf.currentPublisher = publisher
39 })
40
41
42// OR for a remote stream:
43let remotePublishOptions = PhenixPCastExpressFactory.createPublishRemoteOptionsBuilder()
44 .withStreamUri("http://example.com/mystream.mp4")
45 .buildPublishRemoteOptions()
46
47let remotePublishToRoomOptions = PhenixRoomExpressFactory.createPublishToRoomOptionsBuilder()
48 .withStreamType(.user)
49 .withMemberRole(.participant)
50 .withRoomOptions(roomOptions)
51 .withPublishRemoteOptions(remotePublishOptions)
52 .buildPublishToRoomOptions()
53
54// Remaining code is the same as for local stream

Publish To Room Parameters

NameTypeDescription
options (required)OptionsOptions to publish to room with
callback (required)FunctionFunction to call on success/failure of publishing to the room

PhenixPublishToRoomOptionsBuilder

NameTypeDefaultDescription
withRoomOptions (required)PhenixRoomOptionsIf omitted, then withRoomId needs to be provided.
withRoomId (required)NSStringID of room to publish to. If omitted, then withRoomOptions needs to be provided.
withPublishOptions (required) PhenixPublishOptionsEither local or remote publish options are required
withPublishRemoteOptions (required)PhenixPublishRemoteOptionsEither local or remote publish options are required
withMemberRole (required)PhenixMemberRoleRole of member to join room as (used if not already in room). See Member Roles
withStreamType (required)PhenixStreamTypeType of stream to publish. See Stream Types
withScreenName (optional)NSStringautomatically generatedScreen name of self member
withViewerStreamSelectionStrategy (optional)PhenixStreamSelectionStrategyPhenixStreamSelectionStrategyMostRecentStream Selection Strategy
buildPublishToRoomOptionsnoneBuilds the PhenixPublishToRoomOptions

Publish To Room Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe status of the operation.
roomServiceRoomServicePhenix room service
publisherPublisherPhenix publisher object
previewRendererRendererOptional 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
1import PhenixSdk
2
3let roomExpress: PhenixRoomExpress = ... // previously obtained
4
5let 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
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10