[WIP] roc-streaminggh-675 Rework latency tuning

- Extract LatencyTuner to be reused from LatencyMonitor and FeedbackMonitor - Also reuse LatencyConfig and LatencyMetrics - Refine LatencyConfig defaults - Use LinkMeter in LatencyMonitor to obtain jitter - Latency backend can't be disabled; there is now always a valid backend selected, however latency *tuning* can be disabled via latency tuner profile - Receiver reports NIQ length and stalling to sender via a non-standard RTCP XR report - API: replace roc_clock_sync_backend and roc_clock_sync_profile with roc_latency_tuner_backend and roc_latency_tuner_profile - API: add roc_latency_tuner_backend, roc_latency_tuner_profile, target_latency, latency_tolerance to sender - CLI: replace --clock-backend and --clock-profile with --latency-backend and --latency-profile - CLI: rename --sess-latency to --target-latency - CLI: add --latency-backend, --latency-profile, --target-latency, --latency-tolerance to sender
gavv · Jan 28, 2024 · c46c3bf · c46c3bf
1 parent 19031ba
commit c46c3bf
Show file tree

Hide file tree

Showing 46 changed files with 1,381 additions and 993 deletions.
diff --git a/docs/man/roc-copy.1 b/docs/man/roc-copy.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "ROC-COPY" "1" "2023" "Roc Toolkit 0.3" "Roc Toolkit"
+.TH "ROC-COPY" "1" "2024" "Roc Toolkit 0.3" "Roc Toolkit"
 .SH NAME
 roc-copy \- copy local audio
 .SH SYNOPSIS
@@ -187,6 +187,6 @@ Please report any bugs found via GitHub (\fI\%https://github.com/roc\-streaming/
 .sp
 See authors page on the website for a list of maintainers and contributors (\fI\%https://roc\-streaming.org/toolkit/docs/about_project/authors.html\fP).
 .SH COPYRIGHT
-2023, Roc Streaming authors
+2024, Roc Streaming authors
 .\" Generated by docutils manpage writer.
 .
diff --git a/docs/man/roc-recv.1 b/docs/man/roc-recv.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "ROC-RECV" "1" "2023" "Roc Toolkit 0.3" "Roc Toolkit"
+.TH "ROC-RECV" "1" "2024" "Roc Toolkit 0.3" "Roc Toolkit"
 .SH NAME
 roc-recv \- receive real-time audio
 .SH SYNOPSIS
@@ -78,8 +78,8 @@ IPv4 or IPv6 address of the network interface on which to join the multicast gro
 .B  \-\-reuseaddr
 enable SO_REUSEADDR when binding sockets
 .TP
-.BI \-\-sess\-latency\fB= STRING
-Session target latency, TIME units
+.BI \-\-target\-latency\fB= STRING
+Target latency, TIME units
 .TP
 .BI \-\-io\-latency\fB= STRING
 Playback target latency, TIME units
@@ -105,11 +105,11 @@ Maximum internal frame size, in SIZE units
 .BI \-\-rate\fB= INT
 Override output sample rate, Hz
 .TP
-.BI \-\-clock\-backend\fB= ENUM
-Clock synchronization backend  (possible values=\(dqdisable\(dq, \(dqniq\(dq default=\(ganiq\(aq)
+.BI \-\-latency\-backend\fB= ENUM
+Which latency to use in latency tuner (possible values=\(dqniq\(dq default=\(ganiq\(aq)
 .TP
-.BI \-\-clock\-profile\fB= ENUM
-Clock synchronization profile  (possible values=\(dqdefault\(dq, \(dqresponsive\(dq, \(dqgradual\(dq default=\(gadefault\(aq)
+.BI \-\-latency\-profile\fB= ENUM
+Latency tuning profile  (possible values=\(dqdefault\(dq, \(dqresponsive\(dq, \(dqgradual\(dq, \(dqintact\(dq default=\(gadefault\(aq)
 .TP
 .BI \-\-resampler\-backend\fB= ENUM
 Resampler backend  (possible values=\(dqdefault\(dq, \(dqbuiltin\(dq, \(dqspeex\(dq, \(dqspeexdec\(dq default=\(gadefault\(aq)
@@ -480,7 +480,7 @@ Select lower session latency:
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-\-sess\-latency=50ms
+$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-\-target\-latency=50ms
 .ft P
 .fi
 .UNINDENT
@@ -506,7 +506,7 @@ Manually specify thresholds and timeouts:
 .nf
 .ft C
 $ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
-    \-\-sess\-latency=50ms \-\-latency\-tolerance=20ms \e
+    \-\-target\-latency=50ms \-\-latency\-tolerance=20ms \e
     \-\-no\-play\-timeout=200s \-\-choppy\-play\-timeout=500ms
 .ft P
 .fi
@@ -526,14 +526,14 @@ $ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
 .UNINDENT
 .UNINDENT
 .sp
-Manually specify clock synchronization parameters:
+Manually specify latency tuning parameters:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
 $ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
-    \-\-clock\-backend=niq \-\-clock\-profile=gradual
+    \-\-latency\-backend=niq \-\-latency\-profile=gradual
 .ft P
 .fi
 .UNINDENT
@@ -559,6 +559,6 @@ Please report any bugs found via GitHub (\fI\%https://github.com/roc\-streaming/
 .sp
 See authors page on the website for a list of maintainers and contributors (\fI\%https://roc\-streaming.org/toolkit/docs/about_project/authors.html\fP).
 .SH COPYRIGHT
-2023, Roc Streaming authors
+2024, Roc Streaming authors
 .\" Generated by docutils manpage writer.
 .
diff --git a/docs/man/roc-send.1 b/docs/man/roc-send.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "ROC-SEND" "1" "2023" "Roc Toolkit 0.3" "Roc Toolkit"
+.TH "ROC-SEND" "1" "2024" "Roc Toolkit 0.3" "Roc Toolkit"
 .SH NAME
 roc-send \- send real-time audio
 .SH SYNOPSIS
@@ -69,9 +69,15 @@ Remote control endpoint
 .B  \-\-reuseaddr
 enable SO_REUSEADDR when binding sockets
 .TP
+.BI \-\-target\-latency\fB= STRING
+Target latency, TIME units
+.TP
 .BI \-\-io\-latency\fB= STRING
 Recording target latency, TIME units
 .TP
+.BI \-\-latency\-tolerance\fB= STRING
+Maximum latency deviation, TIME units
+.TP
 .BI \-\-nbsrc\fB= INT
 Number of source packets in FEC block
 .TP
@@ -93,6 +99,12 @@ Maximum internal frame size, in SIZE units
 .BI \-\-rate\fB= INT
 Override input sample rate, Hz
 .TP
+.BI \-\-latency\-backend\fB= ENUM
+Which latency to use in latency tuner (possible values=\(dqniq\(dq default=\(ganiq\(aq)
+.TP
+.BI \-\-latency\-profile\fB= ENUM
+Latency tuning profile  (possible values=\(dqresponsive\(dq, \(dqgradual\(dq, \(dqintact\(dq default=\(gaintact\(aq)
+.TP
 .BI \-\-resampler\-backend\fB= ENUM
 Resampler backend  (possible values=\(dqdefault\(dq, \(dqbuiltin\(dq, \(dqspeex\(dq, \(dqspeexdec\(dq default=\(gadefault\(aq)
 .TP
@@ -442,6 +454,24 @@ $ roc\-send \-vv \-s rtp://192.168.0.3:10001 \e
 .fi
 .UNINDENT
 .UNINDENT
+.sp
+Perform latency tuning on sender instead of receiver:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ roc\-recv \-vv \-o pulse://default \-s rtp+rs8m://0.0.0.0:10001 \e
+    \-r rs8m://0.0.0.0:10002 \-c rtcp://0.0.0.0:10003 \e
+    \-\-latency\-profile=intact \-\-target\-latency=200ms
+
+$ roc\-send \-vv \-i file:./input.wav \-s rtp+rs8m://192.168.0.3:10001 \e
+    \-r rs8m://192.168.0.3:10002 \-c rtcp://192.168.0.3:10003 \e
+    \-\-latency\-profile=gradual \-\-target\-latency=200ms
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SH ENVIRONMENT VARIABLES
 .sp
 The following environment variables are supported:
@@ -463,6 +493,6 @@ Please report any bugs found via GitHub (\fI\%https://github.com/roc\-streaming/
 .sp
 See authors page on the website for a list of maintainers and contributors (\fI\%https://roc\-streaming.org/toolkit/docs/about_project/authors.html\fP).
 .SH COPYRIGHT
-2023, Roc Streaming authors
+2024, Roc Streaming authors
 .\" Generated by docutils manpage writer.
 .
diff --git a/docs/sphinx/api/reference.rst b/docs/sphinx/api/reference.rst
@@ -197,9 +197,9 @@ roc_config
 
 .. doxygenenum:: roc_clock_source
 
-.. doxygenenum:: roc_clock_sync_backend
+.. doxygenenum:: roc_latency_tuner_backend
 
-.. doxygenenum:: roc_clock_sync_profile
+.. doxygenenum:: roc_latency_tuner_profile
 
 .. doxygenenum:: roc_resampler_backend
 

diff --git a/docs/sphinx/manuals/roc_recv.rst b/docs/sphinx/manuals/roc_recv.rst
@@ -27,7 +27,7 @@ Options
 -c, --control=ENDPOINT_URI    Local control endpoint
 --miface=MIFACE               IPv4 or IPv6 address of the network interface on which to join the multicast group
 --reuseaddr                   enable SO_REUSEADDR when binding sockets
---sess-latency=STRING         Session target latency, TIME units
+--target-latency=STRING       Target latency, TIME units
 --io-latency=STRING           Playback target latency, TIME units
 --latency-tolerance=STRING    Maximum latency deviation, TIME units
 --no-play-timeout=STRING      No playback timeout, TIME units
@@ -36,8 +36,8 @@ Options
 --max-packet-size=SIZE        Maximum packet size, in SIZE units
 --max-frame-size=SIZE         Maximum internal frame size, in SIZE units
 --rate=INT                    Override output sample rate, Hz
---clock-backend=ENUM          Clock synchronization backend  (possible values="disable", "niq" default=`niq')
---clock-profile=ENUM          Clock synchronization profile  (possible values="default", "responsive", "gradual" default=`default')
+--latency-backend=ENUM        Which latency to use in latency tuner (possible values="niq" default=`niq')
+--latency-profile=ENUM        Latency tuning profile  (possible values="default", "responsive", "gradual", "intact" default=`default')
 --resampler-backend=ENUM      Resampler backend  (possible values="default", "builtin", "speex", "speexdec" default=`default')
 --resampler-profile=ENUM      Resampler profile  (possible values="low", "medium", "high" default=`medium')
 -1, --oneshot                 Exit when last connected client disconnects (default=off)
@@ -287,7 +287,7 @@ Select lower session latency:
 
 .. code::
 
-    $ roc-recv -vv -s rtp://0.0.0.0:10001 --sess-latency=50ms
+    $ roc-recv -vv -s rtp://0.0.0.0:10001 --target-latency=50ms
 
 Select lower I/O latency and frame length:
 
@@ -301,7 +301,7 @@ Manually specify thresholds and timeouts:
 .. code::
 
     $ roc-recv -vv -s rtp://0.0.0.0:10001 \
-        --sess-latency=50ms --latency-tolerance=20ms \
+        --target-latency=50ms --latency-tolerance=20ms \
         --no-play-timeout=200s --choppy-play-timeout=500ms
 
 Manually specify resampling parameters:
@@ -311,12 +311,12 @@ Manually specify resampling parameters:
     $ roc-recv -vv -s rtp://0.0.0.0:10001 \
         --resampler-backend=speex --resampler-profile=high
 
-Manually specify clock synchronization parameters:
+Manually specify latency tuning parameters:
 
 .. code::
 
     $ roc-recv -vv -s rtp://0.0.0.0:10001 \
-        --clock-backend=niq --clock-profile=gradual
+        --latency-backend=niq --latency-profile=gradual
 
 ENVIRONMENT VARIABLES
 =====================

diff --git a/docs/sphinx/manuals/roc_send.rst b/docs/sphinx/manuals/roc_send.rst
@@ -24,14 +24,18 @@ Options
 -r, --repair=ENDPOINT_URI   Remote repair endpoint
 -c, --control=ENDPOINT_URI  Remote control endpoint
 --reuseaddr                 enable SO_REUSEADDR when binding sockets
+--target-latency=STRING     Target latency, TIME units
 --io-latency=STRING         Recording target latency, TIME units
+--latency-tolerance=STRING  Maximum latency deviation, TIME units
 --nbsrc=INT                 Number of source packets in FEC block
 --nbrpr=INT                 Number of repair packets in FEC block
 --packet-len=STRING         Outgoing packet length, TIME units
 --frame-len=TIME            Duration of the internal frames, TIME units
 --max-packet-size=SIZE      Maximum packet size, in SIZE units
 --max-frame-size=SIZE       Maximum internal frame size, in SIZE units
 --rate=INT                  Override input sample rate, Hz
+--latency-backend=ENUM      Which latency to use in latency tuner (possible values="niq" default=`niq')
+--latency-profile=ENUM      Latency tuning profile  (possible values="responsive", "gradual", "intact" default=`intact')
 --resampler-backend=ENUM    Resampler backend  (possible values="default", "builtin", "speex", "speexdec" default=`default')
 --resampler-profile=ENUM    Resampler profile  (possible values="low", "medium", "high" default=`medium')
 --interleaving              Enable packet interleaving  (default=off)
@@ -262,6 +266,18 @@ Manually specify resampling parameters:
     $ roc-send -vv -s rtp://192.168.0.3:10001 \
         --resampler-backend=speex --resampler-profile=high
 
+Perform latency tuning on sender instead of receiver:
+
+.. code::
+
+    $ roc-recv -vv -o pulse://default -s rtp+rs8m://0.0.0.0:10001 \
+        -r rs8m://0.0.0.0:10002 -c rtcp://0.0.0.0:10003 \
+        --latency-profile=intact --target-latency=200ms
+
+    $ roc-send -vv -i file:./input.wav -s rtp+rs8m://192.168.0.3:10001 \
+        -r rs8m://192.168.0.3:10002 -c rtcp://192.168.0.3:10003 \
+        --latency-profile=gradual --target-latency=200ms
+
 ENVIRONMENT VARIABLES
 =====================