• 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
  • Web SDK 1.0
    • Overview
    • Express API
    • Low-Level API
  • Web SDK 2.0
    • Overview
    • Channel
  • Browser Support
  • Web Examples
  • Release Notes

Channel Express

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.

JavaScript
1var channelExpress = new sdk.express.ChannelExpress(options);

Initializing Options

NameTypeDescription
features (optional)[Array Feature]The list of features you would like supported
onError (optional)FunctionFunction to be called when authentication fails or a failure occurs that is unrecoverable.
authToken (optional)StringAn 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)BooleanTreat 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)BooleanRe-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
1channelExpress.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.

Plain Vanilla Javascript Example

JavaScript
1options.webPlayerLoader = function (callback) {
2 var script = document.createElement('script');
3 script.onload = function () {
4 callback(window['phenix-web-player']);
5 };
6 script.src =
7 'https://dl.phenixrts.com/WebPlayer/2020.0.latest/phenix-web-player-bundled.min.js';
8
9 document.head.appendChild(script);
10};
JavaScript
1options.shakaLoader = function (callback) {
2 var script = document.createElement('script');
3 script.onload = function () {
4 callback(window.shaka);
5 };
6 script.src =
7 'https://ajax.googleapis.com/ajax/libs/shaka-player/2.5.14/shaka-player.compiled.js';
8
9 document.head.appendChild(script);
10};

React.js + Webpack 4.X Example:

JavaScript
1options.webPlayerLoader = (callback) => {
2 import(/* webpackChunkName: "phenix-web-player" */ 'phenix-web-player')
3 .then((module) => {
4 const webPlayer = module.default;
5
6 callback(webPlayer);
7 })
8 .catch((e) => {
9 console.error('Failed to load phenix web player', e);
10
11 callback(null);
12 });
13};
JavaScript
1options.shakaLoader = (callback) => {
2 import(/* webpackChunkName: "shaka-player" */ 'shaka-player').then(module => {
3 const shaka = module.default;
4 const canPlayHls: document.createElement('video').canPlayType('application/vnd.apple.mpegURL') === 'maybe';
5
6 if (!canPlayHls && !shaka.Player.isBrowserSupported()) {
7 shaka.polyfill.installAll();
8 }
9
10 callback(shaka);
11 }).catch(e => {
12 console.error('Failed to load shaka', e);
13
14 callback(null);
15 });
16};

View a Channel

Join a channel and automatically view the most recent content published to that channel.

View interactive and editable example on JSFiddle

View example on Github

JavaScript
1var options = {
2 alias: 'MyAwesomeChannel',
3 videoElement: document.querySelector('#myVideoId'),
4};
5
6channelExpress.joinChannel(
7 options,
8 function joinChannelCallback(error, response) {
9 if (error) {
10 // Handle error
11 }
12
13 if (response.status === 'room-not-found') {
14 // Handle channel not found - Create a Channel Or Publish to a Channel
15 } else if (response.status !== 'ok') {
16 // Handle error
17 }
18
19 // Successfully joined channel
20 if (response.status === 'ok' && response.channelService) {
21 // Do something with channelService
22 }
23 },
24 function subscriberCallback(error, response) {
25 if (error) {
26 // Handle error
27 }
28
29 if (response.status === 'no-stream-playing') {
30 // Handle no stream playing in channel - Wait for one to start
31 } else if (response.status !== 'ok') {
32 // Handle error
33 }
34
35 // Successfully subscribed to most recent channel presenter
36 if (response.status === 'ok' && response.mediaStream) {
37 // Do something with mediaStream
38 }
39
40 if (response.renderer) {
41 // Returned if videoElement option passed in - Do something with renderer
42
43 response.renderer.on('autoMuted', function handleAutoMuted() {
44 // The browser refused to play video with audio therefore the stream was started muted.
45 // Handle this case properly in your UI so that the user can unmute its stream
46 });
47
48 response.renderer.on('failedToPlay', function handleEnded(reason) {
49 if (reason === 'failed-to-play') {
50 // Failed to play media stream
51 }
52 if (reason === 'failed-to-play-unmuted') {
53 // Failed to play media stream given the auto mute was disabled
54 }
55 if (reason === 'paused-by-background') {
56 // Unable to resume playback after pause in Safari
57 }
58 });
59 }
60 }
61);

View Channel Parameters

NameTypeDescription
options (required)OptionsOptions to join channel with
joinChannelCallback (required)FunctionFunction to call on success/failure of joining the channel. See Join Channel Callback Arguments
subscriberCallback (required)FunctionFunction to call on when the most recent presenter changes. See Express Subscribe Callback Arguments

View Channel Options

NameTypeDefault ValueDescription
alias (required)StringAlias of the channel to view
channelId (optional)StringAlternative to alias - Id of the channel to view
streamSelectionStrategy (optional)Stringmost-recentStrategy for selecting streams
streamToken (optional)StringA stream token used to connect to the stream.
subscriberOptions (optional)[Object SubscriberOptions]Additional options to use when subscribing.
videoElement (optional)html5 video elementVideo element to attach media stream to. If nothing is passed in, you may manually attach the media stream to an element.

Stream Selection Strategy

StrategyDescription
most-recentSelect the most recent stream. Viewing stream changes any time a stream starts or is updated in the room.
high-availabilitySelect streams for increased reliability and redundancy. Viewing stream will only change in the event of a failure of the prior selected stream.

Join Channel Callback Response

NameTypeDescription
statusStringThe status of the operation. See Join Channel Callback Status Codes.
channelService[object ChannelService]The channel service object.
channel[object Channel]An immutable channel object containing the information about the channel.

Join Channel Callback Status Codes

StatusDescription
okSuccessfully joined the channel.
not-foundThe channel that is being joined does not exist.
variesJoining channel failed for other reasons.

[object ChannelService]

NameSignatureReturnsDescription
getChatService()[object ChatService]The chat service associated with the channel.

[object Channel]

NameSignatureReturnsDescription
getChannelId()stringThe channel ID.
getObservableAlias()Observable(of string)Observable of channel alias.
getObservableName()Observable(of string)Observable of channel name.
getObservableDescription()Observable(of string)Observable of channel description.
getObservableType()Observable(of string)Observable of channel type. Will be equal to Channel.
getObservableMembers()Observable(of array)Observable of array of visible members in the channel.
toJson()objectReturns channel object with current observable values.

[object Member]

NameSignatureReturnsDescription
getSessionId()stringThe session ID of the member.
getObservableRole()Observable(of string)Observable of member role.
getObservableState()Observable(of string)Observable of member state.
getObservableScreenName()Observable(of string)Observable of member screen name.
getObservableStreams()Observable(of array)Observable of array of streams belonging to the member.
getObservableLastUpdate()Observable(of number)Observable of utc timestamp.
getLastUpdate()NumberCurrent last update value of the member.

Member Roles

RoleDescription
ParticipantMember with streams and is visible to all members.
AudienceMember with no streams and is not visible to other members.
PresenterPresenter participant member.
ModeratorPrivileged participant member.

Member States

RoleDescription
ActiveMember is active.
PassiveMember is not active.
HandRaisedMember is requesting to become active.
InactiveMember is not active.
OfflineMember has left the room.

[object Stream]

The stream object represent any stream resource.

NameSignatureReturnsDescription
getUri()stringThe stream uri representing the stream resource
getType()stringThe stream type
getObservableAudioState()Observable(of string)Observable of stream video state
getObservableVideoState()Observable(of string)Observable of stream audio state

Stream Types

TypeDescription
PresentationPresentation stream
AudioAudio-only stream
UserGeneral purpose stream

Stream Track States

StateDescription
TrackEnabledTrack is enabled
TrackDisabledTrack is disabled
TrackEndedTrack has ended

Join Channel Subscriber Callback Status Codes

StatusDescription
okSuccessfully subscribed to the presenter.
no-stream-playingThere is no presenter in channel to subscribe to. Waiting for a presenter to appear in channel.
unsupported-featuresThe type of stream is not compatible with the enabled feature set of the browser. E.g. real-time on IE.
unauthorizedAccess to stream was no authorized. Check if your edge token uses the correct channel alias.
variesSubscribe to presenter failed for other reasons. Note that channel express automatically retries failure condition that are retriable including failover.

[Object SubscriberOptions]

NameTypeDefaultDescription
targetLatency (optional)number8The target latency to achieve when playing back Dash or HLS streams.
receiveAudio (optional)booleantrueWhether or not to receive audio on the stream.
receiveVideo (optional)booleantrueWhether or not to receive video on the stream.
disableAudioIfNoOutputFound (optional)booleanfalseWhether to disable audio if no audio is found to avoid stream monitor failures.
disableAutoMuting (optional)booleanfalseWhether to disable fall back to muted streams if browser refuses auto play of audio.
iceConnectionTimeout (optional)number12000The default timeout in milliseconds for the ICE connection to successfully connect.
tags (optional)Array of StringsTags 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.

View interactive and editable example on JSFiddle

View example on Github

JavaScript
1var options = {
2 channel: {
3 name: 'MyAwesomeChannel',
4 alias: 'MyAwesomeChannelAlias', // Not required but if it is provided we will use this as the alias instead of pre-generating one for you.
5 },
6 publishToken: 'DIGEST:...',
7 mediaConstraints: { audio: true, video: true },
8 videoElement: document.querySelector('#myVideoId'),
9};
10
11channelExpress.publishToChannel(options, function callback(error, response) {
12 if (error) {
13 // Handle error
14 }
15
16 if (response.status !== 'ok') {
17 // Handle error
18 }
19
20 // Successfully published to channel
21 if (response.status === 'ok' && response.publisher) {
22 // Do something with publisher
23 }
24});

Publish To Channel Parameters

NameTypeDescription
options (required)OptionsOptions to publish to channel with
callback (required)FunctionFunction to call on success/failure of publishing to the channel

Publish To Channel Options

NameTypeDefault ValueDescription
channel (required)ObjectChannel Options
capabilities (optional) (deprecated)ArrayThe list of all capabilities to publish with.
mediaConstraints (required)ObjectMedia constraints on the getting the user media. For example - {audio: true, video: true}
userMediaStream (optional)Objectalternative to mediaConstraints - you can pass user media stream returned from getUserMedia.
streamUri (optional)Stringalternative to mediaConstraints. Use to publish remote media. Link to remote media (mp4, rtmp, etc.)
streamType (optional)StringPresenterType of stream to publish. See Stream Types
memberRole (optional)StringPresentationRole of member to join channel as (used if not already in channel). See Member Roles
resolution (optional)number720Desired size of the video
frameRate (optional)number15Desired frame rate of the video
aspectRatio (optional)string16x9Desired aspect ratio of the video
onResolveMedia (optional)functionReturns the options that were used to successfully get user media
publishToken (optional)StringThis token is a publish token that will include all capabilities and access rights to publish.
videoElement (optional)html5 video elementVideo element to attach media stream to. If nothing is passed you may manually attach the media stream to an element.
monitor (optional)ObjectOptions for monitoring a publisher for failure.
connectOptions (optional)Array of StringsList of options for publishing from a remote source.
tags (optional)Array of StringsTags for the stream
prerollSkipDuration (optional)int500Remote media only. The amount of milliseconds to skip at the beginning of the media.

Channel Options

NameTypeDefault ValueDescription
name (required)StringChannel Name
alias (Optional)StringChannel Alias
description (Optional)StringDescription of the Channel

Publish To Channel Callback Arguments

NameTypeDescription
statusStringThe status of the operation. See Publish Callback Status Codes
publisher[object Publisher]Phenix publisher object

Publish Screen to a Channel

Publish your screen, tab, or application window to a channel. An error will be returned if a channel corresponding to the Channel Options passed does not exist. If you have not entered the channel via joinChannel or publishToChannel methods then a model for Self will be created.

JavaScript
1var options = {
2 channel: {
3 name: 'MyAwesomeChannel',
4 alias: 'MyAwesomeChannelAlias', // Not required but if it is provided we will use this as the alias instead of pre-generating one for you.
5 },
6 publishToken: 'DIGEST:...',
7 mediaConstraints: { audio: true, video: true },
8 videoElement: document.querySelector('#myVideoId'),
9};
10
11channelExpress.publishScreenToChannel(
12 options,
13 function callback(error, response) {
14 if (error) {
15 // Handle error
16 }
17
18 if (response.status !== 'ok') {
19 // Handle error
20 }
21
22 // Successfully published to channel
23 if (response.status === 'ok' && response.publisher) {
24 // Do something with publisher
25 }
26 }
27);

Publish Screen To Channel Parameters

NameTypeDescription
options (required)OptionsOptions to publish to channel with
callback (required)FunctionFunction to call on success/failure of publishing to the room

Publish Screen To Channel Options

NameTypeDefault ValueDescription
channel (required)ObjectChannel Options
capabilities (optional) (deprecated)ArrayThe list of all capabilities to publish with.
mediaConstraints (optional)Object{screen: true}Media constraints on the getting the user media.
userMediaStream (optional)Objectalternative to mediaConstraints - you can pass user media stream returned from getUserMedia.
streamType (optional)StringPresenterType of stream to publish. See Stream Types
memberRole (optional)StringPresentationRole of member to join channel as (used if not already in channel). See Member Roles
resolution (optional)number720Desired size of the video
frameRate (optional)number15Desired frame rate of the video
aspectRatio (optional)string16x9Desired aspect ratio of the video
onResolveMedia (optional)functionReturns the options that were used to successfully get user media
publishToken (optional)StringThis token is a publish token that will include all capabilities and access rights to publish.
videoElement (optional)html5 video elementVideo element to attach media stream to. If nothing is passed you may manually attach the media stream to an element.
monitor (optional)Object{options: {monitorFrameRate: false, videoBitRateThreshold: 1000, conditionCountForNotificationThreshold: 8}}Options for monitoring a publisher for failure.
connectOptions (optional)Array of StringsList of options for publishing from a remote source.
tags (optional)Array of StringsTags for the stream

Publish Screen To Channel Callback Arguments

NameTypeDescription
statusStringThe status of the operation. See Publish Callback Status Codes
publisher[object Publisher]Phenix publisher object

Create a Channel (deprecated)

Creation of Channels from client SDKs is deprecated. Channels should be created by the backend using the REST API.
JavaScript
1var options = {
2 channel: {
3 name: 'MyAwesomeChannel',
4 alias: 'MyAwesomeChannelAlias', // Not required but if it is provided we will use this as the alias instead of pre-generating one for you.
5 },
6};
7
8channelExpress.createChannel(options, function callback(error, response) {
9 if (error) {
10 // Handle error
11 }
12
13 if (response.status === 'already-exists') {
14 // Channel already exists
15 // Do something with channelService
16 } else if (response.status !== 'ok') {
17 // Handle error
18 }
19
20 // Successfully created channel
21 if (response.status === 'ok' && response.channelService) {
22 // Do something with channelService
23 }
24});

Express Create Channel Parameters

NameTypeDescription
options (required)OptionsOptions to create channel with
callback (required)FunctionFunction to call on success/failure of creating to the channel. See Create Channel Callback Arguments

Express Create Channel Options

NameTypeDefault ValueDescription
channel (required)ObjectChannel Options

Express Create Channel Callback Arguments

NameTypeDescription
statusStringThe status of the operation. See Create Room Callback Status Codes
channel[object Room]Immutable Phenix room object
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10