• 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

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
1import android.content.Context;
2
3import com.phenixrts.common.RequestStatus;
4import com.phenixrts.environment.android.AndroidContext;
5import com.phenixrts.express.PCastExpress;
6import com.phenixrts.express.PCastExpressFactory;
7import com.phenixrts.express.PCastExpressOptions;
8import com.phenixrts.pcast.PCastInitializeOptions;
9
10// IMPORTANT: Before accessing any of the static factories, make sure the context is passed to Phenix:
11final Context context = ...; // e.g. Activity.getApplication();
12AndroidContext.setContext(context);
13
14final PCastExpressOptions pcastExpressOptions =
15 PCastExpressFactory.createPCastExpressOptionsBuilder()
16 .withBackendUri("https://example.yourdomain.com/phenix/")
17 .withUnrecoverableErrorCallback((RequestStatus status, String description) -> {
18 // Best to restart app, or attempt to re-create PCastExpress
19 })
20 .buildPCastExpressOptions();
21
22final PCastExpress pcastExpress = PCastExpressFactory.createPCastExpress(pcastExpressOptions);

PCastExpressOptionsBuilder

NameTypeDefaultDescription
withBackendUri (required)StringUrl to your backend. We send requests here to authenticate and get streaming tokens.
withAuthenticationData (optional)StringYour 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)StringThe authentication token generated using the Phenix EdgeAuth library.
withUnrecoverableErrorCallback (optional)PCastExpressOptions.UnrecoverableErrorCallbackFunction to be called when authentication fails or a failure occurs that is unrecoverable.
withPCastUri (optional)StringAllows overriding default PCast™ URI.
withPCastInitializationOptions (optional)PCastInitializeOptionsUse custom options when initializing PCast™.
withAuthenticationRouteOverride (optional)StringauthAllows override of default route for authentication tokens
withStreamRouteOverride (optional)StringstreamAllows override of default route for stream tokens
buildPCastExpressOptionsnoneBuilds the PCastExpressOptions

Publishing Local Media

Publish local user media:

  • Camera
  • Microphone
  • Screen (on supported devices)
Java
1import android.view.SurfaceView;
2import com.phenixrts.common.RequestStatus;
3import com.phenixrts.express.ExpressPublisher;
4import com.phenixrts.express.PCastExpress;
5import com.phenixrts.express.PCastExpressFactory;
6import com.phenixrts.express.PublishOptions;
7import com.phenixrts.pcast.AudioEchoCancelationMode;
8import com.phenixrts.pcast.DeviceCapability;
9import com.phenixrts.pcast.DeviceConstraint;
10import com.phenixrts.pcast.FacingMode;
11import com.phenixrts.pcast.Renderer;
12import com.phenixrts.pcast.UserMediaOptions;
13import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
14import java.util.Arrays;
15
16final PCastExpress pcastExpress = ...; // previously obtained
17
18final UserMediaOptions userMediaConstraints = new UserMediaOptions();
19
20userMediaConstraints.getVideoOptions().enabled = true;
21userMediaConstraints.getVideoOptions().capabilityConstraints.put(
22 DeviceCapability.FACING_MODE,
23 Arrays.asList(new DeviceConstraint(FacingMode.USER)));
24
25userMediaConstraints.getAudioOptions().enabled = true;
26userMediaConstraints.getAudioOptions().capabilityConstraints.put(
27 DeviceCapability.AUDIO_ECHO_CANCELATION_MODE,
28 Arrays.asList(new DeviceConstraint(AudioEchoCancelationMode.ON)));
29
30final PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
31 .withCapabilities(new String[] {"real-time"})
32 .withMediaConstraints(userMediaConstraints)
33 .buildPublishOptions();
34
35pcastExpress.publish(publishOptions, (RequestStatus status, ExpressPublisher publisher) -> {
36 if (status == RequestStatus.OK) {
37 // Do something with publisher
38 } else {
39 // Handle error
40 }
41});
42
43
44// Create a publisher with an automatically started preview renderer
45final SurfaceView view = ...; // previously obtained
46final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
47
48final PublishOptions publishOptionsWithPreview = PCastExpressFactory.createPublishOptionsBuilder()
49 .withCapabilities(new String[] {"real-time"})
50 .withMediaConstraints(userMediaConstraints)
51 .withPreviewRenderer(renderSurface)
52 .buildPublishOptions();
53
54pcastExpress.publish(
55 publishOptions, (RequestStatus status, ExpressPublisher publisher, Renderer preview) -> {
56 if (status == RequestStatus.OK) {
57 // Do something with publisher and preview renderer
58 } else {
59 // Handle error
60 }
61});

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

NameTypeDescription
options (required)PublishOptionsPublish options
callback (required)PCastExpress.PublishCallback or PCastExpress.PublishWithPreviewCallbackCallback for error/success handling

PublishOptionsBuilder

NameTypeDefaultDescription
withMediaConstraints (required)UserMediaOptionsgetUserMedia options Constraints to get the user media.
withUserMedia (optional)UserMediaStreamalternative 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)AndroidVideoRenderSurfaceRender layer on which to display local preview. If none of the withPreview... methods are called, no preview renderer will be instantiated.
withPreviewRenderer (optional)noneWill trigger instantiation of preview renderer. Useful for audio only type streams that do not require a render surface.
withPreviewRendererOptions (optional)RendererOptionsOptions passed to preview renderer. Will trigger instantiation of preview renderer.
withMonitor (optional)MonitorOptions.SetupFailedCallback, MonitorOptions.StreamEndedCallback, MonitorOptionsOptions for monitoring a publisher for failure.
withConnectOptions (optional)Strings[]List of options for publishing.
withTags (optional)Strings[]Tags for the stream.
withStreamToken (optional)StringThe publish token generated using the Phenix EdgeAuth library.
buildPublishOptionsnoneBuilds the PublishOptions

ExpressPublisher Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation
publisherExpressPublisherPublisher object
previewRendererRendererOptionally 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.

NameSignatureReturnsDescription
stop()voidStops publisher. Subscribers will receive stream ended.
stop(reason)voidStops publisher with a custom reason. Subscribers will receive StreamEndedReason.CUSTOM reason.
enableAudio()voidUnmutes audio.
disableAudio()voidMutes audio.
enableVideo()voidUnmutes video.
disableVideo()voidMutes video (black frames).
setDataQualityChangedCallback(callback)voidListen for Data Quality Feedback
limitBandwidth(bandwidthLimitInBps)DisposableTemporarily limit published video bitrate, see Limit Bitrate
getStreamId()StringReturns stream ID of publisher
hasEnded()boolIndicates 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
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.express.ExpressPublisher;
3import com.phenixrts.express.PCastExpress;
4import com.phenixrts.express.PCastExpressFactory;
5import com.phenixrts.express.PublishRemoteOptions;
6
7final PCastExpress pcastExpress = ...; // previously obtained
8
9final PublishRemoteOptions publishRemoteOptions = PCastExpressFactory.createPublishRemoteOptionsBuilder()
10 .withStreamUri("http://mycdn.example.com/mystream.mp4")
11 .withCapabilities(new String[] {})
12 .buildPublishRemoteOptions();
13
14pcastExpress.publishRemote(publishRemoteOptions, (RequestStatus status, ExpressPublisher publisher) -> {
15 if (status == RequestStatus.OK) {
16 // Do something with publisher
17 } else {
18 // Handle error
19 }
20});

Publish Remote Options Parameters

NameTypeDescription
options (required)PublishRemoteOptionsPublish Remote options
callback (required)PCastExpress.PublishCallbackCallback for error/success handling

PublishRemoteOptionsBuilder

NameTypeDefaultDescription
withCapabilities (required)String[]The list of all capabilities to publish with.
withStreamUri (required)StringLink to remote media (mp4, rtmp, etc.)
withStreamToken (optional)StringThe 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)doubleMaximum frame rate constraint.
withExactFrameRateConstraint (optional)doubleExact frame rate constraint.
withPrerollSkipDuration (optional)long500The amount of time to skip at the beginning of the media in milliseconds.
buildPublishRemoteOptionsnoneBuilds the PublishRemoteOptions

Publish Remote Options Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation. See Publish Callback Status Codes
publisherExpressPublisherPhenix publisher object

Subscribing to Published Media

Subscribe to streams published with the Phenix platform

Java
1import android.view.SurfaceView;
2import com.phenixrts.common.RequestStatus;
3import com.phenixrts.express.ExpressSubscriber;
4import com.phenixrts.express.PCastExpress;
5import com.phenixrts.express.PCastExpressFactory;
6import com.phenixrts.express.SubscribeOptions;
7import com.phenixrts.pcast.Renderer;
8import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
9
10final PCastExpress pcastExpress = ...; // previously obtained
11final SurfaceView view = ...; // previously obtained
12
13final AndroidVideoRenderSurface renderSurface = new AndroidVideoRenderSurface(view.getHolder());
14
15final SubscribeOptions subscribeOptions = PCastExpressFactory.createSubscribeOptionsBuilder()
16 .withStreamId("us-west#us-west1-b.zzzzzzzz.20000000.xxxxxxxx")
17 .withCapabilities(new String[] {"streaming"})
18 .withRenderer(renderSurface)
19 .buildSubscribeOptions();
20
21pcastExpress.subscribe(
22 subscribeOptions,
23 (RequestStatus status, ExpressSubscriber subscriber, Renderer renderer) -> {
24 if (status == RequestStatus.OK) {
25 // Do something with subscriber
26
27 if (renderer != null) {
28 // Returned if `withRenderer...` option was enabled - Do something with renderer
29 }
30 } else {
31 // Handle error
32 }
33});

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

Subscribe Parameters

NameTypeDescription
options (required)SubscribeOptionsSubscribe options
callback (required)PCastExpress.SubscribeCallbackCallback for error/success handling

Subscribe Options

NameTypeDefaultDescription
withStreamId (required)StringThe stream ID of the published stream
withCapabilities (required)String[]The list of all capabilities to subscribe with.
withStreamToken (optional)StringThe subscribe token generated using the Phenix EdgeAuth library.
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.
withMonitor (optional)MonitorOptions.SetupFailedCallback, MonitorOptions.StreamEndedCallback, MonitorOptionsOptions for monitoring a subscriber for failure.
withConnectOptions (optional)String[]List of options for subscribing.
withTags (optional)NSString[]Tags for the stream
buildSubscribeOptionsnoneBuilds the SubscribeOptions

ExpressSubscriber

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

NameSignatureReturnsDescription
createRenderer()RendererCreates a new renderer. This should only be called if none of the withRenderer... builder methods were invoked.
createRenderer(RendererOptions)RendererCreates 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()voidStops subscription. This will trigger the stream ended event.
disableAudio()voidMutes audio.
enableVideo()voidUnmutes video.
disableVideo()voidMutes 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
1import com.phenixrts.common.OptionalAction;
2import com.phenixrts.common.RequestStatus;
3import com.phenixrts.express.ExpressSubscriber;
4import com.phenixrts.express.MonitorOptions;
5import com.phenixrts.express.PCastExpressFactory;
6import com.phenixrts.express.SubscribeOptions;
7import com.phenixrts.pcast.StreamEndedReason;
8
9final MonitorOptions monitorOptions = PCastExpressFactory.createMonitorOptionsBuilder()
10 .buildMonitorOptions();
11
12final SubscribeOptions subscribeOptions = PCastExpressFactory.createSubscribeOptionsBuilder()
13 .withStreamId("us-west#us-west1-b.zzzzzzzz.20000000.xxxxxxxx")
14 .withCapabilities(new String[] {"real-time"})
15 .withMonitor(
16 (RequestStatus status, OptionalAction retry) -> {
17 if (retry.isPresent()) {
18 if (shouldRetry()) { // <- Your logic goes here
19 retry.perform();
20 } else {
21 retry.dismiss();
22 }
23 }
24 },
25 (StreamEndedReason reason, String description, OptionalAction retry) -> {
26 if (retry.isPresent()) {
27 if (reason == StreamEndedReason.FAILED) { // <- Just an example
28 retry.perform();
29 } else {
30 retry.dismiss();
31 }
32 }
33 },
34 monitorOptions)
35 .buildSubscribeOptions();

OptionalAction

NameSignatureReturnsDescription
perform()voidPerforms the action. This will cause a failure if isPresent is false.
dismiss()voidDismisses the action (if any). Can be called multiple times, will result in isPresent to return false. Invoking close has same effect.
isPresent()booleanIndicates whether an action can be performed.

MonitorSetupFailedCallback Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation.
retryOptionalActionOptionally allow retrying the failed stream.

MonitorStreamEndedCallback Callback Arguments

NameTypeDescription
reasonStreamEndedReasonReason for stream ended.
descriptionStringOptional additional ended reason description. Carries custom message.
retryOptionalActionOptionally 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
1import com.phenixrts.common.RequestStatus;
2import com.phenixrts.express.PCastExpress;
3import com.phenixrts.pcast.UserMediaOptions;
4import com.phenixrts.pcast.UserMediaStream;
5
6final PCastExpress pcastExpress = ...; // previously obtained
7
8final UserMediaOptions userMediaOptions = new UserMediaOptions();
9
10pcastExpress.getUserMedia(userMediaOptions, (RequestStatus status, UserMediaStream userMedia) -> {
11 if (status == RequestStatus.OK) {
12 // Do something with user media stream
13 } else {
14 // Handle error
15 }
16});

Express Get User Media Parameters

NameTypeDescription
options (required)UserMediaOptionsUser media options
callback (required)PCastExpress.GetUserMediaCallbackCallback for error/success handling

Express Get User Media Callback Arguments

NameTypeDescription
statusRequestStatusThe status of the operation.
userMediaUserMediaStreamUser 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
1import com.phenixrts.express.PCastExpress;
2import com.phenixrts.pcast.PCast;
3
4final PCastExpress pcastExpress = ...; // previously obtained
5
6final 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
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10