Documentation updates

gavv · Jan 30, 2024 · e34f0b5 · e34f0b5
1 parent 7b662b3
commit e34f0b5
Show file tree

Hide file tree

Showing 7 changed files with 84 additions and 43 deletions.
diff --git a/docs/sphinx/building/user_cookbook.rst b/docs/sphinx/building/user_cookbook.rst
@@ -211,7 +211,7 @@ Raspberry Pi (64-bit)
 
     # build libraries and tools
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-aarch64-linux-gnu \
+        rocstreaming/toolchain-aarch64-linux-gnu:gcc-7.4 \
           scons -Q \
             --host=aarch64-linux-gnu \
             --build-3rdparty=all \
@@ -235,7 +235,7 @@ Raspberry Pi 2 and later (32-bit)
 
     # build libraries and tools
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-arm-linux-gnueabihf \
+        rocstreaming/toolchain-arm-linux-gnueabihf:gcc-4.9 \
           scons -Q \
             --host=arm-linux-gnueabihf \
             --build-3rdparty=all \
@@ -259,7 +259,7 @@ Raspberry Pi 1 and Zero (32-bit)
 
     # build libraries and tools
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi \
+        rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi:gcc-4.7 \
           scons -Q \
             --host=arm-bcm2708hardfp-linux-gnueabi \
             --build-3rdparty=all

diff --git a/docs/sphinx/development/roadmap.rst b/docs/sphinx/development/roadmap.rst
@@ -6,7 +6,7 @@ Basic features
 
 - |:ballot_box_with_check:| Real-time streaming with guaranteed latency
 - |:ballot_box_with_check:| Clock drift compensation driven by receiver
-- |:white_large_square:| Clock drift compensation driven by sender
+- |:ballot_box_with_check:| Clock drift compensation driven by sender
 - |:ballot_box_with_check:| Packet loss recovery using FEC
 - |:ballot_box_with_check:| Session multiplexing
 - |:ballot_box_with_check:| Stream breakage detection
@@ -45,15 +45,17 @@ Extensibility
 - |:white_large_square:| Provide custom allocator
 - |:ballot_box_with_check:| Register custom payload types
 - |:white_large_square:| Register custom codecs
+- |:white_large_square:| Register custom mixer
 
 Protocols
 =========
 
 - |:ballot_box_with_check:| RTP/AVPF
 - |:ballot_box_with_check:| FECFRAME (Reed-Solomon and LDPC-Staircase FEC codes based on `OpenFEC <http://openfec.org/>`_)
-- |:white_large_square:| RTCP
-- |:white_large_square:| RTCP XR (extended reports)
-- |:white_large_square:| SDP and RTSP
+- |:ballot_box_with_check:| RTCP
+- |:ballot_box_with_check:| RTCP XR (extended reports)
+- |:white_large_square:| SDP
+- |:white_large_square:| RTSP
 - |:white_large_square:| SRTP
 - |:white_large_square:| DTLS
 
@@ -80,6 +82,8 @@ Audio backends
 - |:white_large_square:| WASAPI (Windows)
 - |:ballot_box_with_check:| SoX (universal)
 - |:white_large_square:| FFmpeg
+- |:white_large_square:| libsndfile
+- |:white_large_square:| WAV
 
 API
 ===
@@ -109,8 +113,9 @@ Integrations
 Bindings
 ========
 
-- |:ballot_box_with_check:| Go (roc-go)
 - |:ballot_box_with_check:| Java (roc-java)
+- |:ballot_box_with_check:| Go (roc-go)
+- |:white_large_square:| Rust
 
 Portability
 ===========

diff --git a/docs/sphinx/internals/audio_backends.rst b/docs/sphinx/internals/audio_backends.rst
@@ -16,13 +16,13 @@ syntax                     meaning                    example
 ``<driver>://<device>``    audio device name          ``alsa://hw:0``
 ``<driver>://default``     default audio device       ``pulse://default``
 ``file://<abs_path>``      audio file (absolute path) ``file:///home/user/test.wav``
-``file://<rel_path>``      audio file (relative path) ``file:./test.wav``
+``file:<rel_path>``        audio file (relative path) ``file:./test.wav``
 ``file://-`` or ``file:-`` stdin or stdout            ``file:-``
 ========================== ========================== ==============
 
 User can specify input file/device (**source**) for ``roc-send`` via ``--input`` option, and output file/device (**sink**) for ``roec-recv`` via ``--output`` option.
 
-When device is used, user specifies driver explicitly (e.g. ``alsa://`` for ALSA, ``pulse://`` for PulseAudio, etc). When file is used, file driver is automatically selected automatically, usually by file extension. However, user may force usage of specific driver for the file via ``--input-format`` or ``--output-format`` option.
+When device is used, user specifies driver explicitly (e.g. ``alsa://`` for ALSA, ``pulse://`` for PulseAudio, etc). When file is used, file driver is selected automatically, usually by file extension. However, user may force usage of specific driver for the file via ``--input-format`` or ``--output-format`` option.
 
 See :doc:`manual pages </manuals>` for more details.
 

diff --git a/docs/sphinx/internals/network_protocols.rst b/docs/sphinx/internals/network_protocols.rst
@@ -5,18 +5,51 @@ Roc needs several network protocols to deliver data between the sender and the r
 
 Roc doesn't invent new protocols. Instead, it relies on existing open standards to take advantage of their careful design and potential interoperability with other software. Roc implements all protocols by itself, for two reasons. First, not all protocols have a suitable open implementation. Second, the protocol support is tightly integrated into the Roc pipeline and it would be hard to employ a stand-alone implementation.
 
-Although Roc is designed to support arbitrary protocols, currently all supported protocols are RTP-based. RTP by itself is very basic but also very extensible. To employ RTP, one needs to select an RTP profile and, if necessary, some RTP extensions. Roc employs RTP Audio/Video Profile which specifies how to stream audio and video using RTP. Roc also employs FEC Framework, which specifies how to incorporate various FEC schemes into RTP.
+Although Roc is designed to support arbitrary protocols, so far all supported protocols are RTP-based. RTP by itself is very basic but also very extensible. To employ RTP, one needs to select an RTP profile and, if necessary, some RTP extensions. Roc employs RTP Audio/Video Profile which specifies how to stream audio and video using RTP. Roc also employs FEC Framework, which specifies how to incorporate various FEC schemes into RTP.
 
-Note that employing FEC Framework increases the service quality but also breaks interoperability with RTP implementations that are not aware of this extension. If you need compatibility with such applications, you should disable FEC in Roc.
+Note that employing FEC Framework increases the service quality but also breaks interoperability with RTP implementations that are not aware of this extension. If you need compatibility with such applications, you should disable FEC in Roc
+
+Roc also employs various RTCP extensions to exchange non-media reports between sender and receiver. Usually this doesn't break interoperability with implementations that don't support extensions, however some features may not work with such implementations (e.g. sender-side latency tuning).
 
 Here is the full list of the network protocols implemented by Roc:
 
-================================================= ================================ ============
-RFC                                               name                             comment
-================================================= ================================ ============
-`RFC 3550 <https://tools.ietf.org/html/rfc3550>`_ RTP                              Real-time Transport Protocol
-`RFC 3551 <https://tools.ietf.org/html/rfc3551>`_ RTP A/V Profile                  Audio and video profile for RTP
-`RFC 6363 <https://tools.ietf.org/html/rfc6363>`_ FEC Framework                    A framework for adding various FEC schemes to RTP
-`RFC 6865 <https://tools.ietf.org/html/rfc6865>`_ Simple Reed-Solomon FEC Scheme   FEC scheme for FECFRAME
-`RFC 6816 <https://tools.ietf.org/html/rfc6816>`_ Simple LDPC-Staircase FEC Scheme FEC scheme for FECFRAME
-================================================= ================================ ============
+.. list-table::
+   :widths: 10 60 30
+   :header-rows: 1
+
+   * - **RFC**
+     - **Name**
+     - **Comment**
+
+   * - `RFC 3550 <https://tools.ietf.org/html/rfc3550>`_
+     - `RTP: A Transport Protocol for Real-Time Applications`
+     - Basic RTP and RTCP
+
+   * - `RFC 3551 <https://tools.ietf.org/html/rfc3551>`_
+     - `RTP Profile for Audio and Video Conferences with Minimal Control`
+     - RTP AVPF (Audio/Video Profile)
+
+   * - `RFC 3611 <https://tools.ietf.org/html/rfc3611>`_
+     - `RTP Control Protocol Extended Reports`
+     - | RTCP XR
+       | (supported blocks: DLRR, RRTR)
+
+   * - `RFC 6776 <https://tools.ietf.org/html/rfc6776>`_
+     - `Measurement Identity and Information Reporting Using a Source Description (SDES) Item and an RTCP Extended Report (XR) Block`
+     - RTCP XR Measurement Information Block
+
+   * - `RFC 6843 <https://tools.ietf.org/html/rfc6843>`_
+     - `RTP Control Protocol (RTCP) Extended Report (XR) Block for Delay Metric Reporting`
+     - RTCP XR Delay Metrics Block
+
+   * - `RFC 6363 <https://tools.ietf.org/html/rfc6363>`_
+     - `Forward Error Correction (FEC) Framework`
+     - FECFRAME
+
+   * - `RFC 6865 <https://tools.ietf.org/html/rfc6865>`_
+     - `Simple Reed-Solomon Forward Error Correction (FEC) Scheme for FECFRAME`
+     - Reed-Solomon FEC Scheme
+
+   * - `RFC 6816 <https://tools.ietf.org/html/rfc6816>`_
+     - `Simple Low-Density Parity Check (LDPC) Staircase Forward Error Correction (FEC) Scheme for FECFRAME`
+     - LDPC-Staircase FEC Scheme
diff --git a/docs/sphinx/internals/timestamps.rst b/docs/sphinx/internals/timestamps.rst
@@ -8,10 +8,11 @@ Timestamps
 Types of timestamps
 ===================
 
-:doc:`Packets and frames </internals/packets_frames>` have two major types of timestamps:
+:doc:`Packets and frames </internals/packets_frames>` have three major types of timestamps:
 
 * STS - stream timestamp
 * CTS - capture timestamp
+* RTS - receive timestamp
 
 **Stream timestamp** (STS) describes position of the first sample in packet or frame using abstract stream clock.
 
@@ -28,18 +29,20 @@ The clock for CTS always belongs to the local system, no matter if we're on send
 * On sender, CTS of packet or frame is set to the system time when its first sample was captured.
 * On receiver, CTS is set to an estimation of the same value, converted to receiver system clock, i.e. the system time *of receiver* when the first sample was captured *on sender*.
 
-Unlike STS, this field does not directly correspond to any field inside RTP packet. Instead, sender and receiver exchange RTCP packets which help them to map STS to CTS, as described below.
+Unlike STS, this field does not directly correspond to any field inside RTP packet. Instead, sender and receiver exchange RTCP packets which help them to map STS to CTS, as described in the further sections.
+
+**Receive timestamp** (RTS) is the time when the packet reached incoming network queue.
+
+The clock for RTS is the same as for CTS: local Unix-time UTC clock, counting nanoseconds since Unix Epoch.
+
+This timestamp is used only on receiver and only for packets.
 
 Use of timestamps
 =================
 
 Stream timestamps are used to position packets in the continuous stream of samples. When a packet arrives to receiver, its stream timestamp defines where exactly it will be inserted into receiver stream.
 
-.. note::
-
-   Features below are still under construction.
-
-Capture timestamps have the following usages:
+Capture and receive timestamps have the following usages:
 
 * Estimate end-to-end latency between sender and receiver. To compute it, receiver needs to find the difference between the time when the frame was captured (i.e. capture timestamp) and the time when the frame is actually played (which receiver knows).
 

diff --git a/docs/sphinx/portability/cross_compiling.rst b/docs/sphinx/portability/cross_compiling.rst
@@ -46,7 +46,7 @@ Here is how you can build Roc with this toolchain using `rocstreaming/toolchain-
 
     $ cd /path/to/roc
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-aarch64-linux-gnu \
+        rocstreaming/toolchain-aarch64-linux-gnu:gcc-7.4 \
           scons \
             --host=aarch64-linux-gnu \
             --build-3rdparty=all
@@ -89,7 +89,7 @@ Here is how you can build Roc with this toolchain using `rocstreaming/toolchain-
 
     $ cd /path/to/roc
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-arm-linux-gnueabihf \
+        rocstreaming/toolchain-arm-linux-gnueabihf:gcc-4.9 \
           scons \
             --host=arm-linux-gnueabihf \
             --build-3rdparty=all
@@ -132,7 +132,7 @@ Here is how you can build Roc with this toolchain using `rocstreaming/toolchain-
 
     $ cd /path/to/roc
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi \
+        rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi:gcc-4.7 \
           scons \
             --host=arm-bcm2708hardfp-linux-gnueabi \
             --build-3rdparty=all
@@ -347,35 +347,35 @@ If PulseAudio support is enabled, install libltdl and libpulse:
 Running cross-compiled tests in QEMU
 ====================================
 
-Running a test on 32-bit ARMv6 CPU using `rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi <https://hub.docker.com/r/rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi/>`_ Docker image:
+Running a test on 64-bit ARMv8 CPU using `rocstreaming/toolchain-aarch64-linux-gnu <https://hub.docker.com/r/rocstreaming/toolchain-aarch64-linux-gnu/>`_ Docker image:
 
 .. code::
 
     $ cd /path/to/roc
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi \
-          env LD_LIBRARY_PATH="/opt/sysroot/lib:${PWD}/3rdparty/arm-bcm2708hardfp-linux-gnueabi/rpath" \
-            qemu-arm -L /opt/sysroot -cpu arm1176 \
-              ./bin/arm-bcm2708hardfp-linux-gnueabi/roc-test-core
+        rocstreaming/toolchain-aarch64-linux-gnu:gcc-7.4 \
+          env LD_LIBRARY_PATH="/opt/sysroot/lib:${PWD}/3rdparty/aarch64-linux-gnu/rpath" \
+            qemu-aarch64 -L /opt/sysroot -cpu cortex-a53 \
+              ./bin/aarch64-linux-gnu/roc-test-core
 
 Running a test on 32-bit ARMv7 CPU using `rocstreaming/toolchain-arm-linux-gnueabihf <https://hub.docker.com/r/rocstreaming/toolchain-arm-linux-gnueabihf/>`_ Docker image:
 
 .. code::
 
     $ cd /path/to/roc
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-arm-linux-gnueabihf \
+        rocstreaming/toolchain-arm-linux-gnueabihf:gcc-4.9 \
           env LD_LIBRARY_PATH="/opt/sysroot/lib:${PWD}/3rdparty/arm-linux-gnueabihf/rpath" \
             qemu-arm -L /opt/sysroot -cpu cortex-a15 \
               ./bin/arm-linux-gnueabihf/roc-test-core
 
-Running a test on 64-bit ARMv8 CPU using `rocstreaming/toolchain-aarch64-linux-gnu <https://hub.docker.com/r/rocstreaming/toolchain-aarch64-linux-gnu/>`_ Docker image:
+Running a test on 32-bit ARMv6 CPU using `rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi <https://hub.docker.com/r/rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi/>`_ Docker image:
 
 .. code::
 
     $ cd /path/to/roc
     $ docker run -t --rm -u "${UID}" -v "${PWD}:${PWD}" -w "${PWD}" \
-        rocstreaming/toolchain-aarch64-linux-gnu \
-          env LD_LIBRARY_PATH="/opt/sysroot/lib:${PWD}/3rdparty/aarch64-linux-gnu/rpath" \
-            qemu-aarch64 -L /opt/sysroot -cpu cortex-a53 \
-              ./bin/aarch64-linux-gnu/roc-test-core
+        rocstreaming/toolchain-arm-bcm2708hardfp-linux-gnueabi:gcc-4.7 \
+          env LD_LIBRARY_PATH="/opt/sysroot/lib:${PWD}/3rdparty/arm-bcm2708hardfp-linux-gnueabi/rpath" \
+            qemu-arm -L /opt/sysroot -cpu arm1176 \
+              ./bin/arm-bcm2708hardfp-linux-gnueabi/roc-test-core
diff --git a/docs/sphinx/portability/supported_platforms.rst b/docs/sphinx/portability/supported_platforms.rst
@@ -29,7 +29,7 @@ The following specific platform configurations are tested on a **regular basis**
 
 Linux distributions:
 
-* Ubuntu (22.04, 20.04, 18.04, 16.04, 14.04)
+* Ubuntu (24.04, 22.04, 20.04, 18.04, 16.04, 14.04)
 * Debian (stable)
 * Fedora (latest)
 * CentOS (latest)