Update docs for cli tools

roc-streaming · Nov 22, 2023 · 57b932b · 57b932b
1 parent 3f43695
commit 57b932b
Show file tree

Hide file tree

Showing 7 changed files with 202 additions and 104 deletions.
diff --git a/docs/man/roc-copy.1 b/docs/man/roc-copy.1
@@ -154,7 +154,8 @@ Input from stdin, output to stdout:
 .sp
 .nf
 .ft C
-$ roc\-copy \-vv \-\-input\-format=wav \-i file:\- \-\-output\-format=wav \-o file:\- >./output.wav <./input.wav
+$ roc\-copy \-vv \-\-input\-format=wav \-i file:\- \e
+    \-\-output\-format=wav \-o file:\- >./output.wav <./input.wav
 .ft P
 .fi
 .UNINDENT

diff --git a/docs/man/roc-recv.1 b/docs/man/roc-recv.1
@@ -277,81 +277,86 @@ $ roc\-recv \-vv \-s rtp://0.0.0.0:10001
 .UNINDENT
 .UNINDENT
 .sp
-Bind two source and repair endpoints to all IPv4 interfaces (but not IPv6):
+Bind source, repair, and control endpoints to all IPv4 interfaces (but not IPv6):
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp+rs8m://0.0.0.0:10001 \-r rs8m://0.0.0.0:10002
+$ roc\-recv \-vv \-s rtp+rs8m://0.0.0.0:10001 \-r rs8m://0.0.0.0:10002 \e
+    \-c rtcp://0.0.0.0:10003
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Bind two source and repair endpoints to all IPv6 interfaces (but not IPv4):
+Bind source, repair, and control endpoints to all IPv6 interfaces (but not IPv4):
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp+rs8m://[::]:10001 \-r rs8m://[::]:10002
+$ roc\-recv \-vv \-s rtp+rs8m://[::]:10001 \-r rs8m://[::]:10002 \-c rtcp://[::]:10003
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Bind two source and repair endpoints to a particular network interface:
+Bind source, repair, and control endpoints to a particular network interface:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002
+$ roc\-recv \-vv \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002 \e
+    \-c rtcp://192.168.0.3:10003
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Bind three source, repair, and control endpoints:
+Bind endpoints to a particular multicast address and join to a multicast group on a particular network interface:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \e
-    \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002 \-c rtcp://192.168.0.3:10003
+$ roc\-recv \-vv \-s rtp+rs8m://225.1.2.3:10001 \-r rs8m://225.1.2.3:10002 \e
+    \-c rtcp://225.1.2.3:10003 \e
+    \-\-miface 192.168.0.3
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Bind two source and repair endpoints to a particular multicast address and join to a multicast group on a particular network interface:
+Bind two sets of source, repair, and control endpoints (six endpoints in total):
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp+rs8m://225.1.2.3:10001 \-r rs8m://225.1.2.3:10002 \-\-miface 192.168.0.3
+$ roc\-recv \-vv \e
+    \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002 \e
+        \-c rtcp://192.168.0.3:10003 \e
+    \-s rtp+rs8m://198.214.0.7:10001 \-r rs8m://198.214.0.7:10002 \e
+        \-c rtcp://198.214.0.7:10003
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
+.SS I/O examples
 .sp
-Bind two sets of source, repair, and control endpoints:
+Output to the default device (omit \fB\-o\fP):
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \e
-    \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002 \-c rtcp://192.168.0.3:10003 \e
-    \-s rtp+rs8m://198.214.0.7:10001 \-r rs8m://198.214.0.7:10002 \-c rtcp://198.214.0.7:10003
+$ roc\-recv \-vv \-s rtp://0.0.0.0:10001
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
-.SS I/O examples
 .sp
 Output to the default ALSA device:
 .INDENT 0.0
@@ -395,7 +400,7 @@ Output to a file in WAV format (specify format manually):
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-o file:./output \-\-output\-format wav
+$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-o file:./output.file \-\-output\-format wav
 .ft P
 .fi
 .UNINDENT
@@ -456,46 +461,73 @@ Select the LDPC\-Staircase FEC scheme:
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp+ldpc://0.0.0.0:10001 \-r ldpc://0.0.0.0:10002
+$ roc\-recv \-vv \-s rtp+ldpc://0.0.0.0:10001 \-r ldpc://0.0.0.0:10002 \e
+    \-c rtcp://0.0.0.0:10003
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Select lower session latency:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-\-sess\-latency=50ms
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Select lower I/O latency and frame length:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
+    \-\-io\-latency=20ms \-\-frame\-length 4ms
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Select higher session latency and timeouts:
+Manually specify thresholds and timeouts:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
 $ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
-    \-\-sess\-latency=5s \-\-min\-latency=\-1s \-\-max\-latency=10s \-\-np\-timeout=10s \-\-bp\-timeout=10s
+    \-\-sess\-latency=50ms \-\-latency\-tolerance=20ms \e
+    \-\-no\-play\-timeout=200s \-\-choppy\-play\-timeout=500ms
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Select higher I/O latency:
+Manually specify resampling parameters:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
 $ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
-    \-\-io\-latency=200ms
+    \-\-resampler\-backend=speex \-\-resampler\-profile=high
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Select resampler profile:
+Manually specify clock synchronization parameters:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
 $ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
-    \-\-resampler\-profile=high
+    \-\-clock\-backend=niq \-\-clock\-profile=gradual
 .ft P
 .fi
 .UNINDENT

diff --git a/docs/man/roc-send.1 b/docs/man/roc-send.1
@@ -93,9 +93,6 @@ Duration of the internal frames, TIME units
 .BI \-\-rate\fB= INT
 Override input sample rate, Hz
 .TP
-.B  \-\-no\-resampling
-Disable resampling  (default=off)
-.TP
 .BI \-\-resampler\-backend\fB= ENUM
 Resampler backend  (possible values=\(dqdefault\(dq, \(dqbuiltin\(dq, \(dqspeex\(dq, \(dqspeexdec\(dq default=\(gadefault\(aq)
 .TP
@@ -246,38 +243,27 @@ $ roc\-send \-vv \-i file:./input.wav \-s rtp://192.168.0.3:10001
 .UNINDENT
 .UNINDENT
 .sp
-Send file to receiver with two IPv4 source and repair endpoints:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ roc\-send \-vv \-i file:./input.wav \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Send file to receiver with two IPv6 source and repair endpoints:
+Send file to receiver with IPv4 source, repair, and control endpoints:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-send \-vv \-i file:./input.wav \-s rtp+rs8m://[2001:db8::]:10001 \-r rs8m://[2001:db8::]:10002
+$ 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
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Send file to receiver with three IPv4 source, repair, and control endpoints:
+Send file to receiver with IPv6 source, repair, and control endpoints:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-send \-vv \-i file:./input.wav \e
-    \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002 \-c rtcp://192.168.0.3:10003
+$ roc\-send \-vv \-i file:./input.wav \-s rtp+rs8m://[2001:db8::]:10001 \e
+    \-r rs8m://[2001:db8::]:10002 \-r rtcp://[2001:db8::]:10003
 .ft P
 .fi
 .UNINDENT
@@ -291,8 +277,10 @@ Send file to two receivers, each with three endpoints:
 .ft C
 $ roc\-send \-vv \e
     \-i file:./input.wav \e
-    \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002 \-c rtcp://192.168.0.3:10003 \e
-    \-s rtp+rs8m://198.214.0.7:10001 \-r rs8m://198.214.0.7:10002 \-c rtcp://198.214.0.7:10003
+    \-s rtp+rs8m://192.168.0.3:10001 \-r rs8m://192.168.0.3:10002 \e
+        \-c rtcp://192.168.0.3:10003 \e
+    \-s rtp+rs8m://198.214.0.7:10001 \-r rs8m://198.214.0.7:10002 \e
+        \-c rtcp://198.214.0.7:10003
 .ft P
 .fi
 .UNINDENT
@@ -335,13 +323,25 @@ $ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-i pulse://alsa_input.pci\-0000_00
 .UNINDENT
 .UNINDENT
 .sp
-Send WAV file, specify format manually:
+Send WAV file (guess format by extension):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-i file:./input.wav
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Send WAV file (specify format manually):
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-i file:./input \-\-input\-format wav
+$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-i file:./input.file \-\-input\-format wav
 .ft P
 .fi
 .UNINDENT
@@ -359,7 +359,7 @@ $ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-i file:\- \-\-input\-format wav <
 .UNINDENT
 .UNINDENT
 .sp
-Send WAV file, specify full URI:
+Send WAV file (specify absolute path):
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -390,21 +390,48 @@ Select the LDPC\-Staircase FEC scheme and a larger block size:
 .sp
 .nf
 .ft C
-$ roc\-send \-vv \-i file:./input.wav \e
-    \-s rtp+ldpc://192.168.0.3:10001 \-r ldpc://192.168.0.3:10002 \e
+$ roc\-send \-vv \-i file:./input.wav \-s rtp+ldpc://192.168.0.3:10001 \e
+    \-r ldpc://192.168.0.3:10002 \-c ldpc://192.168.0.3:10003 \e
     \-\-nbsrc=1000 \-\-nbrpr=500
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Select resampler profile:
+Select lower packet length:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ roc\-send \-vv \-i file:./input.wav \-s rtp+ldpc://192.168.0.3:10001 \e
+    \-\-packet\-length 2500us
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Select lower I/O latency and frame length:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \e
+    \-\-io\-latency=20ms \-\-frame\-length 4ms
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Manually specify resampling parameters:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-\-resampler\-profile=high
+$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \e
+    \-\-resampler\-backend=speex \-\-resampler\-profile=high
 .ft P
 .fi
 .UNINDENT

diff --git a/docs/sphinx/manuals/roc_copy.rst b/docs/sphinx/manuals/roc_copy.rst
@@ -78,7 +78,8 @@ Input from stdin, output to stdout:
 
 .. code::
 
-    $ roc-copy -vv --input-format=wav -i file:- --output-format=wav -o file:- >./output.wav <./input.wav
+    $ roc-copy -vv --input-format=wav -i file:- \
+        --output-format=wav -o file:- >./output.wav <./input.wav
 
 SEE ALSO
 ========