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 backendEndpointUri = "https://example.yourdomain.com/phenix/"

let pcastExpressOptions = PhenixPCastExpressFactory.createPCastExpressOptionsBuilder()
    .withBackendUri(backendEndpointUri)
    .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)
    .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.
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 a local or remote 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()
    .withCapabilities(["hd", "streaming"])  // Example capabilities
    .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		Either provide this or remote publish options.
withPublishRemoteOptions (required)	PhenixRemotePublishOptions		Either provide this or publish 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

Page Content

v2023-01-31T21:25:10