• 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™ API

Initializing

Before using a PCast™ object, it must be initialized as shown.

Java
1import com.phenixrts.pcast.PCast;
2import com.phenixrts.pcast.PCastInitializeOptions;
3import com.phenixrts.pcast.android.AndroidPCastFactory;
4
5PCast pcast = AndroidPCastFactory.createPCast(this);
6
7// #1 Default initialization options
8pcast.initialize();
9
10// OR
11
12// #2 Custom initialization options (initialized by constructor)
13final boolean enableProcessTerminationSignalHandling = false;
14PCastInitializeOptions initOptions = new PCastInitializeOptions(
15 enableProcessTerminationSignalHandling);
16
17pcast.initialize(initOptions);

Initialize Options

NameDescription
enableProcessTerminationSignalHandlingControls if process termination signal handling is enabled or not
configureLoggingControl if phenix logging is enabled
streamingSourceMappingAllows partial override of streaming source URIs

Stream Source Mapping

Optional field that can be provided with PCastInitializeOptions. It only has an effect on the subscriber side, and only for streams with the "streaming" capability (on both publisher and subscriber side). The property allows you to redirect requests from the SDKs player to your own CDN.

Java
1import com.phenixrts.pcast.PCastInitializeOptions;
2import com.phenixrts.pcast.StreamingSourceMapping;
3
4final String patternToReplace = "https:\\/\\/phenixrts\\.com\\/video";
5final String replacement = "https://myown.cdn.com";
6final StreamingSourceMapping streamingSourceMapping = new StreamingSourceMapping(
7 patternToReplace, replacement);
8
9final boolean enableProcessTerminationSignalHandling = false;
10final boolean configureLogging = true;
11
12final PCastInitializeOptions pcastInitOptions = new PCastInitializeOptions(
13 enableProcessTerminationSignalHandling,
14 configureLogging,
15 streamingSourceMapping);
NameDescription
patternToReplaceA regular expression indicating with part of the incoming streaming source URI to replace
replacementThe replacement string to insert into the streaming source URI

Note: The regular expression has to be properly escaped to work correctly.

Connect and Authenticate

Follow the example for connecting and authenticating to PCast™.

Java
1import android.util.Log;
2import com.phenixrts.pcast.PCast;
3import com.phenixrts.pcast.RequestStatus;
4
5// Created via EdgeAuth library
6String authenticationToken = ...;
7// Previously initialized
8PCast pcast = ...;
9
10pcast.start(
11 authenticationToken,
12 new PCast.AuthenticationCallback() {
13 @Override
14 public void onEvent(
15 PCast pcast,
16 RequestStatus requestStatus,
17 String sessionId) {
18 if (requestStatus == RequestStatus.OK) {
19 Log.i("Phenix SDK Example", "PCast started...");
20 } else {
21 Log.e("Phenix SDK Example", "Failed to start PCast...");
22 }
23 }
24 },
25 new PCast.OnlineCallback() {
26 @Override
27 public void onEvent(PCast pcast) {
28 Log.i("Phenix SDK Example", "We are online...");
29 }
30 },
31 new PCast.OfflineCallback() {
32 @Override
33 public void onEvent(PCast pcast) {
34 Log.i("Phenix SDK Example", "We are offline...");
35 }
36 });

Connect and Authenticate Parameters

NameTypeDescription
authenticationToken (required)stringThe authentication token generated using the Phenix EdgeAuth library
authenticationCallback (required)PCast.AuthenticationCallbackCalled upon successful authentication or when authentication failed or has to be redone. Upon successful authentication, the authenticationCallback will be called with status=RequestStatus.OK. If at any time a new authenticationToken is required, then the authenticationCallback is called with status=RequestStatus.UNAUTHORIZED to indicate that we are no longer authenticated.
onlineCallback (required)PCast.OnlineCallbackCalled when the client is connected to the streaming platform
offlineCallback (required)PCast.OfflineCallbackCalled when the client is disconnected from the streaming platform. Ongoing streams may continue while we are temporarily disconnected. However, no new streams can be started while being disconnected. The client automatically tries to reconnect and will call onlineCallback when it succeeds in doing so or eventually call authenticationCallback to indicate that re-authentication is required.

Authentication Callback Status Codes

StatusValid FieldsDescription
RequestStatus.OKsessionIdAuthentication succeeded, the sessionId is populated
RequestStatus.UNAUTHORIZEDnoneAuthentication failed or re-authentication required
variesnoneAuthentication failed for other reasons

Disconnect

Please follow the self explanatory example for disconnecting from PCast™.

Java
1import com.phenixrts.pcast.PCast;
2import com.phenixrts.pcast.RequestStatus;
3
4// Previously initialized and started
5PCast pcast = ...;
6
7pcast.stop();
8
9// Once you are done using PCast (e.g. exiting the app)
10pcast.shutdown();

Get Local User Media

Please follow the self explanatory example for getting local user media.

Java
1import com.phenixrts.pcast.FacingMode;
2import com.phenixrts.pcast.PCast;
3import com.phenixrts.pcast.UserMediaOptions;
4import com.phenixrts.pcast.UserMediaStream;
5import com.phenixrts.pcast.android.AndroidPCastFactory;
6
7// Previously initialized and started
8PCast pcast = ...;
9
10UserMediaOptions gumOptions = new UserMediaOptions();
11
12// Customize options if desired
13gumOptions.getVideoOptions().capabilityConstraints.put(
14 DeviceCapability.FACING_MODE, Arrays.asList(new DeviceConstraint(FacingMode.USER)));
15gumOptions.getAudioOptions().enabled = false;
16
17pcast.getUserMedia(
18 gumOptions,
19 new PCast.UserMediaCallback() {
20 @Override
21 public void onEvent(
22 PCast pcast,
23 RequestStatus status,
24 UserMediaStream userMediaStream) {
25 // Check status and store 'userMediaStream'
26 }
27 });

Get Local User Media Parameters

NameTypeDescription
options (required)UserMediaOptionsThe options defining the requested user media stream
userMediaCallback (required)PCast.UserMediaCallbackUpon acquiring of the user media stream, the userMediaCallback will be called with status=RequestStatus.OK. If the user media is currently used by another application, then you may receive a code status=RequestStatus.CONFLICT . If the operation fails with status=RequestStatus.FAILED then please check the logs for more information

Device Capability

NameDescription
DeviceCapability.WIDTHWidth in pixels
DeviceCapability.HEIGHTHeight in pixels
DeviceCapability.FRAME_RATENumber of frames per second
DeviceCapability.FACING_MODEFacing mode
DeviceCapability.FLASH_MODEFlash mode
DeviceCapability.DEVICE_IDDevice ID string (obtain from here)
DeviceCapability.LOCATIONDevice Location
DeviceCapability.POLAR_PATTERNPolar pattern
DeviceCapability.AUDIO_ECHO_CANCELATION_MODEAudio echo cancelation mode

Constraint Type

NameDescription
ConstraintType.MINHard constraint: Capability must have at least the specified value
ConstraintType.MAXHard constraint: Capability must have at most the specified value
ConstraintType.EXACTHard constraint: Capability must have exactly the specified value
ConstraintType.IDEALSoft constraint: Capability should have specified value, but other values are acceptable (default)

Facing Mode

NameDescription
FacingMode.AUTOMATICSelect a facing mode automatically (default)
FacingMode.ENVIRONMENTFacing the surrounding environment (e.g., back camera)
FacingMode.USERFacing the user (e.g., front camera)

Flash Mode

Only applicable to video devices

NameDescription
FlashMode.AUTOMATICFlash is turned on automatically when needed (default)
FlashMode.ALWAYS_ONFlash is on (if available)
FlashMode.ALWAYS_OFFFlash is off

Device Location

NameDescription
Location.AUTOMATICSelect any device (default)
Location.UPPERMounted on top of phone/tablet
Location.LOWERMounted at bottom of phone/tablet

Polar Pattern

Only applicable to audio devices

NameDescription
PolarPattern.AUTOMATICAutomatically select pattern (default)
PolarPattern.OMNIDIRECTIONALEqually sensitive to sound from any direction
PolarPattern.CARDIOIDMost sensitive to sound from the direction in which the data source points and is (nearly) insensitive to sound from the opposite direction
PolarPattern.SUBCARDIOIDMost sensitive to sound from the direction in which the data source points and is less sensitive to sound from the opposite direction

Note: This option is currently not supported on Android

Audio Echo Cancelation Mode

Only applicable to audio devices

NameDescription
AudioEchoCancelationMode.AUTOMATICAutomatically select AEC mode (default)
AudioEchoCancelationMode.ONEnable AEC if available
AudioEchoCancelationMode.OFFDisable AEC

Note (as of v2019.2.0): Automatic mode is currently always set to "off" on Android.

Note 2 (as of v2019.2.0): AudioEchoCancelationMode must be set to ON in the UserMediaOptions for all published streams and RendererOptions for all subscribed streams in order for AEC to work reliably on all Android devices.

Updating Options

Sometimes you find it useful to change the camera while a stream is running or just would like to turn on the flash light temporarily.

Java
1import com.phenixrts.pcast.UserMediaOptions;
2import com.phenixrts.pcast.UserMediaStream;
3
4// Previously obtained via 'getUserMedia'
5UserMediaStream userMediaStream = ...;
6
7// Previously initialized and used with 'getUserMedia'
8UserMediaOptions gumOptions = new UserMediaOptions();
9
10gumOptions.getVideoOptions().capabilityConstraints.put(
11 DeviceCapability.FACING_MODE, Arrays.asList(new DeviceConstraint(FacingMode.ENVIRONMENT)));
12gumOptions.getVideoOptions().capabilityConstraints.put(
13 DeviceCapability.FLASH_MODE, Arrays.asList(new DeviceConstraint(FlashMode.ALWAYS_ON)));
14gumOptions.getVideoOptions().capabilityConstraints.put(
15 DeviceCapability.HEIGHT,
16 Arrays.asList(new DeviceConstraint(720, ConstraintType.EXACT)));
17gumOptions.getVideoOptions().capabilityConstraints.put(
18 DeviceCapability.WIDTH,
19 Arrays.asList(
20 new DeviceConstraint(800, ConstraintType.MIN),
21 new DeviceConstraint(1500, ConstraintType.MAX)));
22
23userMediaStream.applyOptions(gumOptions);

Enumerating Source Devices

You can get a list of available source devices.

Java
1import android.util.Log;
2import com.phenixrts.pcast.MediaType;
3import com.phenixrts.pcast.PCast;
4import com.phenixrts.pcast.SourceDeviceInfo;
5
6// Previously initialized and started
7PCast pcast = ...;
8
9pcast.enumerateSourceDevices(
10 MediaType.VIDEO,
11 new PCast.EnumerateSourceDevicesCallback() {
12 @Override
13 public void onEvent(PCast pcast, SourceDeviceInfo[] devices) {
14 // Store devices as needed
15 }
16 });

Enumerating Source Devices Parameters

NameTypeDescription
mediaType (required)MediaTypeThe media type for which to enumerate source devices

SourceDeviceInfo fields

NameTypeDescription
idStringSource device ID
nameStringSource device Name
mediaTypeMediaTypeSource device media type
deviceTypeSourceDeviceTypeSource device type
facingModeFacingModeSource device facing mode

Media Type

NameDescription
MediaType.VIDEOVideo
MediaType.AUDIOAudio

Source Device Type

NameDescription
SourceDeviceType.NULLNull device (e.g. blank screen or silence)
SourceDeviceType.PHYSICALPhysical device (e.g. camera or microphone)
SourceDeviceType.SYSTEM_OUTPUTSystem output capture (screencast)

Screencasting android 5.0 or later

You can also stream the screen of your phone.

In order to do this, you must first enumerate the available source devices to find the screencast device ID.

Find the screencast device ID

Java
1import android.util.Log;
2import com.phenixrts.pcast.MediaType;
3import com.phenixrts.pcast.PCast;
4import com.phenixrts.pcast.SourceDeviceInfo;
5import com.phenixrts.pcast.SourceDeviceType;
6
7// Previously initialized and started
8PCast pcast = ...;
9
10pcast.enumerateSourceDevices(
11 MediaType.VIDEO,
12 new PCast.EnumerateSourceDevicesCallback() {
13 @Override
14 public void onEvent(PCast pcast, SourceDeviceInfo[] devices) {
15 for (SourceDeviceInfo info : devices) {
16 if (info.sourceDeviceType == SourceDeviceType.SYSTEM_OUTPUT) {
17 Log.i("Phenix SDK Example", "Screencasting is available");
18 String screenCaptureDeviceId = info.id;
19 // Store screenCaptureDeviceId
20 }
21 }
22 }
23 });
24
25pcast.enumerateSourceDevices();

The screen capture device requires a valid android.media.projection.MediaProjection object to be passed to the SDK before it can be used. The MediaProjection must stay valid for the duration of the screencast.

Next, pass a valid android.media.projection.MediaProjection object

Java
1import android.media.projection.MediaProjection;
2import com.phenixrts.pcast.android.AndroidPCastFactory;
3
4// Previously obtained by calling
5// android.media.projection.MediaProjectionManager.getMediaProjection(),
6// see Android API reference.
7MediaProjection mediaProjection = ...;
8
9AndroidPCastFactory.setMediaProjection(mediaProjection);

Finally, pass the screen capture device ID

Next, pass the screen capture device ID to getUserMedia() in the user media options.

Java
1import com.phenixrts.pcast.FacingMode;
2import com.phenixrts.pcast.PCast;
3import com.phenixrts.pcast.UserMediaOptions;
4import com.phenixrts.pcast.UserMediaStream;
5
6// Previously initialized and started
7PCast pcast = ...;
8
9// Found by calling enumerateSourceDevices() as described above
10String screenCaptureDeviceId = ...;
11
12UserMediaOptions gumOptions = new UserMediaOptions();
13
14gumOptions.getVideoOptions().capabilityConstraints.put(
15 DeviceCapability.DEVICE_ID, Arrays.asList(new DeviceConstraint(screenCaptureDeviceId)));
16
17pcast.getUserMedia(
18 gumOptions,
19 new PCast.UserMediaCallback() {
20 @Override
21 public void onEvent(
22 PCast pcast,
23 RequestStatus status,
24 UserMediaStream userMediaStream) {
25 // Check status and store 'userMediaStream'
26 }
27 });

Please follow the self explanatory code snippets for understanding above steps.

Publish a Stream

Java
1import android.util.Log;
2import com.phenixrts.pcast.MediaStream;
3import com.phenixrts.pcast.PCast;
4import com.phenixrts.pcast.Publisher;
5import com.phenixrts.pcast.RequestStatus;
6import com.phenixrts.pcast.StreamEndedReason;
7import com.phenixrts.pcast.UserMediaOptions;
8import com.phenixrts.pcast.UserMediaStream;
9
10// Previously initialized and started
11PCast pcast = ...;
12// Previously created via EdgeAuth library
13String streamToken = ...;
14// Previously obtained via either PCast.subscribe()
15// or UserMediaStream.getMediaStream()
16MediaStream mediaStream = ...;
17
18String[] tags = { "my-tag" };
19
20pcast.publish(
21 streamToken,
22 mediaStream,
23 new PCast.PublishCallback() {
24 @Override
25 public void onEvent(
26 PCast pcast,
27 RequestStatus requestStatus,
28 Publisher publisher) {
29 // Check status and store 'publisher'
30
31 // The "streamId" of the publisher
32 String streamId = publisher.getStreamId();
33
34 if (publisher.hasEnded()) {
35 // Checks if the publisher has ended
36 }
37
38 // Attach publisher ended callback
39 publisher.setPublisherEndedCallback(
40 new Publisher.PublisherEndedCallback() {
41 @Override
42 public void onEvent(
43 Publisher publisher,
44 StreamEndedReason reason,
45 String reasonDescription) {
46 // Called when the stream has ended
47 Log.i("Phenix SDK Example",
48 "Publish stream ended with reason ["
49 + reasonDescription + "]");
50 }
51 });
52
53 // To stop later
54 publisher.stop("I-am-done-publishing");
55 }
56 },
57 tags);

Publishing a Stream Parameters

NameTypeDescription
streamToken (required)StringThe publish token is generated using the Phenix EdgeAuth library
mediaStream (required)MediaStreamThe user media stream acquired through PCast.subscribe(...) or locally with UserMediaStream.getMediaStream()
publishCallback (required)PCast.PublishCallbackCalled upon completion of the operation
tags (optional)String[]Tags that will be provided with the stream notifications to your backend callback endpoint

StreamEndedReason

ReasonDescription
StreamEndedReason.ENDEDThe stream ended normally
StreamEndedReason.FAILEDThe stream failed
StreamEndedReason.CENSOREDThe stream was censored
StreamEndedReason.MAINTENANCEA maintenance event caused this stream to be terminated
StreamEndedReason.CAPACITYThe stream was terminated due to capacity limitations
StreamEndedReason.APP_BACKGROUNDThe stream was terminated due to the mobile app entering into the background
StreamEndedReason.CUSTOMA custom termination reason is provided in the "reasonDescription" field

Process Raw Frames

The frame-ready API allows for pre-processing of raw audio and video frames before they are encoded and transmitted.

Any processing needs to keep up with the incoming frame rate; otherwise some of the incoming frames will be dropped to compensate.

Java
1import android.graphics.Bitmap;
2import com.phenixrts.media.audio.android.AndroidAudioFrame;
3import com.phenixrts.media.video.android.AndroidVideoFrame;
4import com.phenixrts.pcast.FrameNotification;
5import com.phenixrts.pcast.MediaStreamTrack;
6import com.phenixrts.pcast.PCast;
7import com.phenixrts.pcast.UserMediaStream;
8import com.phenixrts.pcast.android.AndroidReadAudioFrameCallback;
9import com.phenixrts.pcast.android.AndroidReadVideoFrameCallback;
10
11// Previously obtained via PCast.getUserMedia
12final UserMediaStream userMediaStream = ...;
13
14final MediaStreamTrack[] videoTracks = userMediaStream.getMediaStream().getVideoTracks();
15
16for (MediaStreamTrack videoTrack : videoTracks) {
17 userMediaStream.setFrameReadyCallback(videoTrack,
18 (frameNotification) -> {
19 frameNotification.read(new AndroidReadVideoFrameCallback() {
20 @Override
21 public void onVideoFrameEvent(AndroidVideoFrame videoFrame) {
22 final Bitmap pixelBuffer = videoFrame.bitmap;
23 final int displayHeightInPixels = pixelBuffer.getHeight();
24 final int displayWidthInPixels = pixelBuffer.getWidth();
25
26 // Manipulate bitmap as needed
27 ...
28
29 frameNotification.write(videoFrame);
30 }
31 });
32 });
33}
34
35final MediaStreamTrack[] audioTracks = userMediaStream.getMediaStream().getAudioTracks();
36
37for (MediaStreamTrack audioTrack : audioTracks) {
38 userMediaStream.setFrameReadyCallback(audioTrack,
39 (frameNotification) -> {
40 frameNotification.read(new AndroidReadAudioFrameCallback() {
41 @Override
42 public void onAudioFrameEvent(AndroidAudioFrame audioFrame) {
43 // Attenuate audio:
44 for (int sampleIndex = 0; sampleIndex < audioFrame.audioSamples.length; ++sampleIndex) {
45 audioFrame.audioSamples[sampleIndex] *= 0.1;
46 }
47
48 frameNotification.write(audioFrame);
49 }
50 });
51 });
52}

Frame Notification API

NameArgumentDescription
readFrameReadyForProcessingCallbackRetrieves current raw frame in form of an AndroidAudioFrame or AndroidVideoFrame
writeAndroidAudioFrame/AndroidVideoFrameWrites back a processed or newly generated frame. The frame can have a different resolution and timestamps
drop(none)Instructs stream to drop the current frame

AndroidAudioFrame

NameTypeDescription
sampleRateInHzintAudio sampling frequency, e.g. 48000
numberOfChannelsintNumber of channels, e.g. 1 for mono, 2 for stereo
timestampInMicrosecondslongTimestamp of current audio frame in us
audioSamplesshort[]Audio samples; if more than one channel is present, then samples will be interleaved

AndroidVideoFrame

NameTypeDescription
bitmapandroid.graphics.BitmapBitmap containing the pixel data. This object also contains other properties such as width and height.
timestampInMicrosecondslongTimestamp of current video frame in us
durationInMicrosecondslongDuration of the current video frame in us

Limit Bitrate

The published video bitrate can be limited temporarily if needed. The returned disposable allows you to control for how long the limitation should stay in effect. If limitBandwidth is called multiple times before any of the previous disposables are released, then only the most recent override will remain in effect until its disposable is released. Relasing any of the disposables from earlier limitBandwidth calls will have no effect.

To release a Disposable deterministrically, call close on it.

Java
1import com.phenixrts.common.Disposable;
2import com.phenixrts.pcast.Publisher;
3
4// Previously obtained
5Publisher publisher = ...;
6
7Disposable disposable = publisher.limitBandwidth(200000);
8
9// ... after some time: force dispose to cancel bandwidth limitation:
10disposable.close();

Limit Bitrate Parameters

NameTypeDescription
bandwidthLimitInBps (required)longMaximum bitrate limit in bps for video

Subscribe to a Stream

Java
1import android.util.Log;
2import com.phenixrts.pcast.MediaStream;
3import com.phenixrts.pcast.PCast;
4import com.phenixrts.pcast.RequestStatus;
5import com.phenixrts.pcast.StreamEndedReason;
6
7// Previously initialized and started
8PCast pcast = ...;
9// Previously created via EdgeAuth library
10String streamToken = ...;
11
12pcast.subscribe(
13 streamToken,
14 new PCast.SubscribeCallback() {
15 @Override
16 public void onEvent(
17 PCast pcast,
18 RequestStatus requestStatus,
19 MediaStream mediaStream) {
20 // Check status and store 'mediaStream'
21
22 // Attach stream ended callback
23 mediaStream.setStreamEndedCallback(
24 new MediaStream.StreamEndedCallback() {
25 @Override
26 public void onEvent(
27 MediaStream mediaStream,
28 StreamEndedReason reason,
29 String reasonDescription) {
30 Log.i("Phenix SDK Example",
31 "Subscriber stream ended with reason ["
32 + reasonDescription + "]");
33 }
34 }
35 });
36
37 // To stop later
38 mediaStream.stop();
39 }
40 });

Subscribe to a Stream Parameters

NameTypeDescription
streamToken (required)StringThe publish token is generated using the Phenix EdgeAuth library
subscribeCallback (required)PCast.SubsribeCallbackCalled upon completion of the operation

View a Stream

In order to view a stream you have to supply a Surface for the Renderer to draw on.

Java
1import com.phenixrts.pcast.MediaStream;
2import com.phenixrts.pcast.Renderer;
3import com.phenixrts.pcast.RendererStartStatus;
4import com.phenixrts.pcast.android.AndroidVideoRenderSurface;
5
6// Previously obtained via either PCast.subscribe
7// or PhenixUserMediaStream.mediaStream
8MediaStream mediaStream = ...;
9
10// Previously obtained, e.g., from a SurfaceView
11Surface renderSurface = ...;
12
13Renderer renderer = mediaStream.createRenderer();
14
15RendererStartStatus status =
16 renderer.start(new AndroidVideoRenderSurface(renderSurface));
17
18if (status == RendererStartStatus.OK) {
19 Log.i("Phenix SDK Example", "Renderer started successfully");
20} else {
21 Log.e("Phenix SDK Example", "Renderer start failed");
22}
23
24// To stop later
25renderer.stop();

Renderer options

It is possible to pass additional options when creating a renderer.

Java
1import com.phenixrts.pcast.AspectRatioMode;
2import com.phenixrts.pcast.MediaStream;
3import com.phenixrts.pcast.Renderer;
4import com.phenixrts.pcast.RendererOptions;
5
6// Previously obtained via either PCast.subscribe or UserMediaStream.mediaStream
7MediaStream mediaStream = ...;
8
9RendererOptions options = new RendererOptions();
10options.aspectRatioMode = AspectRatioMode.FILL;
11
12Renderer renderer = mediaStream.createRenderer(options);

Properties

NameTypeDescription
aspectRatioMode (optional)AspectRatioModeHow to fill available video render surface
audioEchoCancelationMode (optional)AudioEchoCancelationModeAudio echo cancelation mode
hardwareAcceleratedDecodingMode (optional)HardwareAcceleratedDecodingModeHardware accelerated decoding mode

Aspect Ratio Mode

NameDescription
AspectRatioMode.AUTOMATICDefaults to fill
AspectRatioMode.FILLFill entire render area. Video may be truncated
AspectRatioMode.LETTERBOXBlack bars are added on sides or top/bottom of render area, video will not be truncated

Note: This option is currently only supported for Real-Time streams

Hardware Accelerated Decoding Mode

NameDescription
HardwareAcceleratedDecodingMode.AUTOMATICUse hardware decoding on certified devices
HardwareAcceleratedDecodingMode.ONAlways use hardware decoding
HardwareAcceleratedDecodingMode.OFFAlways use software decoding

Preview Local User Media

Java
1import com.phenixrts.pcast.Renderer;
2import com.phenixrts.pcast.UserMediaStream;
3
4// Previously obtained via 'getUserMedia'
5UserMediaStream userMediaStream = ...;
6
7Renderer renderer = userMediaStream.getMediaStream().createRenderer();

Muting and Unmuting of Audio

Java
1import com.phenixrts.pcast.Renderer;
2
3// Previously obtained from media stream
4Renderer renderer = ...;
5
6boolean isMuted = renderer.isAudioMuted();
7renderer.muteAudio();
8renderer.unmuteAudio();

Taking a Screenshot

If you would like to show a preview, you can take a still image from a renderer.

Java
1import com.phenixrts.pcast.Renderer;
2import com.phenixrts.android.AndroidLastFrameRenderedCallback;
3
4// Previously obtained from media stream and started
5Renderer renderer = ...;
6
7renderer.setLastVideoFrameRenderedReceivedCallback(
8 new AndroidLastFrameRenderedCallback() {
9 @override
10 public void onEvent(Renderer renderer, Bitmap videoFrame) {
11 // Process the frame as needed
12 }
13 });
14
15renderer.requestLastVideoFrameRendered();

You can also take a still image from a local stream.

Java
1import com.phenixrts.pcast.UserMediaStream;
2import com.phenixrts.android.AndroidLastFrameCapturedCallback;
3
4// Previously obtained via 'getUserMedia'
5UserMediaStream userMediaStream = ...;
6
7userMediaStream.setLastVideoFrameCapturedReceivedCallback(
8 new AndroidLastFrameCapturedCallback() {
9 @override
10 public void onEvent(Renderer renderer, Bitmap videoFrame) {
11 // Process the frame as needed
12 }
13 });
14
15userMediaStream.requestLastVideoFrameCaptured();

Data Quality Feedback

If you like to show the user feedback about how their internet connectivity affects the stream quality, you can listen for data quality notifications.

Java
1import com.phenixrts.pcast.DataQualityReason;
2import com.phenixrts.pcast.DataQualityStatus;
3import com.phenixrts.pcast.Publisher;
4import com.phenixrts.pcast.Renderer;
5
6// Previously obtained from media stream and started
7Renderer renderer = ...;
8
9renderer.setDataQualityChangedCallback(
10 new Renderer.DataQualityChangedCallback() {
11 @Override
12 public void onEvent(
13 Renderer renderer,
14 DataQualityStatus quality,
15 DataQualityReason reason) {
16 // Inform user, take action based on status and reason
17 }
18 });
19
20// Previously obtained via PCast.publish
21Publisher publisher = ...;
22
23publisher.setDataQualityChangedCallback(
24 new Publisher.DataQualityChangedCallback() {
25 @Override
26 public void onEvent(
27 Publisher publisher,
28 DataQualityStatus quality,
29 DataQualityReason reason) {
30 // Inform user, take action based on status and reason
31 }
32 });

Data Quality Status for Publishers

StatusReasonDescription
DataQualityStatus.NO_DATADataQualityReason.NONEThe publisher has a bad internet connection and no data is being streamed.
DataQualityStatus.NO_DATADataQualityReason.UPLOAD_LIMITEDThe publisher has a bad internet connection and no data is being streamed.
DataQualityStatus.ALLDataQualityReason.NONEGood internet connection and no quality reduction in effect.
DataQualityStatus.ALLDataQualityReason.UPLOAD_LIMITEDThe publisher has a slow internet connection and the quality of the stream is reduced.
DataQualityStatus.ALLDataQualityReason.NETWORK_LIMITEDSubscribers have bad internet connections and the quality of the stream is reduced.
DataQualityStatus.AUDIO_ONLYDataQualityReason.UPLOAD_LIMITEDThe publisher has a bad internet connection and only audio is streamed.
DataQualityStatus.AUDIO_ONLYDataQualityReason.NETWORK_LIMITEDSubscribers have bad internet connections and only audio is streamed.

Data Quality Status for Viewers

StatusReasonDescription
DataQualityStatus.NO_DATADataQualityReason.NONEThe subscriber has a bad internet connection and no data is being received.
DataQualityStatus.NO_DATADataQualityReason.DOWNLOAD_LIMITEDThe subscriber has a bad internet connection and no data is being received.
DataQualityStatus.NO_DATADataQualityReason.PUBLISHER_LIMITEDThe publisher has a bad internet connection and no data is being received.
DataQualityStatus.NO_DATADataQualityReason.NETWORK_LIMITEDThe network is limiting the quality of the stream and no data is being received.
DataQualityStatus.ALLDataQualityReason.NONEGood internet connection and no quality reduction in effect.
DataQualityStatus.ALLDataQualityReason.DOWNLOAD_LIMITEDThe subscriber has a bad internet connection and the quality of the stream is reduced.
DataQualityStatus.ALLDataQualityReason.PUBLISHER_LIMITEDThe publisher has a bad internet connection and the quality of the stream is reduced.
DataQualityStatus.ALLDataQualityReason.NETWORK_LIMITEDOther subscribers have bad internet connections and the quality of the stream is reduced.
DataQualityStatus.AUDIO_ONLYDataQualityReason.NONEAudio only stream, good internet connection and no quality reduction in effect.
DataQualityStatus.AUDIO_ONLYDataQualityReason.DOWNLOAD_LIMITEDThe subscriber has a bad internet connection and is only receiving audio.
DataQualityStatus.AUDIO_ONLYDataQualityReason.PUBLISHER_LIMITEDThe publisher has a bad internet connection and the subscriber is only receiving audio.
DataQualityStatus.AUDIO_ONLYDataQualityReason.NETWORK_LIMITEDThe network is limiting the quality of the stream and the subscriber is only receiving audio.

Handling Dimension Changes

Cameras may be switched at runtime and devices may be rotated. Register a handler to receive a notification whenever the video dimension changes.

Java
1import com.phenixrts.pcast.Dimensions;
2import com.phenixrts.pcast.Renderer;
3
4// Previously obtained from media stream
5Renderer renderer = ...;
6
7renderer.setVideoDisplayDimensionsChangedCallback(
8 new Renderer.VideoDisplayDimensionsChangedCallback() {
9 @Override
10 public void onEvent(
11 Renderer renderer,
12 Dimensions displayDimensions) {
13 // Can get called multiple times while rendering a stream
14 // Values in displayDimensions.width, displayDimensions.height
15 }
16 });
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10