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
PhenixPCastExpressFactory
| Name | Signature | Returns | Description |
|---|---|---|---|
| createPCastExpressOptionsBuilder | (UnrecoverableErrorCallback) | PhenixPCastExpressOptionsBuilder | Creates PhenixPCastExpressOptionsBuilder with unrecoverable error callback. |
Swift
import PhenixSdk
let pcastExpressOptions = PhenixPCastExpressFactory.createPCastExpressOptionsBuilder(unrecoverableErrorCallback: { status, errorDescription in
// Best option is to try rebuilding the ChannelExpress instance and/or quit your app
})
.buildPCastExpressOptions()
let roomExpressOptions = PhenixRoomExpressFactory.createRoomExpressOptionsBuilder()
.withPCastExpressOptions(pcastExpressOptions)
.buildRoomExpressOptions()
let channelExpressOptions = PhenixChannelExpressFactory.createChannelExpressOptionsBuilder()
.withRoomExpressOptions(roomExpressOptions)
.buildChannelExpressOptions()
let 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
import PhenixSdk
let channelExpress: PhenixChannelExpress = ... // previously obtained
let renderLayer: CALayer = ... // previously obtained
// Just an example (you can omit renderer options if defaults are ok)
let rendererOptions = PhenixRendererOptions()
options.aspectRatioMode = .letterbox
let joinChannelOptions = PhenixChannelExpressFactory.createJoinChannelOptionsBuilder()
.withStreamToken("DIGEST:eyJhc...")
.withStreamSelectionStrategy(.mostRecent)
.withRenderer(renderLayer)
.withRendererOptions(rendererOptions)
.buildJoinChannelOptions()
channelExpress.joinChannel(
joinChannelOptions,
{ [weak self] (requestStatus: PhenixRequestStatus, roomService: PhenixRoomService?) in
guard requestStatus == .ok, let strongSelf = self else {
// Handle channel join error
return
}
// Important: Store room service reference, otherwise we will leave channel again immediately:
strongSelf.currentRoomService = roomService
},
{ [weak self]
(requestStatus: PhenixRequestStatus,
expressSubscriber: PhenixExpressSubscriber?,
renderer: PhenixRenderer?) in
guard let strongSelf = self else {
return
}
if (requestStatus == .ok) {
// Successfully subscribed to a stream. No need to hold on to any references
} else if (requestStatus == .noStreamPlaying) {
// No stream playing in channel, update UI accordingy
} else {
// We failed to subscribe and retry attempts must have failed
}
});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 |
|---|---|---|---|
| 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
import PhenixSdk
let channelExpress: PhenixChannelExpress = ... // previously obtained
let renderLayer: CALayer = ... // previously obtained
// Example constraints. Audio and video are enabled by default
let mediaConstraints = PhenixUserMediaOptions()
mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.facingMode.rawValue] =
[PhenixDeviceConstraint.initWith(.user)]
mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.frameRate.rawValue] =
[PhenixDeviceConstraint.initWith(15)]
mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.height.rawValue] =
[PhenixDeviceConstraint.initWith(720)]
mediaConstraints.video.capabilityConstraints[PhenixDeviceCapability.width.rawValue] =
[PhenixDeviceConstraint.initWith(1280)]
mediaConstraints.audio.capabilityConstraints[PhenixDeviceCapability.audioEchoCancellationMode.rawValue] =
[PhenixDeviceConstraint.initWith(PhenixAudioEchoCancellationMode.on)]
let publishOptions = PhenixPCastExpressFactory.createPublishOptionsBuilder()
.withStreamToken("DIGEST:eyJhc...")
.withMediaConstraints(mediaConstraints)
.withPreviewRenderer(renderLayer)
.buildPublishOptions()
let publishToChannelOptions = PhenixChannelExpressFactory.createPublishToChannelOptionsBuilder()
.withPublishOptions(publishOptions)
.buildPublishToChannelOptions()
channelExpress.publish(
toChannel: publishToChannelOptions,
withPreviewCallback: { [weak self] (
status: PhenixRequestStatus,
roomService: PhenixRoomService?,
publisher: PhenixExpressPublisher?,
previewRenderer: PhenixRenderer?) in
guard status == .ok, let strongSelf = self else {
// Handle channel publish error
return
}
// Important: Store publisher reference, otherwise we will stop publishing again immediately:
strongSelf.currentPublisher = publisher
})
// OR (without a preview):
channelExpress.publish(
toChannel: publishToChannelOptions,
withCallback: { [weak self] (
status: PhenixRequestStatus,
roomService: PhenixRoomService?,
publisher: PhenixExpressPublisher?) in
guard status == .ok, let strongSelf = self else {
// Handle channel publish error
return
}
// Important: Store publisher reference, otherwise we will stop publishing again immediately:
strongSelf.currentPublisher = publisher
})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 |
|---|---|---|---|
| withPublishOptions (required) | PhenixPublishOptions | Provide 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 |
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 |
v2025-01-13T17:19:39.000Z