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

Java
import android.content.Context;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.environment.android.AndroidContext;
import com.phenixrts.express.ChannelExpressFactory;
import com.phenixrts.express.ChannelExpressOptions;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.PCastExpressOptions;
import com.phenixrts.express.RoomExpressFactory;
import com.phenixrts.express.RoomExpressOptions;

// IMPORTANT: Before accessing any of the static factories, make sure the context is passed to Phenix:
final Context context = ...;  // e.g. Activity.getApplication();
AndroidContext.setContext(context);

final PCastExpressOptions pcastExpressOptions =
    PCastExpressFactory.createPCastExpressOptionsBuilder()
        .withStreamToken("DIGEST:eyJhc...")
        .withUnrecoverableErrorCallback((status, description) -> {
          // Best option is to try rebuilding the ChannelExpress instance and/or quit
          // your app
        })
        .buildPCastExpressOptions();

final RoomExpressOptions roomExpressOptions =
    RoomExpressFactory.createRoomExpressOptionsBuilder()
        .withPCastExpressOptions(pcastExpressOptions)
        .buildRoomExpressOptions();

final ChannelExpressOptions channelExpressOptions =
    ChannelExpressFactory.createChannelExpressOptionsBuilder()
        .withRoomExpressOptions(roomExpressOptions)
        .buildChannelExpressOptions();

final ChannelExpress channelExpress = ChannelExpressFactory.createChannelExpress(channelExpressOptions);

ChannelExpressOptionsBuilder

Name	Type	Default	Description
withRoomExpressOptions (required)	RoomExpressOptions		See RoomExpressOptionsBuilder
buildChannelExpressOptions	none		Builds the `ChannelExpressOptions`

View a Channel

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

Java
import android.view.SurfaceView;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.ChannelExpress;
import com.phenixrts.express.ChannelExpressFactory;
import com.phenixrts.express.JoinChannelOptions;
import com.phenixrts.express.JoinRoomOptions;
import com.phenixrts.express.RoomExpressFactory;
import com.phenixrts.pcast.RendererOptions;
import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
import com.phenixrts.room.RoomService;

final ChannelExpress channelExpress = ...;  // previously obtained
final SurfaceView view = ...;  // previously obtained

final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());

// Just an example (you can omit renderer options if defaults are ok)
final RendererOptions rendererOptions = new RendererOptions();
rendererOptions.aspectRatioMode = AspectRatioMode.LETTERBOX;

final JoinRoomOptions joinRoomOptions = RoomExpressFactory.createJoinRoomOptionsBuilder()
    .withRoomId("us-central#xxxxx#channel")
    .withStreamToken("DIGEST:eyJhc...")
    .buildJoinRoomOptions();
final JoinChannelOptions joinChannelOptions =
    ChannelExpressFactory.createJoinChannelOptionsBuilder()
        .withJoinRoomOptions(joinRoomOptions)
        .withRenderer(renderSurface)
        .withRendererOptions(rendererOptions)
        .buildJoinChannelOptions();

this.channelExpress.joinChannel(
    joinChannelOptions,
    (RequestStatus status, RoomService roomService) -> {
      if (status != RequestStatus.OK) {
        // Handle room join error
        return;
      }

      // Important: Store room service reference, otherwise we will leave channel again
      // as soon as this RoomService instance is garbage collected:
      OuterClass.this.currentRoomService = roomService;
    },
    (RequestStatus status, ExpressSubscriber subscriber, Renderer renderer) -> {
      switch (status) {
        case OK:
          // Successfully subscribed to a stream. No need to hold on to any references
          break;

        case NO_STREAM_PLAYING:
          // No stream playing in channel, update UI accordingy
          break;

        default:
          // We failed to subscribe and retry attempts must have failed
          break;
      }
    });

View Channel Parameters

Name	Type	Description
options (required)	Options	Options to join channel with
joinChannelCallback (required)	ChannelExpress.JoinChannelCallback	Function to call on success/failure of joining the channel.
subscriberCallback (required)	PCastExpress.SubscribeCallback	Function to call on when the most recent presenter changes.

JoinChannelOptionsBuilder

Name	Type	Default	Description
withJoinRoomOptions (required)	JoinRoomOptions		See JoinRoomOptionsBuilder
withStreamToken (required)	NSString		The publish token generated using the Phenix EdgeAuth library.
withRenderer (optional)	AndroidVideoRenderSurface		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)	RendererOptions		Options passed to renderer. Will trigger instantiation of renderer.
withStreamSelectionStrategy (optional)	StreamSelectionStrategy	StreamSelectionStrategy.MOST_RECENT	Determines how member streams are selected for subscriptions.
buildJoinChannelOptions	none		Builds the `JoinChannelOptions`

Stream Selection Strategy

Strategy	Description
StreamSelectionStrategy.MOST_RECENT	Select the most recent stream. Viewing stream changes any time a stream starts or is updated in the room.
StreamSelectionStrategy.HIGH_AVAILABILITY	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	RoomService	Room service object

View Channel Subscriber Callback Status Codes

Status	Description
ok	Successfully subscribed to presenter
no-stream-playing	No presenter in room 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.

Java
import android.view.SurfaceView;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.ChannelExpress;
import com.phenixrts.express.ChannelExpressFactory;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.PublishOptions;
import com.phenixrts.express.PublishToChannelOptions;
import com.phenixrts.express.RoomExpressFactory;
import com.phenixrts.pcast.DeviceCapability;
import com.phenixrts.pcast.FacingMode;
import com.phenixrts.pcast.RendererOptions;
import com.phenixrts.pcast.UserMediaOptions;
import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
import com.phenixrts.room.ChannelOptions;
import com.phenixrts.room.RoomServiceFactory;

final ChannelExpress channelExpress = ...;  // previously obtained
final SurfaceView view = ...;  // previously obtained

final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());

// 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 `PublishToChannelOptions` below
final ChannelOptions channelOptions = RoomServiceFactory.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
final UserMediaOptions mediaConstraints = new UserMediaOptions();
mediaConstraints.getVideoOptions().capabilityConstraints.put(
    DeviceCapability.FACING_MODE, Arrays.asList(new DeviceConstraint(FacingMode.USER)));
mediaConstraints.getVideoOptions().capabilityConstraints.put(
    DeviceCapability.FRAME_RATE, Arrays.asList(new DeviceConstraint(15)));
mediaConstraints.getVideoOptions().capabilityConstraints.put(
    DeviceCapability.HEIGHT, Arrays.asList(new DeviceConstraint(720)));
mediaConstraints.getVideoOptions().capabilityConstraints.put(
    DeviceCapability.WIDTH, Arrays.asList(new DeviceConstraint(1280)));

final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
    .withStreamToken("DIGEST:eyJhc...")
    .withMediaConstraints(mediaConstraints)
    .withPreviewRenderer(renderSurface)
    .buildPublishOptions();

final PublishToChannelOptions publishToChannelOptions =
    ChannelExpressFactory.createPublishToChannelOptionsBuilder()
        .withChannelOptions(channelOptions)
        .withPublishOptions(publishOptions)
        .buildPublishToChannelOptions();

channelExpress.publishToChannel(
    publishToChannelOptions,
    (publishStatus, roomService, publisher, previewRenderer) -> {
      if (publishStatus != RequestStatus.OK) {
        // Handle channel publish error
        return;
      }

      // Important: Store publisher reference, otherwise we will stop publishing again immediately:
      currentPublisher = publisher;
    }
);

// OR (without a preview):

channelExpress.publishToChannel(
    publishToChannelOptions,
    (publishStatus, roomService, publisher) -> {
      if (publishStatus != RequestStatus.OK) {
        // Handle channel publish error
        return;
      }

      // Important: Store publisher reference, otherwise we will stop publishing again immediately:
      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

PublishToChannelOptionsBuilder

Name	Type	Default	Description
withChannelOptions (required)	ChannelOptions		See ChannelOptionsBuilder. 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)	PublishOptions		Publish options
withMemberRole (optional)	MemberRole	MemberRole.PRESENTER	Role of member to join channel as (used if not already in channel).
withStreamType (optional)	StreamType	StreamType.PRESENTATION	Type of stream to publish.
withScreenName (optional)	String	random unique string	Screen name of self member
withViewerStreamSelectionStrategy (optional)	StreamSelectionStrategy	StreamSelectionStrategy.MOST_RECENT	Stream selection strategy; must match the strategy channel viewers are using.
buildPublishToChannelOptions	none		Builds the `PublishToChannelOptions`

ChannelOptionsBuilder

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 `ChannelOptions`

Publish To Channel Callback Arguments

Name	Type	Description
status	RequestStatus	The status of the operation
roomService	RoomService	Phenix room service
publisher	ExpressPublisher	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.

Java
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.ChannelExpress;
import com.phenixrts.room.ChannelOptions;
import com.phenixrts.room.RoomServiceFactory;

final ChannelExpress channelExpress = ...;  // previously obtained

final ChannelOptions channelOptions = RoomServiceFactory.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();

this.channelExpress.createChannel(
    channelOptions,
    (status, channel) -> {
      if (status != RequestStatus.OK) {
        // Handle room create error
        return;
      }

      // use `channel` to e.g. join
    });

Express Create Channel Parameters

Name	Type	Description
options (required)	ChannelOptions	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	RequestStatus	The status of the operation.
channel	ImmutableRoom	Immutable room object

Page Content

v2023-09-12T20:09:36.000Z

Channel Express

Initializing#Copied URL

ChannelExpressOptionsBuilder#Copied URL

View a Channel#Copied URL

View Channel Parameters#Copied URL

JoinChannelOptionsBuilder#Copied URL

Stream Selection Strategy#Copied URL

Express Join Channel Callback Arguments#Copied URL

View Channel Subscriber Callback Status Codes#Copied URL

Publish to a Channel#Copied URL

Publish To Channel Parameters#Copied URL

PublishToChannelOptionsBuilder#Copied URL

ChannelOptionsBuilder#Copied URL

Publish To Channel Callback Arguments#Copied URL

Create a Channel (deprecated)#Copied URL

Express Create Channel Parameters#Copied URL

Express Create Channel Callback Arguments#Copied URL