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
import PhenixSdk
let pcastExpressOptions = PhenixPCastExpressFactory.createPCastExpressOptionsBuilder()
.withAuthenticationToken("DIGEST:eyJhc...")
.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 joinRoomOptions = PhenixRoomExpressFactory.createJoinRoomOptionsBuilder()
.withRoomAlias("MyAwesomeChannel")
.buildJoinRoomOptions()
let joinChannelOptions = PhenixChannelExpressFactory.createJoinChannelOptionsBuilder()
.withJoinRoomOptions(joinRoomOptions)
.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 |
---|---|---|---|
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
import PhenixSdk
let channelExpress: PhenixChannelExpress = ... // previously obtained
let renderLayer: CALayer = ... // previously obtained
// Using ChannelOptions means that the channel may or may not already exist.
// If the channel ID is known in advance, it is recommended to use `withChannelId` instead
// of `withChannelOptions` when assembling the `PhenixPublishToChannelOptions` below
let channelOptions = PhenixRoomServiceFactory.createChannelOptionsBuilder()
.withName("MyAwesomeChannel")
// Not required but if it is provided we will use this as the alias instead
// of pre-generating one for you:
.withAlias("MyAwesomeChannelAlias")
.buildChannelOptions()
// 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.audioEchoCancelationMode.rawValue] =
[PhenixDeviceConstraint.initWith(PhenixAudioEchoCancelationMode.on)]
let publishOptions = PhenixPCastExpressFactory.createPublishOptionsBuilder()
.withStreamToken("DIGEST:eyJhc...")
.withMediaConstraints(mediaConstraints)
.withPreviewRenderer(renderLayer)
.buildPublishOptions()
let publishToChannelOptions = PhenixChannelExpressFactory.createPublishToChannelOptionsBuilder()
.withChannelOptions(channelOptions)
.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 |
---|---|---|---|
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
import PhenixSdk
let channelExpress: PhenixChannelExpress = ... // previously obtained
let channelOptions = PhenixRoomServiceFactory.createChannelOptionsBuilder()
.withName("MyAwesomeChannel")
.withAlias("MyAwesomeChannelAlias") // Not required but if it is provided we will use this as the alias instead
// of pre-generating one for you.
.buildChannelOptions()
channelExpress.createChannel(
channelOptions,
{ (status: PhenixRequestStatus, channel: PhenixImmutableRoom?) in
guard status == .ok else {
// Handle room create error
return
}
// use `channel` to e.g. join
})
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 |
v2024-03-07T16:32:22.000Z