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

Initializing

Before using a PCast™ object, you need to initialize it.

Objective-C
1@import PhenixSdk;
2
3id<PhenixPCast> pcast = [PhenixPCastFactory createPCast];
4
5// #1 Default initialization options
6[pcast initialize];
7
8// OR
9
10// #2 Custom initialization options
11PhenixPCastInitializeOptions* initOptions = [PhenixPCastInitializeOptions new];
12initOptions.enableProcessTerminationSignalHandling = NO;
13
14[pcast 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 PhenixPCastInitializeOptions. 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.

Objective-C
1@import PhenixSdk;
2
3id<PhenixPCastInitializeOptions> initOptions = [PhenixPCastInitializeOptions new];
4initOptions.streamingSourceMapping = [PhenixStreamingSourceMapping new];
5
6initOptions.streamingSourceMapping.patternToReplace = @"https:\\/\\/phenixrts\\.com\\/video";
7initOptions.streamingSourceMapping.replacement = @"https://myown.cdn.com";
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

Objective-C
1@import PhenixSdk;
2
3// Generated via EdgeAuth library
4NSString* authenticationToken = ...;
5// Previously initialized
6id<PhenixPCast> pcast = ...;
7
8[pcast start:
9 authenticationToken:
10 ^(id<PhenixPCast> pcast, PhenixRequestStatus status, NSString* sessionId) {
11 if (status == PhenixRequestStatusOk) {
12 NSLog(@"PCast started...");
13 } else {
14 NSLog(@"Failed to start PCast...");
15 }
16 }:
17 ^(id<PhenixPCast> pcast) {
18 NSLog(@"We are online...");
19 }:
20 ^(id<PhenixPCast> pcast) {
21 NSLog(@"We are offline...");
22 }];

Authentication Parameters

NameTypeDescription
authenticationToken (required)stringThe authentication token generated using the Phenix EdgeAuth library
authenticationCallback (required)lambda (pcast, status, sessionId)Called upon successful authentication or when authentication failed or has to be redone. Upon successful authentication, the authenticationCallback will be called with status=PhenixRequestStatusOk. If at any time a new authenticationToken is required, then the authenticationCallback is called with status=PhenixRequestStatusUnauthorized to indicate that we are no longer authenticated.
onlineCallback (required)lambda (pcast)Called when the client is connected to the streaming platform
offlineCallback (required)lambda (pcast)Called 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
PhenixRequestStatusOksessionIdAuthentication succeeded, the sessionId is populated
PhenixRequestStatusUnauthorizednoneAuthentication failed or re-authentication required
variesnoneAuthentication failed for other reasons

Disconnecting

Objective-C
1@import PhenixSdk;
2
3// Previously initialized and started
4id<PhenixPCast> pcast = ...;
5
6[pcast stop];
7
8// Once you are done using PCast (e.g. exiting the app)
9[pcast shutdown];

Get Local User Media

Objective-C
1@import PhenixSdk;
2
3// Previously initialized and started
4id<PhenixPCast> pcast = ...;
5
6PhenixUserMediaOptions* gumOptions = [PhenixUserMediaOptions new]
7
8// Customize options if desired
9gumOptions.video.capabilityConstraints
10 [[NSNumber numberWithInteger:PhenixDeviceCapabilityFacingMode]] =
11 @[ [PhenixDeviceConstraint initWithFacingMode:PhenixFacingModeUser] ];
12gumOptions.video.capabilityConstraints
13 [[NSNumber numberWithInteger: PhenixDeviceCapabilityFlashMode]] =
14 @[ [PhenixDeviceConstraint initWithFlashMode:PhenixFlashModeAlwaysOff] ];
15gumOptions.video.capabilityConstraints
16 [[NSNumber numberWithInteger: PhenixDeviceCapabilityHeight]] =
17 @[ [PhenixDeviceConstraint initWithDouble:720:PhenixConstraintTypeExact] ];
18gumOptions.video.capabilityConstraints
19 [[NSNumber numberWithInteger: PhenixDeviceCapabilityWidth]] =
20 @[ [PhenixDeviceConstraint initWithDouble:800:PhenixConstraintTypeMin],
21 [PhenixDeviceConstraint initWithDouble:1500:PhenixConstraintTypeMax] ];
22gumOptions.audio.enabled = NO;
23
24[pcast getUserMedia:
25 gumOptions:
26 ^(id<PhenixPCast> pcast,
27 PhenixRequestStatus status,
28 id<PhenixUserMediaStream> userMediaStream) {
29 // Check status and store 'userMediaStream'
30 }];

Get Local User Media Parameters

NameTypeDescription
options (required)PhenixUserMediaOptionsThe options defining the requested user media stream
userMediaCallback (required)lambda (pcast, status, userMediaStream)Upon acquiring of the user media stream, the userMediaCallback will be called with status=PhenixRequestStatusOk. If the user media is currently used by another application, then you may receive a code status=PhenixRequestStatusConflict . If the operation fails with status=PhenixRequestStatusFailed then please check the logs for more information

Device Capability

Note: iPhone models earlier than the iPhone 6 will be limited to publishing at 720p due to hardware limitations.

NameDescription
PhenixDeviceCapabilityWidthWidth in pixels
PhenixDeviceCapabilityHeightHeight in pixels
PhenixDeviceCapabilityFrameRateNumber of frames per second
PhenixDeviceCapabilityFacingModeFacing mode
PhenixDeviceCapabilityFlashModeFlash mode
PhenixDeviceCapabilityDeviceIdDevice ID string (obtain from here)
PhenixDeviceCapabilityLocationDevice Location
PhenixDeviceCapabilityPolarPatternPolar pattern
PhenixDeviceCapabilityAudioEchoCancelationModeAudio echo cancelation mode
PhenixVideoSourceRotationModeVideo source rotation mode

Constraint Type

NameDescription
PhenixConstraintTypeMinHard constraint: Capability must have at least the specified value
PhenixConstraintTypeMaxHard constraint: Capability must have at most the specified value
PhenixConstraintTypeExactHard constraint: Capability must have exactly the specified value
PhenixConstraintTypeIdealSoft constraint: Capability should have specified value, but other values are acceptable (default)

Facing Mode

NameDescription
PhenixFacingModeAutomaticSelect a facing mode automatically (default)
PhenixFacingModeEnvironmentFacing the surrounding environment (e.g., back camera)
PhenixFacingModeUserFacing the user (e.g., front camera)

Flash Mode

Only applicable to video devices

NameDescription
PhenixFlashModeAutomaticFlash is turned on automatically when needed (default)
PhenixFlashModeAlwaysOnFlash is on (if available)
PhenixFlashModeAlwaysOffFlash is off

Device Location

NameDescription
PhenixLocationAutomaticSelect any device (default)
PhenixLocationUpperMounted on top of phone/tablet
PhenixLocationLowerMounted at bottom of phone/tablet

Polar Pattern

Only applicable to audio devices

NameDescription
PhenixPolarPatternAutomaticAutomatically select pattern (default)
PhenixPolarPatternOmnidirectionalEqually sensitive to sound from any direction
PhenixPolarPatternCardioidMost sensitive to sound from the direction in which the data source points and is (nearly) insensitive to sound from the opposite direction
PhenixPolarPatternSubcardioidMost sensitive to sound from the direction in which the data source points and is less sensitive to sound from the opposite direction

Audio Echo Cancelation Mode

Only applicable to audio devices

NameDescription
PhenixAudioEchoCancelationModeAutomaticAutomatically select AEC (default)
PhenixAudioEchoCancelationModeOnEnable AEC if available
PhenixAudioEchoCancelationModeOffDisabled AEC

Video source rotation mode

Only applicable to video devices. Determines how to orient captured video frames.

Follow device rotation will ensure that video frames match the orientation in which the user is holding the device, regardless of how the app UI may be oriented. This is generally the behavior expected by a user, i.e. if the user is holding the device sideways, then video should be in landscape mode.

Following UI rotation allows your app to keep the video orientation locked to the UI rotation, regardless of how the user is holding the device. This makes it possible for instance to lock your UI in portrait mode, and have portrait video output even if the user is holding the device sideways.

NameDescription
PhenixVideoSourceRotationModeAutomaticAutomatically select rotation mode (default)
PhenixVideoSourceRotationModeFollowDeviceRotationVideo frames oriented according to how device is held
PhenixVideoSourceRotationModeFollowUiRotationVideo frames oriented according to UI orientation

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.

Objective-C
1@import PhenixSdk;
2
3// Previously obtained via 'getUserMedia'
4id<PhenixUserMediaStream> userMediaStream = ...;
5
6// Previously initialized and used with 'getUserMedia'
7PhenixUserMediaOptions* gumOptions;
8
9[gumOptions.video.capabilityConstraints
10 [[NSNumber numberWithInteger:PhenixDeviceCapabilityFacingMode]][0]
11 updateFacingMode:PhenixFacingModeEnvironment];
12gumOptions.video.capabilityConstraints
13 [[NSNumber numberWithInteger:PhenixDeviceCapabilityFlashMode]][0]
14 updateFlashMode: PhenixFlashModeAlwaysOn];
15
16[userMediaStream applyOptions:gumOptions];

Enumerating Source Devices

You can get a list of available source devices.

Objective-C
1@import PhenixSdk;
2
3// Previously initialized and started
4id<PhenixPCast> pcast = ...;
5
6[pcast enumerateSourceDevices:^(id<PhenixPCast> pcast, NSArray<PhenixSourceDeviceInfo*>* devices) {
7 // Store devices as needed
8}:PhenixMediaTypeVideo];

Enumerating Source Devices Parameters

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

PhenixSourceDeviceInfo fields

NameTypeDescription
idNSStringSource device ID
nameNSStringSource device Name
mediaTypePhenixMediaTypeSource device media type
deviceTypePhenixSourceDeviceTypeSource device type
facingModePhenixFacingModeSource device facing mode

Media Type

NameDescription
PhenixMediaTypeVideoVideo
PhenixMediaTypeAudioAudio

Source Device Type

NameDescription
PhenixSourceDeviceTypeNullNull device (e.g. blank screen or silence)
PhenixSourceDeviceTypePhysicalPhysical device (e.g. camera or microphone)
PhenixSourceDeviceTypeSystemOutputSystem output capture (screencast)
PhenixSourceDeviceTypeSyntheticSynthetic source, used for testing
PhenixSourceDeviceTypeUriUri source, used to stream from uri

Publish a Stream

Objective-C
1@import PhenixSdk;
2
3// Previously initialized and started
4id<PhenixPCast> pcast = ...;
5// Previously generated via EdgeAuth library
6NSString* streamToken = ...;
7// Previously obtained via either PCast.subscribe or PhenixUserMediaStream.mediaStream
8id<PhenixMediaStream> mediaStream = ...;
9
10NSArray* tags = @[ @"my-tag" ];
11
12[pcast publish:
13 streamToken:
14 mediaStream:
15 ^(id<PhenixPCast> pcast, PhenixRequestStatus status, id<PhenixPublisher> publisher) {
16 // Check status and store 'publisher'
17
18 // The "streamId" of the publisher
19 NSString* streamId = publisher.streamId;
20
21 if (publisher.hasEnded == YES) {
22 // Checks if the publisher has ended
23 }
24
25 // Attach publisher ended callback
26 [publisher setPublisherEndedCallback:
27 ^(id<PhenixPublisher> publisher,
28 PhenixStreamEndedReason reason,
29 NSString* reasonDescription) {
30 // Called when the stream has ended
31 NSLog(@"Publish stream ended with reason [%@]", reasonDescription);
32 }];
33
34 // To stop later
35 [publisher stop:@"I-am-done-publishing"];
36 }:
37 tags];

Publish a Stream Parameters

NameTypeDescription
streamToken (required)stringThe publish token is generated using the Phenix EdgeAuth library
mediaStream (required)PhenixMediaStreamThe user media stream acquired through PCast.subscribe(...) or locally with PhenixUserMediaStream.mediaStream
publishCallback (required)lambdaCalled upon completion of the operation
tags (optional)array of stringsTags that will be provided with the stream notifications to your backend callback endpoint

PhenixStreamEndedReason

ReasonDescription
PhenixStreamEndedReasonEndedThe stream ended normally
PhenixStreamEndedReasonFailedThe stream failed
PhenixStreamEndedReasonCensoredThe stream was censored
PhenixStreamEndedReasonMaintenanceA maintenance event caused this stream to be terminated
PhenixStreamEndedReasonCapacityThe stream was terminated due to capacity limitations
PhenixStreamEndedReasonAppBackgroundThe stream was terminated due to the mobile app entering into the background
PhenixStreamEndedReasonCustomA custom termination reason is provided in the "reasonDescription" field

Subscribe to a Stream

Objective-C
1@import PhenixSdk;
2
3// Previously initialized and started
4id<PhenixPCast> pcast = ...;
5// Previously generated via EdgeAuth library
6NSString* streamToken = ...;
7
8[pcast subscribe:
9 streamToken:
10 ^(id<PhenixPCast> pcast,
11 PhenixRequestStatus status,
12 id<PhenixMediaStream> mediaStream) {
13 // Check status and store 'mediaStream'
14
15 // Attach stream ended callback
16 [mediaStream setStreamEndedCallback:
17 ^(id<PhenixMediaStream> mediaStream,
18 PhenixStreamEndedReason reason,
19 NSString* reasonDescription) {
20 NSLog(@"Subscriber stream ended with reason [%@]", reasonDescription);
21 }];
22
23 // To stop later
24 [mediaStream stop];
25 }];

Subscribe to a Stream Parameters

NameTypeDescription
streamToken (required)stringThe publish token is generated using the Phenix EdgeAuth library
subscribeCallback (required)lambdaCalled upon completion of the operation

View a Stream

In order to view a stream you have to attach it to a render surface.

Objective-C
1@import PhenixSdk;
2
3// Previously obtained via either PCast.subscribe or PhenixUserMediaStream.mediaStream
4id<PhenixMediaStream> mediaStream = ...;
5
6id<PhenixRenderer> renderer = [mediaStream createRenderer];
7
8[renderer setRenderSurfaceReadyCallback:
9 ^(id<PhenixRenderer> renderer, CALayer* renderSurface) {
10 // Attach layer to UI and set fill options and/or resize as needed
11 // NOTE: This may be called more than once (e.g. after interruptions)
12 }];
13
14PhenixRendererStartStatus status = [renderer start];
15
16// To stop later
17[renderer stop];

Renderer options

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

Objective-C
1@import PhenixSdk;
2
3// Previously obtained via either PCast.subscribe or PhenixUserMediaStream.mediaStream
4id<PhenixMediaStream> mediaStream = ...;
5
6PhenixRendererOptions* options = [PhenixRendererOptions new];
7options.aspectRatioMode = PhenixAspectRatioModeFill;
8options.useNullVideoDevice = NO;
9options.useNullAudioDevice = YES;
10
11
12id<PhenixRenderer> renderer = [mediaStream createRenderer:options];

Properties

NameTypeDefaultDescription
aspectRatioMode (optional)PhenixAspectRatioModePhenixAspectRatioModeFillHow to fill available video render surface
useNullAudioDevice (optional)BOOLfalseAudio will not be routed to a physical renderer device if true
useNullVideoDevice (optional)BOOLfalseVideo will not be routed to a physical renderer device if true.
hardwareAcceleratedDecodingMode (optional)PhenixHardwareAcceleratedDecodingModePhenixHardwareAcceleratedDecodingModeAutomaticHardware accelerated decoding mode

When using null devices you can still use the frame-ready API to receive the raw audio and/or video frames.

Hardware Accelerated Decoding Mode

NameDescription
PhenixHardwareAcceleratedDecodingModeAutomaticUse hardware decoding on certified devices
PhenixHardwareAcceleratedDecodingModeOnAlways use hardware decoding
PhenixHardwareAcceleratedDecodingModeOffAlways use software decoding

Aspect Ratio Mode

NameDescription
PhenixAspectRatioModeAutomaticDefaults to fill
PhenixAspectRatioModeFillFill entire render area. Video may be truncated
PhenixAspectRatioModeLetterboxBlack bars are added on sides or top/bottom of render area, video will not be truncated

Preview Local User Media

Objective-C
1@import PhenixSdk;
2
3// Previously obtained via 'getUserMedia'
4id<PhenixUserMediaStream> userMediaStream = ...;
5
6id<PhenixRenderer> renderer = [userMediaStream.mediaStream createRenderer];

Muting and Unmuting of Audio

Objective-C
1@import PhenixSdk;
2
3// Previously obtained from media stream
4id<PhenixRenderer> renderer = ...;
5
6BOOL isMuted = renderer.audioMuted;
7[renderer muteAudio];
8[renderer unmuteAudio];

Taking a Screenshot

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

Objective-C
1@import PhenixSdk;
2
3// Previously obtained from media stream and started
4id<PhenixRenderer> renderer = ...;
5
6[renderer setLastVideoFrameRenderedReceivedCallback:
7 ^(id<PhenixRenderer> pcast, CVPixelBufferRef nativeVideoFrame) {
8 // NOTE: If frame is dispatched to another thread, ensure its reference
9 // is kept alive by using CVPixelBufferRetain/CVPixelBufferRelease
10 }];
11[renderer requestLastVideoFrameRendered];

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.

Objective-C
1@import PhenixSdk;
2
3// Previously obtained from media stream and started
4id<PhenixRenderer> renderer = ...;
5
6[renderer setDataQualityChangedCallback:
7 ^(id<PhenixRenderer> renderer,
8 PhenixDataQualityStatus status,
9 PhenixDataQualityReason reason) {
10 // Inform user, take action based on status and reason
11 }];
12
13// Previously obtained via PCast.publish
14id<PhenixPublisher> publisher = ...;
15
16[publisher setDataQualityChangedCallback:
17 ^(id<PhenixPublisher> publisher,
18 PhenixDataQualityStatus status,
19 PhenixDataQualityReason reason) {
20 // Inform user, take action based on status and reason
21 }];

Data Quality Status For Publishers

StatusReasonDescription
PhenixDataQualityStatusNoDataPhenixDataQualityReasonNoneThe publisher has a bad internet connection and no data is being streamed.
PhenixDataQualityStatusNoDataPhenixDataQualityReasonUploadLimitedThe publisher has a bad internet connection and no data is being streamed.
PhenixDataQualityStatusAllPhenixDataQualityReasonNoneGood internet connection and no quality reduction in effect.
PhenixDataQualityStatusAllPhenixDataQualityReasonUploadLimitedThe publisher has a slow internet connection and the quality of the stream is reduced.
PhenixDataQualityStatusAllPhenixDataQualityReasonNetworkLimitedSubscribers have bad internet connections and the quality of the stream is reduced.
PhenixDataQualityStatusAudioOnlyPhenixDataQualityReasonUploadLimitedThe publisher has a bad internet connection and only audio is streamed.
PhenixDataQualityStatusAudioOnlyPhenixDataQualityReasonNetworkLimitedSubscribers have bad internet connections and only audio is streamed.

Data Quality Status For Viewers

StatusReasonDescription
PhenixDataQualityStatusNoDataPhenixDataQualityReasonNoneThe subscriber has a bad internet connection and no data is being received.
PhenixDataQualityStatusNoDataPhenixDataQualityReasonDownloadLimitedThe subscriber has a bad internet connection and no data is being received.
PhenixDataQualityStatusNoDataPhenixDataQualityReasonPublisherLimitedThe publisher has a bad internet connection and no data is being received.
PhenixDataQualityStatusNoDataPhenixDataQualityReasonNetworkLimitedThe network is limiting the quality of the stream and no data is being received.
PhenixDataQualityStatusAllPhenixDataQualityReasonNoneGood internet connection and no quality reduction in effect.
PhenixDataQualityStatusAllPhenixDataQualityReasonDownloadLimitedThe subscriber has a bad internet connection and the quality of the stream is reduced.
PhenixDataQualityStatusAllPhenixDataQualityReasonPublisherLimitedThe publisher has a bad internet connection and the quality of the stream is reduced.
PhenixDataQualityStatusAllPhenixDataQualityReasonNetworkLimitedOther subscribers have bad internet connections and the quality of the stream is reduced.
PhenixDataQualityStatusAudioOnlyPhenixDataQualityReasonNoneAudio only stream, good internet connection and no quality reduction in effect.
PhenixDataQualityStatusAudioOnlyPhenixDataQualityReasonDownloadLimitedThe subscriber has a bad internet connection and is only receiving audio.
PhenixDataQualityStatusAudioOnlyPhenixDataQualityReasonPublisherLimitedThe publisher has a bad internet connection and the subscriber is only receiving audio.
PhenixDataQualityStatusAudioOnlyPhenixDataQualityReasonNetworkLimitedThe 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.

Objective-C
1@import PhenixSdk;
2
3// Previously obtained from media stream
4id<PhenixRenderer> renderer = ...;
5
6[renderer setVideoDisplayDimensionsChangedCallback:
7 ^(id<PhenixRenderer> renderer, const struct PhenixDimensions* displayDimensions) {
8 // displayDimensions->width, displayDimensions->height
9 // Can get called multiple times while rendering a stream
10 }];
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10