ROC-RECV(1)

💖 NAME 💖

roc-recv — receive real-time audio 🎧✨

---

🌸 SYNOPSIS 🌸

roc-recv OPTIONS

---

🎀 DESCRIPTION 🎀

okay so bestie, here's the tea: roc-recv catches audio streams flying in from remote senders and writes them straight to an audio device or a file. that's the whole vibe. 🦋

💅 Options 💅

• -h, --help — print the help and dip out 👋
• -V, --version — print the version and dip out 🏷️
• -v, --verbose — turn the verbosity level up (and yes you can use it multiple times, stack it like scrunchies) 🔥
• -L, --list-supported — list all the supported schemes and formats 📋
• -o,--output=IO_URI — the output file or device URI 💾
• --output-format=FILE_FORMAT — force the output file format, no auto-detect energy 🔒
• --backup=IO_URI — the backup file or device URI (if you set it, it gets used whenever there are literally no sessions) 🙈
• --backup-format=FILE_FORMAT — force the backup file format 🔒
• -s,--source=ENDPOINT_URI — the local source endpoint 🌱
• -r,--repair=ENDPOINT_URI — the local repair endpoint 🩹
• -c,--control=ENDPOINT_URI — the local control endpoint 🎛️
• --miface=MIFACE — the IPv4 or IPv6 address of the network interface you wanna join the multicast group on 🌐
• --reuseaddr — enable SO_REUSEADDR when binding sockets 🔁
• --target-latency=STRING — target latency, in TIME units ⏱️
• --io-latency=STRING — playback target latency, in TIME units ⏱️
• --latency-tolerance=STRING — max deviation from target latency, in TIME units 📏
• --no-play-timeout=STRING — no playback timeout, in TIME units ⌛
• --choppy-play-timeout=STRING — choppy playback timeout, in TIME units 😭
• --frame-len=TIME — duration of the internal frames, in 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 the output sample rate, in Hz 🎵
• --latency-backend=ENUM — which latency to use in the latency tuner (possible values are "niq", default is niq) 🎚️
• --latency-profile=ENUM — the latency tuning profile (possible values are "default", "responsive", "gradual", "intact", default is default) 🎚️
• --resampler-backend=ENUM — the resampler backend (possible values are "default", "builtin", "speex", "speexdec", default is default) 🔄
• --resampler-profile=ENUM — the resampler profile (possible values are "low", "medium", "high", default is medium) 🔄
• -1, --oneshot — exit when the last connected client disconnects (default is off) 🚪
• --profiling — enable self-profiling (default is off) 📊
• --beep — enable beeping on packet loss (default is off) 🔊
• --color=ENUM — set the colored logging mode for stderr output (possible values are "auto", "always", "never", default is auto) 🌈

🌐 Endpoint URI 🌐

the --source, --repair, and --control options define the network endpoints where you receive the traffic. that's the whole point bestie.

ENDPOINT_URI should look like this:

protocol://host[:port][/path][?query]

Examples, served fresh:

• rtsp://localhost:123/path?query
• rtp+rs8m://localhost:123
• rtp://0.0.0.0:123
• rtp://[::1]:123
• rtcp://0.0.0.0:123

you can grab the list of supported protocols with the --list-supported option, no cap. 👑

the host field should be either an FQDN (domain name), or an IPv4 address, or an IPv6 address wrapped in square brackets. it can be 0.0.0.0 (for IPv4) or [::] (for IPv6) to bind the endpoint to all network interfaces. 🌍

the port field can be left out if the protocol defines a standard port. otherwise it's mandatory, fr. and it can be set to zero to bind the endpoint to a randomly chosen ephemeral port. 🎲

the path and query fields are only allowed for protocols that support them, like RTSP. 🛤️

if FEC is enabled on the sender, you need to provide a pair of a source and repair endpoint. the two endpoints should use compatible protocols, like rtp+rs8m:// for the source endpoint and rs8m:// for the repair endpoint. if FEC is disabled, you just provide a single source endpoint. 💫

Supported source and repair protocols:

• source rtp://, repair none (bare RTP without FEC) 🍃
• source rtp+rs8m://, repair rs8m:// (RTP with Reed-Solomon FEC) 🛡️
• source rtp+ldpc://, repair ldpc:// (RTP with LDPC-Staircase FEC) 🛡️

on top of that, it's recommended to provide a control endpoint. it's used to exchange non-media info that identifies the session, carries feedback, etc. if you don't provide a control endpoint, the session operates in a reduced fallback mode, which may be less robust and may not support all the features. 😬

Supported control protocols:

• rtcp://

💾 IO URI 💾

the --output and --backup options need a device or file URI in one of these forms:

• DEVICE_TYPE://DEVICE_NAME — an audio device 🔊
• DEVICE_TYPE://default — the default audio device for that device type ✨
• file:///ABS/PATH — an absolute file path 📁
• file://localhost/ABS/PATH — an absolute file path, alternative form (only the "localhost" host is supported) 📁
• file:/ABS/PATH — an absolute file path, alternative form 📁
• file:REL/PATH — a relative file path 📁
• file://- — stdout 📤
• file:- — stdout, alternative form 📤

Examples, because we love a demo:

• pulse://default
• pulse://alsa_output.pci-0000_00_1f.3.analog-stereo
• alsa://hw:1,0
• file:///home/user/test.wav
• file://localhost/home/user/test.wav
• file:/home/user/test.wav
• file:./test.wav
• file:-

the list of supported schemes and file formats is available via the --list-supported option. 📋

if --output is omitted, the default driver and device get selected. if --backup is omitted, no backup source is used. simple as that. 🫶

the --output-format and --backup-format options can force the output or backup file format. if the option is omitted, the file format is auto-detected. and heads up: the option is always required when the output or backup is stdout or stdin. ⚠️

the path component of the URI you provide gets percent-decoded. for convenience, unencoded characters are allowed too, except that % should always be encoded as %25. 📝

for example, the file named /foo/bar%/[baz] may be specified using either of these URIs: file:///foo%2Fbar%25%2F%5Bbaz%5D and file:///foo/bar%25/[baz]. 🤓

📡 Multicast interface 📡

if the --miface option is present, it defines an IP address of the network interface to join the multicast group on. if it's not present, no multicast group should be joined. 🚫

real talk: it's not possible to receive multicast traffic without joining a multicast group. so you should either provide the multicast interface, or join the group manually using foreign tools. 💀

MIFACE should be an IP address of the network interface to join the multicast group on. it may be 0.0.0.0 (for IPv4) or :: (for IPv6) to join the multicast group on all available interfaces. 🌍

🧚 Multiple slots 🧚

you can specify multiple sets of endpoints to retrieve media from multiple addresses. main character energy, honestly.

those endpoint sets are called slots. all slots should have the same set of endpoint types (source, repair, etc) and should use the same protocols for them. all slots should also have their own multicast interface option, if it's used. 🎰

🔁 SO_REUSEADDR 🔁

if the --reuseaddr option is provided, the SO_REUSEADDR socket option will be enabled for all sockets (by default it's enabled only for multicast sockets). 🔧

for TCP, it lets you immediately reuse a recently closed socket in TIME_WAIT state, which may be useful when you want to be able to restart the server quickly. ⚡

for UDP, it lets multiple processes bind to the same address, which may be useful if you're using systemd socket activation. 👯

regardless of the option, SO_REUSEADDR is always disabled when binding to an ephemeral port. 🚫

🎶 Backup audio 🎶

if the --backup option is given, it defines the input audio device or file that will be played when there are no connected sessions. if it's not given, silence is played instead. 🤫

the backup file is restarted from the beginning each time the last session disconnects. and the playback of the backup file is automatically looped. 🔁

⏱️ Time units ⏱️

TIME should have one of the following forms:

123ns; 1.23us; 1.23ms; 1.23s; 1.23m; 1.23h;

📏 Size units 📏

SIZE should have one of the following forms:

123; 1.23K; 1.23M; 1.23G;

🎧 EXAMPLES 🎧

okay bestie this is the part where it gets fun — real commands you can literally copy-paste. every single one is here, nothing skipped, i promise. ✨

---

💖 Endpoint examples

bind one bare RTP endpoint on all IPv4 interfaces:

$ roc-recv -vv -s rtp://0.0.0.0:10001

bind source, repair, and control endpoints to all IPv4 interfaces (but not IPv6):

$ roc-recv -vv -s rtp+rs8m://0.0.0.0:10001 -r rs8m://0.0.0.0:10002 \
    -c rtcp://0.0.0.0:10003

bind source, repair, and control endpoints to all IPv6 interfaces (but not IPv4):

$ roc-recv -vv -s rtp+rs8m://[::]:10001 -r rs8m://[::]:10002 -c rtcp://[::]:10003

bind source, repair, and control endpoints to a particular network interface:

$ roc-recv -vv -s rtp+rs8m://192.168.0.3:10001 -r rs8m://192.168.0.3:10002 \
    -c rtcp://192.168.0.3:10003

bind endpoints to a particular multicast address and join a multicast group on a particular network interface:

$ roc-recv -vv -s rtp+rs8m://225.1.2.3:10001 -r rs8m://225.1.2.3:10002 \
    -c rtcp://225.1.2.3:10003 \
    --miface 192.168.0.3

bind two sets of source, repair, and control endpoints (that's six endpoints in total, we love a multitasker):

$ roc-recv -vv \
    -s rtp+rs8m://192.168.0.3:10001 -r rs8m://192.168.0.3:10002 \
        -c rtcp://192.168.0.3:10003 \
    -s rtp+rs8m://198.214.0.7:10001 -r rs8m://198.214.0.7:10002 \
        -c rtcp://198.214.0.7:10003

---

🎀 I/O examples

output to the default device (just omit -o, she's low maintenance like that):

$ roc-recv -vv -s rtp://0.0.0.0:10001

output to the default ALSA device:

$ roc-recv -vv -s rtp://0.0.0.0:10001 -o alsa://default

output to a specific PulseAudio device:

$ roc-recv -vv -s rtp://0.0.0.0:10001 -o pulse://alsa_input.pci-0000_00_1f.3.analog-stereo

output to a file in WAV format (guess the format by extension, she's smart):

$ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:./output.wav

output to a file in WAV format (specify the format manually, no guessing):

$ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:./output.file --output-format wav

output to stdout in WAV format:

$ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:- --output-format wav >./output.wav

output to a file in WAV format (absolute path era):

$ roc-recv -vv -s rtp://0.0.0.0:10001 -o file:///home/user/output.wav

specify backup file:

$ roc-recv -vv -s rtp://0.0.0.0:10001 --backup file:./backup.wav

---

🧚 Tuning examples

force a specific rate on the output device:

$ roc-recv -vv -s rtp://0.0.0.0:10001 --rate=44100

select the LDPC-Staircase FEC scheme:

$ roc-recv -vv -s rtp+ldpc://0.0.0.0:10001 -r ldpc://0.0.0.0:10002 \
    -c rtcp://0.0.0.0:10003

select lower session latency:

$ roc-recv -vv -s rtp://0.0.0.0:10001 --target-latency=50ms

select lower I/O latency and frame length:

$ roc-recv -vv -s rtp://0.0.0.0:10001 \
    --io-latency=20ms --frame-len 4ms

manually specify thresholds and timeouts:

$ roc-recv -vv -s rtp://0.0.0.0:10001 \
    --target-latency=50ms --min-latency=40ms --max-latency 60ms \
    --no-play-timeout=200ms --choppy-play-timeout=500ms

manually specify resampling parameters:

$ roc-recv -vv -s rtp://0.0.0.0:10001 \
    --resampler-backend=speex --resampler-profile=high

manually specify latency tuning parameters:

$ roc-recv -vv -s rtp://0.0.0.0:10001 \
    --latency-backend=niq --latency-profile=gradual

---

🌈 ENVIRONMENT VARIABLES 🌈

these are the env vars she supports, bestie:

• NO_COLOR — so by default, terminal coloring is automatically detected. set this to a non-empty string</> and boom, terminal coloring is disabled. it has lower precedence than the --color option though, so don't come for it if --color overrules it. 💅
• FORCE_COLOR — same deal, by default terminal coloring is automatically detected. set this one to a positive integer to enable/force terminal coloring. it has lower precedence than the NO_COLOR variable and the --color option. so the pecking order is real. 👑

---

👀 SEE ALSO 👀

roc-send(1), and the Roc web site at https://roc-streaming.org/ — go read it, it's giving documentation excellence.

---

💀 BUGS 💀

found a bug? please report any bugs found via GitHub (<https://github.com/roc-streaming/roc-toolkit/>). do it for the culture. 🫶

---

👑 AUTHORS 👑

see the authors page on the website for a list of maintainers and contributors (<https://roc-streaming.org/toolkit/docs/about_project/authors.html>). icons, all of them.

---

🌸 COPYRIGHT 🌸

2024, Roc Streaming authors

---

and that's the whole page bestie, we ate and left no crumbs 🍓 — this was Roc Toolkit 0.4, dated 2024, and it's the ROC-RECV(1) manual. go forth and receive some audio, you absolute main character. 💖✨🦋