4. ristreceiver Syntax and Examples

The ristreceiver is provided as a fully featured example program. You may use it as-is for testing or even production, or you may examine the code for ideas in creating your own utilities. This documents >ristreceiver by printing its help text, then providing explanations for it, and by providing examples of its usage.

The help text consists of two parts. The default help, which documents the global parameters which affect all RIST connections run from a particular instance, plus specific URL help, which sets the parameters for each RIST connectiong between sender and receiver pair separately.

Main Help - Global Parameters

Main help can be accessed via ristsender --help >enter<

Usage: %s [OPTIONS] Where OPTIONS are: -i | --inputurl rist://... * | Comma separated list of input URLs | -o | --outputurl udp://... * | Comma separated list of output URLs | -b | --buffer value | Default buffer size for packet retransmissions | -s | --secret PWD | Default pre-shared encryption secret | -e | --encryption-type TYPE | Default Encryption type (0, 128 = AES-128, 256 = AES-256)| -p | --profile number | Rist profile (0 = simple, 1 = main, 2 = advanced) | -t | --tun IfName | TUN interface name for oob data output | -S | --statsinterval value (ms) | Interval at which stats get printed, 0 to disable | -v | --verbose-level value | To disable logging: -1, log levels match syslog levels | -h | --help | Show this help | -u | --help-url | Show all the possible url options |

• == mandatory value Default values: %s --profile 1 --stats 1000 --verbose-level 6 ristreceiver version 3.1.0.2

Additional Explanations

Below are additional explanations of each of the above parameters:

• -i | --inputurl refers to the rist sender(s) this binary should "receive" from. rist://123.124.125.126:8194 would refer to an external host ristsender at that address and port. Note the even numbered port. The inputurl parameter provides a large number of individual customization possibilities. We refer you to the section dedicated to the URL parameters, below. You can list up to ten URLs, separating them by commas.

• -o | --outputurl refers to the outgoingstream(s), which is subsequently to be sent to a viewer application. This is normally a udp or rtp media stream to a host/port in the private network or the localhost adapter. As an example, udp://192.168.100.1:8193. You will find additional information on the url parameters in the section dedicated to the URL parameters. You can list up to ten URLs, separating them by commas.

• -b | --buffer refers to the size of the buffer which stores the most recently received packets. By examining sequence numbers within the packets stored in the buffer, the receiver can determin if any are missing. If so, it can re-request them, and the ristsender resends the missing packet(s). The buffer size will work best at four to seven times the ping time between the longest locations. This allows time for requests for the retransmission of a lost or corrupted packet, and the subsequent retransmission of its replacement. If your stream traverses undersea fiber routes or other types of sometimes unstable or congested routes, you may require an even bigger buffer. This buffer will "delay" the stream by the amount of the buffer, but the stream will arrive without added jitter.

• -s | --secret PWD sets the specified passphrase for Main or Advanced profile encryption. Note that simple protocol does not support encryption, and that you must in addition to -s specify the -e (encryption type) parameter. The rotating keys shall be placed inside the rtcp messages, using your -e parameter as the pre-shared key.

• -e | --encryption-type specifies the specific encrytion. Specify "128" for AES-128 or "256" for AES-256. Remember that you must also specify the pass phrase, and that encryption is not supported for the simple protocol at all.

• -p | --profile number specifies the profile type for the RIST connection. Choose "0" for simple, "1" for main, or "2" for advanced

The simple profile provides a minimal implemenation for transport of an rtp or udp stream over a given port between two hosts, with an additional port used for status and re-request messages. Note that it is expected that simple profile viewer applications such as vlc 4.x, currently in beta, will promote widespread adoption of the RIST protocol to a global audience.

The main profile provides additional features, most notably the optional use of a tunnel (utilizing only one port) between hosts through which both messages and media can traverse, with support for encryption and multiplexing. It also provides for multiple network paths, which enables load balancing and redundancy.

The advanced profile adds lz4 compression of the GRE tunnel, a quick but efficient form of compression.

In general, you should find that the Simple and Main profile configured libRIST connections should be interoperable with other vendors' RIST implementations, depending upon how true each vendor implementation is to the RIST standards, which are still relatively new. The Advanced profile is compatible only with connections using the libRIST implementation.

• -t | --tun IfName The device name for the Main or Advanced protocol tunnel which shall convey both media stream and messaging. This would typically be a device name such as tun0. ristreceiver will create the actual tunnel as a true bi-directional tunnel similar to an SSL tunnel. You, however, will create an adaptor in the OS before running ristreceiver. For example, at a bash prompt as root, you might run ip tuntap add mode tun dev tun21

• -S | --statsinterval value (ms) specifies the time in milliseconds (default is 1000 ms or 1 second) between statistics summaries. A value of zero disables the stats. When testing or tuning libRIST, you will find the stats, and in particular, the statistics pertaining to the resends and lost packets an important means of understanding how best to set up your connections.

• -v | --verbose-level value The verbosity settings match the standard Syslog options. These are self explanatory: -1 for disable. 3 for errors only. 4 adds warnings. 5 adds notices. 6 adds info. 7 for debug mode. 100 allows you to dry-run or simulate the RIST connection.

• -h | --help displays the help text shown above, which is for the global settings of one or more RIST connections controlled by this instance.

• -u | --help-url displays the help regarding URL construction, which provides the settings on a connection by connection basis.

Examples