Configuration
Table of Contents
Most (but not all, see below) of the settings in Kurento can be set statically in configuration files:
/etc/kurento/kurento.conf.json
The main configuration file. Provides settings for the behavior of Kurento Media Server itself.
/etc/kurento/modules/kurento/MediaElement.conf.ini
Generic parameters for all kinds of MediaElement.
/etc/kurento/modules/kurento/SdpEndpoint.conf.ini
Audio/video parameters for SdpEndpoints (i.e. WebRtcEndpoint and RtpEndpoint).
/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini
Specific parameters for WebRtcEndpoint.
/etc/kurento/modules/kurento/HttpEndpoint.conf.ini
Specific parameters for HttpEndpoint.
/etc/default/kurento-media-server
This file is loaded by the system’s service init files. Defines some environment variables, which have an effect on features such as the Debug Logging, or the Core Dump files that are generated when a crash happens.
For other settings not directly available in configuration files, make sure to read the Client API SDK docs, where all exposed methods are documented:
The Kurento Docker images also accept some environment variables that map directly to settings in the above files. If this is not flexible enough, you can always use a bind-mount or volume with a different set of configuration files in /etc/kurento/
. For some tips about these techniques, go to Kurento in Docker.
Debug Logging
KMS uses the environment variable GST_DEBUG
to define the debug level of all underlying modules. Check Debug Logging for more information about this and other environment variables.
Set this variable to change the verbosity level of the log messages generated by KMS.
Local install
Set environment variable
GST_DEBUG
in/etc/default/kurento-media-server
.
Docker
Pass environment variable
GST_DEBUG
:docker run [...] \ -e GST_DEBUG="Kurento*:5" \ kurento/kurento-media-server:7.0.0
STUN/TURN Server
Read When are STUN and TURN needed? to learn about when you might need to use these, and STUN/TURN server install for guidance on how to install your own STUN/TURN server.
Local install
Set values
stunServerAddress
andstunServerPort
to use a STUN server, or setturnURL
to use a TURN server; in/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini
.
Docker
Pass environment variables
KMS_STUN_IP
andKMS_STUN_PORT
for STUN, orKMS_TURN_URL
for TURN.
Client API
Java: setStunServerAddress and setStunServerPort for STUN, or setTurnUrl for TURN.
JavaScript: setStunServerAddress and setStunServerPort for STUN, or setTurnUrl for TURN.
Network Interface
To specify the network interface name(s) that KMS should use to communicate from the environment where it is running (either a physical machine, a virtual machine, a Docker container, etc.)
Local install
Set value
networkInterfaces
in/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini
.
Docker
Pass environment variable
KMS_NETWORK_INTERFACES
.
Client API
Java: setNetworkInterfaces.
JavaScript: setNetworkInterfaces.
WebRTC Bitrate
The default MaxVideoSendBandwidth range of the WebRtcEndpoint is a VERY conservative one, and leads to a low maximum video quality. Most applications will probably want to increase this to higher values such as 2000 kbps (2 mbps): Java, JavaScript.
There are several ways to override the default settings for variable bitrate and network bandwidth estimation:
setEncoderBitrate / setMinEncoderBitrate / setMaxEncoderBitrate
This setting is also configurable in
/etc/kurento/modules/kurento/MediaElement.conf.ini
.
RTP Ports
These two parameters define the minimum and maximum ports that Kurento Media Server will bind to (listen) in order to receive remote RTP packets. This affects the operation of both RtpEndpoint and WebRtcEndpoint.
Plain RTP (RtpEndpoint) needs 2 ports for each media kind: an even port is used for RTP, and the next odd port is used for RTCP. WebRTC (WebRtcEndpoint) uses RTCP Multiplexing (rtcp-mux) when possible, so it only uses 1 port for each media kind.
Local install
Set values
minPort
,maxPort
in/etc/kurento/modules/kurento/BaseRtpEndpoint.conf.ini
.
Docker
Pass environment variables
KMS_MIN_PORT
,KMS_MAX_PORT
.
Advanced Settings
These settings are only provided for advanced users who know what they are doing and why they need them. For most cases, the default values are good enough for most users.
ICE-TCP
ICE-TCP is what allows WebRTC endpoints to exchange ICE candidates that use the TCP protocol; in other words, the feature of using TCP instead of UDP for WebRTC communications.
If you have a well known scenario and you are 100% sure that UDP will work, then disabling TCP provides slightly faster times when establishing WebRTC sessions. I.e., with ICE-TCP disabled, the time between joining a call and actually seeing the video will be shorter.
Of course, if you cannot guarantee that UDP will work in your network, then you should leave this setting enabled, which is the default. Otherwise, UDP might fail and there would be no TCP fallback for WebRTC to work.
Local install
Set value
iceTcp
to 1 (ON) or 0 (OFF) in/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini
.
Docker
Set environment variable
KMS_ICE_TCP
to 1 (ON) or 0 (OFF).
Client API
External IP Address
When this feature is used, all of the Kurento IPv4 and/or IPv6 ICE candidates are mangled to contain the given address. This can speed up WebRTC connection establishment in scenarios where the external or public IP is already well known, also having the benefit that STUN won’t be needed for the media server.
Local install
Set values
externalIPv4
,externalIPv6
in/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini
.
Docker
Pass environment variables
KMS_EXTERNAL_IPV4
,KMS_EXTERNAL_IPV6
.If the special value
auto
is used, then the container will auto-discover its own public IP address by performing a DNS query to some of the well established providers (OpenDNS, Google, Cloudflare). You can review the script here: getmyip.sh. In cases where these services are not reachable, the external IP parameters are left unset.
Client API
Java: setExternalIPv4.
JavaScript: setExternalIPv4.
Maximum Transmission Unit
The MTU is a hard limit on the size that outbound packets will have. For some users it is important being able to lower the packet size in order to prevent fragmentation.
For the vast majority of use cases it is better to use the default MTU value of 1200 Bytes, which is also the default value in most popular implementations of WebRTC (see Browser MTU).
Local install
Set value
mtu
in/etc/kurento/modules/kurento/BaseRtpEndpoint.conf.ini
.
Docker
Pass environment variable
KMS_MTU
.
Client API
WebRTC DTLS certificates
By default, Kurento uses a different self-signed certificate for every WebRtcEndpoint (see Media Plane security (DTLS)). If you want or need to use the same cert for every endpoint, first join both your certificate (chain) file(s) and the private key with a command such as this one:
# Make a single file to be used with Kurento Media Server.
cat cert.pem key.pem >cert+key.pem
Then, configure the path to cert+key.pem
:
Local install
Set either of
pemCertificateRSA
orpemCertificateECDSA
with the path to your certificate file in/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini
.
Docker
Pass environment variables
KMS_PEM_CERTIFICATE_RSA
orKMS_PEM_CERTIFICATE_ECDSA
with the path inside the container. Also, make sure the file is actually found in that path; normally you would do that with a bind-mount, a Docker volume, or a custom Docker image. For more information and examples, check Kurento in Docker.
Recorder packet loss correction
The parameter gapsFix
determines which of the packet loss correction techniques should be used for recordings. Packet loss can happen for example when an RTP or WebRTC media flow suffers from network congestion and some packets don’t arrive at the media server. When this happens, it causes gaps in the recorded stream.
Currently there are two techniques implemented:
NONE
: Do not fix gaps.Leave the stream as-is, and store it with any gaps that the stream might have. Some players are clever enough to adapt to this during playback, so that the gaps are reduced to a minimum and no problems are perceived by the user; other players are not so sophisticated, and will struggle trying to decode a file that contains gaps. For example, trying to play such a file directly with Chrome will cause lipsync issues (audio and video will fall out of sync).
This is the best choice if you need consistent durations across multiple simultaneous recordings (i.e. you are recording N participants of a room, and you want the N videos to have the same exact duration). Another usual reason to prefer this mode is if you are anyway going to post-process the recordings (e.g. with an extra FFmpeg step).
GENPTS
: Adjust timestamps to generate a smooth progression over all frames.This technique rewrites the timestamp of all frames, so that gaps are suppressed. It provides the best playback experience for recordings that need to be played as-is (i.e. they won’t be post-processed). However, fixing timestamps might cause a change in the total duration of a file. So different recordings from the same session might end up with slightly different durations.
See the extended description of GapsFixMethod for more details about these settings.
Local install
Set
gapsFix
with the preferred gaps fix method in/etc/kurento/modules/kurento/RecorderEndpoint.conf.ini
.