Digging Deeper - PCast™ Express
The PCast™ Express API extends the PCast™ API to provide a single-step, configuration based API for:
- Publishing local medias
- Publishing remote media (deprecated)
- 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
const pcastExpressOptions = {
authToken: token,
};
var pcastExpress = new sdk.express.PCastExpress(pcastExpressOptions);
Initializing Options
Name | Type | Description |
---|---|---|
backendUri (required) | String | URL to your backend. We send requests here to authenticate and get streaming tokens. |
authenticationData (required) | Object | 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. |
onError (optional) | Function | Function to be called when authentication fails or a failure occurs that is unrecoverable. |
authToken (optional) | String | The authentication token generated using the Phenix EdgeAuth library. |
treatBackgroundAsOffline (optional) | Boolean | Treat background as offline. This is especially useful on iOS browsers where the network connection may be stopped when the browser is in background. This forces a reconnect upon entering foreground which can greatly improve the time to reconnect. |
reAuthenticateOnForeground (optional) | Boolean | Re-authenticate when entering foreground. This will force the session and connection to be revalidated upon entering foreground. This is automatically set to true if the treatBackgroundAsOffline option is enabled. |
Get PCast™ Express from Room Express
Get the underlying instance from an already instantiated Room Express. This is preferred to creating another instance as this will introduce more overhead.
var pcastExpress = roomExpress.getPCastExpress();
Publishing Local Media
Publish local user media:
- Camera
- Microphone
- Screen (on supported devices)
Publishing remote media from the WebSDK is deprecated. Remote media should be published using the REST API.
var options = {
publishToken: 'DIGEST:...',
mediaConstraints: { audio: true, video: true },
videoElement: document.querySelector('#myVideoId'),
};
pcastExpress.publish(options, function callback(error, response) {
if (error) {
// Handle error
}
if (response.status !== 'ok') {
// Handle error
}
// Successfully published
if (response.status === 'ok' && response.publisher) {
// Do something with publisher
}
});
Publish Parameters
Name | Type | Description |
---|---|---|
options (required) | object | Publish options |
callback (required) | function | Callback for error/success handling |
Publish options
Name | Type | Default Value | Description |
---|---|---|---|
capabilities (optional) (deprecated) | Array | The list of all capabilities to publish with. | |
mediaConstraints (required) | Object | Media constraints on the getting the user media. For example - {audio: true, video: true} | |
userMediaStream (optional) | Object | alternative to mediaConstraints - you can pass user media stream returned from getUserMedia. | |
resolution (optional) | number | 720 | Desired size for the video equal to the height for landscape and width for portrait aspect ratios. |
frameRate (optional) | number | 15 | Desired frame rate for the video |
aspectRatio (optional) | string | 16x9 | Desired aspect ratio for the video |
onResolveMedia (optional) | function | Returns the options that were used to successfully get user media | |
publishToken (optional) | String | This token is a publish token that will include all capabilities and access rights to publish. | |
videoElement (optional) | html5 video element | Video element to attach media stream to. If nothing is passed you may manually attach the media stream to an element. | |
monitor (optional) | Object | Options for monitoring a publisher for failure. | |
connectOptions (optional) | Array of Strings | List of options for publishing from a remote source. | |
tags (optional) | Array of Strings | Tags for the stream |
Publish Callback Arguments
Name | Type | Description |
---|---|---|
status | String | The status of the operation. See Publish Callback Status Codes |
publisher | [object Publisher] | Phenix publisher object |
Publishing Remote Media (deprecated)
Publishing remote media from the WebSDK is deprecated. Remote media should be published using the REST API.
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.
var options = {
publishToken: 'DIGEST:...',
streamUri: 'https://routeToMyVideo/video.mp4',
videoElement: document.querySelector('#myVideoId'),
};
pcastExpress.publishRemote(options, function callback(error, response) {
if (error) {
// Handle error
}
if (response.status !== 'ok') {
// Handle error
}
// Successfully published
if (response.status === 'ok' && response.publisher) {
// Do something with publisher
}
});
Publish Remote Parameters
Name | Type | Description |
---|---|---|
options (required) | object | Publish Remote options |
callback (required) | function | Callback for error/success handling |
Publish Remote Options
Name | Type | Default Value | Description |
---|---|---|---|
capabilities (optional) (deprecated) | Array | The list of all capabilities to publish with. | |
streamUri (required) | String | Link to remote media (mp4, rtmp, etc.) | |
streamToken (optional) | String | The publish token generated using the Phenix EdgeAuth library. | |
connectOptions (optional) | Array of Strings | List of options for publishing from a remote source. | |
tags (optional) | Array of Strings | Tags for the stream | |
frameRate (optional) | Object | Frame rate constraints. For example - {max: 30, exact: 30} | |
prerollSkipDuration (optional) | int | 500 | The amount of milliseconds to skip at the beginning of the media. |
Publish Remote Callback Arguments
Name | Type | Description |
---|---|---|
status | String | The status of the operation. See Publish Callback Status Codes |
publisher | [object Publisher] | Phenix publisher object |
Subscribing to Published Media
Subscribe to streams published with the Phenix platform
var options = {
streamId: publisher.getStreamId(),
publishToken: 'DIGEST:...',
videoElement: document.querySelector('#myVideoId'),
};
pcastExpress.subscribe(options, function callback(error, response) {
if (error) {
// Handle error
}
if (response.status !== 'ok') {
// Handle error
}
// Successfully subscribed
if (response.status === 'ok' && response.mediaStream) {
// Do something with mediaStream
if (response.renderer) {
// Returned if videoElement option passed in - Do something with renderer
response.renderer.on('autoMuted', function handleAutoMuted() {
// The browser refused to play video with audio therefore the stream was started muted.
// Handle this case properly in your UI so that the user can unmute its stream
});
response.renderer.on('failedToPlay', function handleEnded(reason) {
if (reason === 'failed-to-play') {
// Failed to play media stream
}
if (reason === 'failed-to-play-unmuted') {
// Failed to play media stream given the auto mute was disabled
}
if (reason === 'paused-by-background') {
// Unable to resume playback after pause in Safari
}
});
}
}
});
Subscribe Parameters
Name | Type | Description |
---|---|---|
options (required) | object | Subscribe options |
callback (required) | function | Callback for error/success handling |
Subscribe Options
Name | Type | Default Value | Description |
---|---|---|---|
streamId (required) | String | The stream ID of the published stream | |
capabilities (optional) (deprecated) | Array | The list of all capabilities to subscribe with. | |
streamToken (optional) | String | A stream token used to connect to the stream. | |
videoElement (optional) | html5 video element | Video element to attach media stream to. If nothing is passed you may manually attach the media stream to an element. | |
monitor (optional) | Object | Monitor Options | |
connectOptions (optional) | Array of Strings | List of options for subscribing | |
tags (optional) | Array of Strings | Tags for the stream | |
subscriberOptions (optional) | [Object SubscriberOptions] | Additional options to use when subscribing. |
Sample Monitor Options
var monitorOptions = {
options: {
// Optional: Additional options for monitoring a stream
conditionCountForNotificationThreshold: 4,
// Number of conditions before triggering callback
},
callback: function monitorCallback(error, response) {
// Optional: Handle monitor event
if (error) {
// Handle error
}
if (response.retry) {
response.retry();
// Re-connects publisher or subscriber stream
}
},
};
Monitor Options
Name | Type | Default Value | Description |
---|---|---|---|
options (optional) | Object | Additional Monitoring options | |
callback (optional) | Function | call function for handling monitor event |
Additional Monitoring options
Name | Type | Default Value | Description |
---|---|---|---|
conditionCountForNotificationThreshold | Number | 3 | Number of consecutive "conditions" that can occur before the callback is triggered. A condition is counted whenever one of the below thresholds is violated. |
frameRateThreshold | Number | 2 | Framerate below which the condition count is incremented (fps) |
videoBitRateThreshold | Number | 6000 | Video bitrate below which the condition count is incremented (bps) |
audioBitRateThreshold | Number | 5000 | Audio bitrate below which the condition count is incremented (bps) |
monitoringInterval | Number | 4000 | When the state is healthy, how often to check the state (milliseconds) |
conditionMonitoringInterval | Number | 1500 | After a condition, how often to check the state (milliseconds) |
monitorFrameRate | Bool | true | Enable or disable the frameRateThreshold |
monitorBitRate | Bool | true | Enable or disable the videoBitRateThreshold and audioBitRateThreshold |
monitorState | Bool | true | Enable or disable monitoring of the native state of the RTCPeerConnection |
Express Subscribe Callback Arguments
Name | Type | Description |
---|---|---|
status | String | The status of the operation. See Subscribe Callback Status Codes |
mediaStream | [object MediaStream] | Phenix media stream object |
renderer | [object Renderer] | Optionally returns Phenix renderer if videoElement option is passed in |
retry | Function | Optionally returns a function to retry subscription if unable to start stream |
Express Get User Media
Get local user media. Use for more granular control over requesting media and handling failure. We automatically resolve any constraint errors when getting the user media:
- for a resolution issue (width or height): drop to the next closest resolution (resolution isn't supported on the requested device)
- for a frame rate issue: remove the frame rate constraint (frame rate isn't supported on device)
- for an aspect ratio issue: drop to next aspect ratio at highest requested resolution (aspect ratio at resolutions is not supported)
var options = {
mediaConstraints: { audio: true, video: true },
resolution: 1080,
frameRate: 30,
aspectRatio: '4x3',
};
pcastExpress.getUserMedia(options, function callback(error, response) {
if (error) {
// Handle error
}
if (response.status !== 'ok') {
// Handle error
}
// Successfully got user media
if (response.status === 'ok' && response.userMedia) {
// Do something with userMedia
}
});
Get User Media Parameters
Name | Type | Description |
---|---|---|
options (required) | object | Publish options |
callback (required) | function | Callback for error/success handling |
Get User Media options
Name | Type | Default Value | Description |
---|---|---|---|
mediaConstraints (required) | Object | Media constraints on the getting the user media. For example - {audio: true, video: true} | |
resolution (optional) | number | 720 | Desired size of the video |
frameRate (optional) | number | 15 | Desired frame rate for the video |
aspectRatio (optional) | string | 16x9 | Desired aspect ratio for the video |
onResolveMedia (optional) | function | Returns the options that were used to successfully get user media |
Get User Media Callback Arguments
Name | Type | Description |
---|---|---|
status | String | The status of the operation. |
userMedia | native MediaStream | The browser's native media stream object. |
Supported Resolutions
Any resolution may be passed. If we are unable to get the user media at that resolution we will drop to the next closest resolution at that aspect ratio in the table below. We will continue dropping to the next closest resolution until we run out of options or the user media is successfully received. Similarly, when all resolution options at an aspect ratio are exhausted we will attempt to resolve the highest resolution requested at the next lowest aspect ratio.
Aspect Ratio | Resolution (Longer dimension) | Shorter dimension | Description |
---|---|---|---|
9x16 | 1920 | 1080 | 1080p (FHD) |
1366 | 768 | ||
1280 | 720 | 720p (HD) | |
1024 | 576 | ||
854 | 480 | 480p | |
640 | 360 | 360p (nHD) | |
320 | 180 | ||
3x4 | 1600 | 1200 | UXGA |
1440 | 1080 | ||
960 | 720 | ||
800 | 600 | SVGA | |
768 | 576 | ||
640 | 480 | VGA | |
480 | 360 | ||
320 | 240 | QVGA | |
160 | 120 | QQVGA | |
16x9 | 1080 | 1920 | 1080p (FHD) |
768 | 1366 | ||
720 | 1280 | 720p (HD) | |
576 | 1024 | ||
480 | 854 | 480p | |
360 | 640 | 360p (nHD) | |
180 | 320 | ||
4x3 | 1200 | 1600 | UXGA |
1080 | 1440 | ||
720 | 960 | ||
600 | 800 | SVGA | |
576 | 768 | ||
480 | 640 | VGA | |
360 | 480 | ||
240 | 320 | QVGA | |
120 | 160 | QQVGA |
Longer dimension is the width for landscape orientations and the height for portrait orientations.
Shorter dimension is the height for landscape orientations and the width for portrait orientations.
Portrait orientations are only supported by some browsers including newer versions of Chrome and Opera.
Supported Frame Rates
60, 30, 15, or any other value. If a frame rate is not resolved we will request media without the frame rate constraint.
Get PCast™
Get the underlying instance of the PCast™. This is preferred to creating another instance as this will introduce more overhead.
var pcast = pcastExpress.getPCast();
Clean up PCast™ Express
Dispose of all active connections and clean up all handlers.
var pcastExpress = pcastExpress.dispose();