Android Channel Express - PhenixRTS Docs

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

PCastExpressFactory

Name	Signature	Returns	Description
createPCastExpressOptionsBuilder	(UnrecoverableErrorCallback)	PCastExpressOptionsBuilder	Creates PCastExpressOptionsBuilder with unrecoverable error callback.

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((status, description) -> {
          // Best option is to try rebuilding the ChannelExpress instance and/or quit
        })
        .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.

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.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 JoinChannelOptions joinChannelOptions =
    ChannelExpressFactory.createJoinChannelOptionsBuilder()
        .withStreamToken("stream token")
        .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
withStreamToken (required)	String		The publish token generated using the Phenix EdgeAuth library that contains a Channel ID or Alias.
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.

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());

// 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)
    .buildPublishOptions();

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

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
withPublishOptions (required)	PublishOptions		Provide 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`

Publish To Channel Callback Arguments

Name	Type	Description
status	RequestStatus	The status of the operation
roomService	RoomService	Phenix room service
publisher	ExpressPublisher	Publisher object