diff --git a/docs/sphinx/building/user_cookbook.rst b/docs/sphinx/building/user_cookbook.rst index 1cc859b2e..34aec8ea7 100644 --- 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 index 2303f272d..48f2fca43 100644 --- 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 `_) -- |: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 index b37b812be..57a151bd0 100644 --- a/docs/sphinx/internals/audio_backends.rst +++ b/docs/sphinx/internals/audio_backends.rst @@ -16,13 +16,13 @@ syntax meaning example ``://`` audio device name ``alsa://hw:0`` ``://default`` default audio device ``pulse://default`` ``file://`` audio file (absolute path) ``file:///home/user/test.wav`` -``file://`` audio file (relative path) ``file:./test.wav`` +``file:`` 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 ` for more details. diff --git a/docs/sphinx/internals/network_protocols.rst b/docs/sphinx/internals/network_protocols.rst index 253a524d3..5ca59a3a0 100644 --- 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 `_ RTP Real-time Transport Protocol -`RFC 3551 `_ RTP A/V Profile Audio and video profile for RTP -`RFC 6363 `_ FEC Framework A framework for adding various FEC schemes to RTP -`RFC 6865 `_ Simple Reed-Solomon FEC Scheme FEC scheme for FECFRAME -`RFC 6816 `_ Simple LDPC-Staircase FEC Scheme FEC scheme for FECFRAME -================================================= ================================ ============ +.. list-table:: + :widths: 10 60 30 + :header-rows: 1 + + * - **RFC** + - **Name** + - **Comment** + + * - `RFC 3550 `_ + - `RTP: A Transport Protocol for Real-Time Applications` + - Basic RTP and RTCP + + * - `RFC 3551 `_ + - `RTP Profile for Audio and Video Conferences with Minimal Control` + - RTP AVPF (Audio/Video Profile) + + * - `RFC 3611 `_ + - `RTP Control Protocol Extended Reports` + - | RTCP XR + | (supported blocks: DLRR, RRTR) + + * - `RFC 6776 `_ + - `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 `_ + - `RTP Control Protocol (RTCP) Extended Report (XR) Block for Delay Metric Reporting` + - RTCP XR Delay Metrics Block + + * - `RFC 6363 `_ + - `Forward Error Correction (FEC) Framework` + - FECFRAME + + * - `RFC 6865 `_ + - `Simple Reed-Solomon Forward Error Correction (FEC) Scheme for FECFRAME` + - Reed-Solomon FEC Scheme + + * - `RFC 6816 `_ + - `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 index 5bf0e9821..16f781ae6 100644 --- a/docs/sphinx/internals/timestamps.rst +++ b/docs/sphinx/internals/timestamps.rst @@ -8,10 +8,11 @@ Timestamps Types of timestamps =================== -:doc:`Packets and frames ` have two major types of timestamps: +:doc:`Packets and 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 index 17d9d0d48..5275f1bde 100644 --- 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,16 +347,16 @@ 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 `_ Docker image: +Running a test on 64-bit ARMv8 CPU using `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 `_ Docker image: @@ -364,18 +364,18 @@ Running a test on 32-bit ARMv7 CPU using `rocstreaming/toolchain-arm-linux-gnuea $ 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 `_ Docker image: +Running a test on 32-bit ARMv6 CPU using `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 index 1ae0b4d20..6ea6bd724 100644 --- 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)