sphinx: Minor updates

docs/sphinx/about_project/features.rst

@@ -8,7 +8,7 @@ High-level features
 
 * streaming CD-quality audio using RTP
 
-* maintaining pre-configured fixed latency
+* maintaining pre-configured fixed or bounded latency
 
 * restoring lost packets using Forward Erasure Correction codes
 
@@ -17,8 +17,8 @@ High-level features
 
 * resampling
 
-  * converting between the sender and receiver clock domains (on receiver)
-  * converting between the network and input/output sample rates (on receiver and sender)
+  * converting between the sender and receiver clock domains to compensate clock drift
+  * converting between the network and input/output sample rates
   * configurable resampler backends and profiles for different CPU and quality requirements
 
 * multiplexing
@@ -43,10 +43,12 @@ Protocols and encodings
 
 * RTP
 
-  * RTP AVP L16 encoding (lossless 44100Hz PCM 16-bit stereo)
+  * RTP AVPF L16 encoding (lossless 44100Hz PCM 16-bit stereo or mono)
 
 * RTCP
 
+* RTCP XR
+
 * FECFRAME
 
   * Reed-Solomon (m=8) FEC scheme (lower latency, lower rates)
@@ -62,23 +64,32 @@ API and tools
   * roc_sender --- send audio stream to receiver
   * roc_receiver --- receive and mix audio streams from senders
 
+* codec API
+
+  * roc_sender_encoder --- encode audio stream into packets
+  * roc_receiver_decoder --- decode audio stream from packets
+
 * command-line tools
 
   * roc-send --- read audio stream from audio device or file and send to receiver
   * roc-recv --- receive and mix audio streams from senders and write to audio device or file
   * roc-copy --- copy audio between local audio devices or files
 
+* PipeWire modules
+
+  * roc-sink --- send audio stream written to the sink to receiver
+  * roc-source --- receive and mix audio streams from senders and write to the connected apps
+
 * PulseAudio modules
 
   * module-roc-sink --- send audio stream written to the sink to receiver
   * module-roc-sink-input --- receive and mix audio streams from senders and write to the connected sink
 
-* PipeWire modules
+* macOS virtual device
 
-  * roc-sink --- send audio stream written to the sink to receiver
-  * roc-source --- receive and mix audio streams from senders and write to the connected apps
+  * roc-vad --- streaming audio device with CLI and gRPC interface
 
-* Mobile apps
+* mobile apps
 
   * Roc Droid -- Android app that connects your phone to other Roc senders and receivers
 
@@ -89,7 +100,7 @@ Bindings
 
 * supported languages:
 
-  * C and C++
+  * C (or C++)
   * Go
   * Java
 
@@ -108,6 +119,5 @@ Portability
 
   * x86_64
   * i686
-  * ARMv6
-  * ARMv7 (Cortex-A 32-bit)
-  * ARMv8 (Cortex-A 64-bit)
+  * ARM
+  * MIPS

docs/sphinx/about_project/licensing.rst

@@ -3,4 +3,6 @@ Licensing
 
 Roc Toolkit source code is licensed under `MPL-2.0 <https://www.mozilla.org/en-US/MPL/2.0/>`_.
 
-If Roc Toolkit is built with OpenFEC support enabled, it must be distributed under a license compatible with CeCCIL-C (LGPL-like license), if LDPC-Staircase codec is disabled, or CeCCIL (GPL-like license), if LDPC-Staircase codec is enabled. Refer to `OpenFEC website <http://openfec.org/patents.html>`_ for further details.
+You may also want to check licenses of the :doc:`dependencies </building/dependencies>`. If you can't use dependencies with strong copyleft licenses like GPL, you may need to disable them at build time.
+
+In particular, if Roc Toolkit is built with OpenFEC support enabled, it must be distributed under a license compatible with CeCCIL-C (LGPL-like license), if LDPC-Staircase codec is disabled, or CeCCIL (GPL-like license), if LDPC-Staircase codec is enabled. Refer to `OpenFEC website <http://openfec.org/patents.html>`_ for further details.

docs/sphinx/about_project/overview.rst

@@ -14,14 +14,18 @@ Basically, it is a network transport, highly specialized for the real-time strea
 
 The project is conceived as a swiss army knife for real-time streaming. It is designed to support a variety of network protocols, encodings, FEC schemes, and related features. Users can build custom configurations dedicated for specific use cases, while balancing quality, robustness, bandwidth, and compatibility.
 
-What problems does it solve?
-----------------------------
+What problems it aims to solve?
+-------------------------------
 
 .. seealso:: :doc:`/about_project/features`
 
+.. note::
+
+   Implementation of some of the below is still work in progress. See :doc:`/development/roadmap` for details.
+
 Real-time streaming needs a special approach. When we create software for it, we must address several problems.
 
-When the network is not reliable (e.g. Wi-Fi or Internet), we need to handle losses. We can't just use a reliable protocol like TCP, because the latency would suffer. We also can't just ignore losses, because the service quality would suffer.
+When the network is not reliable (e.g. Wi-Fi or Internet), we need to handle losses. We can't just mindlessly use a reliable protocol like TCP, because the latency would suffer. We also can't just ignore losses, because the service quality would suffer.
 
 When network conditions are not known beforehand, or are varying in time, we should adapt to changes dynamically. In response to changed conditions, we may need to adjust latency, compression level, redundancy level, and other parameters on fly.
 
@@ -33,20 +37,20 @@ The real-time requirement leads to a compromise between many factors like qualit
 
 Many applications that need real-time streaming often need similar related features. Encryption, QoS control, playback synchronization, to name a few. Such features are also in the scope of this project.
 
-What are project goals?
------------------------
+What are project priorities?
+----------------------------
 
-At the very high level, the project has the following goals:
+At the very high level, the main focus of the project is on these features:
 
-* *guaranteed latency* --- implement real-time streaming with guaranteed latency;
-* *high quality streaming* --- support CD- and DVD-quality audio streams;
-* *robust playback* --- provide good quality of service even on unreliable networks;
+* *guaranteed fixed or bounded latency* --- monitor and tune latency so that it always meets placed constraints;
+* *high quality streaming* --- support CD- and DVD-quality lossless audio streams and compression algorithms suitable for music;
+* *robust playback* --- provide good quality of service even on unreliable networks using lossless packet repair;
 * *high-level and easy to use interface* --- implement a simple and high-level API that hides all the complexity from user;
 * *work "from the box" with optional tuning* --- provide good defaults that work in many environments; and allow fine tuning to achieve best results for specific setup;
-* *adaptive algorithms* --- support adjusting to environment conditions on fly;
-* *comprehensive toolset* --- support multiple protocols and codecs, and give the user the full control of them;
+* *use of adaptive algorithms* --- support adjusting to changing environment conditions on fly;
+* *providing a comprehensive toolset* --- support multiple protocols and codecs, and let the user decide which to use;
 * *portability* --- support multiple operating systems and hardware architectures;
-* *interoperability* --- rely on open, standard protocols.
+* *interoperability* --- rely on open, standard protocols and support communication with compatible implementations.
 
 When do I need it?
 ------------------
@@ -64,7 +68,6 @@ Example applications:
 * concert or hall sound systems
 * online jamming (playing music together remotely)
 * streaming platforms for radio
-* cloud streaming
 
 How do I use it?
 ----------------

docs/sphinx/about_project/publications.rst

@@ -1,14 +1,16 @@
 Publications
 ************
 
-This page lists some known publications, ordered by the publication date, that might be useful in  addition to the documentation.
+This page lists some useful or interesting articles and blog posts, ordered by the publication date.
 
-* `"Updated tutorial for Roc 0.2" <https://gavv.net/articles/roc-tutorial-0.2/>`_ *by Victor Gaydov*
+* `Roc Toolkit 0.3 is out! <https://gavv.net/articles/roc-0.3/>`_
 
-* `"Roc Toolkit 0.2 released" <https://gavv.net/articles/roc-0.2/>`_ *by Victor Gaydov*
+* `Updated tutorial for Roc 0.2 <https://gavv.net/articles/roc-tutorial-0.2/>`_
 
-* `"A step-by-step tutorial for live audio streaming with Roc" <https://gavv.net/articles/roc-tutorial/>`_ *by Victor Gaydov*
+* `Roc Toolkit 0.2 released <https://gavv.net/articles/roc-0.2/>`_
 
-* `"Roc 0.1 released: real-time streaming over the network" <https://gavv.net/articles/roc-0.1/>`_ *by Victor Gaydov*
+* `A step-by-step tutorial for live audio streaming with Roc <https://gavv.net/articles/roc-tutorial/>`_
 
-* `"Working on a new network transport for PulseAudio and ALSA" <https://gavv.net/articles/new-network-transport/>`_ *by Victor Gaydov*
+* `Roc 0.1 released: real-time streaming over the network <https://gavv.net/articles/roc-0.1/>`_
+
+* `Working on a new network transport for PulseAudio and ALSA <https://gavv.net/articles/new-network-transport/>`_

docs/sphinx/building/dependencies.rst

@@ -25,16 +25,16 @@ Build dependencies
      - required, unless you disable building command-line tools
 
    * - pkg-config
-     - optional, used for better detection of system libraries
+     - optional, auto-detected, used for better discovery of system libraries
 
    * - config.guess
-     - | optional, used for better detection of system type
+     - | optional, auto-detected, used for better identification of system type
        | (may be provided by autotools, automake, or libtool)
 
    * - | libtool, intltool, autoconf, automake
        | make, cmake, meson, ninja
      - | optional, used to build dependencies automatically
-       | using ``--build-3rdparty`` option
+       | when ``--build-3rdparty`` option is given
 
 Vendored dependencies
 =====================
@@ -43,14 +43,17 @@ Vendored dependencies
 
    * - **dependency**
      - **version**
+     - **license**
      - **comment**
 
    * - `dr_wav <https://github.com/mackron/dr_libs/blob/master/dr_wav.h/>`_
      - 0.13.14
+     - MIT-0
      - single-header library
 
    * - `hedley <https://nemequ.github.io/hedley/>`_
      - 15
+     - CC0
      - single-header library
 
 Runtime dependencies
@@ -60,42 +63,52 @@ Runtime dependencies
 
    * - **dependency**
      - **version**
+     - **license**
      - **comment**
 
    * - `libatomic_ops <https://github.com/ivmai/libatomic_ops/>`_
      - >= 7.6.0
+     - MIT
      - only required on pre-C11 compilers
 
    * - `libunwind <https://www.nongnu.org/libunwind/>`_
      - >= 1.2.1
+     - X11
      - optional, used to print backtraces
 
    * - `libuv <https://libuv.org>`_
      - >= 1.5.0 (recommended >= 1.35.0)
+     - MIT
      - required
 
    * - `OpenFEC <http://openfec.org>`_
      - >= 1.4.2 (recommended to use `our fork <https://github.com/roc-streaming/openfec>`_)
+     - CeCCIL-C / CeCCIL
      - optional, used for FECFRAME support
 
    * - `OpenSSL <https://www.openssl.org/>`_
      - >= 1.1.1
+     - Apache
      - optional, used for SRTP and DTLS support and CSPRNG
 
    * - `PulseAudio <https://www.freedesktop.org/wiki/Software/PulseAudio/>`_
      - >= 5.0
+     - LGPL
      - optional, used for PulseAudio I/O
 
    * - `SoX <https://sox.sourceforge.net>`_
      - >= 14.4.0
+     - LGPL
      - optional, used for audio I/O
 
    * - `libsndfile <https://libsndfile.github.io/libsndfile/>`_
      - >= 1.0.26
+     - LGPL
      - optional, used for audio I/O
 
    * - `SpeexDSP <https://github.com/xiph/speexdsp>`_
      - >= 1.2beta3
+     - BSD
      - optional, used for fast resampling
 
 .. note::

docs/sphinx/building/user_cookbook.rst

@@ -60,8 +60,8 @@ Ubuntu / Debian
 .. code::
 
     # for Roc
-    $ sudo apt-get install g++ pkg-config scons ragel gengetopt \
-        libuv1-dev libunwind-dev libspeexdsp-dev libsox-dev libssl-dev libpulse-dev
+    $ sudo apt-get install g++ pkg-config scons ragel gengetopt libuv1-dev libunwind-dev \
+        libspeexdsp-dev libsox-dev libsndfile1-dev libssl-dev libpulse-dev
 
     # for 3rd-parties
     $ sudo apt-get install libtool intltool autoconf automake make cmake meson
@@ -82,8 +82,8 @@ Fedora
 .. code::
 
     # for Roc
-    $ sudo dnf install gcc-c++ pkgconfig scons ragel gengetopt \
-        libuv-devel libunwind-devel speexdsp-devel sox-devel openssl-devel pulseaudio-libs-devel
+    $ sudo dnf install gcc-c++ pkgconfig scons ragel gengetopt libuv-devel libunwind-devel \
+        speexdsp-devel sox-devel libsndfile-devel openssl-devel pulseaudio-libs-devel
 
     # for 3rd-parties
     $ sudo dnf install libtool intltool autoconf automake make cmake
@@ -104,8 +104,8 @@ openSUSE
 .. code::
 
     # for Roc
-    $ sudo zypper install gcc-c++ scons ragel gengetopt \
-        libuv-devel libunwind-devel speexdsp-devel sox-devel libopenssl-3-devel libpulse-devel
+    $ sudo zypper install gcc-c++ scons ragel gengetopt libuv-devel libunwind-devel \
+        speexdsp-devel sox-devel libsndfile-devel libopenssl-3-devel libpulse-devel
 
     # for 3rd-parties
     $ sudo zypper install pkg-config intltool libtool autoconf automake make cmake
@@ -129,8 +129,8 @@ Centos
     $ sudo yum install epel-release
 
     # for Roc
-    $ sudo yum install gcc-c++ pkgconfig scons ragel gengetopt \
-        libunwind-devel speex-devel sox-devel openssl11-devel pulseaudio-libs-devel
+    $ sudo yum install gcc-c++ pkgconfig scons ragel gengetopt libunwind-devel \
+        speex-devel sox-devel libsndfile-devel openssl11-devel pulseaudio-libs-devel
 
     # for 3rd-parties
     $ sudo yum install libtool intltool autoconf automake make cmake
@@ -151,8 +151,8 @@ Arch Linux
 .. code::
 
     # for Roc
-    $ sudo pacman -S gcc pkgconf scons ragel gengetopt \
-        libuv libunwind speexdsp sox openssl gsm libpulse
+    $ sudo pacman -S gcc pkgconf scons ragel gengetopt libuv libunwind \
+        speexdsp sox libsndfile openssl gsm libpulse
 
     # for 3rd-parties
     $ sudo pacman -S grep gawk libtool intltool autoconf automake make cmake
@@ -173,8 +173,8 @@ Alpine Linux
 .. code::
 
     # for Roc
-    $ sudo apk add g++ pkgconf scons ragel gengetopt \
-        libuv-dev libunwind-dev speexdsp-dev sox-dev openssl-dev pulseaudio-dev
+    $ sudo apk add g++ pkgconf scons ragel gengetopt libuv-dev libunwind-dev \
+        speexdsp-dev sox-dev libsndfile-dev openssl-dev pulseaudio-dev
 
     # for 3rd-parties
     $ sudo apk add libtool autoconf automake make cmake
@@ -195,8 +195,9 @@ NixOS
 .. code::
 
     # for Roc and 3rd-parties
-    $ nix-shell -p gcc autoconf automake cmake gengetopt gnumake intltool libpulseaudio \
-        libtool libunwind libuv meson pkg-config ragel scons sox openssl speexdsp
+    $ nix-shell -p gcc autoconf automake cmake gengetopt gnumake intltool libtool meson \
+        pkg-config scons ragel \
+        libuv libunwind speexdsp sox libsndfile openssl libpulseaudio
 
     # clone repo
     $ git clone https://github.com/roc-streaming/roc-toolkit.git
@@ -371,7 +372,7 @@ Then you can run the following commands:
 .. code::
 
     # for Roc
-    $ brew install pkg-config scons ragel gengetopt libuv speexdsp sox openssl@3
+    $ brew install pkg-config scons ragel gengetopt libuv speexdsp sox libsndfile openssl@3
 
     # for 3rd-parties
     $ brew install libtool autoconf automake make cmake

docs/sphinx/internals/audio_backends.rst

@@ -76,6 +76,8 @@ The following table lists implemented audio backends:
 ==================== =========== ===============
 backend              drivers     description
 ==================== =========== ===============
-SoxBackend           many        universal backend that supports many audio systems and file formats using libsox
 PulseaudioBackend    ``pulse``   native PulseAudio backend using libpulse
+SndfileBackend       many        read and write various audio files using libsndfile
+WavBackend           ``wav``     read and write audio files without external dependencies
+SoxBackend           many        universal backend that supports many audio systems and file formats using libsox
 ==================== =========== ===============

docs/sphinx/internals/network_protocols.rst

@@ -1,13 +1,15 @@
 Network protocols
 *****************
 
-Roc needs several network protocols to deliver data between the sender and the receiver.
+Roc uses several network protocols for exchanging data between sender and receiver.
 
-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.
+Roc avoids inventing new protocols and relies on existing open standards, to take advantage of their careful design and potential interoperability with other software. Roc implements from scratch most protocols (but not codecs). Sometimes there is just no suitable and reusable open implementation. Often the protocol logic must be tightly integrated into the pipeline and it would be hard to employ a stand-alone implementation.
 
-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.
+Although Roc is designed to support arbitrary protocols, and most of the code is generic, 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.
 
-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
+As a basis, Roc uses RTP Audio/Video Profile (AVPF) which specifies how to stream audio and video using RTP.
+
+It also employs FEC Framework (FECFRAME), which specifies how to incorporate various FEC schemes into RTP. Using FECFRAME may prevent interoperability with third-party RTP implementations that don't support it. If you need compatibility with such applications, you can disable FEC.
 
 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).