Page Content
Channel Express - Deprecated
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 |
v2025-01-13T17:19:39.000Z