PCast™ Express

The PCast™ Express extends the PCast™ API to provide a single-step configuration based API for:

• Publishing local media
• Subscribing to published streams

This API is intended to be used as a supplement to the Room Express although it can be used to stream all on its own.

Initializing

import android.content.Context;

import com.phenixrts.common.RequestStatus;
import com.phenixrts.environment.android.AndroidContext;
import com.phenixrts.express.PCastExpress;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.PCastExpressOptions;
import com.phenixrts.pcast.PCastInitializeOptions;

// 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((RequestStatus status, String description) -> {
          // Best to restart app, or attempt to re-create PCastExpress
        })
        .buildPCastExpressOptions();

final PCastExpress pcastExpress = PCastExpressFactory.createPCastExpress(pcastExpressOptions);

PCastExpressOptionsBuilder

Publishing Local Media

Publish local user media:

• Camera
• Microphone
• Screen (on supported devices)

import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.ExpressPublisher;
import com.phenixrts.express.PCastExpress;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.PublishOptions;
import com.phenixrts.pcast.AudioEchoCancellationMode;
import com.phenixrts.pcast.DeviceCapability;
import com.phenixrts.pcast.DeviceConstraint;
import com.phenixrts.pcast.FacingMode;
import com.phenixrts.pcast.UserMediaOptions;
import java.util.Arrays;

final PCastExpress pcastExpress = ...;  // previously obtained

final UserMediaOptions userMediaConstraints = new UserMediaOptions();

userMediaConstraints.getVideoOptions().enabled = true;
userMediaConstraints.getVideoOptions().capabilityConstraints.put(
    DeviceCapability.FACING_MODE,
    Arrays.asList(new DeviceConstraint(FacingMode.USER)));

userMediaConstraints.getAudioOptions().enabled = true;
userMediaConstraints.getAudioOptions().capabilityConstraints.put(
    DeviceCapability.AUDIO_ECHO_CANCELLATION_MODE,
    Arrays.asList(new DeviceConstraint(AudioEchoCancellationMode.ON)));

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

pcastExpress.publish(publishOptions, (RequestStatus status, ExpressPublisher publisher) -> {
  if (status == RequestStatus.OK) {
    // Do something with publisher
  } else {
    // Handle error
  }
});

// Create a publisher
final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
    .withStreamToken("DIGEST:eyJhc...")
    .withMediaConstraints(userMediaConstraints)
    .buildPublishOptions();

pcastExpress.publish(
    publishOptions, (RequestStatus status, ExpressPublisher publisher) -> {
  if (status == RequestStatus.OK) {
    // Do something with publisher
  } else {
    // Handle error
  }
});

Notes:

• The publisher will remain active for as long as you keep a reference to it
• Force release of the publisher by invoking dispose on it

Publisher Parameters

PublishOptionsBuilder

ExpressPublisher Callback Arguments

ExpressPublisher

Shares most methods with regular Publisher returned by PCast™, see Publish a Stream.

Subscribing to Published Media

Subscribe to streams published with the Phenix platform

import android.view.SurfaceView;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.ExpressSubscriber;
import com.phenixrts.express.PCastExpress;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.SubscribeOptions;
import com.phenixrts.pcast.Renderer;
import com.phenixrts.pcast.android.AndroidVideoRenderSurface;

final PCastExpress pcastExpress = ...;  // previously obtained
final SurfaceView view = ...;  // previously obtained

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

final SubscribeOptions subscribeOptions = PCastExpressFactory.createSubscribeOptionsBuilder()
    .withStreamId("us-west#us-west1-b.zzzzzzzz.20000000.xxxxxxxx")
    .withStreamToken("DIGEST:eyJhc...")
    .withRenderer(renderSurface)
    .buildSubscribeOptions();

pcastExpress.subscribe(
    subscribeOptions,
    (RequestStatus status, ExpressSubscriber subscriber, Renderer renderer) -> {
  if (status == RequestStatus.OK) {
    // Do something with subscriber

if (renderer != null) {
      // Returned if `withRenderer...` option was enabled - Do something with renderer
    }
  } else {
    // Handle error
  }
});

Notes:

• The renderer will already have been started by the time it is received by your callback
• If a renderer is provided, your ExpressSubscriber will be kept alive for as long as you are referencing that renderer. There is no need to also store a reference to the subscriber in that case
• Once subscriber and renderer references have been released, the renderer and subscription will automatically be stopped
• To force release renderer or subscriber, you can invoke dispose, which will dispose the underlying resources

Subscribe Parameters

Subscribe Options

ExpressSubscriber

Shares most methods with regular MediaStream returned by PCast™, see Subscribe to a Stream.

NielsenId3TagCallback Arguments

NielsenId3ErrorCallback Arguments

Monitor

Note: On Android, the monitor options are currently ignored, but the callbacks for stream setup and stream ended will be triggered.

Monitor callbacks and options can be passed to subscribe and publish options builders. The first callback gets invoked only when we internally fail to setup a stream. The second callback gets invoked whenever a stream ends, whether it is due to failure or not. The retry OptionalAction allows you to retry publishing or subscribing to the failed stream. You must test first whether there is a retry action present by calling isPresent as it may not be possible to retry the stream (example: a stream that ended normally cannot be retried). You should call dismiss on the retry action to dismiss it, dispose has the same effect. You also may defer invoking the retry action.

Example Monitor for subscribing

import com.phenixrts.common.OptionalAction;
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.ExpressSubscriber;
import com.phenixrts.express.MonitorOptions;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.SubscribeOptions;
import com.phenixrts.pcast.StreamEndedReason;

final MonitorOptions monitorOptions = PCastExpressFactory.createMonitorOptionsBuilder()
    .buildMonitorOptions();

final SubscribeOptions subscribeOptions = PCastExpressFactory.createSubscribeOptionsBuilder()
    .withStreamId("us-west#us-west1-b.zzzzzzzz.20000000.xxxxxxxx")
    .withStreamToken("DIGEST:eyJhc...")
    .withMonitor(
        (RequestStatus status, OptionalAction retry) -> {
          if (retry.isPresent()) {
            if (shouldRetry()) {  // <- Your logic goes here
              retry.perform();
            } else {
              retry.dismiss();
            }
          }
        },
        (StreamEndedReason reason, String description, OptionalAction retry) -> {
          if (retry.isPresent()) {
            if (reason == StreamEndedReason.FAILED) {  // <- Just an example
              retry.perform();
            } else {
              retry.dismiss();
            }
          }
        },
        monitorOptions)
    .buildSubscribeOptions();

OptionalAction

MonitorSetupFailedCallback Callback Arguments

MonitorStreamEndedCallback Callback Arguments

Express Get User Media

Get local user media. For now this is merely a wrapper around Get Local User Media.

import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.PCastExpress;
import com.phenixrts.pcast.UserMediaOptions;
import com.phenixrts.pcast.UserMediaStream;

final PCastExpress pcastExpress = ...;  // previously obtained

final UserMediaOptions userMediaOptions = new UserMediaOptions();

pcastExpress.getUserMedia(userMediaOptions, (RequestStatus status, UserMediaStream userMedia) -> {
  if (status == RequestStatus.OK) {
    // Do something with user media stream
  } else {
    // Handle error
  }
});

Express Get User Media Parameters

Express Get User Media Callback Arguments

Get PCast™

Get the underlying instance of the PCast™. This is preferred to creating another instance as this will introduce more overhead.

import com.phenixrts.express.PCastExpress;
import com.phenixrts.pcast.PCast;

final PCastExpress pcastExpress = ...;  // previously obtained

final PCast pcast = pcastExpress.getPCast();

Handling authentication failure

To observe SDK AuthenticationStatus:

import com.phenixrts.common.AuthenticationStatus;
import com.phenixrts.common.Disposable;

Disposable disposable = ...  // declare a property

this.disposable = pcastExpress.getObservableAuthenticationStatus().subscribe((change) -> {
  if (change == AuthenticationStatus.UNAUTHENTICATED) {
    this.handleUnauthenticatedStatus();
  }
});

To fetch a new fresh Authentication token and set a new fetched token to SDK:

import com.phenixrts.common.RequestStatus;

void fetchANewAuthenticationToken(closure: (token: String) -> Unit) {
    // This method calls a client backend to fetch a new authentication token generated using [EdgeAuth library](../api/#creating-authentication-and-stream-tokens).
    // and returns a fetched token using closure callback
}

void handleUnauthenticatedStatus() {
    fetchANewAuthenticationToken((token) -> {
        // Set a new token to SDK
        final RequestStatus status = this.pcastExpress.setAuthenticationToken(token)
        if (status != PhenixRequestStatus.ok) {
            // Handle error when setting a new token
            // This situation can only occur if the token is invalid and cannot be processed by the SDK.
        }
    });
}

PCastExpress

When the SDK attempts to authenticate with an expired token, it receives an "unauthenticated" status. In this state, publish and subscribe operations are not possible.

The code sample shows how to re-authenticate the SDK when necessary.

Notes:

• The implementation of ObservableAuthenticationStatus subscriber should be asynchronous and should not contain any blocking operations.
• The client fetchANewAuthenticationToken method should be executed as quickly as possible. During the “unauthenticated” state, the SDK will be unable to perform publish or subscribe operations.
• Attempts to publish and subscribe, when the SDK's authentication status is not authenticated, will wait for successful authentication for 18 seconds before timing out.

Clean up

Subscribers and publishers are kept alive for as long as they are being referenced in your app. To force SDK objects to release their resources, you can call dispose on them. PCastExpress will only shut down once it is no longer being referenced or dispose has been called on it.