============= Configuration ============= .. contents:: 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: * `Kurento Client JavaDoc <../_static/client-javadoc/index.html>`__. * `Kurento Client JsDoc <../_static/client-jsdoc/index.html>`__. The :ref:`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 :ref:`faq-docker`. Debug Logging ============= KMS uses the environment variable ``GST_DEBUG`` to define the debug level of all underlying modules. Check :doc:`/features/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``: .. code-block:: shell docker run [...] \ -e GST_DEBUG="Kurento*:5" \ kurento/kurento-media-server:7.3.0 .. _configuration-stun-turn: STUN/TURN Server ================ Read :ref:`faq-stun-needed` to learn about when you might need to use these, and :ref:`installation-stun-turn` for guidance on how to install your own STUN/TURN server. **Local install** * Set values ``stunServerAddress`` and ``stunServerPort`` to use a STUN server, or set ``turnURL`` to use a TURN server; in ``/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini``. **Docker** * Pass environment variables ``KMS_STUN_IP`` and ``KMS_STUN_PORT`` for STUN, or ``KMS_TURN_URL`` for TURN. **Client API** * Java: `setStunServerAddress <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setStunServerAddress(java.lang.String)>`__ and `setStunServerPort <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setStunServerPort(int)>`__ for STUN, or `setTurnUrl <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setTurnUrl(java.lang.String)>`__ for TURN. * JavaScript: `setStunServerAddress <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setStunServerAddress>`__ and `setStunServerPort <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setStunServerPort>`__ for STUN, or `setTurnUrl <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#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 <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setNetworkInterfaces(java.lang.String)>`__. * JavaScript: `setNetworkInterfaces <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setNetworkInterfaces>`__. .. _configuration-bitrate: 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 <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html#setMaxVideoSendBandwidth(int)>`__, `JavaScript <../_static/client-jsdoc/module-core_abstracts.BaseRtpEndpoint.html#setMaxVideoSendBandwidth>`__. There are several ways to override the default settings for variable bitrate and network bandwidth estimation: * `setMinVideoRecvBandwidth <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html#setMinVideoRecvBandwidth(int)>`__ / `setMaxVideoRecvBandwidth <../_static/client-javadoc/org/kurento/client/SdpEndpoint.html#setMaxVideoRecvBandwidth(int)>`__ * `setMinVideoSendBandwidth <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html#setMinVideoSendBandwidth(int)>`__ / `setMaxVideoSendBandwidth <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html#setMaxVideoSendBandwidth(int)>`__ * `setEncoderBitrate <../_static/client-javadoc/org/kurento/client/MediaElement.html#setEncoderBitrate(int)>`__ / `setMinEncoderBitrate <../_static/client-javadoc/org/kurento/client/MediaElement.html#setMinEncoderBitrate(int)>`__ / `setMaxEncoderBitrate <../_static/client-javadoc/org/kurento/client/MediaElement.html#setMaxEncoderBitrate(int)>`__ - 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** * Java: `setIceTcp <../../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setIceTcp(boolean)>`__. * JavaScript: `setIceTcp <../../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setIceTcp>`__. 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 <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setExternalIPv4(java.lang.String)>`__. * JavaScript: `setExternalIPv4 <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#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 :ref:`browser-mtu`). **Local install** * Set value ``mtu`` in ``/etc/kurento/modules/kurento/BaseRtpEndpoint.conf.ini``. **Docker** * Pass environment variable ``KMS_MTU``. **Client API** * Java: `setMtu <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html#setMtu(int)>`__. * JavaScript: `setMtu <../_static/client-jsdoc/module-core_abstracts.BaseRtpEndpoint.html#setMtu>`__. .. _configuration-dtls: WebRTC DTLS certificates ------------------------ By default, Kurento uses a different self-signed certificate for every WebRtcEndpoint (see :ref:`features-security-kms-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: .. code-block:: shell # 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`` or ``pemCertificateECDSA`` with the path to your certificate file in ``/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini``. **Docker** * Pass environment variables ``KMS_PEM_CERTIFICATE_RSA`` or ``KMS_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 :ref:`faq-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 <../_static/client-javadoc/org/kurento/client/GapsFixMethod.html>`__ for more details about these settings. **Local install** * Set ``gapsFix`` with the preferred gaps fix method in ``/etc/kurento/modules/kurento/RecorderEndpoint.conf.ini``.