1ROC-RECV(1) Roc Toolkit ROC-RECV(1)
2
6 roc-recv - receive real-time audio
7
9 roc-recv OPTIONS
10
12 Receive audio streams from remote senders and write them to an audio
13 device or file.
14 Options
16 -h, --help
17 Print help and exit
18 -V, --version
20 Print version and exit
21 -v, --verbose
23 Increase verbosity level (may be used multiple times)
24 -L, --list-supported
26 list supported schemes and formats
27 -o,--output=IO_URI
29 Output file or device URI
30 --output-format=FILE_FORMAT
32 Force output file format
33 --backup=IO_URI
35 Backup file or device URI (if set, used when there are no ses‐
36 sions)
37 --backup-format=FILE_FORMAT
39 Force backup file format
40 -s,--source=ENDPOINT_URI
42 Local source endpoint
43 -r,--repair=ENDPOINT_URI
45 Local repair endpoint
46 -c,--control=ENDPOINT_URI
48 Local control endpoint
49 --miface=MIFACE
51 IPv4 or IPv6 address of the network interface on which to join
52 the multicast group
53 --sess-latency=STRING
55 Session target latency, TIME units
56 --min-latency=STRING
58 Session minimum latency, TIME units
59 --max-latency=STRING
61 Session maximum latency, TIME units
62 --io-latency=STRING
64 Playback target latency, TIME units
65 --np-timeout=STRING
67 Session no playback timeout, TIME units
68 --bp-timeout=STRING
70 Session broken playback timeout, TIME units
71 --bp-window=STRING
73 Session breakage detection window, TIME units
74 --packet-limit=INT
76 Maximum packet size, in bytes
77 --frame-limit=INT
79 Maximum internal frame size, in bytes
80 --frame-length=TIME
82 Duration of the internal frames, TIME units
83 --rate=INT
85 Override output sample rate, Hz
86 --no-resampling
88 Disable resampling (default=off)
89 --resampler-backend=ENUM
91 Resampler backend (possible values="default", "builtin",
92 "speex" default=`default')
93 --resampler-profile=ENUM
95 Resampler profile (possible values="low", "medium", "high" de‐
96 fault=`medium')
97 -1, --oneshot
99 Exit when last connected client disconnects (default=off)
100 --poisoning
102 Enable uninitialized memory poisoning (default=off)
103 --profiling
105 Enable self profiling (default=off)
106 --beeping
108 Enable beeping on packet loss (default=off)
109 --color=ENUM
111 Set colored logging mode for stderr output (possible val‐
112 ues="auto", "always", "never" default=`auto')
113 Endpoint URI
115 --source, --repair, and --control options define network endpoints on
116 which to receive the traffic.
117 ENDPOINT_URI should have the following form:
119 protocol://host[:port][/path][?query]
121 Examples:
123 • rtsp://localhost:123/path?query
125 • rtp+rs8m://localhost:123
127 • rtp://0.0.0.0:123
129 • rtp://[::1]:123
131 • rtcp://0.0.0.0:123
133 The list of supported protocols can be retrieved using --list-supported
135 option.
136 The host field should be either FQDN (domain name), or IPv4 address, or
138 IPv6 address in square brackets. It may be 0.0.0.0 (for IPv4) or [::]
139 (for IPv6) to bind endpoint to all network interfaces.
140 The port field can be omitted if the protocol defines standard port.
142 Otherwise, it is mandatory. It may be set to zero to bind endpoint to a
143 radomly chosen ephemeral port.
144 The path and query fields are allowed only for protocols that support
146 them, e.g. for RTSP.
147 If FEC is enabled on sender, a pair of a source and repair endpoints
149 should be provided. The two endpoints should use compatible protocols,
150 e.g. rtp+rs8m:// for source endpoint, and rs8m:// for repair endpoint.
151 If FEC is disabled, a single source endpoint should be provided.
152 Supported source and repair protocols:
154 • source rtp://, repair none (bare RTP without FEC)
156 • source rtp+rs8m://, repair rs8m:// (RTP with Reed-Solomon FEC)
158 • source rtp+ldpc://, repair ldpc:// (RTP with LDPC-Staircase FEC)
160 In addition, it is recommended to provide control endpoint. It is used
162 to exchange non-media information used to identify session, carry feed‐
163 back, etc. If no control endpoint is provided, session operates in re‐
164 duced fallback mode, which may be less robust and may not support all
165 features.
166 Supported control protocols:
168 • rtcp://
170 IO URI
172 --output and --backup options require a device or file URI in one of
173 the following forms:
174 • DEVICE_TYPE://DEVICE_NAME -- audio device
176 • DEVICE_TYPE://default -- default audio device for given device type
178 • file:///ABS/PATH -- absolute file path
180 • file://localhost/ABS/PATH -- absolute file path (alternative form;
182 only "localhost" host is supported)
183 • file:/ABS/PATH -- absolute file path (alternative form)
185 • file:REL/PATH -- relative file path
187 • file://- -- stdout
189 • file:- -- stdout (alternative form)
191 Examples:
193 • pulse://default
195 • pulse://alsa_output.pci-0000_00_1f.3.analog-stereo
197 • alsa://hw:1,0
199 • file:///home/user/test.wav
201 • file://localhost/home/user/test.wav
203 • file:/home/user/test.wav
205 • file:./test.wav
207 • file:-
209 The list of supported schemes and file formats can be retrieved using
211 --list-supported option.
212 If the --output is omitted, the default driver and device are selected.
214 If the --backup is omitted, no backup source is used.
215 The --output-format and --backup-format options can be used to force
217 the output or backup file format. If the option is omitted, the file
218 format is auto-detected. The option is always required when the output
219 or backup is stdout or stdin.
220 The path component of the provided URI is percent-decoded. For conve‐
222 nience, unencoded characters are allowed as well, except that % should
223 be always encoded as %25.
224 For example, the file named /foo/bar%/[baz] may be specified using ei‐
226 ther of the following URIs: file:///foo%2Fbar%25%2F%5Bbaz%5D and
227 file:///foo/bar%25/[baz].
228 Multicast interface
230 If --miface option is present, it defines an IP address of the network
231 interface on which to join the multicast group. If not present, no mul‐
232 ticast group should be joined.
233 It's not possible to receive multicast traffic without joining a multi‐
235 cast group. The user should either provide multicast interface, or join
236 the group manually using foreign tools.
237 MIFACE should be an IP address of the network interface on which to
239 join the multicast group. It may be 0.0.0.0 (for IPv4) or :: (for IPv6)
240 to join the multicast group on all available interfaces.
241 Multiple slots
243 Multiple sets of endpoints can be specified to retrieve media from mul‐
244 tiple addresses.
245 Such endpoint sets are called slots. All slots should have the same set
247 of endpoint types (source, repair, etc) and should use the same proto‐
248 cols for them. All slots should also have their own multicast interface
249 option, if it's used.
250 Backup audio
252 If --backup option is given, it defines input audio device or file
253 which will be played when there are no connected sessions. If it's not
254 given, silence is played instead.
255 Backup file is restarted from the beginning each time when the last
257 session disconnect. The playback of of the backup file is automatically
258 looped.
259 Time units
261 TIME should have one of the following forms:
262 123ns, 123us, 123ms, 123s, 123m, 123h
263
265 Endpoint examples
266 Bind one bare RTP endpoint on all IPv4 interfaces:
267 $ roc-recv -vv -s rtp://0.0.0.0:10001
269 Bind two source and repair endpoints to all IPv4 interfaces (but not
271 IPv6):
272 $ roc-recv -vv -s rtp+rs8m://0.0.0.0:10001 -r rs8m://0.0.0.0:10002
274 Bind two source and repair endpoints to all IPv6 interfaces (but not
276 IPv4):
277 $ roc-recv -vv -s rtp+rs8m://[::]:10001 -r rs8m://[::]:10002
279 Bind two source and repair endpoints to a particular network interface:
281 $ roc-recv -vv -s rtp+rs8m://192.168.0.3:10001 -r rs8m://192.168.0.3:10002
283 Bind three source, repair, and control endpoints:
285 $ roc-recv -vv \
287 -s rtp+rs8m://192.168.0.3:10001 -r rs8m://192.168.0.3:10002 -c rtcp://192.168.0.3:10003
288 Bind two source and repair endpoints to a particular multicast address
290 and join to a multicast group on a particular network interface:
291 $ roc-recv -vv -s rtp+rs8m://225.1.2.3:10001 -r rs8m://225.1.2.3:10002 --miface 192.168.0.3
293 Bind two sets of source, repair, and control endpoints:
295 $ roc-recv -vv \
297 -s rtp+rs8m://192.168.0.3:10001 -r rs8m://192.168.0.3:10002 -c rtcp://192.168.0.3:10003 \
298 -s rtp+rs8m://198.214.0.7:10001 -r rs8m://198.214.0.7:10002 -c rtcp://198.214.0.7:10003
299 I/O examples
301 Output to the default ALSA device:
302 $ roc-recv -vv -s rtp://0.0.0.0:10001 -o alsa://default
304 Output to a specific PulseAudio device:
306 $ roc-recv -vv -s rtp://0.0.0.0:10001 -o pulse://alsa_input.pci-0000_00_1f.3.analog-stereo
308 Output to a file in WAV format (guess format by extension):
310 $ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:./output.wav
312 Output to a file in WAV format (specify format manually):
314 $ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:./output --output-format wav
316 Output to stdout in WAV format:
318 $ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:- --output-format wav >./output.wav
320 Output to a file in WAV format (absolute path):
322 $ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:///home/user/output.wav
324 Specify backup file:
326 $ roc-recv -vv -s rtp://0.0.0.0:10001 --backup file:./backup.wav
328 Tuning examples
330 Force a specific rate on the output device:
331 $ roc-recv -vv -s rtp://0.0.0.0:10001 --rate=44100
333 Select the LDPC-Staircase FEC scheme:
335 $ roc-recv -vv -s rtp+ldpc://0.0.0.0:10001 -r ldpc://0.0.0.0:10002
337 Select higher session latency and timeouts:
339 $ roc-recv -vv -s rtp://0.0.0.0:10001 \
341 --sess-latency=5s --min-latency=-1s --max-latency=10s --np-timeout=10s --bp-timeout=10s
342 Select higher I/O latency:
344 $ roc-recv -vv -s rtp://0.0.0.0:10001 \
346 --io-latency=200ms
347 Select resampler profile:
349 $ roc-recv -vv -s rtp://0.0.0.0:10001 \
351 --resampler-profile=high
352
354 roc-send(1), and the Roc web site at https://roc-streaming.org/
355
357 Please report any bugs found via GitHub (‐
358 https://github.com/roc-streaming/roc-toolkit/).
359
361 See authors page on the website for a list of maintainers and contribu‐
362 tors.
363
365 2023, Roc Streaming authors
366Roc Toolkit 0.2 2023 ROC-RECV(1)