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
Java
1import android.content.Context;2import com.phenixrts.common.RequestStatus;3import com.phenixrts.environment.android.AndroidContext;4import com.phenixrts.express.ChannelExpressFactory;5import com.phenixrts.express.ChannelExpressOptions;6import com.phenixrts.express.PCastExpressFactory;7import com.phenixrts.express.PCastExpressOptions;8import com.phenixrts.express.RoomExpressFactory;9import com.phenixrts.express.RoomExpressOptions;1011// IMPORTANT: Before accessing any of the static factories, make sure the context is passed to Phenix:12final Context context = ...; // e.g. Activity.getApplication();13AndroidContext.setContext(context);1415final PCastExpressOptions pcastExpressOptions =16 PCastExpressFactory.createPCastExpressOptionsBuilder()17 .withStreamToken("DIGEST:eyJhc...")18 .withUnrecoverableErrorCallback((status, description) -> {19 // Best option is to try rebuilding the ChannelExpress instance and/or quit20 // your app21 })22 .buildPCastExpressOptions();2324final RoomExpressOptions roomExpressOptions =25 RoomExpressFactory.createRoomExpressOptionsBuilder()26 .withPCastExpressOptions(pcastExpressOptions)27 .buildRoomExpressOptions();2829final ChannelExpressOptions channelExpressOptions =30 ChannelExpressFactory.createChannelExpressOptionsBuilder()31 .withRoomExpressOptions(roomExpressOptions)32 .buildChannelExpressOptions();3334final 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
1import android.view.SurfaceView;2import com.phenixrts.common.RequestStatus;3import com.phenixrts.express.ChannelExpress;4import com.phenixrts.express.ChannelExpressFactory;5import com.phenixrts.express.JoinChannelOptions;6import com.phenixrts.express.JoinRoomOptions;7import com.phenixrts.express.RoomExpressFactory;8import com.phenixrts.pcast.RendererOptions;9import com.phenixrts.pcast.android.AndroidVideoRenderSurface;10import com.phenixrts.room.RoomService;1112final ChannelExpress channelExpress = ...; // previously obtained13final SurfaceView view = ...; // previously obtained1415final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());1617// Just an example (you can omit renderer options if defaults are ok)18final RendererOptions rendererOptions = new RendererOptions();19rendererOptions.aspectRatioMode = AspectRatioMode.LETTERBOX;2021final JoinRoomOptions joinRoomOptions = RoomExpressFactory.createJoinRoomOptionsBuilder()22 .withRoomId("us-central#xxxxx#channel")23 .withStreamToken("DIGEST:eyJhc...")24 .buildJoinRoomOptions();25final JoinChannelOptions joinChannelOptions =26 ChannelExpressFactory.createJoinChannelOptionsBuilder()27 .withJoinRoomOptions(joinRoomOptions)28 .withRenderer(renderSurface)29 .withRendererOptions(rendererOptions)30 .buildJoinChannelOptions();3132this.channelExpress.joinChannel(33 joinChannelOptions,34 (RequestStatus status, RoomService roomService) -> {35 if (status != RequestStatus.OK) {36 // Handle room join error37 return;38 }3940 // Important: Store room service reference, otherwise we will leave channel again41 // as soon as this RoomService instance is garbage collected:42 OuterClass.this.currentRoomService = roomService;43 },44 (RequestStatus status, ExpressSubscriber subscriber, Renderer renderer) -> {45 switch (status) {46 case OK:47 // Successfully subscribed to a stream. No need to hold on to any references48 break;4950 case NO_STREAM_PLAYING:51 // No stream playing in channel, update UI accordingy52 break;5354 default:55 // We failed to subscribe and retry attempts must have failed56 break;57 }58 });
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
1import android.view.SurfaceView;2import com.phenixrts.common.RequestStatus;3import com.phenixrts.express.ChannelExpress;4import com.phenixrts.express.ChannelExpressFactory;5import com.phenixrts.express.PCastExpressFactory;6import com.phenixrts.express.PublishOptions;7import com.phenixrts.express.PublishToChannelOptions;8import com.phenixrts.express.RoomExpressFactory;9import com.phenixrts.pcast.DeviceCapability;10import com.phenixrts.pcast.FacingMode;11import com.phenixrts.pcast.RendererOptions;12import com.phenixrts.pcast.UserMediaOptions;13import com.phenixrts.pcast.android.AndroidVideoRenderSurface;14import com.phenixrts.room.ChannelOptions;15import com.phenixrts.room.RoomServiceFactory;1617final ChannelExpress channelExpress = ...; // previously obtained18final SurfaceView view = ...; // previously obtained1920final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());2122// Using ChannelOptions means that the channel may or may not already exist.23// If the channel ID is known in advance, it is recommended to use `withChannelId` instead24// of `withChannelOptions` when assembling the `PublishToChannelOptions` below25final ChannelOptions channelOptions = RoomServiceFactory.createChannelOptionsBuilder()26 .withName("MyAwesomeChannel")27 // Not required but if it is provided we will use this as the alias instead28 // of pre-generating one for you:29 .withAlias("MyAwesomeChannelAlias")30 .buildChannelOptions();3132// Example constraints. Audio and video are enabled by default33final UserMediaOptions mediaConstraints = new UserMediaOptions();34mediaConstraints.getVideoOptions().capabilityConstraints.put(35 DeviceCapability.FACING_MODE, Arrays.asList(new DeviceConstraint(FacingMode.USER)));36mediaConstraints.getVideoOptions().capabilityConstraints.put(37 DeviceCapability.FRAME_RATE, Arrays.asList(new DeviceConstraint(15)));38mediaConstraints.getVideoOptions().capabilityConstraints.put(39 DeviceCapability.HEIGHT, Arrays.asList(new DeviceConstraint(720)));40mediaConstraints.getVideoOptions().capabilityConstraints.put(41 DeviceCapability.WIDTH, Arrays.asList(new DeviceConstraint(1280)));4243final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()44 .withStreamToken("DIGEST:eyJhc...")45 .withMediaConstraints(mediaConstraints)46 .withPreviewRenderer(renderSurface)47 .buildPublishOptions();4849final PublishToChannelOptions publishToChannelOptions =50 ChannelExpressFactory.createPublishToChannelOptionsBuilder()51 .withChannelOptions(channelOptions)52 .withPublishOptions(publishOptions)53 .buildPublishToChannelOptions();5455channelExpress.publishToChannel(56 publishToChannelOptions,57 (publishStatus, roomService, publisher, previewRenderer) -> {58 if (publishStatus != RequestStatus.OK) {59 // Handle channel publish error60 return;61 }6263 // Important: Store publisher reference, otherwise we will stop publishing again immediately:64 currentPublisher = publisher;65 }66);6768// OR (without a preview):6970channelExpress.publishToChannel(71 publishToChannelOptions,72 (publishStatus, roomService, publisher) -> {73 if (publishStatus != RequestStatus.OK) {74 // Handle channel publish error75 return;76 }7778 // Important: Store publisher reference, otherwise we will stop publishing again immediately:79 currentPublisher = publisher;80 }81);
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
1import com.phenixrts.common.RequestStatus;2import com.phenixrts.express.ChannelExpress;3import com.phenixrts.room.ChannelOptions;4import com.phenixrts.room.RoomServiceFactory;56final ChannelExpress channelExpress = ...; // previously obtained78final ChannelOptions channelOptions = RoomServiceFactory.createChannelOptionsBuilder()9 .withName("MyAwesomeChannel")10 // Not required but if it is provided we will use this as the alias instead11 // of pre-generating one for you.12 .withAlias("MyAwesomeChannelAlias")13 .buildChannelOptions();1415this.channelExpress.createChannel(16 channelOptions,17 (status, channel) -> {18 if (status != RequestStatus.OK) {19 // Handle room create error20 return;21 }2223 // use `channel` to e.g. join24 });
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 |
v2023-09-12T20:09:36.000Z