Configuration

The Configuration Console

The LiveSwitch Configuration Console is a Web Application which makes managing your servers, applications, and channels easier than ever. Once you have completed your installation, assuming you installed a Gateway, you can find your Console running on your Gateway's localhost at http://localhost:9090/admin. 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

You already know what Gateways, Media Servers, and SIP Connectors are, but the Console deals with some configuration entities that may be new to you. The configuration entities are used to configure your global environment, your deployment specific environment(s), and your client application environment(s). 

  • Site - global configuration, which is really just your license key and secondary (ephemeral) Redis cache configuration.
  • Deployments - pertains to your server-side deployments (Gateways, Media Servers, and SIP Connectors).
  • 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.

These configuration entities are first class concepts in the Console. With the exception of channels, they 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 of your Site ConfigurationDeployment ConfigurationApplication Configuration, and Channels. This guide also introduces the remaining top level pages of your Console. These are the Home page, the Servers Listing page, the API Keys page, the Certificates page, and the Change Password page.

Home

You Home page 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 a brief status overview of your system health. The status overview informs you of two very important pieces of information:

  1. How many Media Servers are currently operational, and
  2. The secure status of your v1 API.

LiveSwitch Status Overview

If your v1 API does not have authentication enabled, then the above message will appear as a warning. Clicking this message takes you to the API Keys page, which has an area at the top allowing you to opt-in to v1 API authentication. More information is discussed in the API Keys section.

In the case that you have no connected Media Servers the message above will appear as a warning. This is because no connected Media Servers mean that your clients cannot connect in either SFU or MCU mode. Clicking this message takes you to the Servers Listing page, which provides a handy help link to the Media Servers listing documentation where we discuss how to resolve the issue.

You may also notice that the Console has an alert area in the title bar in the shape of a bell. From any page in the Console, clicking on the bell  displays your system status, and allows you to click a status to navigate and gain more information about the particular status alert.

Servers Listing

Your Server Listing page shows you the LiveSwitch server environment. It lists out your Gateways, Media Servers, and SIP Connectors.

Gateways

Your Gateway listing shows the Gateways that are operational in your LiveSwitch infrastructure. You can click the arrow beside each listed Gateway to get more information such as the architecture, core count, etc.

Troubleshooting  - No Gateways Connected

In the case that you have no Gateways running you will see a message to that affect in the listing. This should be impossible, as your Console is using a Gateway to communicate with your backend. If this occurs please contact support@frozenmountain.com.

Media Servers

Your Media Server listing shows the Media Servers that are registered with a Gateway in your LiveSwitch infrastructure. You can click the arrow beside each listed Media Server to get more information such as core count, current connection details, etc.

Troubleshooting  - No Media Servers Connected

This is potentially a serious issue as it means that no client can get an SFU or MCU connection. The most likely causes are:

  1. You did not install a Media Server. In this case please see the Installation guide.
  2. You have misconfigured you serviceBaseUrl, which is how your Media Servers communicate with your Gateway. See the Deployment Configuration section for more information.

SIP Connectors

Your SIP Connector listing shows the SIP Connectors that are registered with a Gateway in your LiveSwitch infrastructure. You can click the arrow beside each listed SIP Connector to get more information such as the architecture, core count, etc.

Troubleshooting  - No SIP Connectors Connected

Please note that this is not necessarily an issue. Many use cases do not require a SIP Connector, and if you have never installed a SIP Connector then this message is perfectly normal. The most likely causes are:

  1. You did not install a SIP Connector. Again, you do not need to provide a SIP Connector if your use case does not require SIP support. If you do then please see the Installation guide.
  2. You have misconfigured you serviceBaseUrl, which is how your SIP Connectors communicate with your Gateway. See the Site Configuration section for more information.

Administrative User

The Configuration Console supports a single user. This is the user that you set up as step 3 of the Initialization Wizard [link this]. This user has full administrative privileges and can access all configuration options supported by the Console.

Note that this user account is specific to accessing your Configuration Console and is distinct from any other Frozen Mountain user account that you may have.

Configuration Entities

Site Configuration

The "Site" configuration manages all global configuration properties. Global properties are:

PostgreSQL Configuration

If you are using the Redis configuration, it's highly recommended that you migrate to the PostgreSQL configuration because the Redis configuration is deprecated and will be removed in a future release.

During installation, you provided a connection string to a PostgreSQL instance which is used to store all of your configuration data. This is the Configuration Connection String. You can only edit the connection string for each server in the configuration JSON file, not through the Console. For more information on managing the Configuration Connection String, see Advanced Topics.

Redis Configuration

Redis Configuration Connection String

Deprecated - Redis Configuration

Redis Configuration is deprecated and will be removed in a future release. It's recommended to use PostgreSQL configuration instead.

During installation, you provided a connection string to a Redis instance which is used to store all of your configuration data. This is the Configuration Connection String. This connection string is configured per server in a JSON configuration file and it is not editable from the Console. For more information on managing the Configuration Connection String please see the discussion in our Advanced Topics. For improved performance, you can configure another Redis instance as a cache. 

Redis Cache Configuration

In addition to your Configuration Connection String, you can also provide a connection string to a Redis instance to be used as ephemeral (cache) storage. You can manage this connection string through the Console.

License Key

Your LiveSwitch license key which is available from your Frozen Mountain Account page. You set this as part of the Initialization process, but you can update it at any time on your Site configuration page. Please copy and paste the entire license key into the provided text area and ensure you have no additional whitespace.

Advanced Information

The Advanced Information section displays some fundamental configuration properties of your LiveSwitch Server On-Premises installation (your "Site"). These are read-only properties. They intended for informational purposes, and not for updates. These properties are:

  • Site Id - The GUID used to identify your site for usage reporting. This can be useful for any usage-related inquiry.
  • Sync Path - The signalling endpoint for clients and servers (e.g. /sync). This path is relative to your Gateway URL, and is not configurable at this time.
  • Admin Path - REST endpoints and Console (e.g. /admin). This path is relative to your Gateway URL, and is not configurable at this time.

Deployment Configuration

The Deployments section lists and allows you to edit all the Deployment configurations you have created.  Deployment configurations contain all your server configuration settings.  At least one Deployment configuration is required and will be the default for all servers if not explicitly overridden.

Deployment Config

To change a server to use a deployment other than the default, you need to edit the configuration file on that server. See Server Specific Configuration for more information.

Deployment Name

This is the name of the deployment as displayed on the listings page.  This is also the name that you will use in the Server Specific Configuration to configure a deployment other than the default for the server.

Default Deployment

One deployment will always be the default configuration.  This deployment is used by services that have no explicit deployment configured.  You can change which deployment should be used as the default from the listing page.

Base URLs Configuration

The Service Base URL indicates the entry point for the Gateway (e.g. http://localhost:8080) and is used by Media Servers and SIP Connectors.  The path relative to the Service Base URL is configured in the AdvancedPathConfiguration section.

Reporting Interval

The Report Interval specifies, in seconds, how frequently to update the connection information for clients that are using the legacy/v1 REST API endpoints.

Logging Configuration

LiveSwitch provides a rich logging framework that supports many different capabilities.

  • Console logging logs to the terminal when you start the server as an application, instead of as a service.
  • File logging logs to a file on the local server.  The defaults location is: %ProgramData%\Frozen Mountain Software\-service-\ for Windows, and /var/log/fm/liveswitch/-service-/ for Linux.  You can override this to any directory.
  • Syslog logs to the system message logging.  The target attribute is the IP where the syslog is sent.  The default is 127.0.0.1.
  • Log Stash logs are sent to the specified the Logstash server.

  • Cloudwatch logs to AWS CloudWatch logging. See the Configuring the CloudWatch Log Provider section below for more information.
Levels

Logging statements have an associated level of severity. Possible log levels are: VERBOSE, DEBUGINFOWARNERROR, and FATAL. The severity level indicates the importance of the message. The levels are, from most severe to least severe:

  • FATAL: The message indicates a fatal application error; the application will need to shut down and no recovery actions are possible.
  • ERROR: The message indicates a normal application error (ie: timeouts, bad user input); this is a normal error state and usually it is possible to proceed.
  • WARN: The message indicates that something abnormal occurred but that the application was not negatively affected; this is used for unexpected values, deprecations or abnormal application state.
  • INFO: This is a trace message; it describes what is going on in the SDK.
  • DEBUG: This is a diagnostic message; it is similar to the INFO level but is used for outputting detailed parameters or for "spammy" messages.
  • VERBOSE: This is a diagnostic message; it is similar to the DEBUG level but is used for outputting extremely low-level detailed tracing messages. It is generally not recommended to configure verbose logging.

The Level attribute allows you to set the level of logs you want to be displayed.  In production, you may want to display no message, and in development, you may want to display all diagnostic messages.

Configuring the CloudWatch Log Provider

This provider dumps the logs directly into a specific AWS CloudWatch log group.

Required attributes are:

  • AWS Region: The CloudWatch region to send the logs.
  • Log Group: The CloudWatch log group to send the logs to.

Basic access configuration requires two attributes:

  • Access Key: Your AWS access key.
  • Secret Key: Your AWS secret key.

Alternatively, you can configure authentication via profile:

  • Deployment Name: The deployment name in which to try and load from an AWS credential file.
  • Deployment Path: The path to an AWS credential file. If missing, the default path is used.

Should you choose not to supply any of accessKeysecretKey, or the profile attributes, then AWS auto-detection is turned on if the service is running on EC2 or ECS. For ECS, the task execution role is used, so you must ensure it has CloudWatch permissions. For EC2, the instance profile role is used if available.

Production Environments

Best Practise: For production environments, it is highly recommended to set your logging level to INFO or higher to minimize performance issues.

Audio/Video Recording

The recording path property allows you to specify the path where your recordings will be stored.  To enable recording, update the ChannelConfiguration.

The strategy setting for recording audio and video streams to disk provides options for "Hierarchical Directories" (default) or "Flat Directory". In both cases, each media stream is written to its own unique file, and start/stop recording events are logged to a JSON file. For example:

[
  {
    "type": "startRecording",
    "timestamp": "2019-09-26T18:45:19.1355473Z",
    "applicationId": "my-app-id",
    "externalId":  "abc",
    "applicationConfigId": "0026de61-d96a-4fa2-9889-54eff922bd46",
    "channelId": "645116",
    "channelConfigId": "81acc2e0-d37e-416d-8594-062da236c4a3",
    "userId": "5e4d172411a04de9b695acf379680bbd",
    "deviceId": "8df7ea25eac24c48b239b047af63487f",
    "clientId": "d4b6e46b679b4e22a2255280e213696c",
    "connectionId": "9a816c8ec0c742ec8eff0f48a86f1714"
  },
  {
    "type": "stopRecording",
    "timestamp": "2019-09-26T18:45:38.5738739Z",
    "applicationId": "my-app-id",
    "applicationConfigId": "0026de61-d96a-4fa2-9889-54eff922bd46",
    "channelId": "645116",
    "externalId": "abc",
    "channelConfigId": "81acc2e0-d37e-416d-8594-062da236c4a3",
    "userId": "5e4d172411a04de9b695acf379680bbd",
    "deviceId": "8df7ea25eac24c48b239b047af63487f",
    "clientId": "d4b6e46b679b4e22a2255280e213696c",
    "connectionId": "9a816c8ec0c742ec8eff0f48a86f1714",
    "data": {
      "videoFile": "C:\\Temp\\0-9a816c8ec0c742ec8eff0f48a86f1714-0-video.mkv",
      "audioFile": "C:\\Temp\\0-9a816c8ec0c742ec8eff0f48a86f1714-0-audio.mka"
    }
  }
]


The Hierarchical Directories strategy writes streams to root/<ApplicationId>/<ChannelId>/<UserId>/<DeviceId>/<ClientId>/<ConnectionId>. Recording events are written on a global basis to root/log.json. This strategy is intended for simple, single-server deployments.

The Flat Directory strategy writes streams directly to root. Recording events are written on a per-connection basis to root/<ConnectionId>.json. This strategy is intended for highly-scalable, multi-server deployments and is recommended for integrating with automated post-processing.

To enable your recording strategy to pick the strategy of choice for your Deployment Configuration.

Clustering

LiveSwitch supports media server clustering, which allows multiple media servers to work together to handle higher traffic volumes than they would be able to alone. Clustering is enabled by default, and all media servers that are connected to a gateway or pool of gateways will automatically attempt to cluster.  There are a few settings you configure to control how your servers are clustered:

  1. CIDR - LiveSwitch media servers in a cluster communicate with each other over TCP sockets. By default, clustering is performed on port 8445 for the cluster connection. If port 8445, is not available, media servers will incrementally try additional port values until either one is successful or until it is clear that clustering is not possible. For instance, if 8445 is available, a media server will try 8446, 8447, etc. in turn until one is successful. Media servers self-determine which IP addresses they bind to these sockets, and generally will use the first one of their interfaces that work.  This is not always ideal. You can configure the binding behaviour by specifying the CIDR attribute.  If specified, a media server will only bind to IP addresses in the specified subnet.
  2. Port - You can change the default port that a media server will listen on by specifying the port attribute. Note - if you specify a port attribute, a media server will only ever listen on a single port. This means that if the port is unavailable, the media server will not attempt to cluster on a different port.
  3. Strategy - You have three options for the strategy that is employed to assign clients to a clustered media server:
    1. Round Robin - Sequentially go through each media server to assign the next client.
    2. Spill Over - Send all clients to the same media server until a threshold is met and then switch to the next media server.
    3. Least Connections - Send the next client to the media server with the least number of active connections.
Capacity Threshold Triggers

You can configure the thresholds that are used on a media server to determine when it is considered "overcapacity".  Once a media server is overcapacity, the gateway service will attempt to assign clients to a different media server instance.  The thresholds are:

  1. CPU - This value is expressed as a percentage of CPU use.  If the CPU usage exceeds this threshold value, the media server will be considered overcapacity.
  2. Memory - This value is expressed in MB.  This threshold is used to identify whether a media server is over capacity while clustering multiple servers. If the memory consumed by a media server exceeds this threshold and multiple servers are available, that server will be temporarily declared to be over capacity and will not be in use for future connections until capacity constraints are no longer exceeded. Values less than 500 MB are not recommended.
  3. Bandwidth - This value is expressed in Mbps.  If either upstream or downstream bandwidth exceeds this threshold value, the media server will be considered overcapacity.
  4. Thresholds - Threshold settings configure how many connections media servers will accept. For MCU or SFU connections, media servers are allocated until the threshold for connections is reached. When these are exceeded, all media servers are allocated, no new connections will be possible until the number of connections falls below the threshold.

SIP Configuration

SIP Configuration documentation is available in the SIP Connector documentation.

Webhook Configuration

Webhooks allow you to extend LiveSwitch functionality by hooking your own processing into events from each server.  All servers provide access to Started and Stopped events. The Media Server and SIP Connector also provide access to Registered and Unregistered events.  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 Server 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.

External STUN URLs Configuration

Media Servers can specify up to two external STUN servers to use to automatically discover their publicly routable IP address and port. This may be necessary when they are behind a NAT and do not have a public IP address.  Frozen Mountain provides a STUN/TURN server available at stun.frozenmountain.com for demo purposes only. Other public STUN servers: stun.l.google.com:19302 and stun.services.mozilla.com.

Forbidden TURN Peer CIDRs Configuration

It's possible that malicious clients with valid TURN credentials allocate UDP sockets on the Media Server and use that as a proxy to communicate with internal services over private or reserved IP ranges. To prevent this, LiveSwitch forbids a list of classless inter-domain routing (CIDR) ranges by default. You can add or remove CIDRs if needed.

Rate Limiting Configuration

To enable rate limiting on your /sync endpoint click the toggle to enable rate-limiting. You can configure a separate policy per CIDR as necessary, but generally, one default policy for the 0.0.0.0/0 CIDR is most useful. For a given policy, configure the maximum Limit (number of requests) to allow for a given Period (in seconds). This can prevent your deployment from being overwhelmed by unexpected signaling traffic.

Advanced Configuration

HTTP/HTTPS Bindings

Best Practices - TLS Termination

We strongly recommend using a reverse proxy (like nginx or haproxy) or load balancer for TLS termination.


HTTP/HTTPS Bindings

Editing these settings can break your service deployments in such a way that the only recovery path is to edit fields in Redis directly. Only make changes to this configuration if you are sure of what you are doing.

These are used to configure the ports on the Gateway that clients will connect on.

  • CIDR: Used to restrict the interfaces for binding. When empty, will bind on all interfaces. (optional)

  • Port: The port to bind.

  • ‘Apply to Sync’ and 'Apply to Admin': Restrict which bindings apply to Sync and Admin. See AdvancedPathConfiguration.

  • Certificate: Select one of the configured Certificates to apply to this binding (HTTPS only).

TURN/TURNS Bindings

These are used to configure the bindings for the embedded TURN server.  See here for more information.

  • CIDR: Used to restrict the interfaces for binding. When empty, will bind relay services on all interfaces. (optional)

  • Port: The port used for relay connections.

  • Protocol: Networking protocol used for communication between clients and relay server.  Relay candidates on the server will still be advertised as UDP candidates when TCP is chosen for communication between the client and the server.

  • Certificate: Select one of the configured Certificates to apply to this binding (TURNS only).

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 SIP Mappings, Webhook Configurations, and the Application's Shared Secret. Read on for more information.

If you have a "Default Application" configured, it will be displayed at the top of the listing page in its own section. Let's discuss what this "Default Application" is, and why it is not recommended.

The Default Application

The Default Application is a legacy pattern. It is deprecated but still supported at this time for customers that are migrating from 1.2.x (or older) installations. Older versions of LiveSwitch would allow a client to join a conference without specifying a particular application. In this case, the client would join a special default application which used a special '*' identifier as its ID as long as they supplied the correct shared secret. The problem with this approach is that it is relatively simple to brute force the shared secret. With no default Application, attackers must brute force two values, the shared secret AND the name of the Application (its ID), making it exponentially harder for a rogue client to piggyback on your LiveSwitch server infrastructure.

Deprecated - Default Application

Making use of the "Default Application" pattern is NOT recommended. It is provided only for legacy purposes.

Default Application Status

At the top of the page of a given Application a message is displayed informing you whether or not this Application is set to be used as your default. For the reasons discussed above, you are also warned that this is not the best practice. That said, you can click the SET button to have any of your Applications set as your default should you choose to do so. Only one Application can act as the default at a given time, but again, it is recommended that you do NOT configure a default Application. Instead, configure all of your clients to be explicit about the Application AND Channel they join. 

SIP Inbound Mapping Configuration

SIP configuration for Inbound Mappings is available in the SIP Connector documentation.

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.

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. 

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 at the end of 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 the Gateway 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 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.

Default Channel vs Default Application

If you have read the section on The Default Application then you might have some concerns about this Default Channel feature. Please note that since the Shared Secret exists at the Application level, and not at the Channel level, the Default Channel does not suffer from the same security concern.

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.
  • L16: 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 Media Server 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 Media Server may be unable to accept connections.

SFU Configuration

SFU Configuration allows you to set configuration options for the LiveSwitch Media Server when it is running in SFU mode. 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 the Media Server will attempt to negotiate with participants.

MCU Configuration

MCU Configuration allows you to set configuration options for a LiveSwitch Media Server when it is running in MCU mode. MCU stands for Multipoint Control Unit. With MCU, participants send their audio/video streams to the Media Server for processing. The Media Server decodes, rescales, and mixes all incoming streams into a single new stream and then encodes and sends it to all participants. The benefits of an MCU are bandwidth-friendly and less CPU intensive on the client-side—instead of processing multiple streams, clients decode and render only one stream.

Limit MCU Bandwith

You can set the maximum upstream rate of the incoming stream bitrate in kbps. Enter your desired values in Audio Input Max Bitrate and Video Input Max Bitrate. If not set, the default values are used.

The Per Connection Video Output control excludes each participant's local video from the MCU output video, which means that participants don't see themselves in the video output. Enabling this consumes significant server resources, so don't enable it unless you really need to. 

Define Output Frame Resolution and Rate

It will help if you use the common resolutions, as not all combinations are valid for all codecs. For example, 147x933 is not a valid resolution. You should also keep your frame rate to a reasonable value. Anything beyond 30 frames per second requires a powerful server to keep up in larger video conferences.

To define the MCU video output frame resolution and rate, enter the desired value in Video Output WidthVideo Output Height, and Video Output Frame Rate

Control MCU Layout

You can specify the margin between the frames in the output video in Video Input Margin.

If the input video frame is smaller than the output video frame, the output video fills the space with black bars. You can enable Crop Input Videos to enlarge the input video to fit the output video frame.

You can also customize how each video frame is displayed in your MCU output using a JavaScript layout function. Your function can return a static layout or generate a dynamic layout based on the passed parameters.

To customize the MCU layout, paste your function code directly in JavaScript Layout Function or use the REST API.

The function structure looks like the following:

JavaScript layout function
/**
 * @param {inputs[]} inputs  The current inputs.
 * @param {output}  output  The current output.
 *
 * @return {Layout}         The desired layout.
 */
function layout(inputs, output) {
  ...
  return {
    size: output.size,
    frames: ...
  };
}

Your custom function name must be layout and the parameter names of the layout function must be inputs and output.

Custom Layout Interfaces
interface inputs {
  connectionId: string;
  clientId: string;
  deviceId: string;
  userId: string;
  size: Size;
}

interface output {
  size: Size;
  channelId: string;
  applicationId: string;
}

interface layout {
  frames: Frame[],
  size: Size;
}

interface Frame {
  origin: Point;
  size: Size;
  orientation: number; // 0, 90, 180, or 270
}

interface Point {
  x: number;
  y: number;
}

interface Size {
  width: number;
  height: number;
}
A Basic Static Layout Example

The following code example demonstrates a basic Javascript layout function. The function displays participants side by side and from left to right. It keeps sections empty until the participants joining in. A max of four participants are shown at a time, but everyone can be heard. The diagram shows what it looks like from two to four participants.

JavaScript code
function layout(inputs, output) {
    var rows = 2;
    var cols = 2;
    var frameWidth = 360;
    var frameHeight = 240;
    var layout = {
        frames: [],
        size: {
            width: frameWidth * cols,
            height: frameHeight * rows
        }
    };
    for (var i = 0; i < inputs.length; i++) {
        var col = 0;
        var row = 0;    
        if(i === 1) {
            col = 1;
            row = 0;            
        }
        if(i === 2) {
            col = 0;
            row = 1;
        }
        if(i === 3) {
            col = 1;
            row = 1;            
        }        
 
        layout.frames.push({
            origin: {
                x: col * frameWidth,
                y: row * frameHeight
            },
            size: {
                width: frameWidth,
                height: frameHeight
            },
            orientation: 0
        });
    }
    return layout;
}
A Complex Circular Layout Example

The following code example demonstrates a more complex circular layout example function. The diagram shows what it looks like from five to six participants.

JavaScript code
/**
 * Apply a circular layout.
*/
function layout(inputs, output) {
    var center = {
        x: output.size.width / 2,
        y: output.size.height / 2
    };
    var radius = Math.min(output.size.width, output.size.height) / 4;
    // the top of the circle
    var angle = 1.5 * Math.PI;
    var frames = [];
    for (var i = 0; i < inputs.length; i++) {
        frames.push({
            orientation: 0,
            origin: {
                x: (radius * Math.cos(angle) + center.x) - (radius / 2),
                y: (radius * Math.sin(angle) + center.y) - (radius / 2),
            },
            size: {
                width: radius,
                height: radius
            }
        });
        angle += (2 * Math.PI / inputs.length);
    }
    return {
        size: output.size,
        frames: frames
    };
}
Configure Skia

LiveSwitch's MCU supports Skia graphics rendering engine. You can configure Skia in Skia Config:

  • Turn on Antialias to smooth jagged edges in the video image.
  • Turn on Dither to make the low-resolution image look better.
  • Select the desired Filter Quality.
Configure MCU Simulcast

LiveSwitch version 1.9.0 and higher supports Simulcast, which allows multiple encoding per stream. In the Simulcast section, you can specify the maximum number of encodings per audio and video input. You can also set the bitrate, frame rate, and video scaling for each video encoding.

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.

Connection Statistics Interval

The Connection Statistics Interval property determines the granularity in milliseconds at which connection statistics are sampled.

Performance Consideration

It is highly recommended not to set this value too low. Setting it to less than 1000 ms could have severe CPU performance implications.

Audio/Video Recording Enabled

This configuration property controls whether or not the LiveSwitch Media Server records media for any clients in the Channel. To enable recording move the switch to the Enabled position. The recording path can be customized in your Deployment Configuration. Otherwise, the server's default temp directory will be used.

Note that in a peer to peer session, no recording is performed. This is because in this type of session, no users are connected to the LiveSwitch Media Server itself. If you wish to record a session, you must ensure that it is an SFU or MCU session.

SIP Outbound Caller ID Configuration

SIP Outbound Caller ID Configuration is available in the SIP Connector documentation.

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 FailedConnection Updated, and Connection Stats. 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.

Gathering Connection Stats

Note that there is more detailed discussion on the Connection Stats Webhook available here.

API Keys

The API Keys page allows you to secure your v1 API and manage your API keys.

Securing Your v1 API

LiveSwitch 1.2.x (and lower) Gateways required that access to your administrative route be blocked by your firewall thus preventing unauthorized access to administrative functionality via the REST API. With LiveSwitch 1.3.x (and higher) this is still an option. However, you can alternatively use API Keys. To prevent a breaking change when migrating between 1.2.x and 1.3.x the v1 API is not secured by default. This ensures that any service currently using the v1 API will continue to do so without interruption.

Best Practice

It is considered best practice to secure your v1 API. 

After you have secured your v1 APIs, you will need add in API key to the header of your v1 API call.

CURL Example
curl -H "Accept:application/json" -H "X-API-Key: 8b45e287-6470-4727-81c6-39a2589e" -v https://localhost:9090/admin/api/v1.0/mediaservers

Managing API Keys

API Keys can be created in the Console from the API Keys page. To create an API key, click the New API Key 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 your Gateway.

Certificates

Best Practices - TLS Termination

We strongly recommend using a reverse proxy (like nginx or haproxy) or load balancer for TLS termination.

The Certificates page provides a central place to manage your certificates, which are necessary for configuring HTTPS and TURNS bindings. For more information on these secure bindings see the Deployment Configuration section. To support a variety of use cases, the Console provides three methods to manage certificates.

Supported use cases are:

  1. Wildcarded domains (typical) - Nice, convenient, central management for certificates. Your TURNS/HTTPS bindings make use of the certificates you have configured, and your certificates are issued for wildcarded domains, meaning they can be used across all your subdomains and it does not matter under which subdomain your server is actually running.
  2. Migration case - For certificates that existed in 1.2.x (or older) installs.
  3. Individual certificates per server - Certificates are not wildcarded, and you must refer to an actual certificate residing on a server somewhere.

Certificates, Bindings, and Deployments

 To make use of a certificate you MUST actually set up a Deployment Configuration with HTTPS/TURNS bindings using this certificate, AND configure the Deployment in your servers' JSON config. This last need only be done once, after that you can update certificates as needed, and use the Console to update the bindings for that Deployment. JSON config need not be updated in this case. For more information on configuring your servers with a Deployment Configuration please see the Deployment Configuration section.

To support these use cases the Console allows you to upload .PFX certificate files, or for certificates that you have placed on a server yourself you can refer to them by file path or by the certificate's hash (Windows Certificate Store).

Uploading Certificates from a Certificate File

This method supports the typical "wildcarded domain" use case. Under the File Certificates section of the page, click the NEW CERTIFICATE button to upload your (optionally password protected) .PFX certificate file.

Best Practice

It is considered best practice to manage your certificates using this method. When you upload a certificate file it is validated as part of the upload process, so any problems with the certificate are reported to you when you attempt to upload the certificate, which allows you to fix the issue immediately.

Specifying Certificates by Path

This method supports the "migration" and "individual cert per server" use cases. It is intended specifically for Linux servers. Under the Path Certificates section of the page, click the NEW CERTIFICATE button to specify the full file system path to your certificate. When your server starts up it will attempt to load this certificate from the file system.

Not Recommended

Be aware that certificates specified by file path cannot be verified by the Console. We have no way of knowing if your certificate configuration will work until the server for which it is configured attempts to load it from the file system. Wherever possible we recommend managing your certificates by uploading a .PFX file.

Specifying Certificates by Hash

This method supports the "migration" and "individual cert per server" use cases. It is intended specifically for Windows servers. Under the Hash Certificates section of the page, click the NEW CERTIFICATE button to specify your certificate's hash value. When your server starts up it will attempt to load this certificate from the Windows Certificate Store using this hash.

Not Recommended

Be aware that certificates specified by hash cannot be verified by the Console. We have no way of knowing if your certificate configuration will work until the server for which it is configured attempts to load it from the Windows Certificate Store. Wherever possible we recommend managing your certificates by uploading a .PFX file.