ROC-SEND(1)

💖 ROC-SEND(1) — send real-time audio 💖

okay bestie, welcome to roc-send, a little icon from the Roc Toolkit family (section 1 of the manual, for all you pedants keeping score 💅). she reads audio and yeets it across the network to a receiver. let's get into it.

---

✨ NAME ✨

roc-send — send real-time audio 🎀

---

🌸 SYNOPSIS 🌸

roc-send OPTIONS

---

🦋 DESCRIPTION 🦋

Read an audio stream from an audio device or a file, and send it to a remote receiver. that's the whole gig. no cap.

💅 Options 💅

• -h, --help — print help and dip. bye bestie 👋
• -V, --version — print the version and dip.
• -v, --verbose — bump the verbosity level. yes you can use it multiple times, stack that vibe 🔥
• -L, --list-supported — list the supported schemes and formats.
• -i,--input=IO_URI — the input file or device URI. where the audio comes from, your origin story ✨
• --input-format=FILE_FORMAT — force the input file format, no guessing.
• -s,--source=ENDPOINT_URI — the remote source endpoint.
• -r,--repair=ENDPOINT_URI — the remote repair endpoint.
• -c,--control=ENDPOINT_URI — the remote control endpoint.
• --reuseaddr — enable SO_REUSEADDR when binding sockets.
• --target-latency=STRING — target latency, in TIME units.
• --io-latency=STRING — recording target latency, in TIME units.
• --latency-tolerance=STRING — maximum deviation from target latency, in TIME units.
• --nbsrc=INT — number of source packets in the FEC block.
• --nbrpr=INT — number of repair packets in FEC block.
• --packet-len=STRING — outgoing packet length, 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 input sample rate, in Hz.
• --latency-backend=ENUM — which latency to use in the 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).
• --profiling — enable self profiling (default = off).
• --color=ENUM — set colored logging mode for stderr output (possible values "auto", "always", "never", default auto).

---

🎀 Endpoint URI 🎀

the --source, --repair, and --control options define the network endpoints that the traffic gets sent to. it's giving "where are we going" energy.

ENDPOINT_URI should have the following form:

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

Examples:

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

the list of supported protocols can be retrieved using the --list-supported option. slay.

the host field should be either an FQDN (domain name), or an IPv4 address, or an IPv6 address in square brackets.

the port field can be omitted if the protocol defines a standard port. otherwise, it is mandatory — no skipping, bestie 🙈

the path and query fields are allowed only for protocols that support them, e.g. for RTSP.

if FEC is enabled, a pair of a source and repair endpoints should be provided. the two endpoints should use compatible protocols, e.g. rtp+rs8m:// for the source endpoint, and rs8m:// for the repair endpoint. if FEC is disabled, a single source endpoint should be provided.

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)

in addition, it is recommended to provide a control endpoint. it is used to exchange non-media information used to identify session, carry feedback, etc. if no control endpoint is provided, the session operates in reduced fallback mode, which may be less robust and may not support all features. lowkey important, don't skip it ✨

supported control protocols:

• rtcp://

---

🌈 IO URI 🌈

the --input option requires a device or file URI in one of the following forms:

• DEVICE_TYPE://DEVICE_NAME — audio device
• DEVICE_TYPE://default — default audio device for given device type
• file:///ABS/PATH — absolute file path
• file://localhost/ABS/PATH — absolute file path (alternative form; only "localhost" host is supported)
• file:/ABS/PATH — absolute file path (alternative form)
• file:REL/PATH — relative file path
• file://- — stdin
• file:- — stdin (alternative form)

Examples:

• pulse://default
• pulse://alsa_input.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 can be retrieved using the --list-supported option.

if the --input is omitted, the default driver and device are selected. main character energy, she just picks for you 💅

the --input-format option can be used to force the input file format. if it is omitted, the file format is auto-detected. this option is always required when the input is stdin. fr fr, don't forget it.

the path component of the provided URI is percent-decoded. for convenience, unencoded characters are allowed as well, except that % should be always encoded as %25.

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

---

👑 Multiple slots 👑

multiple sets of endpoints can be specified to send media to multiple addresses. yes, she can serve multiple looks at once.

such 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. consistency is the vibe check 🌸

---

🔥 SO_REUSEADDR 🔥

if the --reuseaddr option is provided, the SO_REUSEADDR socket option will be enabled for all sockets.

for TCP, it allows immediately reusing a recently closed socket in TIME_WAIT state, which may be useful you want to be able to restart server quickly.

for UDP, it allows multiple processes to 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 ephemeral port.

---

⭐ 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 💜

🌟 Endpoint examples 🌟

send file to receiver with one bare RTP endpoint:

$ roc-send -vv -i file:./input.wav -s rtp://192.168.0.3:10001

send file to receiver with IPv4 source, repair, and control endpoints:

$ 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

send file to receiver with IPv6 source, repair, and control endpoints:

$ roc-send -vv -i file:./input.wav -s rtp+rs8m://[2001:db8::]:10001 \
    -r rs8m://[2001:db8::]:10002 -r rtcp://[2001:db8::]:10003

send file to two receivers, each with three endpoints:

$ 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 \
    -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 🎧

capture sound from the default device (omit -i):

$ roc-send -vv -s rtp://192.168.0.3:10001

capture sound from the default ALSA device:

$ roc-send -vv -s rtp://192.168.0.3:10001 -i alsa://default

capture sound from a specific PulseAudio device:

$ roc-send -vv -s rtp://192.168.0.3:10001 -i pulse://alsa_input.pci-0000_00_1f.3.analog-stereo

send WAV file (guess format by extension):

$ roc-send -vv -s rtp://192.168.0.3:10001 -i file:./input.wav

send WAV file (specify format manually):

$ roc-send -vv -s rtp://192.168.0.3:10001 -i file:./input.file --input-format wav

send WAV from stdin:

$ roc-send -vv -s rtp://192.168.0.3:10001 -i file:- --input-format wav <./input.wav

send WAV file (specify absolute path):

$ roc-send -vv -s rtp://192.168.0.3:10001 -i file:///home/user/input.wav

🧚 Tuning examples 🧚

force a specific rate on the input device:

$ roc-send -vv -s rtp://192.168.0.3:10001 --rate=44100

select the LDPC-Staircase FEC scheme and a larger block size:

$ roc-send -vv -i file:./input.wav -s rtp+ldpc://192.168.0.3:10001 \
    -r ldpc://192.168.0.3:10002 -c ldpc://192.168.0.3:10003 \
    --nbsrc=1000 --nbrpr=500

select smaller packet length:

$ roc-send -vv -i file:./input.wav -s rtp+ldpc://192.168.0.3:10001 \
    --packet-len 2500us

select lower I/O latency and frame length:

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

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:

$ 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 🌈

the following environment variables are supported:

• NO_COLOR — by default, terminal coloring is automatically detected. this environment variable can be set to a non-empty string to disable terminal coloring. it has lower precedence than the --color option.
• FORCE_COLOR — by default, terminal coloring is automatically detected. this environment variable can be set to a positive integer to enable/force terminal coloring. it has lower precedence than the NO_COLOR variable and the --color option.

---

👀 SEE ALSO 👀

roc-recv(1), and the Roc web site at https://roc-streaming.org/

---

💀 BUGS 💀

please report any bugs found via GitHub (https://github.com/roc-streaming/roc-toolkit/). she is not perfect, okay, be nice 🙈

---

🫶 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).

---

🎀 COPYRIGHT 🎀

2024, Roc Streaming authors

---

and that's the whole page, bestie 💖 this was Roc Toolkit 0.4, dated 2024 — sending real-time audio like the icon she is. periodt. 👑✨