• 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

Channel Express

Single-step configuration based API for setting up a channel - a one-size-fits-all solution for all your one-to-many streaming applications. The Channel Express extends the lower-level Room Service API to provide easy solutions to:

  • View a channel
  • Publish to a channel

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 channelExpressOptions = PhenixChannelExpressFactory.createChannelExpressOptionsBuilder()
14 .withRoomExpressOptions(roomExpressOptions)
15 .buildChannelExpressOptions()
16
17let channelExpress = PhenixChannelExpressFactory.createChannelExpress(channelExpressOptions)

ChannelExpressOptionsBuilder

NameTypeDefaultDescription
withRoomExpressOptions (required)PhenixRoomExpressOptionsSee PhenixRoomExpressOptionsBuilder
buildChannelExpressOptionsnoneBuilds the PhenixChannelExpressOptions

View a Channel

Join a channel and automatically view the most recent content published to that channel.

Swift
1import PhenixSdk
2
3let channelExpress: PhenixChannelExpress = ... // previously obtained
4let renderLayer: CALayer = ... // previously obtained
5
6// Just an example (you can omit renderer options if defaults are ok)
7let rendererOptions = PhenixRendererOptions()
8options.aspectRatioMode = .letterbox
9
10let joinRoomOptions = PhenixRoomExpressFactory.createJoinRoomOptionsBuilder()
11 .withRoomAlias("MyAwesomeChannel")
12 .buildJoinRoomOptions()
13
14let joinChannelOptions = PhenixChannelExpressFactory.createJoinChannelOptionsBuilder()
15 .withJoinRoomOptions(joinRoomOptions)
16 .withStreamSelectionStrategy(.mostRecent)
17 .withRenderer(renderLayer)
18 .withRendererOptions(rendererOptions)
19 .buildJoinChannelOptions()
20
21channelExpress.joinChannel(
22 joinChannelOptions,
23 { [weak self] (requestStatus: PhenixRequestStatus, roomService: PhenixRoomService?) in
24 guard requestStatus == .ok, let strongSelf = self else {
25 // Handle channel join error
26 return
27 }
28
29 // Important: Store room service reference, otherwise we will leave channel again immediately:
30 strongSelf.currentRoomService = roomService
31 },
32 { [weak self]
33 (requestStatus: PhenixRequestStatus,
34 expressSubscriber: PhenixExpressSubscriber?,
35 renderer: PhenixRenderer?) in
36 guard let strongSelf = self else {
37 return
38 }
39 if (requestStatus == .ok) {
40 // Successfully subscribed to a stream. No need to hold on to any references
41 } else if (requestStatus == .noStreamPlaying) {
42 // No stream playing in channel, update UI accordingy
43 } else {
44 // We failed to subscribe and retry attempts must have failed
45 }
46 });

View Channel Parameters

NameTypeDescription
options (required)OptionsOptions to join channel with
joinChannelCallback (required)FunctionFunction to call on success/failure of joining the channel.
subscriberCallback (required)FunctionFunction to call on when the most recent presenter changes.

PhenixJoinChannelOptionsBuilder

NameTypeDefaultDescription
withJoinRoomOptions (required)PhenixJoinRoomOptionsSee PhenixJoinRoomOptionsBuilder.
withRenderer (optional)CALayerRender layer on which to display stream. If none of the withRenderer... methods are called, no renderer will be instantiated.
withRenderer (optional)noneWill trigger instantiation of renderer. Useful for audio only type streams that do not require a render surface.
withRendererOptions (optional)PhenixRendererOptionsOptions passed to renderer. Will trigger instantiation of renderer.
withStreamSelectionStrategy (optional)PhenixStreamSelectionStrategyPhenixStreamSelectionStrategyMostRecentDetermines how member streams are selected for subscriptions.
buildJoinChannelOptionsnoneBuilds the PhenixJoinChannelOptions

Stream Selection Strategy

StrategyDescription
PhenixStreamSelectionStrategyMostRecentSelect the most recent stream. Viewing stream changes any time a stream starts or is updated in the room.
PhenixStreamSelectionStrategyHighAvailabilitySelect streams for increased reliability and redundancy. Viewing stream will only change in the event of a failure of the prior selected stream.

Express Join Channel Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe status of the operation
roomServicePhenixRoomServicePhenix room service object

View Channel Subscriber Callback Status Codes

StatusDescription
PhenixRequestStatusOkSuccessfully subscribed to presenter
PhenixRequestStatusNoStreamPlayingNo presenter in channel to subscribe to. Wait for presenter to join.
variesSubscribe to presenter failed for other reasons

Publish to a Channel

Publish a local or remote media to a channel. Users that are viewing the channel will see your media.

Swift
1import PhenixSdk
2
3let channelExpress: PhenixChannelExpress = ... // previously obtained
4let renderLayer: CALayer = ... // previously obtained
5
6// Using ChannelOptions means that the channel may or may not already exist.
7// If the channel ID is known in advance, it is recommended to use `withChannelId` instead
8// of `withChannelOptions` when assembling the `PhenixPublishToChannelOptions` below
9let channelOptions = PhenixRoomServiceFactory.createChannelOptionsBuilder()
10 .withName("MyAwesomeChannel")
11 // Not required but if it is provided we will use this as the alias instead
12 // of pre-generating one for you:
13 .withAlias("MyAwesomeChannelAlias")
14 .buildChannelOptions()
15
16// Example constraints. Audio and video are enabled by default
17let mediaConstraints = PhenixUserMediaOptions()
18mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.facingMode.rawValue] =
19 [PhenixDeviceConstraint.initWith(.user)]
20mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.frameRate.rawValue] =
21 [PhenixDeviceConstraint.initWith(15)]
22mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.height.rawValue] =
23 [PhenixDeviceConstraint.initWith(720)]
24mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.width.rawValue] =
25 [PhenixDeviceConstraint.initWith(1280)]
26
27mediaConstraints.audio.capabilityConstraints[PhenixDeviceCapability.audioEchoCancelationMode.rawValue] =
28 [PhenixDeviceConstraint.initWith(PhenixAudioEchoCancelationMode.on)]
29
30let publishOptions = PhenixPCastExpressFactory.createPublishOptionsBuilder()
31 .withCapabilities(["hd", "streaming"]) // Example capabilities
32 .withMediaConstraints(mediaConstraints)
33 .withPreviewRenderer(renderLayer)
34 .buildPublishOptions()
35
36let publishToChannelOptions = PhenixChannelExpressFactory.createPublishToChannelOptionsBuilder()
37 .withChannelOptions(channelOptions)
38 .withPublishOptions(publishOptions)
39 .buildPublishToChannelOptions()
40
41channelExpress.publish(
42 toChannel: publishToChannelOptions,
43 withPreviewCallback: { [weak self] (
44 status: PhenixRequestStatus,
45 roomService: PhenixRoomService?,
46 publisher: PhenixExpressPublisher?,
47 previewRenderer: PhenixRenderer?) in
48 guard status == .ok, let strongSelf = self else {
49 // Handle channel publish error
50 return
51 }
52
53 // Important: Store publisher reference, otherwise we will stop publishing again immediately:
54 strongSelf.currentPublisher = publisher
55 })
56
57// OR (without a preview):
58
59channelExpress.publish(
60 toChannel: publishToChannelOptions,
61 withCallback: { [weak self] (
62 status: PhenixRequestStatus,
63 roomService: PhenixRoomService?,
64 publisher: PhenixExpressPublisher?) in
65 guard status == .ok, let strongSelf = self else {
66 // Handle channel publish error
67 return
68 }
69
70 // Important: Store publisher reference, otherwise we will stop publishing again immediately:
71 strongSelf.currentPublisher = publisher
72 })

Publish To Channel Parameters

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

PhenixPublishToChannelOptionsBuilder

Name
Type
Default
Description
withChannelOptions (required)PhenixChannelOptionsSee PhenixChannelOptionsBuilder. If omitted, then withChannelId needs to be provided.
withChannelId (required)StringID of channel to publish to. If omitted, then withChannelOptions needs to be provided.
withPublishOptions (required)PhenixPublishOptionsEither provide this or remote publish options.
withPublishRemoteOptions (required)PhenixRemotePublishOptionsEither provide this or publish options.
withMemberRole (optional)PhenixMemberRolePhenixMemberRolePresenterRole of member to join channel as (used if not already in channel).
withStreamType (optional)PhenixStreamTypePhenixStreamTypePresentationType of stream to publish
withScreenName (optional)Stringrandom unique stringYour screen name
withViewerStreamSelectionStrategy (optional)PhenixStreamSelectionStrategyPhenixStreamSelectionStrategyMostRecentStream selection strategy; must match the strategy channel viewers are using.
buildPublishToChannelOptionsnoneBuilds the PhenixPublishToChannelOptions

PhenixChannelOptionsBuilder

NameTypeDefaultDescription
withName (required)StringName of channel
withAlias (optional)StringgeneratedChannel Alias
withDescription (optional)StringemptyChannel description
buildChannelOptionsnoneBuilds the PhenixChannelOptions

Publish To Channel Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe status of the operation
roomServiceRoomServicePhenix room service
publisherPhenixExpressPublisherPhenix publisher object

Create a Channel (deprecated)

Creation of Channels from client SDKs is deprecated. Channels should be created by the backend using the REST API.
Swift
1import PhenixSdk
2
3let channelExpress: PhenixChannelExpress = ... // previously obtained
4
5let channelOptions = PhenixRoomServiceFactory.createChannelOptionsBuilder()
6 .withName("MyAwesomeChannel")
7 .withAlias("MyAwesomeChannelAlias") // Not required but if it is provided we will use this as the alias instead
8 // of pre-generating one for you.
9 .buildChannelOptions()
10
11channelExpress.createChannel(
12 channelOptions,
13 { (status: PhenixRequestStatus, channel: PhenixImmutableRoom?) in
14 guard status == .ok else {
15 // Handle room create error
16 return
17 }
18
19 // use `channel` to e.g. join
20 })

Express Create Channel Parameters

NameTypeDescription
options (required)PhenixChannelOptionsOptions to create channel with
callback (required)FunctionFunction to call on success/failure of creating to the channel. See Create Channel Callback Arguments

Express Create Channel Callback Arguments

NameTypeDescription
statusPhenixRequestStatusThe status of the operation.
channelPhenixImmutableRoomImmutable Phenix room object
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10