Page Content
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 PhenixSdk23let pcastExpressOptions = PhenixPCastExpressFactory.createPCastExpressOptionsBuilder()4 .withAuthenticationToken("DIGEST:eyJhc...")5 .buildPCastExpressOptions()67let roomExpressOptions = PhenixRoomExpressFactory.createRoomExpressOptionsBuilder()8 .withPCastExpressOptions(pcastExpressOptions)9 .buildRoomExpressOptions()1011let channelExpressOptions = PhenixChannelExpressFactory.createChannelExpressOptionsBuilder()12 .withRoomExpressOptions(roomExpressOptions)13 .buildChannelExpressOptions()1415let channelExpress = PhenixChannelExpressFactory.createChannelExpress(channelExpressOptions)
ChannelExpressOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withRoomExpressOptions (required) | PhenixRoomExpressOptions | See PhenixRoomExpressOptionsBuilder | |
buildChannelExpressOptions | none | Builds the PhenixChannelExpressOptions |
View a Channel
Join a channel and automatically view the most recent content published to that channel.
Swift
1import PhenixSdk23let channelExpress: PhenixChannelExpress = ... // previously obtained4let renderLayer: CALayer = ... // previously obtained56// Just an example (you can omit renderer options if defaults are ok)7let rendererOptions = PhenixRendererOptions()8options.aspectRatioMode = .letterbox910let joinRoomOptions = PhenixRoomExpressFactory.createJoinRoomOptionsBuilder()11 .withRoomAlias("MyAwesomeChannel")12 .buildJoinRoomOptions()1314let joinChannelOptions = PhenixChannelExpressFactory.createJoinChannelOptionsBuilder()15 .withJoinRoomOptions(joinRoomOptions)16 .withStreamToken("DIGEST:eyJhc...")17 .withStreamSelectionStrategy(.mostRecent)18 .withRenderer(renderLayer)19 .withRendererOptions(rendererOptions)20 .buildJoinChannelOptions()2122channelExpress.joinChannel(23 joinChannelOptions,24 { [weak self] (requestStatus: PhenixRequestStatus, roomService: PhenixRoomService?) in25 guard requestStatus == .ok, let strongSelf = self else {26 // Handle channel join error27 return28 }2930 // Important: Store room service reference, otherwise we will leave channel again immediately:31 strongSelf.currentRoomService = roomService32 },33 { [weak self]34 (requestStatus: PhenixRequestStatus,35 expressSubscriber: PhenixExpressSubscriber?,36 renderer: PhenixRenderer?) in37 guard let strongSelf = self else {38 return39 }40 if (requestStatus == .ok) {41 // Successfully subscribed to a stream. No need to hold on to any references42 } else if (requestStatus == .noStreamPlaying) {43 // No stream playing in channel, update UI accordingy44 } else {45 // We failed to subscribe and retry attempts must have failed46 }47 });
View Channel Parameters
Name | Type | Description |
---|---|---|
options (required) | Options | Options to join channel with |
joinChannelCallback (required) | Function | Function to call on success/failure of joining the channel. |
subscriberCallback (required) | Function | Function to call on when the most recent presenter changes. |
PhenixJoinChannelOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withJoinRoomOptions (required) | PhenixJoinRoomOptions | See PhenixJoinRoomOptionsBuilder. | |
withStreamToken (required) | NSString | The publish token generated using the Phenix EdgeAuth library. | |
withRenderer (optional) | CALayer | Render layer on which to display stream. If none of the withRenderer... methods are called, no renderer will be instantiated. | |
withRenderer (optional) | none | Will trigger instantiation of renderer. Useful for audio only type streams that do not require a render surface. | |
withRendererOptions (optional) | PhenixRendererOptions | Options passed to renderer. Will trigger instantiation of renderer. | |
withStreamSelectionStrategy (optional) | PhenixStreamSelectionStrategy | PhenixStreamSelectionStrategyMostRecent | Determines how member streams are selected for subscriptions. |
buildJoinChannelOptions | none | Builds the PhenixJoinChannelOptions |
Stream Selection Strategy
Strategy | Description |
---|---|
PhenixStreamSelectionStrategyMostRecent | Select the most recent stream. Viewing stream changes any time a stream starts or is updated in the room. |
PhenixStreamSelectionStrategyHighAvailability | Select 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
Name | Type | Description |
---|---|---|
status | PhenixRequestStatus | The status of the operation |
roomService | PhenixRoomService | Phenix room service object |
View Channel Subscriber Callback Status Codes
Status | Description |
---|---|
PhenixRequestStatusOk | Successfully subscribed to presenter |
PhenixRequestStatusNoStreamPlaying | No presenter in channel to subscribe to. Wait for presenter to join. |
varies | Subscribe to presenter failed for other reasons |
Publish to a Channel
Publish local media to a channel. Users that are viewing the channel will see your media.
Swift
1import PhenixSdk23let channelExpress: PhenixChannelExpress = ... // previously obtained4let renderLayer: CALayer = ... // previously obtained56// 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` instead8// of `withChannelOptions` when assembling the `PhenixPublishToChannelOptions` below9let channelOptions = PhenixRoomServiceFactory.createChannelOptionsBuilder()10 .withName("MyAwesomeChannel")11 // Not required but if it is provided we will use this as the alias instead12 // of pre-generating one for you:13 .withAlias("MyAwesomeChannelAlias")14 .buildChannelOptions()1516// Example constraints. Audio and video are enabled by default17let 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)]2627mediaConstraints.audio.capabilityConstraints[PhenixDeviceCapability.audioEchoCancelationMode.rawValue] =28 [PhenixDeviceConstraint.initWith(PhenixAudioEchoCancelationMode.on)]2930let publishOptions = PhenixPCastExpressFactory.createPublishOptionsBuilder()31 .withStreamToken("DIGEST:eyJhc...")32 .withMediaConstraints(mediaConstraints)33 .withPreviewRenderer(renderLayer)34 .buildPublishOptions()3536let publishToChannelOptions = PhenixChannelExpressFactory.createPublishToChannelOptionsBuilder()37 .withChannelOptions(channelOptions)38 .withPublishOptions(publishOptions)39 .buildPublishToChannelOptions()4041channelExpress.publish(42 toChannel: publishToChannelOptions,43 withPreviewCallback: { [weak self] (44 status: PhenixRequestStatus,45 roomService: PhenixRoomService?,46 publisher: PhenixExpressPublisher?,47 previewRenderer: PhenixRenderer?) in48 guard status == .ok, let strongSelf = self else {49 // Handle channel publish error50 return51 }5253 // Important: Store publisher reference, otherwise we will stop publishing again immediately:54 strongSelf.currentPublisher = publisher55 })5657// OR (without a preview):5859channelExpress.publish(60 toChannel: publishToChannelOptions,61 withCallback: { [weak self] (62 status: PhenixRequestStatus,63 roomService: PhenixRoomService?,64 publisher: PhenixExpressPublisher?) in65 guard status == .ok, let strongSelf = self else {66 // Handle channel publish error67 return68 }6970 // Important: Store publisher reference, otherwise we will stop publishing again immediately:71 strongSelf.currentPublisher = publisher72 })
Publish To Channel Parameters
Name | Type | Description |
---|---|---|
options (required) | Options | Options to publish to channel with |
publisherCallback (required) | Function | Function to call on success/failure of publishing to the channel |
PhenixPublishToChannelOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withChannelOptions (required) | PhenixChannelOptions | See PhenixChannelOptionsBuilder. If omitted, then withChannelId needs to be provided. | |
withChannelId (required) | String | ID of channel to publish to. If omitted, then withChannelOptions needs to be provided. | |
withPublishOptions (required) | PhenixPublishOptions | Publishing options | |
withMemberRole (optional) | PhenixMemberRole | PhenixMemberRolePresenter | Role of member to join channel as (used if not already in channel). |
withStreamType (optional) | PhenixStreamType | PhenixStreamTypePresentation | Type of stream to publish |
withScreenName (optional) | String | random unique string | Your screen name |
withViewerStreamSelectionStrategy (optional) | PhenixStreamSelectionStrategy | PhenixStreamSelectionStrategyMostRecent | Stream selection strategy; must match the strategy channel viewers are using. |
buildPublishToChannelOptions | none | Builds the PhenixPublishToChannelOptions |
PhenixChannelOptionsBuilder
Name | Type | Default | Description |
---|---|---|---|
withName (required) | String | Name of channel | |
withAlias (optional) | String | generated | Channel Alias |
withDescription (optional) | String | empty | Channel description |
buildChannelOptions | none | Builds the PhenixChannelOptions |
Publish To Channel Callback Arguments
Name | Type | Description |
---|---|---|
status | PhenixRequestStatus | The status of the operation |
roomService | RoomService | Phenix room service |
publisher | PhenixExpressPublisher | Phenix 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 PhenixSdk23let channelExpress: PhenixChannelExpress = ... // previously obtained45let channelOptions = PhenixRoomServiceFactory.createChannelOptionsBuilder()6 .withName("MyAwesomeChannel")7 .withAlias("MyAwesomeChannelAlias") // Not required but if it is provided we will use this as the alias instead8 // of pre-generating one for you.9 .buildChannelOptions()1011channelExpress.createChannel(12 channelOptions,13 { (status: PhenixRequestStatus, channel: PhenixImmutableRoom?) in14 guard status == .ok else {15 // Handle room create error16 return17 }1819 // use `channel` to e.g. join20 })
Express Create Channel Parameters
Name | Type | Description |
---|---|---|
options (required) | PhenixChannelOptions | Options to create channel with |
callback (required) | Function | Function to call on success/failure of creating to the channel. See Create Channel Callback Arguments |
Express Create Channel Callback Arguments
Name | Type | Description |
---|---|---|
status | PhenixRequestStatus | The status of the operation. |
channel | PhenixImmutableRoom | Immutable Phenix room object |
v2023-09-12T20:09:36.000Z