Skip to content

Commit

Permalink
Merge remote-tracking branch 'upstream/develop' into develop
Browse files Browse the repository at this point in the history
  • Loading branch information
@runei
runei committed Jul 17, 2024
2 parents 1865eea + dcc3e88 commit 3f0ecff
Show file tree
Hide file tree
Showing 161 changed files with 9,863 additions and 2,399 deletions.
3 changes: 3 additions & 0 deletions SConstruct
View file
Original file line number Diff line number Diff line change
Expand Up @@ -910,6 +910,9 @@ if meta.compiler in ['gcc', 'clang']:
env.Append(CXXFLAGS=[
'-std=c++98',
])
env.Append(CFLAGS=[
'-std=c99',
])

env.Append(CXXFLAGS=[
'-fno-exceptions',
Expand Down
8 changes: 4 additions & 4 deletions docs/man/roc-recv.1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,15 +117,15 @@ Resampler backend (possible values=\(dqdefault\(dq, \(dqbuiltin\(dq, \(dqspeex\
.BI \-\-resampler\-profile\fB= ENUM
Resampler profile (possible values=\(dqlow\(dq, \(dqmedium\(dq, \(dqhigh\(dq default=\(gamedium\(aq)
.TP
.BI \-\-plc\fB= ENUM
Which PLC algorithm to use (possible values=\(dqnone\(dq, \(dqbeep\(dq default=\(ganone\(aq)
.TP
.B \-1\fP,\fB \-\-oneshot
Exit when last connected client disconnects (default=off)
.TP
.B \-\-profiling
Enable self\-profiling (default=off)
.TP
.B \-\-beep
Enable beeping on packet loss (default=off)
.TP
.BI \-\-color\fB= ENUM
Set colored logging mode for stderr output (possible values=\(dqauto\(dq, \(dqalways\(dq, \(dqnever\(dq default=\(gaauto\(aq)
.UNINDENT
Expand Down Expand Up @@ -155,7 +155,7 @@ The list of supported protocols can be retrieved using \fB\-\-list\-supported\fP
.sp
The host field should be either FQDN (domain name), or IPv4 address, or IPv6 address in square brackets. It may be \fB0.0.0.0\fP (for IPv4) or \fB[::]\fP (for IPv6) to bind endpoint to all network interfaces.
.sp
The port field can be omitted if the protocol defines standard port. Otherwise, it is mandatory. It may be set to zero to bind endpoint to a radomly chosen ephemeral port.
The port field can be omitted if the protocol defines standard port. Otherwise, it is mandatory. It may be set to zero to bind endpoint to a randomly chosen ephemeral port.
.sp
The path and query fields are allowed only for protocols that support them, e.g. for RTSP.
.sp
Expand Down
4 changes: 4 additions & 0 deletions docs/sphinx/_static/sphinx_extras.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,7 @@ table.align-center {
width: 180px;
height: 90px;
}

.api-examples li a {
background-color: #d0dcdf36;
}
141 changes: 108 additions & 33 deletions docs/sphinx/api/examples.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,57 +5,132 @@ Examples
:local:
:depth: 2

Basic sender and receiver
-------------------------
How to run
----------

* `basic_sender_sine_wave.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/basic_sender_sine_wave.c>`_
Every linked example is a complete self-sufficient program, which you can build in one command (exact command is provided in the header comment of each example). It typically looks like this:

Basic sender example.
.. code::
This example creates a sender and connects it to remote receiver.
Then it generates a 10-second beep and writes it to the sender.
cc -o basic_sender_sine_wave basic_sender_sine_wave.c -lroc -lm
* `basic_sender_from_pulseaudio.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/basic_sender_from_pulseaudio.c>`_
Then you can run example like this:

Basic sender example.
.. code::
This example creates a sender and connects it to remote receiver.
Then it records audio stream from PulseAudio and writes it to the sender.
./basic_sender_sine_wave
* `basic_receiver_to_pulseaudio.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/basic_receiver_to_pulseaudio.c>`_
Alternatively, you can follow instructions from :doc:`/building/user_cookbook` to build the project, but add ``--enable-examples`` flag to scons invocation. All examples are then built automatically and put to the output binary directory.

Basic receiver example.
Basic senders and receivers
---------------------------

This example creates a receiver and binds it to a known address.
Then it reads audio stream from the receiver and plays it using PulseAudio.
.. note::

Network protocols
-----------------
Examples in this group use the same set of hard-coded IP (localhost) and ports. If you peek any pair of ``basic_sender_xxx`` and ``basic_receiver_xxx`` examples and run them in two terminals, you should see in logs that the sender has connected to the receiver.

.. cssclass:: api_examples

* **Sender (beep)** (`basic_sender_sine_wave.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/basic_sender_sine_wave.c>`_)

Minimal sender:
- creates a sender and connects it to remote address
- generates a 10-second beep and writes it to the sender

* **Sender (PulseAudio)** (`basic_sender_pulseaudio.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/basic_sender_pulseaudio.c>`_)

Another minimal sender:
- creates a sender and connects it to remote address
- captures audio stream from PulseAudio source and writes it to the sender

* **Receiver (WAV file)** (`basic_receiver_wav_file.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/basic_receiver_wav_file.c>`_)

Minimal receiver:
- creates a receiver and binds it to a local address
- reads audio stream from the receiver and writes it to a WAV file

* **Receiver (PulseAudio)** (`basic_receiver_pulseaudio.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/basic_receiver_pulseaudio.c>`_)

Another minimal receiver:
- creates a receiver and binds it to a local address
- reads audio stream from the receiver and plays to PulseAudio sink

Advanced network configuration
------------------------------

.. note::

Every example in this group contains both sender and receiver (or a few of them), running on different threads. So you can peek any of the ``send_recv_xxx`` examples and run it standalone.

.. cssclass:: api_examples

* `send_receive_rtp.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/send_receive_rtp.c>`_
* **Bare RTP** (`send_recv_rtp.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/send_recv_rtp.c>`_)

Send and receive samples using bare RTP.
Sending and receiving using bare RTP without extensions:
- creates a receiver and binds it to a single RTP endpoint
- creates a sender and connects it to the receiver endpoint
- one thread writes audio stream to the sender
- another thread reads audio stream from receiver

This example creates a receiver and binds it to an RTP endpoint.
Then it creates a sender and connects it to the receiver endpoint.
Then it starts writing audio stream to the sender and reading it from receiver.
* **RTP + FECFRAME + RTCP** (`send_recv_rtp_rtcp_fec.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/send_recv_rtp_rtcp_fec.c>`_)

* `send_receive_rtp_with_fecframe.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/send_receive_rtp_with_fecframe.c>`_
Sending a receiving using RTP + FECFRAME + RTCP.

This example is like the previous one, but it uses three endpoints (on both sender and receiver):
- source endpoint is used to transmit audio stream (via RTP)
- repair endpoint is used to transmit redundant stream for loss recovery (via FECFRAME)
- control endpoint is used to transmit bidirectional control traffic (via RTCP)

* **Multicast IP** (`send_recv_multicast.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/send_recv_multicast.c>`_)

This example shows how to send stream to multiple receivers using IP multicast:
- creates two receivers and binds them to multicast endpoints
- creates a sender and connects it to the multicast endpoints
- one thread writes audio stream to the sender
- another two threads read audio stream from receivers

* **One sender + two unicast receivers** (`send_recv_1_sender_2_receivers.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/send_recv_1_sender_2_receivers.c>`_)

This example shows how to use slots mechanism to connect sender to two different receivers using unicast addresses:
- creates two receivers and binds each one to its own unicast address
- creates a sender
- connects slot 1 of the sender to the first receiver
- connects slot 2 of the sender to the second receiver
- one thread writes audio stream to the sender
- another two threads read audio stream from receivers

* **Two senders + one receiver with two unicast addresses** (`send_recv_2_senders_1_receiver.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/send_recv_2_senders_1_receiver.c>`_)

This example shows how to use slots mechanism to bind receiver to two different addresses (for example on different network interfaces or using different network protocols), and then connect two senders to those address.
- creates a receiver
- binds slot 1 of the receiver to the first address, using bare RTP
- binds slot 2 of the receiver to the second address, using RTP + FECFRAME + RTCP
- creates two senders and connects each one to its own address of the receiver
- two threads writes audio stream to the senders
- another thread reads mixed audio stream from receiver

Custom plugins
--------------

.. cssclass:: api_examples

* **Packet loss concealment (PLC)** (`plugin_plc.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/plugin_plc.c>`_)

Packet loss concealment is used to reduce distortion caused by packet losses that can't be repaired by FEC, by filling gaps with interpolated data. This example shows how you can implement and register custom PLC implementation with your own interpolation algorithm.

Utility functions
-----------------

Send and receive samples using RTP and FECFRAME.
.. cssclass:: api_examples

This example is like `send_receive_rtp.c`, but it creates two endpoints:
- the first, source endpoint is used to transmit audio stream
- the second, repair endpoint is used to transmit redundant stream
* **Endpoint URIs** (`uri_manipulation.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/uri_manipulation.c>`_)

The redundant stream is used on receiver to recover lost audio packets.
This is useful on unreliable networks.
Demonstrates how to build endpoint URI and access its individual parts.

Miscellaneous
-------------
* **Logger settings** (`misc_logging.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/misc_logging.c>`_)

* `uri_manipulation.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/uri_manipulation.c>`_
Demonstrates how to configure log level and log handler.

URI manipulation example.
* **Version checks** (`misc_version.c <https://github.com/roc-streaming/roc-toolkit/blob/master/src/public_api/examples/misc_version.c>`_)

This example demonstrates how to build endpoint URI and access its individual parts.
Demonstrates how to check library version at compile-time and run-time.
22 changes: 22 additions & 0 deletions docs/sphinx/api/reference.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ roc_context

.. doxygenfunction:: roc_context_register_encoding

.. doxygenfunction:: roc_context_register_plc

.. doxygenfunction:: roc_context_close

roc_sender
Expand Down Expand Up @@ -209,6 +211,8 @@ roc_config

.. doxygenenum:: roc_resampler_profile

.. doxygenenum:: roc_plc_backend

.. doxygenstruct:: roc_context_config
:members:

Expand All @@ -234,6 +238,24 @@ roc_metrics
.. doxygenstruct:: roc_receiver_metrics
:members:

roc_plugin
==========

.. code-block:: c
#include <roc/plugin.h>
.. doxygenenumvalue:: ROC_ENCODING_ID_MIN

.. doxygenenumvalue:: ROC_ENCODING_ID_MAX

.. doxygenenumvalue:: ROC_PLUGIN_ID_MIN

.. doxygenenumvalue:: ROC_PLUGIN_ID_MAX

.. doxygenstruct:: roc_plugin_plc
:members:

roc_log
=======

Expand Down
72 changes: 17 additions & 55 deletions docs/sphinx/development/coding_guidelines.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,7 @@ Portability

* The code should run on a variety of operating systems, compilers, and hardware architectures, including rather old compilers and distributions. See :doc:`supported platforms </portability/supported_platforms>` page.

.. raw:: html

<span></span>
\

* The code specific to platform, compiler, or optional features and dependencies, should be isolated inside corresponding :ref:`target directories <targets>`. All other code should be portable across all supported configurations.

Expand All @@ -48,57 +46,39 @@ Best practices

* The code should compile without warnings. Use ``--enable-werror`` :doc:`option </building/scons_options>` to turn warnings into errors.

.. raw:: html

<span></span>
\

* Cover every component with class-level unit tests if possible. Additionally, cover high-level features with pipeline-level integration tests. We use `CppUTest <https://cpputest.github.io/>`_.

.. raw:: html

<span></span>
\

* Prefer RAII and smart pointers for resource management.

.. raw:: html

<span></span>
\

* Prefer either non-copyable or trivial-copy objects. Avoid making "heavy" operations implicit, in particular, operations involving memory management.

.. raw:: html

<span></span>
\

* Use ``const`` when it's useful.

.. raw:: html

<span></span>
\

* Use anonymous namespaces instead of static globals, functions, and constants.

.. raw:: html

<span></span>
\

* Use enums instead of defines, when possible.

.. raw:: html

<span></span>
\

* Use arenas and pools for memory management.

.. raw:: html

<span></span>
\

* Carefully log (using ``roc_log``) all important events and information needed to understand why an error occurred.

.. raw:: html

<span></span>
\

* Panic (using ``roc_panic``) when a contract or an invariant is broken. A panic is always preferred over a crash or undefined behavior. However, remember that panics are only for bugs in Roc itself. Never panic on invalid or unexpected data from the outside world.

Expand All @@ -107,33 +87,23 @@ Coding style

* The code should be formatted using ``scons fmt``, which invokes ``clang-format``. If it goes awry, you can prevent a file from being formatted by adding it to ``.fmtignore``.

.. raw:: html

<span></span>
\

* Header and source files should contain the "Roc Streaming authors" copyright and license header. Running ``scons fmt`` will automatically insert them.

.. raw:: html

<span></span>
\

* Headers, classes, public members, and free functions should be documented using Doxygen. Use ``--enable-doxygen`` :doc:`option </building/scons_options>` to enable warnings about undocumented elements.

.. raw:: html

<span></span>
\

* Prefer creating individual .h and .cpp files for every class. Use snake_case for file names and old-style header guards, which are automatically inserted by ``scons fmt``.

.. raw:: html

<span></span>
\

* Use upper case SNAKE_CASE for macros, CamelCase for class names, and lower case snake_case for methods, functions, fields, and variables. Add trailing underscore\_ for private methods and fields.

.. raw:: html

<span></span>
\

* Members in class should have the following order:

Expand All @@ -150,9 +120,7 @@ Coding style
* methods
* fields

.. raw:: html

<span></span>
\

* The code should be formatted according to our 1TBS-like indentation style defined in ``.clang-format`` config:

Expand All @@ -161,12 +129,6 @@ Coding style
* use braces even for single-statement blocks;
* don't place condition or loop bodies at the same line as the control statement.

.. raw:: html

<span></span>
\

* ``#endif`` and ``#else`` statements should have trailing ``// <NAME>`` and ``// !<NAME>`` comments. Namespace closing brace should have trailing ``// namespace <name>`` comment.

.. raw:: html

<span></span>
Loading

0 comments on commit 3f0ecff

Please sign in to comment.