Single-step configuration based API for setting up a channel - a one-size-fits-all solution for all your one-to-many streaming applications. The Channel Express extends the lower-level Room Service API to provide easy solutions to:
View a channel
Publish to a channel
Initializing
Initialization is a critical step in the lifecycle of viewing a channel. Once ChannelExpress is initialized, the client connects to our Platform. This connection utilizes sophisticated recovery mechanisms to deal with network changes and/or temporary connectivity issues.
Due to the inherent scale that some channels bring along, the ChannelExpress needs to be initialized as soon as possible after the end user loads the web app. This approach provides our platform the necessary telemetry to adjust the capacity to the actual size of the audience which may exceed hundreds of thousands of concurrent users.
Function to be called when authentication fails or a failure occurs that is unrecoverable.
authToken (optional)
String
An authentication token used to connect to the platform.
pcastExpress (optional)
[object PCastExpress]
Optionally pass in an already instantiated PCastExpress. This reduces the amount of overhead and is preferred to instantiating separate instances. If provided backendUri and authenticationData are not required.
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.
shakaLoader (optional)
function(callback)
Function that asynchronously returns the instance of Shaka Player. See npm.js shaka-player. Certified version 2.5.X.
webPlayerLoader (optional)
function(callback)
Function that asynchronously returns the instance of the Phenix Web Player. It's recommended to use the Phenix Web Player to play DASH/HLS streams. See npm.js phenix-web-player. Certified version >=2020.0.2.
Clean Up Channel Express
Dispose of all connections and clean up handlers.
JavaScript
channelExpress.dispose();
Enabling DASH/HLS Playback
The player for DASH/HLS is loaded asynchronously to enable lazy loading for this functionality on-demand. This speeds up startup and thus time to first frame for the real-time use case by not loading modules that are not required.
The exact approach how to load the player asynchronously depends on the bundling framework. Webpack 4.X supports lazy loading.
varoptions= {alias: 'MyAwesomeChannel',videoElement: document.querySelector('#myVideoId'),};channelExpress.joinChannel(options,functionjoinChannelCallback(error, response) {if (error) {// Handle error }if (response.status==='room-not-found') {// Handle channel not found - Create a Channel Or Publish to a Channel } elseif (response.status!=='ok') {// Handle error }// Successfully joined channelif (response.status==='ok'&&response.channelService) {// Do something with channelService } },functionsubscriberCallback(error, response) {if (error) {// Handle error }if (response.status==='no-stream-playing') {// Handle no stream playing in channel - Wait for one to start } elseif (response.status!=='ok') {// Handle error }// Successfully subscribed to most recent channel presenterif (response.status==='ok'&&response.mediaStream) {// Do something with mediaStream }if (response.renderer) {// Returned if videoElement option passed in - Do something with rendererresponse.renderer.on('autoMuted', functionhandleAutoMuted() {// 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', functionhandleEnded(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 } }); } });
There is no presenter in channel to subscribe to. Waiting for a presenter to appear in channel.
unsupported-features
The type of stream is not compatible with the enabled feature set of the browser. E.g. real-time on IE.
unauthorized
Access to stream was no authorized. Check if your edge token uses the correct channel alias.
varies
Subscribe to presenter failed for other reasons. Note that channel express automatically retries failure condition that are retriable including failover.
[Object SubscriberOptions]
Name
Type
Default
Description
targetLatency (optional)
number
8
The target latency to achieve when playing back Dash or HLS streams.
receiveAudio (optional)
boolean
true
Whether or not to receive audio on the stream.
receiveVideo (optional)
boolean
true
Whether or not to receive video on the stream.
disableAudioIfNoOutputFound (optional)
boolean
false
Whether to disable audio if no audio is found to avoid stream monitor failures.
disableAutoMuting (optional)
boolean
false
Whether to disable fall back to muted streams if browser refuses auto play of audio.
iceConnectionTimeout (optional)
number
12000
The default timeout in milliseconds for the ICE connection to successfully connect.
tags (optional)
Array of Strings
Tags for the stream
Publish to a Channel
Publish a local or remote media to a channel. Users that are viewing the channel will see your media.
Publishing remote media from the WebSDK is deprecated. Remote media should be
published using the REST API.
varoptions= {channel: {name: 'MyAwesomeChannel',alias: 'MyAwesomeChannelAlias', // Not required but if it is provided we will use this as the alias instead of pre-generating one for you. },publishToken: 'DIGEST:...',mediaConstraints: { audio: true, video: true },videoElement: document.querySelector('#myVideoId'),};channelExpress.publishToChannel(options, functioncallback(error, response) {if (error) {// Handle error }if (response.status!=='ok') {// Handle error }// Successfully published to channelif (response.status==='ok'&&response.publisher) {// Do something with publisher }});
Publish To Channel Parameters
Name
Type
Description
options (required)
Options
Options to publish to channel with
callback (required)
Function
Function to call on success/failure of publishing to the channel
Creation of Channels from client SDKs is deprecated. Channels should be
created by the backend using the REST
API.
JavaScript
varoptions= {channel: {name: 'MyAwesomeChannel',alias: 'MyAwesomeChannelAlias', // Not required but if it is provided we will use this as the alias instead of pre-generating one for you. },};channelExpress.createChannel(options, functioncallback(error, response) {if (error) {// Handle error }if (response.status==='already-exists') {// Channel already exists// Do something with channelService } elseif (response.status!=='ok') {// Handle error }// Successfully created channelif (response.status==='ok'&&response.channelService) {// Do something with channelService }});