• Skip to Search
  • Skip to Content
  • Skip to Side Navigation
Getting StartedSDK ReferenceGlossary
  • Home
  • Getting Started
  • SDK Reference
  • Portal
  • How-To
  • Troubleshooting
  • FAQs
  • Reference
  • Glossary
REST API
Web SDK
Android SDK
iOS SDK
Unity SDK
React Native SDK
EdgeAuth SDK
  • Overview
  • Express API
    • Channel
    • Room
    • PCast™
  • Low-Level API
    • Room
    • Chat
    • PCast™
  • Examples
  • Release Notes

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;
10
11// 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);
14
15final PCastExpressOptions pcastExpressOptions =
16 PCastExpressFactory.createPCastExpressOptionsBuilder()
17 .withBackendUri("https://example.yourdomain.com/phenix/")
18 .withUnrecoverableErrorCallback((status, description) -> {
19 // Best option is to try rebuilding the ChannelExpress instance and/or quit
20 // your app
21 })
22 .buildPCastExpressOptions();
23
24final RoomExpressOptions roomExpressOptions =
25 RoomExpressFactory.createRoomExpressOptionsBuilder()
26 .withPCastExpressOptions(pcastExpressOptions)
27 .buildRoomExpressOptions();
28
29final ChannelExpressOptions channelExpressOptions =
30 ChannelExpressFactory.createChannelExpressOptionsBuilder()
31 .withRoomExpressOptions(roomExpressOptions)
32 .buildChannelExpressOptions();
33
34final ChannelExpress channelExpress = ChannelExpressFactory.createChannelExpress(channelExpressOptions);

ChannelExpressOptionsBuilder

NameTypeDefaultDescription
withRoomExpressOptions (required)RoomExpressOptionsSee RoomExpressOptionsBuilder
buildChannelExpressOptionsnoneBuilds 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;
11
12final ChannelExpress channelExpress = ...; // previously obtained
13final SurfaceView view = ...; // previously obtained
14
15final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
16
17// Just an example (you can omit renderer options if defaults are ok)
18final RendererOptions rendererOptions = new RendererOptions();
19rendererOptions.aspectRatioMode = AspectRatioMode.LETTERBOX;
20
21final JoinRoomOptions joinRoomOptions = RoomExpressFactory.createJoinRoomOptionsBuilder()
22 .withRoomId("us-central#xxxxx#channel")
23 .withCapabilities(new String[] { "real-time" })
24 .buildJoinRoomOptions();
25final JoinChannelOptions joinChannelOptions =
26 ChannelExpressFactory.createJoinChannelOptionsBuilder()
27 .withJoinRoomOptions(joinRoomOptions)
28 .withRenderer(renderSurface)
29 .withRendererOptions(rendererOptions)
30 .buildJoinChannelOptions();
31
32this.channelExpress.joinChannel(
33 joinChannelOptions,
34 (RequestStatus status, RoomService roomService) -> {
35 if (status != RequestStatus.OK) {
36 // Handle room join error
37 return;
38 }
39
40 // Important: Store room service reference, otherwise we will leave channel again
41 // 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 references
48 break;
49
50 case NO_STREAM_PLAYING:
51 // No stream playing in channel, update UI accordingy
52 break;
53
54 default:
55 // We failed to subscribe and retry attempts must have failed
56 break;
57 }
58 });

View Channel Parameters

NameTypeDescription
options (required)OptionsOptions to join channel with
joinChannelCallback (required)ChannelExpress.JoinChannelCallbackFunction to call on success/failure of joining the channel.
subscriberCallback (required)PCastExpress.SubscribeCallbackFunction to call on when the most recent presenter changes.

JoinChannelOptionsBuilder

NameTypeDefaultDescription
withJoinRoomOptions (required)JoinRoomOptionsSee JoinRoomOptionsBuilder
withRenderer (optional)AndroidVideoRenderSurfaceRender layer on which to display stream. If none of the withRenderer... methods are called, no renderer will be instantiated.
withRenderer (optional)noneWill trigger instantiation of renderer. Useful for audio only type streams that do not require a render surface.
withRendererOptions (optional)RendererOptionsOptions passed to renderer. Will trigger instantiation of renderer.
withStreamSelectionStrategy (optional)StreamSelectionStrategyStreamSelectionStrategy.MOST_RECENTDetermines how member streams are selected for subscriptions.
buildJoinChannelOptionsnoneBuilds the JoinChannelOptions

Stream Selection Strategy

StrategyDescription
StreamSelectionStrategy.MOST_RECENTSelect the most recent stream. Viewing stream changes any time a stream starts or is updated in the room.
StreamSelectionStrategy.HIGH_AVAILABILITYSelect 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

NameTypeDescription
statusPhenixRequestStatusThe status of the operation
roomServiceRoomServiceRoom service object

View Channel Subscriber Callback Status Codes

StatusDescription
okSuccessfully subscribed to presenter
no-stream-playingNo presenter in room to subscribe to. Wait for presenter to join.
variesSubscribe 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.

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;
16
17final ChannelExpress channelExpress = ...; // previously obtained
18final SurfaceView view = ...; // previously obtained
19
20final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
21
22// 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` instead
24// of `withChannelOptions` when assembling the `PublishToChannelOptions` below
25final ChannelOptions channelOptions = RoomServiceFactory.createChannelOptionsBuilder()
26 .withName("MyAwesomeChannel")
27 // Not required but if it is provided we will use this as the alias instead
28 // of pre-generating one for you:
29 .withAlias("MyAwesomeChannelAlias")
30 .buildChannelOptions();
31
32// Example constraints. Audio and video are enabled by default
33final 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)));
42
43final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
44 .withCapabilities(new String[]{"hd", "streaming"})
45 .withMediaConstraints(mediaConstraints)
46 .withPreviewRenderer(renderSurface)
47 .buildPublishOptions();
48
49final PublishToChannelOptions publishToChannelOptions =
50 ChannelExpressFactory.createPublishToChannelOptionsBuilder()
51 .withChannelOptions(channelOptions)
52 .withPublishOptions(publishOptions)
53 .buildPublishToChannelOptions();
54
55channelExpress.publishToChannel(
56 publishToChannelOptions,
57 (publishStatus, roomService, publisher, previewRenderer) -> {
58 if (publishStatus != RequestStatus.OK) {
59 // Handle channel publish error
60 return;
61 }
62
63 // Important: Store publisher reference, otherwise we will stop publishing again immediately:
64 currentPublisher = publisher;
65 }
66);
67
68// OR (without a preview):
69
70channelExpress.publishToChannel(
71 publishToChannelOptions,
72 (publishStatus, roomService, publisher) -> {
73 if (publishStatus != RequestStatus.OK) {
74 // Handle channel publish error
75 return;
76 }
77
78 // Important: Store publisher reference, otherwise we will stop publishing again immediately:
79 currentPublisher = publisher;
80 }
81);

Publish To Channel Parameters

NameTypeDescription
options (required)OptionsOptions to publish to channel with
publisherCallback (required)FunctionFunction to call on success/failure of publishing to the channel

PublishToChannelOptionsBuilder

Name
Type
Default
Description
withChannelOptions (required)ChannelOptionsSee ChannelOptionsBuilder. If omitted, then withChannelId needs to be provided.
withChannelId (required)StringID of channel to publish to. If omitted, then withChannelOptions needs to be provided.
withPublishOptions (required)PublishOptionsEither provide this or remote publish options
withPublishRemoteOptions (required)RemotePublishOptionsEither provide this or publish options.
withMemberRole (optional)MemberRoleMemberRole.PRESENTERRole of member to join channel as (used if not already in channel).
withStreamType (optional)StreamTypeStreamType.PRESENTATIONType of stream to publish.
withScreenName (optional)Stringrandom unique stringScreen name of self member
withViewerStreamSelectionStrategy (optional)StreamSelectionStrategyStreamSelectionStrategy.MOST_RECENTStream selection strategy; must match the strategy channel viewers are using.
buildPublishToChannelOptionsnoneBuilds the PublishToChannelOptions

ChannelOptionsBuilder

NameTypeDefaultDescription
withName (required)StringName of channel
withAlias (optional)StringgeneratedChannel Alias
withDescription (optional)StringemptyChannel description
buildChannelOptionsnoneBuilds the ChannelOptions

Publish To Channel Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation
roomServiceRoomServicePhenix room service
publisherExpressPublisherPublisher 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;
5
6final ChannelExpress channelExpress = ...; // previously obtained
7
8final ChannelOptions channelOptions = RoomServiceFactory.createChannelOptionsBuilder()
9 .withName("MyAwesomeChannel")
10 // Not required but if it is provided we will use this as the alias instead
11 // of pre-generating one for you.
12 .withAlias("MyAwesomeChannelAlias")
13 .buildChannelOptions();
14
15this.channelExpress.createChannel(
16 channelOptions,
17 (status, channel) -> {
18 if (status != RequestStatus.OK) {
19 // Handle room create error
20 return;
21 }
22
23 // use `channel` to e.g. join
24 });

Express Create Channel Parameters

NameTypeDescription
options (required)ChannelOptionsOptions to create channel with
callback (required)FunctionFunction to call on success/failure of creating to the channel. See Create Channel Callback Arguments

Express Create Channel Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation.
channelImmutableRoomImmutable room object
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10