Code autogenerated from Kurento/doc-kurento@cf50857

source/knowledge/browser.rst

@@ -236,26 +236,6 @@ Autoplay:
 
 
 
-H.264 encoding/decoding profile
-===============================
-
-By default, Chrome uses this line in the SDP Offer for an H.264 media:
-
-.. code-block:: text
-
-   a=fmtp:100 level-asymmetry-allowed=1;packetization-mode=1;profile-level-id=42e01f
-
-`profile-level-id` is an SDP attribute, defined in [RFC 6184] as the hexadecimal representation of the *Sequence Parameter Set* (SPS) from the H.264 Specification. The value **42e01f** decomposes as the following parameters:
-- `profile_idc` = 0x42 = 66
-- `profile-iop` = 0xE0 = 1110_0000
-- `level_idc` = 0x1F = 31
-
-:rfc:`6184`.
-
-These values translate into the **Constrained Baseline Profile, Level 3.1**.
-
-
-
 Command-line
 ============
 
@@ -336,15 +316,54 @@ WebRTC **bandwidth estimation (BWE)** was implemented first with *Google REMB*,
 
 
 
+.. _browser-video:
+
 Video Encoding
 ==============
 
-The WebRTC **maximum video bitrate** is limited by a simple calculation based on its **width** and **height**:
+Video Bitrate
+-------------
+
+Web browsers will adapt their output video quality according to what they detect is the network quality. Most browsers will adapt the **video bitrate**; in addition, Chrome also adapts the **video resolution**.
+
+The **maximum video bitrate** is calculated by the WebRTC stack, by following a simple rule based on the video dimensions:
 
 * 600 kbps if ``width * height <= 320 * 240``.
 * 1700 kbps if ``width * height <= 640 * 480``.
 * 2000 kbps (2 Mbps) if ``width * height <= 960 * 540``.
 * 2500 kbps (2.5 Mbps) for bigger video sizes.
-* Even for bigger sizes, bitrate max is 1200 kbps if video is a screen capture.
+* 1200 kbps in any case, if the video is a screen capture.
+
+Source: The ``GetMaxDefaultVideoBitrateKbps()`` function in `libwebrtc source code <https://webrtc.googlesource.com/src/+/d82a02c837d33cdfd75121e40dcccd32515e42d6/media/engine/webrtc_video_engine.cc#231>`__.
 
-`libwebrtc source code <https://webrtc.googlesource.com/src/+/d82a02c837d33cdfd75121e40dcccd32515e42d6/media/engine/webrtc_video_engine.cc#231>`__ (``GetMaxDefaultVideoBitrateKbps``).
+Browsers offer internal stats through a special web address that you can use to verify what is really being sent by their WebRTC stack.
+
+For example, to check the outbound stats in Chrome:
+
+#. Open this URL: ``chrome://webrtc-internals/``.
+#. Look for the stat name "*Stats graphs for RTCOutboundRTPVideoStream (outbound-rtp)*".
+#. You will find the effective output video bitrate in ``[bytesSent_in_bits/s]``, and the output resolution in ``frameWidth`` and ``frameHeight``.
+
+You can also check what is the network bandwidth estimation in Chrome:
+
+#. Look for the stat name "*Stats graphs for RTCIceCandidatePair (candidate-pair)*". Note that there might be several of these, but only one will be active.
+#. Find the output network bandwidth estimation in ``availableOutgoingBitrate``. Chrome will try to slowly increase its output bitrate, until it reaches this estimation.
+
+
+
+H.264 profile
+-------------
+
+By default, Chrome uses this line in the SDP Offer for an H.264 media:
+
+.. code-block:: text
+
+   a=fmtp:100 level-asymmetry-allowed=1;packetization-mode=1;profile-level-id=42e01f
+
+`profile-level-id` is an SDP attribute, defined in :rfc:`6184` as the hexadecimal representation of the *Sequence Parameter Set* (SPS) from the H.264 Specification. The value **42e01f** decomposes as the following parameters:
+
+* `profile_idc` = 0x42 = 66
+* `profile-iop` = 0xE0 = 1110_0000
+* `level_idc` = 0x1F = 31
+
+These values translate into the **Constrained Baseline Profile, Level 3.1**.

source/knowledge/memory_fragmentation.rst

@@ -26,39 +26,45 @@ Solution
 
 The best option we know about is replacing ``malloc``, the standard memory allocator that comes by default with the system, with a specific-purpose allocator, written with this issue in mind in order to avoid or mitigate it as much as possible.
 
-Two of the most known alternative allocators are `jemalloc <http://jemalloc.net/>`__ (`code repository <https://github.com/jemalloc/jemalloc>`__) and Google's `TCMalloc <https://google.github.io/tcmalloc/>`__ (`code repository <https://github.com/google/tcmalloc>`__).
+Two of the most known alternative allocators are `Jemalloc <http://jemalloc.net/>`__ (`code repository <https://github.com/jemalloc/jemalloc>`__) and Google's `TCMalloc <https://google.github.io/tcmalloc/>`__ (`code repository <https://github.com/google/tcmalloc>`__).
 
-*jemalloc* has been tested with Kurento Media Server, and found to give pretty good results. It is important to note that internal fragmentation cannot be reduced to zero, but this alternative allocator was able to reduce memory fragmentation issues to a minimum.
+Jemalloc has been tested with Kurento Media Server, and found to give pretty good results. It is important to note that internal fragmentation cannot be reduced to zero, but this alternative allocator was able to reduce memory fragmentation issues to a minimum.
 
 
 
 .. _knowledge-memfrag-jemalloc:
 
-Using jemalloc
+Using Jemalloc
 ==============
 
-First install it on your system. For the versions of Ubuntu that are explicitly supported bu Kurento, you an run this command:
+First install it on your system. For the versions of Ubuntu that are explicitly supported by Kurento, you can run this command:
 
 .. code-block:: shell
 
    sudo apt-get update && sudo apt-get install --yes libjemalloc1
 
-*jemalloc* is installed as a standalone library. To actually use it, you need to preload it when launching KMS:
+Jemalloc is installed as a standalone library. To actually use it, you need to preload it when launching KMS:
 
 .. code-block:: shell
 
    LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1  /usr/bin/kurento-media-server
 
-This will use jemalloc with its default configuration, which should be good enough for normal operation.
+This will use Jemalloc with its default configuration, which should be good enough for normal operation.
 
-If you know how to fine-tune the allocator with better settings than the default ones, you can do so on the command line too. A useful environment variable to learn more about the internals of *jemalloc* is ``MALLOC_CONF``. For example:
+If you know how to fine-tune the allocator with better settings than the default ones, you can do so with the ``MALLOC_CONF`` environment variable. For example:
 
 .. code-block:: shell
 
    export MALLOC_CONF=stats_print:true
    LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1  /usr/bin/kurento-media-server
 
-This will cause KMS to dump memory usage statistics when exiting. Those statistics may be used to tune *jemalloc* and define the configuration to use.
+This would cause KMS to dump memory usage statistics when exiting. Those statistics could then be used to tune Jemalloc and define the configuration to use.
+
+.. note::
+
+   To use Jemalloc from inside a Docker container, you'll want to make a custom image that is derived from the official one, where the required package is installed and the Docker Entrypoint script has been modified to add the library preloading step.
+
+   There is some additional information about how to start making a customized image in :ref:`faq-docker`.
 
 .. note::
 
@@ -69,9 +75,7 @@ This will cause KMS to dump memory usage statistics when exiting. Those statisti
 Other suggestions
 =================
 
-It is a good idea to maintain health checks on servers that are running Kurento Media Server and show memory exhaustion issues.
-
-As it still may present some internal fragmentation level (it is really difficult to get rid of this in a server that makes a heavy use of dynamic memory), we suggest maintaining some health probes on KMS, that at least should take care of memory usage and behave as follows:
+It is a good idea to maintain health checks on servers that are running Kurento Media Server, to automatically detect and react against memory exhaustion issues. We suggest maintaining some health probes on KMS, that at least should take care of memory usage and behave as follows:
 
 1. Maintain a probe on memory usage of the Kurento Media Server process.
 

source/langdoc/client-javadoc/org/kurento/client/class-use/Continuation.html

@@ -651,15 +651,15 @@ <h3>Uses of <a href="../../../../org/kurento/client/Continuation.html" title="in
 </tr>
 <tr class="altColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">MediaPipeline.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaPipeline.html#getGstreamerDot-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&gt;&nbsp;cont)</code>
+<td class="colLast"><span class="typeNameLabel">MediaElement.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaElement.html#getGstreamerDot-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&gt;&nbsp;cont)</code>
 <div class="block">Asynchronous version of getGstreamerDot:
  <a href="../../../../org/kurento/client/Continuation.html#onSuccess-F-"><code>onSuccess(F)</code></a> is called when the action is
  done.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">MediaElement.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaElement.html#getGstreamerDot-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&gt;&nbsp;cont)</code>
+<td class="colLast"><span class="typeNameLabel">MediaPipeline.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaPipeline.html#getGstreamerDot-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&gt;&nbsp;cont)</code>
 <div class="block">Asynchronous version of getGstreamerDot:
  <a href="../../../../org/kurento/client/Continuation.html#onSuccess-F-"><code>onSuccess(F)</code></a> is called when the action is
  done.</div>
@@ -676,7 +676,7 @@ <h3>Uses of <a href="../../../../org/kurento/client/Continuation.html" title="in
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">MediaPipeline.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaPipeline.html#getGstreamerDot-org.kurento.client.GstreamerDotDetails-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/GstreamerDotDetails.html" title="enum in org.kurento.client">GstreamerDotDetails</a>&nbsp;details,
+<td class="colLast"><span class="typeNameLabel">MediaElement.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaElement.html#getGstreamerDot-org.kurento.client.GstreamerDotDetails-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/GstreamerDotDetails.html" title="enum in org.kurento.client">GstreamerDotDetails</a>&nbsp;details,
                <a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&gt;&nbsp;cont)</code>
 <div class="block">Asynchronous version of getGstreamerDot:
  <a href="../../../../org/kurento/client/Continuation.html#onSuccess-F-"><code>onSuccess(F)</code></a> is called when the action is
@@ -685,7 +685,7 @@ <h3>Uses of <a href="../../../../org/kurento/client/Continuation.html" title="in
 </tr>
 <tr class="altColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">MediaElement.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaElement.html#getGstreamerDot-org.kurento.client.GstreamerDotDetails-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/GstreamerDotDetails.html" title="enum in org.kurento.client">GstreamerDotDetails</a>&nbsp;details,
+<td class="colLast"><span class="typeNameLabel">MediaPipeline.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/MediaPipeline.html#getGstreamerDot-org.kurento.client.GstreamerDotDetails-org.kurento.client.Continuation-">getGstreamerDot</a></span>(<a href="../../../../org/kurento/client/GstreamerDotDetails.html" title="enum in org.kurento.client">GstreamerDotDetails</a>&nbsp;details,
                <a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&gt;&nbsp;cont)</code>
 <div class="block">Asynchronous version of getGstreamerDot:
  <a href="../../../../org/kurento/client/Continuation.html#onSuccess-F-"><code>onSuccess(F)</code></a> is called when the action is