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:
The next sections of this document will describe the configuration options for this element.
Editing the Media Server Section
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
gatewayspecifies which LiveSwitch Gateway to connect to
connectionsets the local network settings for connections from the media server
codecsspecifies which codecs that the media server should use
mcuconfigures settings specific to MCU mode
sfuconfigures settings specific to SFU mode
recordingenables or disables session recording
Each of these is explored in detail in the following sections.
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 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.
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
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,
publicIPAddress. If you know the public IP address of your LiveSwitch Media Server, you should specify it here using the
publicIPAddress attribute, like so:
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
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.
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
Then, in your client code, set
Enabled on your
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
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
vp8element. You can additionally set the bitrate with the
bitrateattribute. This value is in kbps.
- H264: Enabled with the
h264element. You can additionally set the bitrate with the
bitrateattribute. This value is in kbps.
- Opus: Enabled with the
opuselement. You can additionally set the bitrate with the
bitrateattribute. This value is in kbps.
- PCMU: Enabled with the
- PCMA: Enabled with the
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:
Note that if you disable too many codecs, the LiveSwitch Media Server will be unable to accept connections.
Configuring MCU Sessions
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.
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.
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,
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.
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:
Starting with your specified path, recordings are written to
> 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.
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.
You can modify any setting under the
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:
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.