PCast™ Express

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

Publishing local media
Publishing remote media (ingest)
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

Java
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()
        .withBackendUri("https://example.yourdomain.com/phenix/")
        .withUnrecoverableErrorCallback((RequestStatus status, String description) -> {
          // Best to restart app, or attempt to re-create PCastExpress
        })
        .buildPCastExpressOptions();

final PCastExpress pcastExpress = PCastExpressFactory.createPCastExpress(pcastExpressOptions);

PCastExpressOptionsBuilder

Name	Type	Default	Description
withBackendUri (required)	String		Url to your backend. We send requests here to authenticate and get streaming tokens.
withAuthenticationData (optional)	String		Your authentication data for the user. On every request, this will be sent to your backend through a HTTP POST request and all its attributes would be accessible on the request body. Needs to be valid JSON.
withAuthenticationToken (optional)	String		The authentication token generated using the Phenix EdgeAuth library.
withUnrecoverableErrorCallback (optional)		PCastExpressOptions.UnrecoverableErrorCallback	Function to be called when authentication fails or a failure occurs that is unrecoverable.
withPCastUri (optional)	String		Allows overriding default PCast™ URI.
withPCastInitializationOptions (optional)	PCastInitializeOptions		Use custom options when initializing PCast™.
withAuthenticationRouteOverride (optional)	String	auth	Allows override of default route for authentication tokens
withStreamRouteOverride (optional)	String	stream	Allows override of default route for stream tokens
buildPCastExpressOptions	none		Builds the `PCastExpressOptions`

Publishing Local Media

Publish local user media:

Camera
Microphone
Screen (on supported devices)

Java
import android.view.SurfaceView;
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.AudioEchoCancelationMode;
import com.phenixrts.pcast.DeviceCapability;
import com.phenixrts.pcast.DeviceConstraint;
import com.phenixrts.pcast.FacingMode;
import com.phenixrts.pcast.Renderer;
import com.phenixrts.pcast.UserMediaOptions;
import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
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_CANCELATION_MODE,
    Arrays.asList(new DeviceConstraint(AudioEchoCancelationMode.ON)));

final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
    .withCapabilities(new String[] {"real-time"})
    .withMediaConstraints(userMediaConstraints)
    .buildPublishOptions();

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


// Create a publisher with an automatically started preview renderer
final SurfaceView view = ...;  // previously obtained
final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());

final PublishOptions publishOptionsWithPreview = PCastExpressFactory.createPublishOptionsBuilder()
    .withCapabilities(new String[] {"real-time"})
    .withMediaConstraints(userMediaConstraints)
    .withPreviewRenderer(renderSurface)
    .buildPublishOptions();

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

Notes:

The preview renderer will already have been started by the time it is received by your callback
The publisher will remain active for as long as you keep a reference to it
You can force release of the publisher by invoking close on it

Publisher Parameters

Name	Type	Description
options (required)	PublishOptions	Publish options
callback (required)	PCastExpress.PublishCallback or PCastExpress.PublishWithPreviewCallback	Callback for error/success handling

PublishOptionsBuilder

Name	Type	Description
withMediaConstraints (required)	UserMediaOptions	getUserMedia options Constraints to get the user media.
withUserMedia (optional)	UserMediaStream	alternative to `withMediaConstraints` - you can pass user media stream returned from getUserMedia.
withCapabilities (optional)	String[]	The list of all capabilities to publish with. Default is empty array.
withPreviewRenderer (optional)	AndroidVideoRenderSurface	Render layer on which to display local preview. If none of the `withPreview...` methods are called, no preview renderer will be instantiated.
withPreviewRenderer (optional)	none	Will trigger instantiation of preview renderer. Useful for audio only type streams that do not require a render surface.
withPreviewRendererOptions (optional)	RendererOptions	Options passed to preview renderer. Will trigger instantiation of preview renderer.
withMonitor (optional)	MonitorOptions.SetupFailedCallback, MonitorOptions.StreamEndedCallback, MonitorOptions	Options for monitoring a publisher for failure.
withConnectOptions (optional)	Strings[]	List of options for publishing.
withTags (optional)	Strings[]	Tags for the stream.
withStreamToken (optional)	String	The publish token generated using the Phenix EdgeAuth library.
buildPublishOptions	none	Builds the `PublishOptions`

ExpressPublisher Callback Arguments

Name	Type	Description
status	RequestStatus	The status of the operation
publisher	ExpressPublisher	Publisher object
previewRenderer	Renderer	Optionally provided if any of the `withPreview...` methods were called on the options builder and `publish` is invoked with `withPreview`.

ExpressPublisher

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

Name	Signature	Returns	Description
stop	()	void	Stops publisher. Subscribers will receive stream ended.
stop	(reason)	void	Stops publisher with a custom reason. Subscribers will receive `StreamEndedReason.CUSTOM` reason.
enableAudio	()	void	Unmutes audio.
disableAudio	()	void	Mutes audio.
enableVideo	()	void	Unmutes video.
disableVideo	()	void	Mutes video (black frames).
setDataQualityChangedCallback	(callback)	void	Listen for Data Quality Feedback
limitBandwidth	(bandwidthLimitInBps)	Disposable	Temporarily limit published video bitrate, see Limit Bitrate
getStreamId	()	String	Returns stream ID of publisher
hasEnded	()	bool	Indicates whether publisher has ended, e.g. by `stop` having been invoked

Publishing Remote Media (Ingest)

Publish from remote sources into the Phenix platform. This enables us to distribute your source media using the Phenix platform. After publishing users may subscribe to the stream using either pcast subscribe or express subscribe.

Java
import com.phenixrts.common.RequestStatus;
import com.phenixrts.express.ExpressPublisher;
import com.phenixrts.express.PCastExpress;
import com.phenixrts.express.PCastExpressFactory;
import com.phenixrts.express.PublishRemoteOptions;

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

final PublishRemoteOptions publishRemoteOptions = PCastExpressFactory.createPublishRemoteOptionsBuilder()
    .withStreamUri("http://mycdn.example.com/mystream.mp4")
    .withCapabilities(new String[] {})
    .buildPublishRemoteOptions();

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

Publish Remote Options Parameters

Name	Type	Description
options (required)	PublishRemoteOptions	Publish Remote options
callback (required)	PCastExpress.PublishCallback	Callback for error/success handling

PublishRemoteOptionsBuilder

Name	Type	Default	Description
withCapabilities (required)	String[]		The list of all capabilities to publish with.
withStreamUri (required)	String		Link to remote media (mp4, rtmp, etc.)
withStreamToken (optional)	String		The publish token generated using the Phenix EdgeAuth library.
withConnectOptions (optional)	Strings[]		List of options for publishing from a remote source.
withTags (optional)	Strings[]		Tags for the stream
withMaximumFrameRateConstraint (optional)	double		Maximum frame rate constraint.
withExactFrameRateConstraint (optional)	double		Exact frame rate constraint.
withPrerollSkipDuration (optional)	long	500	The amount of time to skip at the beginning of the media in milliseconds.
buildPublishRemoteOptions	none		Builds the `PublishRemoteOptions`

Publish Remote Options Callback Arguments

Name	Type	Description
status	RequestStatus	The status of the operation. See Publish Callback Status Codes
publisher	ExpressPublisher	Phenix publisher object

Subscribing to Published Media

Subscribe to streams published with the Phenix platform

Java
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")
    .withCapabilities(new String[] {"streaming"})
    .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 close, which will dispose the underlying resources

Name	Type	Description
options (required)	SubscribeOptions	Subscribe options
callback (required)	PCastExpress.SubscribeCallback	Callback for error/success handling

Name	Type	Default	Description
withStreamId (required)	String		The stream ID of the published stream
withCapabilities (required)	String[]		The list of all capabilities to subscribe with.
withStreamToken (optional)	String		The subscribe 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.
withMonitor (optional)	MonitorOptions.SetupFailedCallback, MonitorOptions.StreamEndedCallback, MonitorOptions		Options for monitoring a subscriber for failure.
withConnectOptions (optional)	String[]		List of options for subscribing.
withTags (optional)	NSString[]		Tags for the stream
buildSubscribeOptions	none	Builds the `SubscribeOptions`

ExpressSubscriber

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

Name	Signature	Returns	Description
createRenderer	()	Renderer	Creates a new renderer. This should only be called if none of the `withRenderer...` builder methods were invoked.
createRenderer	(RendererOptions)	Renderer	Creates a new renderer with RendererOptions. This should only be called if none of the `withRenderer...` builder methods were invoked.
getAudioTracks	()	MediaStreamTrack[]	Returns all associated audio tracks of this stream
getVideoTracks	()	MediaStreamTrack[]	Returns all associated video tracks of this stream
getTracks	()	MediaStreamTrack[]	Returns all associated tracks of this stream
stop	()	void	Stops subscription. This will trigger the stream ended event.
disableAudio	()	void	Mutes audio.
enableVideo	()	void	Unmutes video.
disableVideo	()	void	Mutes video (black frames).

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 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, close has the same effect. You also may defer invoking the retry action.

Example Monitor for subscribing

Java
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")
    .withCapabilities(new String[] {"real-time"})
    .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

Name	Signature	Returns	Description
perform	()	void	Performs the action. This will cause a failure if `isPresent` is false.
dismiss	()	void	Dismisses the action (if any). Can be called multiple times, will result in `isPresent` to return false. Invoking `close` has same effect.
isPresent	()	boolean	Indicates whether an action can be performed.

MonitorSetupFailedCallback Callback Arguments

Name	Type	Description
status	RequestStatus	The status of the operation.
retry	OptionalAction	Optionally allow retrying the failed stream.

MonitorStreamEndedCallback Callback Arguments

Name	Type	Description
reason	StreamEndedReason	Reason for stream ended.
description	String	Optional additional ended reason description. Carries custom message.
retry	OptionalAction	Optionally allow retrying the failed stream. For normally ended streams `isPresent` will always return false.

Express Get User Media

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

Java
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

Name	Type	Description
options (required)	UserMediaOptions	User media options
callback (required)	PCastExpress.GetUserMediaCallback	Callback for error/success handling

Express Get User Media Callback Arguments

Name	Type	Description
status	RequestStatus	The status of the operation.
userMedia	UserMediaStream	User media stream

Get PCast™

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

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

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

final PCast pcast = pcastExpress.getPCast();

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 close on them . PCastExpress will only shutdown once it is no longer being referenced or close has been called on it.

Page Content

v2023-01-31T21:25:10