Deployment Configuration

Important

If you change any deployment-level configurations, you must restart your Media Servers for the changes to take effect.

The Deployments page allows you to configure and manage different environments for all your services' operational requirements. Deployment configurations contain all your server configuration settings. At least one configured deployment is required and is the default for all servers if not explicitly overridden.

Note

To configure a server to use a deployment other than the default, you must edit the configuration file on that server. For more information, refer to the Server-Specific Configuration topic.

Deployment Name

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

Default Deployment

If there is one deployment, it acts as the default configuration. This deployment is used by services that have no explicit deployment configured. You can change which deployment to be used as the default from the Deployments page.

Base URLs Configuration

The Service Base URL indicates the entry point for the Gateway such as http://localhost:8080 and is used by Media Servers and SIP Connectors. The path relative to the Service Base URL is configured in the Server-Specific Configuration section.

Logging Configuration

LiveSwitch provides a rich logging framework that supports many different capabilities. You can configure as many loggers as you require. There are several different types of logging, and you can further configure the logging level and additional logger properties. You can configure log targets optionally for your Media Servers, Gateways, or Connectors.

Types of Logging

  • Console: Logs to the terminal when you start the server as an application, instead of as a service.
  • File: Logs to a file on the local server. The default location for Windows is %ProgramData%\Frozen Mountain Software\-service-\ and for Linux is /var/log/liveswitch/-service-/. 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 LogStash server.
  • Cloud Watch: Logs to AWS CloudWatch logging. For more information, refer to the Configure the CloudWatch Log Provider section.
  • JSON: Logs are parsed and stored in a structured JSON format.

Levels

Logging statements have an associated level of severity. Possible log levels are VERBOSE, DEBUG, INFO, WARN, ERROR, and FATAL. The severity level indicates the importance of the message.

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

The following levels are from most severe to least severe:

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

Configure 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 through 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.

If you don't supply either the Access Key, Secret Key, or profile attributes, 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.

Note

For production environments, LiveSwitch highly recommends setting your logging level to INFO or higher to minimize performance issues.

Audio/Video Recording

Important

If you change your recording path and strategy, you must restart your Media Servers for the changes to take effect.

Set up your audio and video stream recording path and strategy:

  • Path: Specify a valid path where your recordings must be stored. To enable recording for a specific channel, enable the Audio/Video Recording setting in the Channel Configuration.
Note

Ensure that the application has permission to write to the location of its recording folder.

  • Strategy: To enable your recording strategy, choose one of the following:
    • 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.
    • 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.

In both strategies, 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"
    }
  }
]

After setting up the Path and Strategy, configure a channel to be used for recording.

Redis Cache Configuration

You can provide a connection string to a Redis instance to be used as ephemeral (cache) storage. These settings override those found under Site 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 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 isn't available, media servers incrementally try additional port values until either one is successful or until it's clear that clustering isn't possible. For instance, if 8445 is available, a Media Server tries 8446, 8447, and so on until one is successful. Media servers self-determine which IP addresses they bind to these sockets, and generally use the first one of their interfaces that work. This isn't always ideal. You can configure the binding behavior by specifying the CIDR attribute. If specified, a Media Server only binds to IP addresses in the specified subnet.

  2. Port: You can change the default port that a Media Server listens on by specifying the port attribute. If you specify a port attribute, a Media Server only ever listens on a single port. This means that if the port is unavailable, the Media Server doesn't attempt to cluster on a different port.

  3. Enable Encryption: When enabled, all clustering traffic between Media Servers are encrypted using TLS 1.2. If you enable encryption, you must restart your Media Servers.

  4. Strategy: The following strategies can be employed to assign clients to a clustered Media Server:

    • Round Robin: Sequentially go through each Media Server to assign the next client.
    • Spill Over: Send all clients to the same Media Server until a threshold is met and then switch to the next Media Server.
    • Least Connections: Send the next client to the Media Server with the least number of active connections.
Note

If you want to set clustering allocation strategy at the channel level of your application, refer to the channel-level clustering.

Capacity Threshold Triggers

You can configure the thresholds that are used on a Media Server to determine when it's considered 'over capacity'. Once a Media Server is over capacity, the gateway service attempts to assign clients to a different Media Server instance. The thresholds are:

  • CPU: This value is expressed as a percentage of CPU use. If the CPU usage exceeds this threshold value, the Media Server is considered over capacity.

  • 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 is temporarily declared to be over capacity and isn't going to be in use for future connections until capacity constraints are no longer exceeded. Value less than 500 MB aren't recommended.

  • Bandwidth: This value is expressed in Mbps. If either upstream or downstream bandwidth exceeds this threshold value, the Media Server is considered over capacity.

  • MCU Connections Per CPU: This threshold setting configures how many connections media servers accept. For MCU connections, media servers are allocated until the threshold for connections is reached. When all media servers are allocated, no new connections are possible until the number of connections falls below the threshold.

  • SFU Connections Per CPU: This threshold setting configures how many connections media servers accept. For SFU connections, media servers are allocated until the threshold for connections is reached. When all media servers are allocated, no new connections are possible until the number of connections falls below the threshold.

SIP Configuration

For SIP Configuration, refer to the SIP Connector topic.

Webhook Configuration

What are Webhooks?

Webhooks are powerful tools that allow real-time communication between LiveSwitch and your external systems. They act as customizable event listeners, automatically sending notifications to your specified web server whenever key actions occur within LiveSwitch. This enables you to seamlessly integrate LiveSwitch events into your own applications and workflows.

Here's how it works:

  1. You define a webhook by specifying a URL for your server endpoint.
  2. LiveSwitch monitors for specific events you're interested in.
  3. When an event occurs, LiveSwitch sends an HTTP POST request to your URL.
  4. The request body contains detailed event information in JSON format.
  5. Your server can then process this data and respond accordingly.

With webhooks, you can build responsive, event-driven applications that leverage LiveSwitch's capabilities while seamlessly integrating with your existing infrastructure.

Webhooks are most commonly used to notify customers when a session's recording is ready for download. After a session ends, the system processes the recording by mixing audio and video from all participants into a single file. Once the mixed recording is ready, the system sends a notification via the registered webhook, allowing customers to download the complete recording without manually checking for updates.

Setting Up a New Webhook

To add a new webhook, in the console for the given application, click NEW and configure the following settings:

  • Name: Name of the webhook; it doesn't have to be unique.
  • URL: The server to which event information will be sent via a POST request. Both HTTP and HTTPS are supported, but HTTPS is recommended.
  • Event Category: Choose which level the webhook applies to:
    • Connection (application-level)
    • Client (client-level)
    • Channel (channel-level)
  • Event Lifecycle: The events available for the given category. When triggered, events send a POST request to your configured webhook.
  • Batch: Turn on the control to send multiple events in a single POST request. Otherwise, each event results in a separate POST request.
  • Disabled: Turn on the control to disable all events.

For information on sample JSON object for each event, refer to the Webhooks topic.

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're behind a NAT and don't have a public IP address. LiveSwitch provides a STUN/TURN server available at stun.frozenmountain.com for demo purposes only. Other public STUN servers are stun.l.google.com:19302 and stun.services.mozilla.com.

External Redirect

Declare a server's public-facing Gateway Sync URL, Gateway Admin URLs, and SIP Connector Authority for a cluster environment. This is used to redirect application requests to specific deployments.

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.

Bus Configuration

Bus Configuration allows you to add an Advanced Message Queuing Protocol (AMQP) server such as RabbitMQ to exchange information between the LiveSwitch Server services (Gateway, Media Server, SIP Connector) and your microservices.

To exchange information with LiveSwitch Server, turn on the Enable Bus Configuration toggle and enter your AMQP URI.

You can send messages to or receive notifications from the LiveSwitch Server.

Send Messages

You can set up your AMQP server to send a message to a LiveSwitch channel, user, device, or client. The expected payload is a JSON string with the following structure:

Key Type Required Description Client SDK Counterpart
payload string Required The message sent.
applicationId string Required ID of the application that receives the message.
channelId string Optional ID of the channel that receives the message. channel.OnMessage
userId string Conditional ID of the user that receives the message. Required if deviceId is provided. channel.OnUserMessage
deviceId string Conditional ID of the device that receives the message. Required if clientId is provided. channel.OnDeviceMessage
clientId string Optional ID of the client that receives the message. channel.OnClientMessage
fromUserId string Optional ID of the user that sends the message. senderInfo.getUserId()
fromUserAlias string Optional Alias of the user that sends the message. senderInfo.getUserAlias()
fromClientTag string Optional Tag of the client that sends the message. senderInfo.getClientTag()
fromClientRoles string Optional Role of the client that sends the message. senderInfo.getClientRoles()
fromDeviceId string Optional ID of the device that sends the message. senderInfo.getDeviceId()
fromDeviceAlias string Optional Alias of the device that sends the message. senderInfo.getDeviceAlias()

Receive Notifications

You can use either webhooks or set up your AMQP server to receive event notifications from LiveSwtich. LiveSwitch sends out notifications as an HTTP POST request with the body formatted in JSON for the following events:

Recording Management

Tip

For webhooks related to recording management, refer to the Recording webhooks.

Notable Points

  • The maximum number of upstream connections that can be part of a muxed session depends on the number of CPU cores on the server where the Recording Muxer service is running. Each core can handle a maximum of 4 upstream connections. For example, on an 8 core machine (AWS c5.2xlarge), the maximum number of upstream connections for a muxing session is 32.
  • The minimum width x height for muxed recordings is 160 x 120 (120p).
  • The maximum width x height for muxed recordings is 1920 x 1080 (1080p).
  • The maximum frame rate is 60fps.

Enable Recording Management

Important

If you change any Recording Management settings, you must restart your Media Servers for the changes to take effect.

Enable Recording Management to configure and manage your recordings. The Recording Management services that are intended for use as a unit require the following:

  • A PostgreSQL server for keeping records.
  • A RabbitMQ server for passing messages and managing the job queue.

Set the following:

  • AMQP URI: Your RabbitMQ server URI. The format is: amqps://{user}:{password}@{host}:{port}. For more information, refer to the RabbitMQ URI Specification. If not set, the default RabbitMQ server is used.
  • PostgreSQL URI: Your PostgreSQL server and database. You can use the same PostgreSQL server that you used for the LiveSwitch Server configuration. However, you must use a different database for recording. The format is postgresql://{user}:{password}@{host}:{port}/{database}. For more information, refer to the PostgreSQL Connection String.
  • Expiry Days: The number of days before a new recording expires. If set, the expired recordings are deleted. If not set, the recording doesn't expire.
Note

If you enable Recording Management, ensure that Recording Monitor is configured on the Server configuration console. Recording Mover and Recording Muxer are optional. However, without Recording Mover, no webhook events will be sent and no recordings will be displayed on the Recordings page.

Enable Move

Important

LiveSwitch doesn't officially support S3 Compatible Storage (also known as, non-AWS S3 storage). LiveSwitch would be interested in partnering with you to fully test alternative providers if you have a requirement for non-AWS S3 storage.

You can enable Move to move your recording files to an AWS S3 bucket. Once enabled, set the following:

  • Bucket Name: Required. ID of the AWS S3 bucket.
  • Prefix: If set, it's added to the beginning of any object keys.
  • Region: Required if Endpoint isn't set. Region of your AWS S3 bucket.
  • Access Key: Access key of your AWS S3 bucket.
  • Secret Key: Secret key of your AWS S3 bucket.
  • Endpoint: Required if Region isn't set. Endpoint of the S3 Compatible Storage (non-AWS S3 storage) if it's hosted by another cloud provider.
  • Force Path-style: Force the use of path-style addressing when required if using S3 Compatible Storage (non-AWS S3 storage).

Enable Mux

Having Mux enabled will take multiple files from a recording session and produce a single muxed recording file. When enabled, specify the following:

  • Width: Width of the output video. Defaults to 1280px.
  • Height: Height of the output video. Defaults to 720px.
  • Frame Rate: Frames per second of the output video. Defaults to 30.
  • Background Color: Hexadecimal code for the video background color. Defaults to 000000(black).

Port Range Configuration

LiveSwitch Media Server uses ICE and TURN port ranges to send and receive media traffic. The ranges are:

  • ICE Port Range: For client traffic that's able to connect directly to the Media Server without relaying. Relevant for SFU and MCU connections, but not peer connections. Defaults to ports 49152-57343 and connects through UDP.
  • TURN Port Range: For client traffic that requires a TURN relay to communicate with peers or the Media Server. Relevant for all connections if TURN or TURNS are enabled. Defaults to ports 57344-65535. TURN can connect through UDP or TCP, but TURNS can connect only through TCP.

You can customize the ranges for a deployment if you can't use the default port ranges. For example, the Azure-managed firewall service doesn't allow inbound traffic on ports 64000 and above.

To customize the port ranges, in the LiveSwitch Configuration Console > Deployments > Port Range Configuration section, enter the your customized port ranges.

Note

For production deployment, LiveSwitch recommends setting the ICE port range to 32168-49151 and TURN port range to 49152-65535. Opening up the port ranges ensures that enough ports are available when needed. Each streaming connection from the client uses at least one port from the ICE range and one port from the TURN range if TURN is enabled. If you limit port range per-stream instead of per-connection, ports might not be immediately available for reuse. Therefore, the range should be as large as possible to avoid potential connectivity failure.

Advanced Configuration

HTTP/HTTPS Bindings

Note

It's recommended to use a reverse proxy, such as nginx or haproxy, or load balancer for TLS termination.

Warning

Editing these settings can break your service deployments 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.

Configure the ports on the Gateway that clients connect on.

  • CIDR: Used to restrict the interfaces for binding. When empty, binds on all interfaces. This is optional.
  • Port: The port to bind.
  • Apply to Sync and Apply to Admin: Restrict which bindings apply to Sync and Admin. Refer to the Server-Specific Configuration topic.
  • Certificate: Select one of the configured Certificates to apply to this binding (HTTPS only).

TURN/TURNS Bindings

Configure the bindings for the embedded TURN server.

  • CIDR: Used to restrict the interfaces for binding. When empty, binds relay services on all interfaces. This is optional.
  • Port: The port used for relay connections.
  • Protocol: Networking protocol used for communication between clients and relay server. Relay candidates on the server are still 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).