Configuring the Media Server

The LiveSwitch Media Server is a service that manages media data for LiveSwitch media sessions. In a multipoint conference, the LiveSwitch Media Server performs any forwarding or multiplexing required by the session.

Finding the Configuration File

To configure the LiveSwitch Media Server, navigate to the directory with the service executable file. By default, this is C:\Program Files\Frozen Mountain Software\LiveSwitch\Media Server. In this directory, look for a file named FM.LiveSwitch.MediaServer.Service.config. You can edit this file to change the LiveSwitch Media Server settings.

The LiveSwitch Media Server configuration file has one top-level configuration section, mediaServer. This should be specified in the configuration file, as shown below:

<configuration>
  <configSections>
    <section name="mediaServer" type="FM.LiveSwitch.MediaServer.Configurations.MediaServerConfigurationSection, FM.LiveSwitch.MediaServer" />
  </configSections>
</configuration>

The next sections of this document will describe the configuration options for this element.

Editing the Media Server Section

The mediaServer section provides configuration for the LiveSwitch Media Server that determines how the relay server is configured and which codecs are available to clients. There are several main configuration sections:

  • log specifies the logging level and configuration

  • gateway specifies which LiveSwitch Gateway to connect to
  • connection sets the local network settings for connections from the media server
  • codecs specifies which codecs that the media server should use
  • mcu configures settings specific to MCU mode
  • sfu configures settings specific to SFU mode
  • recording enables or disables session recording

Each of these is explored in detail in the following sections.

Configuring Logging

There are many configuration options for Media Server logging. These are covered in the Configuring Logging documentation. You can jump to that document now, or read through it after you have covered the article on Configuring the SIP Connector. The logging configuration is the same for the Gateway, Media Server, and SIP connector services.

Specifying the Gateway

You must also specify a single gateway element. This element defines how the LiveSwitch Media Server will connect to your LiveSwitch Gateway. The gateway element has two attributes that you must specify, gatewayUrl and sharedSecret. The gatewayUrl attribute should contain the scheme, domain and path to your LiveSwitch Gateway route. Refer to the section on Configuring the Gateway for more information on how to modify this value. The sharedSecret attribute should contain the shared secret that your gateway has specified for LiveSwitch Media Servers. This should be the same value that you have specified in your LiveSwitch Gateway configuration file. Again, refer to the section on Configuring the Gateway for information on configuring this.

<mediaServer>
  <gateway gatewayUrl="http://localhost:8080/sync" sharedSecret="22222222-2222-2222-2222-222222222222" />
</mediaServer>

Again, make sure the shared secret that you specify here matches what is specified in the mediaServers element in your LiveSwitch Gateway configuration file. If it does not, then the LiveSwitch Media Server will not be able to connect to the gateway.

Specifying Local Network Settings

The connection element lets you configure the public IP address of the media server as it will be visible to clients. This element has two possible attributes, stunAddress and publicIPAddress. If you know the public IP address of your LiveSwitch Media Server, you should specify it here using the publicIPAddress attribute, like so:

<mediaServer>
  <connection publicIPAddress="24.0.0.92" />
</mediaServer>

If you do not know the public IP address of your LiveSwitch Media Server, you can instead specify the address of a STUN server. When the LiveSwitch Media Server starts up, it will use this server to discover its own public IP address. When specifying the address of the STUN server, specify the domain and optionally the port (default is 3478). The following example shows the use of the stunAddress attribute.

<mediaServer>
  <connection stunAddress="stun.liveswitch.fm" />
</mediaServer>

Generally, using the stunAddress attribute is more robust, as it automatically handles changes to the public IP address. You should specify only one of these configuration options.

Note

Only specify a stunAddress or a publicIPAddress. If both are specified, connectivity may not be established.

Enabling Bandwidth Adaptation

In your media server configuration, set the bandwidthAdaptationPolicy attribute to enabled on the connection element:

<connection bandwidthAdaptationPolicy="enabled" ... />

Then, in your client code, set BandwidthAdaptationPolicy to Enabled on your VideoStream.

Bandwidth adaptation in browsers

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


Native bandwidth adaptation is experimental

Note that in the native platforms bandwidth adaptation is still experimental and is not recommended for AudioStreams at this time.

Modifying Codec Settings

The codecs element is a collection that contains information on which codecs are supported by the LiveSwitch Media Server. Each codec is represented by its own distinct element - ie: the h264 codec has an h264 element. If a codec element does not appear under this element, then the LiveSwitch Media Server will ignore requests to use it. The available codecs are:

  • VP8: Specified with the vp8 element. You can additionally set the bitrate with the bitrate attribute. This value is in kbps.
  • H264: Enabled with the h264 element. You can additionally set the bitrate with the bitrate attribute. This value is in kbps.
  • Opus: Enabled with the opus element. You can additionally set the bitrate with the bitrate attribute. This value is in kbps.
  • PCMU: Enabled with the pcmu element.
  • PCMA: Enabled with the pcma element.

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. In the example below, h264 will sent with a max of 512 Kbps while vp8 will max out at 1024 Kbps.

The sample configuration below enables all available codecs:

<mediaServer>
  <codecs>
    <vp8 bitrate="1024" />
    <h264 bitrate="512" />
    <opus bitrate="32" />
    <pcmu />
    <pcma />
  </codecs>
</mediaServer>

Note that if you disable too many codecs, the LiveSwitch Media Server will be unable to accept connections.

Configuring MCU Sessions

The mcu element allows you to set configuration options for the LiveSwitch Media Server when it is running in MCU mode. Among other things, this allows you to define how you want the output video to be formatted by the multiplexer. To configure this, add a videoOutput element to your mcu element. With this element, you can set both the dimensions and the frame rate of the video that the MCU outputs. The XML snippet below shows how you can configure the MCU to output video at 1280x720 and at 30 frames per second.

<mcu>
  <videoOutput width="1280" height="720" frameRate="30" />
</mcu>

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 maximum bitrate for participant video while in an MCU session. This is useful to limit the amount of bandwidth that the MCU consumes. To do this, add a videoInput element or an audioInput element and set the maxParticipantBitrate attribute. The value of this attribute is in kbps. This is demonstrated below, where a maximum video bitrate of 1024kbps and a maximum bitrate of 32kbps is set.

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>
  <videoInput maxParticipantBitrate="1024" />
  <audioInput maxParticipantBitrate="32"  />
</mcu>

Configuring SFU Sessions

Similar to the mcu element described above, the sfu element 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, still set the maximum bitrate of the participants' input streams. To configure this, again, you use two elements, videoInput and audioInput. For both, set the maxParticipantBitrate attribute. The sample below demonstrates how to set a maximum video bitrate of 1024kbps and a maximum audio bitrate of 32kbps.

<sfu>
  <videoInput maxParticipantBitrate="1024" />
  <audioInput maxParticipantBitrate="32"  />
</sfu>

Enabling Recording

The recording element controls whether or not the LiveSwitch Media Server records any sessions. The recording element has two attributes, which must both be specified to enable recording. To enable recording, the enabled attribute must be set to "true". You must then specify the path attribute, which must be a path to an existing directory. This is demonstrated below:

<mediaServer>
  <recording enabled="true" path="C:\Temp" />
</mediaServer>

Starting with your specified path, recordings are written to path > appId > channelId > userId > deviceId > clientId > connectionId > audio.mkv or path > appId > channelId > userId > deviceId > clientId > connectionId > video.mkv

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.

Configuring per-Application and per-Channel Settings

The above configuration options modify the settings for the entire LiveSwitch Media Server. This is useful as a default but you may wish to have settings that differ for each application. For example, if you are running a service with a free tier, you may wish to reserve larger amounts of bandwidth for your paying customers. LiveSwitch accommodates this by allowing you to modify individual configuration options at either the application level or the channel level.

The following configuration options demonstrate how to specify a low resolution MCU output stream for one application and a high resolution MCU stream for another.

<mediaServer>
  <application id="my-free-application">
    <mcu>
      <videoOutput width="640" height="360" frameRate="15" />
    </mcu>
  </application>
  <application id="my-paid-application">
    <mcu>
      <videoOutput width="1280" height="720" frameRate="30" />
    </mcu>
  </application>
</mediaServer>

You can also modify the settings on a per-channel level. The following XML sample disables recording by default but enables it for a single channel.

<mediaServer>
  <application id="my-application">
    <recording enabled="false" />
    <channel id="recording-enabled-channel">
      <recording enabled="true" />
    </channel>
  </application>
</mediaServer>

You can modify any setting under the connection, codecs, mcu, sfu and recording configuration elements. You cannot specify application-specific settings for the gateway configuration element.

Restarting the Service

Whenever you modify the configuration for the LiveSwitch Media Server service, you must restart the service for the changes to be applied. Run the following commands in either the Windows Command Prompt or a PowerShell window with administrator access:

net stop "LiveSwitch Media Server"
net start "LiveSwitch Media Server"

Wrapping Up

You're now able to customize the configuration for your LiveSwitch Media Server. LiveSwitch allows you a lot of flexibility with the configuration values, but you should be careful with what you change here. The default values are the default because they work well across a broad spectrum of devices. Particularly when it comes to audio and video streaming, small changes can have a large impact. Next, you should look at the Configuring the SIP Connector, to learn how to set up SIP. If your application doesn't need this feature, instead go to the Configuring Logging section to learn how to configure logging for your services.