Update sphinx docs

docs/man/_static/twemoji.css

@@ -0,0 +1,6 @@
+img.emoji {
+    height: 1em;
+    width: 1em;
+    margin: 0 .05em 0 .1em;
+    vertical-align: -0.1em;
+}

docs/man/_static/twemoji.js

@@ -0,0 +1,10 @@
+function addEvent(element, eventName, fn) {
+    if (element.addEventListener)
+        element.addEventListener(eventName, fn, false);
+    else if (element.attachEvent)
+        element.attachEvent('on' + eventName, fn);
+}
+
+addEvent(window, 'load', function() {
+    twemoji.parse(document.body, {'folder': 'svg', 'ext': '.svg'});
+});

docs/sphinx/conf.py

@@ -21,6 +21,7 @@ def get_version():
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
+    'sphinxemoji.sphinxemoji',
     'breathe',
 ]
 

docs/sphinx/development/coding_guidelines.rst

@@ -13,7 +13,8 @@ The usage of C++ in this project is quite specific. The codebase is primarily wr
 * No C++ features beyond C++98
 * No exceptions
 * No STL (the algorithms-and-containers part of the standard library)
-* Custom "core" library (roc_core)
+* No general-purpose utility libraries like Boost
+* Lightweight "core" library (roc_core) instead of STL
 * Templates are mostly avoided (except utility classes in core)
 * Inheritance is primarily used only for "interface inheritance"
 * Overloading, operators, default arguments are avoided
@@ -24,10 +25,10 @@ The roc_core library makes several essential design choices that differ signific
 * heavy operations, like deep copying or allocations, are never implicit
 * most operations include safety checks and will trigger a panic with stacktrace on incorrect usage
 * most containers are based on intrusive data structures
-* encourages fine-grained memory management based on arenas and pools
-* provides building blocks for lock-free programming
+* fine-grained memory management based on arenas and pools
+* building blocks for lock-free programming
 
-These design choices render Roc codebase pretty unique and distinguish it from both plain C and modern C++.
+These design choices render Roc codebase pretty different from both plain C and modern C++ code.
 
 This approach may not be suitable for every project, but it appears to have been effective in the case of Roc due to its low-level, real-time nature, and at the same time the considerable size of its codebase.
 

docs/sphinx/development/contribution_guidelines.rst

@@ -17,15 +17,15 @@ How you can help
 
 * **Contributing code**
 
-  We are always looking for new contributors. Please refer to the section below for details on the onboarding process.
+  We are always happy to meet new people in the project. Please refer to the section below for details on the onboarding process.
 
 * **Testing**
 
-  We'd appreciate help in testing new releases on your hardware and letting us know if you find any issues. We highly depend on feedback from users to identify bugs and receive suggestions for new features.
+  We also appreciate help in testing new releases. We highly depend on feedback from users to identify bugs and receive suggestions for new features.
 
 * **Writing tutorials**
 
-  If you've built Roc for a niche OS or hardware, or tweaked settings to make it work better for your needs, we'd love it if you share your experience with the community. If you've written a guide, you can send it to us to be added to the :doc:`publications page </about_project/publications>`.
+  If you've built Roc for a niche OS or hardware, or tweaked settings to make it work better for your needs, we'd love if you share your experience with the community. If you wrote a guide, you can send it to us to be added to the :doc:`publications page </about_project/publications>`.
 
 Becoming a contributor
 ======================
@@ -57,7 +57,7 @@ The guide bellow will help you to prepare your first patch.
 
   Some of these tasks are also labeled as `"easy hacks" <https://github.com/roc-streaming/roc-toolkit/labels/easy%20hacks>`_. It indicates that the solution is expected to be pretty straightforward, making them a good entry point to the project.
 
-  Extra labels make it easier to find various kinds of problems, like "tests," "refactoring," "algorithms," "networking," and more.
+  Extra labels make it easier to find various kinds of problems, like "tests," "refactoring," "algorithms," "networking," and so on.
 
   When you pick a task, please leave a comment to let others know so that we don't end up with multiple people doing the same thing. If a task hasn't been assigned, it usually means no one is currently working on it.
 

docs/sphinx/development/roadmap.rst

@@ -4,75 +4,119 @@ Roadmap
 Basic features
 ==============
 
-- ☑ Real-time streaming with guaranteed latency
-- ☑ Session multiplexing
-- ☑ Dynamic sample rate adjustment
-- ☑ Static sample rate conversion
-- ☑ Packet interleaving
-- ☑ Stream breakage detection
-- ☑ Multiple slots on sender and receiver
-- ☑ RTP support
-- ☑ FECFRAME support (Reed-Solomon and LDPC-Staircase FEC codes based on `OpenFEC <http://openfec.org/>`_)
-- ☐ RTCP support for receiver feedback
-- ☐ RTCP XR support (extended reports)
-- ☐ Session negotiation using RTSP
-- ☐ Configurable network encodings
-- ☐ Opus support
-- ☐ Service discovery
+- |: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:| Packet loss recovery using FEC
+- |:ballot_box_with_check:| Session multiplexing
+- |:ballot_box_with_check:| Stream breakage detection
+- |:ballot_box_with_check:| Multiple slots on sender and receiver
+- |:white_large_square:| Configurable network encoding
+- |:ballot_box_with_check:| Automatic channel and rate conversions
+- |:white_large_square:| Automatic encoding conversions
+- |:white_large_square:| IDLE state reporting
 
 Advanced features
 =================
 
-- ☐ Dynamic latency adjustment (requires RTCP)
-- ☐ Dynamic adjustment of FEC block size (requires RTCP)
-- ☐ Dynamic adjustment of FEC code rate (requires RTCP and XRs from `RFC 5725 <https://tools.ietf.org/html/rfc5725>`_)
-- ☐ Dynamic audio bitrate adjustment
-- ☐ Dynamic payload type switch
-- ☐ QoS support
-- ☐ Encryption (SRTP and DTLS)
-- ☐ Packet loss concealment
-- ☐ Lip sync support
-- ☑ Multicast support
-- ☐ Multi-room support (playback synchronization)
-- ☐ Surround sound
-- ☐ Congestion control
-- ☐ Retransmission (probably `RFC 4588 <https://tools.ietf.org/html/rfc4588>`_ and `RFC 4585 <https://tools.ietf.org/html/rfc4585>`_)
-- ☐ More FEC codes (notably `RaptorQ <https://tools.ietf.org/html/rfc6330>`_, see `OpenRQ <https://github.com/openrq-team/OpenRQ>`_ and `orq <https://github.com/olanmatt/orq>`_)
-- ☐ More audio encodings (lossless and lossy)
-- ☐ Video support (requires some research)
-- ☐ Hardware acceleration (maybe OpenMAX)
+- |:white_large_square:| End-to-end latency estimation
+- |:white_large_square:| Dynamic latency adjustment (requires RTCP)
+- |:white_large_square:| Dynamic adjustment of FEC block size (requires RTCP)
+- |:white_large_square:| Dynamic adjustment of FEC code rate (requires RTCP and XRs from `RFC 5725 <https://tools.ietf.org/html/rfc5725>`_)
+- |:white_large_square:| Dynamic audio bitrate adjustment
+- |:white_large_square:| Dynamic payload type switch
+- |:white_large_square:| Encryption support (SRTP and DTLS)
+- |:white_large_square:| QoS support
+- |:white_large_square:| Packet loss concealment (PLC)
+- |:white_large_square:| Lip sync support
+- |:ballot_box_with_check:| Multicast support
+- |:white_large_square:| Multi-room support (synchronized playback)
+- |:white_large_square:| Surround sound
+- |:white_large_square:| Congestion control
+- |:white_large_square:| Retransmission (probably `RFC 4588 <https://tools.ietf.org/html/rfc4588>`_ and `RFC 4585 <https://tools.ietf.org/html/rfc4585>`_)
+- |:white_large_square:| Video support
+- |:white_large_square:| Hardware acceleration (maybe OpenMAX)
+
+Extensibility
+=============
+
+- |:ballot_box_with_check:| Provide custom logger
+- |:white_large_square:| Provide custom allocator
+- |:ballot_box_with_check:| Register custom payload types
+- |:white_large_square:| Register custom codecs
+
+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
+- |:white_large_square:| SRTP
+- |:white_large_square:| DTLS
+
+Codecs
+======
+
+- |:ballot_box_with_check:| PCM
+- |:white_large_square:| Opus
+- |:white_large_square:| Vorbis
+- |:ballot_box_with_check:| Reed-Solomon FEC
+- |:ballot_box_with_check:| LDPC-Staircase FEC
+- |:white_large_square:| RaptorQ FEC
+
+Audio backends
+==============
+
+- |:ballot_box_with_check:| PulseAudio
+- |:white_large_square:| PipeWire
+- |:white_large_square:| ALSA
+- |:white_large_square:| JACK
+- |:white_large_square:| CoreAudio (macOS and iOS)
+- |:white_large_square:| Oboe (Android)
+- |:white_large_square:| WASAPI (Windows)
+- |:ballot_box_with_check:| SoX (universal)
+- |:white_large_square:| FFmpeg
 
 API
 ===
 
-- ☑ Transport API (network sender and receiver)
-- ☐ Audio API (recorder and player)
-- ☐ Control API
-- ☐ Discovery API (publisher and explorer)
-- ☐ Packet API (packet encoder and decoder)
+- |:ballot_box_with_check:| Single-stream transport API (roc_sender / roc_receiver)
+- |:white_large_square:| Multi-stream transport API (roc_transceiver)
+- |:ballot_box_with_check:| Codec API (roc_sender_encoder / roc_receiver_decoder)
+- |:white_large_square:| Relay API (roc_relay)
+- |:white_large_square:| Discovery API (roc_publisher / roc_explorer)
 
 Tools
 =====
 
-- ☑ Sender
-- ☑ Receiver
-- ☐ Relay
+- |:ballot_box_with_check:| Sender (roc-send)
+- |:ballot_box_with_check:| Receiver (roc-recv)
+- |:white_large_square:| Relay (roc-relay)
+- |:white_large_square:| Daemon (rocd)
 
 Integrations
 ============
 
-- ☑ Roc-based transport for PulseAudio
-- ☑ Roc-based transport for PipeWire
-- ☐ Virtual audio device for macOS
-- ☐ Virtual audio device for Windows
-- ☑ Library bindings for other languages
+- |:ballot_box_with_check:| Roc-based transport for PulseAudio (roc-pulse)
+- |:ballot_box_with_check:| Roc-based transport for PipeWire (roc-source, roc-sink)
+- |:white_large_square:| Virtual audio device for macOS (roc-vad)
+- |:white_large_square:| Virtual audio device for Windows
+
+Bindings
+========
+
+- |:ballot_box_with_check:| Go (roc-go)
+- |:ballot_box_with_check:| Java (roc-java)
 
 Portability
 ===========
 
-- ☑ Linux, including Raspberry Pi and clones
-- ☑ Other \*nix systems
-- ☑ macOS
-- ☑ Android
-- ☐ iOS
-- ☐ Windows
+- |:ballot_box_with_check:| Linux
+- |:ballot_box_with_check:| Other \*nix systems
+- |:ballot_box_with_check:| macOS
+- |:ballot_box_with_check:| Android
+- |:white_large_square:| iOS
+- |:white_large_square:| Windows
+- |:white_large_square:| Zephyr