Scroll to navigation

ROC-SEND(1) Roc Toolkit ROC-SEND(1)

NAME

roc-send - send real-time audio

SYNOPSIS

roc-send OPTIONS

DESCRIPTION

Read audio stream from an audio device or file and send it to remote receiver.

Options

Print help and exit
Print version and exit
Increase verbosity level (may be used multiple times)
list supported schemes and formats
Input file or device URI
Force input file format
Remote source endpoint
Remote repair endpoint
Remote control endpoint
enable SO_REUSEADDR when binding sockets
Target latency, TIME units
Recording target latency, TIME units
Maximum deviation from target latency, TIME units
Number of source packets in FEC block
Number of repair packets in FEC block
Outgoing packet length, TIME units
Duration of the internal frames, TIME units
Maximum packet size, in SIZE units
Maximum internal frame size, in SIZE units
Override input sample rate, Hz
Which latency to use in latency tuner (possible values="niq" default=`niq')
Latency tuning profile (possible values="responsive", "gradual", "intact" default=`intact')
Resampler backend (possible values="default", "builtin", "speex", "speexdec" default=`default')
Resampler profile (possible values="low", "medium", "high" default=`medium')
Enable packet interleaving (default=off)
Enable self profiling (default=off)
Set colored logging mode for stderr output (possible values="auto", "always", "never" default=`auto')

Endpoint URI

--source, --repair, and --control options define network endpoints to which to send the traffic.

ENDPOINT_URI should have the following form:

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

Examples:


The list of supported protocols can be retrieved using --list-supported option.

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

The port field can be omitted if the protocol defines standard port. Otherwise, it is mandatory.

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 source endpoint, and rs8m:// for 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 control endpoint. It is used to exchange non-media information used to identify session, carry feedback, etc. If no control endpoint is provided, session operates in reduced fallback mode, which may be less robust and may not support all features.

Supported control protocols:

•
rtcp://

IO URI

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


Examples:


The list of supported schemes and file formats can be retrieved using --list-supported option.

If the --input is omitted, the default driver and device are selected.

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.

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.

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.

SO_REUSEADDR

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

For TCP, it allows immediately reusing 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

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

Size units

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:

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 --color option.
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 NO_COLOR variable and --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/).

AUTHORS

See 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

2024 Roc Toolkit 0.4