Application Configuration

The 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 are shared by all clients, regardless of which channel they join. These properties are SIP Mappings, Webhook Configurations, and the application's Shared Secret.

If you have a "Default Application" configured, it's displayed at the top of the listing page in its own section.

The Default Application

DEPRECATED

Default Application is deprecated. Don't use it.

The Default Application is a legacy pattern. It's 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's 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 piggy back on your LiveSwitch Server infrastructure.

Default Application Status

At the top of the page of a given application, a message is displayed informing you whether this application is set to be used as your default. For the reasons discussed above, you are also warned that this isn't 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. It's recommended that you don't 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 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, see Webhooks in the Developer Guides.

Shared Secret

The Shared Secret is known by both your Application Configuration, and the clients trying to join an application and channel. It's used to authenticate client join requests.

External Redirect

In a cluster environment, you can set up specific deployments to process application requests for the following:

  • Target Gateway Sync URL: For client SDK requests
  • Target Gateway Admin URL: For REST API calls
  • Target SIP Connector Authority: For inbound SIP calls

To set up specific deployments to process application requests, do the following:

  1. On the Deployments page, select your deployment.
    1. In the External Redirect section, select Allow redirect to other deployments for inbound SDK, API, and SIP connections.
    2. In the External Redirect section, enter the following public-facing URLs:
      • Current Gateway Sync URL
      • Current Gateway Admin URL
      • Current SIP Connector Authority
  2. On the Applications page, select your application.
    • In the External Redirect section, enter the URLs of the specific deployment server used for this application:
      • Target Gateway Sync URL
      • Target Gateway Admin URL
      • Target SIP Connector Authority

Recording Management Override

By default, an application uses the Deployment recording management settings. However, you can override them to have application-specific recording management settings.

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.

Expiry Days

Set the number of days that it takes a recording to expire. If set, the expired recordings are deleted. If not set, recordings don't expire.

Mux Disabled

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).

RTMP

Note

If you are using LiveSwitch Connect for broadcasting over RTMP, we recommend you to migrate your application from LiveSwitch Connect to in-product RTMP.

LiveSwitch supports sending RTMP streams to other servers that allow RTMP ingest for your application or channel.

RTMP supports up to five upstream participants.

To enable RTMP ingest from the console, do the following:

  1. Enter the connection URL of the service you want to stream to.

    Note

    You must enter the RTMP protocol you are using in the connection URL. LiveSwitch supports RTMP and RTMPS.

    Warning

    RTMP URL can only be used by one active channel at a time. For more details, see RTMP Simultaneous Stream.

  2. Enter the stream key of the service you want to stream to.

  3. To automatically start RTMP when the channel is activated, turn the toggle switch on. To manually start RTMP through an SDK, turn the toggle switch off.

  4. After you submit your changes to the console, do one of the following to start the RTMP stream on your channel:

    • If your channel is active, restart it.
    • If your channel is active but you can't restart it, start the RTMP stream with the LiveSwitch SDK.
    • If your channel isn't active, activate it.

RTMP Simultaneous Stream

When configuring more than one channel, ensure that you are using different RTMP URLs. If you use the same RTMP URL in multiple channels, then a stream only starts for the first channel that attempts to activate the stream. The second stream to the same RTMP URL fails to establish a connection; however, the users can still connect. This doesn't impact the first stream. If you require RTMP to start on the second channel, you must deactivate the first channel and then you need to manually reactivate the RTMP stream on the second channel.

If your session requires clustering, the initial Media Server with an RTMP connection is prioritized. The subsequent connections and activated Media Server defers to the active RTMP stream as LiveSwitch allows only one attempt to start RTMP on the Media Server. When a channel is activated and streaming starts, RTMP is enabled regardless of any RTMP stream failures. When additional users join the channel on the same Media Server, additional attempts aren't made to start RTMP.

When the channel activates on a new Media Server which is unaware of any active RTMP streams from another source and attempts to establish an RTMP stream, the new RTMP connection fails and RTMP is flagged as enabled. However, the RTMP stream that is active on the initial Media Server is maintained.