Code autogenerated from Kurento/doc-kurento@d7d2a7e

source/user/faq.rst

@@ -294,18 +294,53 @@ Docker is the recommended method of deploying Kurento Media Server, because it m
 
 
 
-How to edit configuration files?
---------------------------------
+.. _faq-docker-config:
+
+How to provide configuration files?
+-----------------------------------
 
-If you want to provide your own configuration files to the Kurento Docker image, the easiest method is to provide them through a `bind-mount <https://docs.docker.com/storage/bind-mounts/>`__. However, the first thing you'll need are the actual files; run these commands to get the default ones from the Kurento Docker image:
+To edit the configuration files that Kurento will use from within a Docker container, the first thing you'll need are the actual files; run these commands to get the default ones from a temporary container:
 
 .. code-block:: shell
 
    CONTAINER="$(docker create kurento/kurento-media-server:latest)"
    docker cp "$CONTAINER":/etc/kurento/. ./etc-kurento
    docker rm "$CONTAINER"
 
-Now, edit the files as needed. Later, provide them to newly created containers:
+After editing these files as needed, provide them to newly created Kurento Docker containers, with any of the mechanisms offered by Docker. Here we show examples for two of them:
+
+
+
+FROM image
+~~~~~~~~~~
+
+Creating a custom Docker image is a good choice for changing Kurento configuration files when you don't have direct control of the host environment. The `FROM <https://docs.docker.com/engine/reference/builder/#from>`__ feature of *Dockerfiles* can be used to derive directly from the official `Kurento Docker image <https://hub.docker.com/r/kurento/kurento-media-server>`__ and create your own fully customized image.
+
+A ``Dockerfile`` such as this one would be a good enough starting point:
+
+.. code-block:: docker
+
+   FROM kurento/kurento-media-server:latest
+   COPY etc-kurento/* /etc/kurento/
+
+Now, build the new image:
+
+.. code-block:: shell-session
+
+   $ docker build --tag kms-with-my-config:latest .
+   Step 1/2 : FROM kurento/kurento-media-server:latest
+   Step 2/2 : COPY etc-kurento/* /etc/kurento/
+   Successfully built 3d2bedb31a9d
+   Successfully tagged kms-with-my-config:latest
+
+And use the new image "*kms-with-my-config:latest*" in place of the original one.
+
+
+
+Bind mount
+~~~~~~~~~~
+
+A `bind-mount <https://docs.docker.com/storage/bind-mounts/>`__ will replace the default set of config files inside the official Kurento Docker image, with the ones you provide from the host filesystem. This method can be used if you are in control of the host system:
 
 .. code-block:: shell
 

source/user/troubleshooting.rst

@@ -663,12 +663,33 @@ Element-specific info
 PlayerEndpoint
 --------------
 
+RTSP broken audio
+~~~~~~~~~~~~~~~~~
+
+If you have your own RTSP tool generating OPUS encoded audio to be consumed in Kurento with a *PlayerEndpoint* (`Java <https://doc-kurento.readthedocs.io/en/latest/_static/client-javadoc/org/kurento/client/PlayerEndpoint.html>`__, `JavaScript <https://doc-kurento.readthedocs.io/en/latest/_static/client-jsdoc/module-elements.PlayerEndpoint.html>`__), and the resulting audio is very choppy and robotic, you should start by verifying that your encoding process is configured correctly for the OPUS frame size used in WebRTC.
+
+This was the case for a user who later shared with us the reasons for the bad quality audio they were perceiving:
+
+    `Bad audio quality <https://groups.google.com/g/kurento/c/nq-BNeZn2P8>`__
+
+    > *There was a mismatch between the incoming raw audio frame size and the opus encoding frame size,
+    which resulted in a bad encoding cadence causing irregular encoded frame intervals.*
+
+    > *We remedied this by ensuring that the incoming audio frame size and the opus encoding frame size are
+    the same --- or the incoming frame size is a divisor of the encoding frame size.*
+
+
+
 RTSP broken video
 ~~~~~~~~~~~~~~~~~
 
 Some users have reported huge macro-blocks or straight out broken video frames when using a PlayerEndpoint to receive an RTSP stream containing H.264 video. A possible solution to fix this issue is to fine-tune the PlayerEndpoint's **networkCache** parameter. It basically sets the buffer size (in milliseconds) that the underlying GStreamer decoding element will use to cache the stream.
 
-There's no science for that parameter, though. The perfect value depends on your network topology and efficiency, so you should proceed in a trial-and-error approach. For some situations, values lower than **100ms** have worked fine; some users have reported that 10ms was required to make their specific camera work, others have seen good results with setting this parameter to **0ms**.
+There's no science for that parameter, though. The perfect value depends on your network topology and efficiency, so you should proceed in a trial-and-error approach. For some situations, values lower than **100ms** have worked fine; some users have reported that 10ms was required to make their specific camera work, others have seen good results with setting this parameter to **0ms**. However, these are outlier cases and normally a higher *networkCache* is needed.
+
+In principle, *networkCache = 0* would mean that all RTP packets must be exactly on point at the expected times in the RTSP stream, or else they will be dropped. So even a slight amount of jitter or delay in the network might cause packets to be dropped when they arrive to the PlayerEndpoint.
+
+*networkCache* translates directly to the *latency* property of GStreamer's `rtspsrc <https://gstreamer.freedesktop.org/documentation/rtsp/rtspsrc.html>`__ element, which in turn is passed to the `rtpbin <https://gstreamer.freedesktop.org/documentation/rtpmanager/rtpbin.html>`__ and ultimately the `rtpjitterbuffer <https://gstreamer.freedesktop.org/documentation/rtpmanager/rtpjitterbuffer.html>`__ inside it.
 
 
 

source/user/writing_modules.rst

@@ -229,7 +229,7 @@ It is perfectly possible to install and use additional Kurento modules with Dock
 
 Our recommendation is to leverage the `FROM <https://docs.docker.com/engine/reference/builder/#from>`__ feature of *Dockerfiles*, to derive directly from a `Kurento Docker image <https://hub.docker.com/r/kurento/kurento-media-server>`__, and create your own fully customized image.
 
-A *Dockerfile* such as this one would be a good enough starting point:
+A ``Dockerfile`` such as this one would be a good enough starting point:
 
 .. code-block:: docker