Cloud Console

The Configuration and Reporting Console

The LiveSwitch Cloud Console is a Web Application which makes managing your applications and channels easier than ever Additionally, the Console provides a Dashboard which presents Channel, Client, and Connection statistics reports giving you insight into how your users are using your Client Applications. Access your Console by logging into https://console.liveswitch.io. This guide introduces you to the Console and its features. There are several important concepts to cover before we go on, so that you understand what it is you are configuring, and how it applies to your LiveSwitch infrastructure.

Concepts

The Console deals with some configuration entities that may be new to you. These configuration entities are used to configure your client application environment(s). 

  • Applications - client application shared secret and global settings.
  • Channels - subordinate to a given application, channel configuration is specific to particular channels joined by your clients and is focused primarily on specifying media settings.

Applications and Channels are first class concepts in the Console. Applications have their own prime spot in the top level navigation. Channels are special because they belong to an Application, and as such are listed as part of their Application's page.

This has been a brief introduction to the Console's configuration entities, read on for a more comprehensive discussion on configuring the available configuration properties for Applications and Channels. This guide also introduces the remaining top level pages of your Console. These are the Dashboard page, the API Keys page, the Subscription page,  and the Downloads page.

Dashboard

You Dashboard is the first page you will see whenever you log in to the Console. It is a landing area, and it also provides you with several reports regarding Channel, Client, and Connection statistics. These statistics are always relevant to a particular Application, so your Dashboard provides an Application selector for you, which will default to your first configured Application, while allowing you to switch between Applications at will.

For the selected Application the Dashboard lists a count of currently active Clients, Connections, and Channels. It displays reports on the number of connections per hour, and the number of connections per day. It also provides several aggregate reports on Client Platform usage and Browser Usage, along with a report on the geographical distribution of client connections.

Real-time Channel, Client, and Connection details are listed in the Connections Statistics table. The table also provides an option to view historical connection details for the previous 24 hours. Drilling down in the Connections Statistics table ultimately takes you to the Stats page for the given connections, where you are presented with WebRTC connection statistics graphs showing the quality of your connections.

Sessions

Session info page displays channel session activities for each application.

Live shows channels that are currently in use. You are able to see User Count, Device Count,  Client Count and Connection Count of each session.

Previous 24 Hours shows channels that have been used for the last 24 hours. You are able to see Start Time, Stop Time, Client Count, Duration and Quality of each session.

Configuration Entities

Application Configuration

Your Applications page displays a listing of your configured Applications. Applications consist of one or more channels. Channels are what your clients join, and are used for specifying the media configuration clients make use of for SFU or MCU connections. Applications also specify some useful configuration properties that will be shared by all clients, regardless of which channel they join. These properties are the Application's Tag, Shared Secret, and Webhook Configurations. Read on for more information.

Tag

The tag is a human readable label for your Application. It is simply an easy way for you to refer to a given Application, and has no bearing on behaviour.

Application ID

The Application Identifier used in your Client code. This is read only, and is not configurable by design.

Gateway URL

The Gateway URL indicates the entry point for the Gateway (https://cloud.liveswitch.io) and is used by LiveSwitch Media Servers and SIP Connectors. 

Shared Secret

The Shared Secret is known by both your Application Configuration, and the clients trying to join an Application and Channel. It is used to authenticate client join requests. See the Client docs for more information on configuring shared secrets in your LiveSwitch client side code. 

Webhook Configuration

Webhooks allow you to extend LiveSwitch functionality by hooking your own processing into Application level events. These events are Client RegisteredClient Unregistered, and Client Updated. Add a new webhook by clicking the NEW button and supplying:

  • Name - A human readable name of the webhook (does not have to be unique).
  • URL - The server to POST event information to (both HTTP and HTTPS are supported, but HTTPS is recommended).
  • Event Triggers - The Application level events will trigger a POST to your webhook.
  • Batch - POST multiple events in a single call. Without this set each event will result in a separate call.
  • Reliable - In the event of a failure, continue trying until successful.
  • Disabled - A convenience mechanism which supports disabling the hook while allowing you to keep the configuration.

Channel Configuration

Channels provide a mechanism for specifying media configuration used by client MCU and SFU connections. Channels belong to an Application, and are listed on the Application's page.

Within the context of an Application clients can have many different use cases. Channels are the best way to meet the requirements of a given use case. For example, clients might join a Channel to stream audio/video from their mic and camera, and join a different Channel specifically to stream screen capture video. The first channel needs to configure audio/video encoders, but the latter need not configure audio and it may specify a different video encoding configuration. Channels support many different configuration properties. Read on for a comprehensive discussion. However, let's first discuss how Channel Configurations are matched to a client requesting to join a Channel.

The Channel Pattern and the Default Channel

Channels have a Channel Pattern instead of a name, and this pattern supports the wildcard '*' character. When a client requests to join a Channel LiveSwitch Cloud will look at all of the Channels available and pick the Channel that best matches. Matches are attempted in the order specified in your Application's Channel listing. If you want to change the attempted matching order you can just drag Channels around in the listing to get the order that works best.

One special case is provided here - the "Default Channel". The Default Channel has a Channel ID Pattern equal to the wildcard character '*'. As you might imagine, this will match anything and everything. The Default Channel is provided for you when you create an Application. The Default Channel is always last in the list of an Application's Channels meaning that it will match last. It is a catch-all, which serves to ensure your clients will always have a Channel Configuration applied to their connections. You can configure your Default Channel to meet your most general requirements.

Now that you understand what Channels are, and how they can be used, let's consider all of the configuration properties provided by the Channel Configuration.

Audio Codecs

The Audio Codecs Configuration allows you to specify which audio codecs are supported by the LiveSwitch Media Server. The available codecs are:

  • Opus: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.
  • PCMU: Enabled by turning the switch to the on position.
  • PCMA: Enabled by turning the switch to the on position.
  • G.722: Enabled by turning the switch to the on position.

Please note that bitrate here (in Kbps) is a downstream rate, which means that if you specify 1024, then this is the maximum rate that will be sent in the downstream.

Codecs

Note that if you disable too many codecs, the LiveSwitch Cloud may be unable to accept connections.

Video Codecs

The Video Codecs Configuration allows you to specify which video codecs are supported by the LiveSwitch Media Server. The available codecs are:

  • VP8: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.
  • VP9: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.
  • H264: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.

Please note that bitrate here (in Kbps) is a downstream rate, which means that if you specify 1024, then this is the maximum rate that will be sent in the downstream.

Codecs

Note that if you disable too many codecs, the LiveSwitch Cloud may be unable to accept connections.

SFU Configuration

SFU Configuration allows you to set configuration options for SFU connections. You are not able to set the video or audio output, as the SFU does not actually perform any processing of audio and video streams - it merely forwards them. You can however, configure is the Video Input Max Bitrate and Audio Input Max Bitrate for participants while in an SFU session. The value of these properties is in kbps.

Please note that bitrate here (in Kbps) is an upstream rate, which means that if you specify 1024, then this is what LiveSwitch Cloud will attempt to negotiate with participants.

MCU Configuration

MCU Configuration allows you to set configuration options for MCU connections. Among other things, this allows you to define how you want the output video to be formatted by the multiplexer. To configure this you can set both the Frame Width and Frame Height dimensions, and the Target Frame Rate of the video that the MCU outputs.

For video resolutions, you should try to stick to common resolutions, as not all combinations are valid for all codecs. For example, don't enter 147x933. You should also keep your frame rate to a reasonable value. Anything beyond 30 frames per second will require a powerful server to keep up in larger video conferences.

Another aspect that you can configure is the Video Input Max Bitrate and Audio Input Max Bitrate for participants while in an MCU session. This is useful to limit the amount of bandwidth that the MCU consumes. The value of these properties is in kbps.

Please note that bitrate here (in Kbps) is an upstream rate, which means that if you specify 1024, then this is what LiveSwitch Cloud will attempt to negotiate with participants.

For controlling mixer layout, the Video Input Margin allows you to specify the amount of pixels to use as a margin between video frames in the MCU video output, and the Crop Input Videos toggle adds support for cropping video frames to fill all available space in MCU video output. For even more customization of your MCU video layout you can specify your own layout function.

Configuring MCU Simulcast

MCU Simulcast can be enabled and configured in your Channel Configuration's MCU Configuration section. This feature allows for multiple encodings per stream, and is detailed here.

Under Simulcast Config, enter the maximum number of encodings per video input. You can configure up to 3.

Pressing "New" adds an encoding. An encoding configuration will appear, and you can set the bitrate (in Kbps), frame rate and video scaling as desired for that encoding. This new encoding can be modified at any time by changing the values and hitting "Save", or deleted by clicking the 'x'.

Bandwidth Adaptation Policy

Your Bandwidth Adaptation Policy property is Enabled by default to turn on bandwidth adaptation for your SFU and MCU connections. This is the recommended setting. In your native client code, the VideoStream BandwidthAdaptationPolicy is also Enabled by default. If you wish to disable bandwidth adaptation then you can set the VideoStream BandwidthAdaptationPolicy to Disabled, but please note that this is not recommended.

Bandwidth Adaptation in Browser Clients

Bandwidth adaptation is enabled by default in WebRTC-capable browser clients (Chrome, Firefox, Edge, and Safari).

Bandwidth Adaptation and AudioStreams

Please note that the LiveSwitch native SDK does not support bandwidth adaptation for AudioStreams at this time.

Webhook Configuration

Webhooks allow you to extend LiveSwitch functionality by hooking your own processing into Channel level events. The Client events are Client Joined and Client Left. The Connection events are Connection InitializingConnection ConnectingConnection ConnectedConnection ClosingConnection ClosedConnection FailingConnection Failed, and Connection Updated. Add a new webhook by clicking the NEW button and supplying:

  • Name - A human readable name of the webhook (does not have to be unique).
  • URL - The server to POST event information to (both HTTP and HTTPS are supported, but HTTPS is recommended).
  • Event Triggers - The Application level events will trigger a POST to your webhook.
  • Batch - POST multiple events in a single call. Without this set each event will result in a separate call.
  • Reliable - In the event of a failure, continue trying until successful.
  • Disabled - A convenience mechanism which supports disabling the hook while allowing you to keep the configuration.

API Keys

The API Keys page allows you to manage your API keys. API keys are used to authenticate with the Cloud OData REST API. A valid API key must be included in HTTP requests to the REST API via the X-API-Key header. 

REST API Rate Limiting

The Cloud REST API imposes rate limiting. Limits are 20 requests per API Key per second. Exceeding this limit results in a 429 "Too Many Requests" response.

Managing API Keys

API Keys can be created in the Console from the API Keys page. To create an API key, click the New button. You are required to provide a tag, which is simply a human readable label for a key. Note that tags need not be unique and can be edited at any time.

Revoking API Keys

You can revoke an API key at any time by deleting it. Be aware that any API call using a revoked key will return a 401 Unauthorized response from the Cloud REST API.

Subscription

The Subscription page allows you to manage your LiveSwitch Cloud subscription. Use the form to upgrade or cancel your subscription at any time.

Downloads

The Downloads page provides a link to each supported Client SDK. The Download page always links to the latest Cloud compatible version of the Client SDK. That is, the latest version of the Client SDK that will interop with the current version of LiveSwitch Cloud. Click any link to download the Client SDK of your choice.