RTP Tools 1.9
Author: Henning Schulzrinne
Keywords: RTP; rtptools; debugging

# RTP Tools (Version 1.9)

## Description

The rtptools distribution consists of a number of small applications that can be used for processing RTP data.

`rtpplay`
  Play back RTP sessions recorded by `rtpdump`
`rtpsend`
  Generate RTP packets from textual description, generated by hand or `rtpdump`
`rtpdump`
  Parse and print RTP packets, generating output files suitable for `rtpplay` and `rtpsend`
`rtptrans`
  RTP translator between unicast and multicast networks; also translates between VAT and RTP formats.

## Installation

The RTP tools are available from: ftp://ftp.cs.columbia.edu/pub/schulzrinne/rtptools

The RTP tools should compile on any Posix-compliant platform supporting sockets. They have been tested on SunOS 4.1, SunOS 5.x (Solaris), SGI Irix, and HP-UX. Edit the directories and libraries at the top of `Makefile` and type `make`. The compiler must support ANSI C: `gcc` does, Sun `cc` does not.

Note: You must use the `sun4` architecture for SunOS 4.1.x and `sun5` for SunOS 5.x (Solaris). You will get system call errors if you do not.

## General Usage Hints

Network addresses can be either multicast or unicast addresses, unless stated otherwise. They may be specified in dotted-decimal notation (e.g., 224.2.0.1) or as a host name (e.g., `lupus.fokus.gmd.de`). Port numbers must be given as decimal numbers in the range of 1 to 65535. Network addresses are specified as destination/port/ttl. The time-to-live (ttl) value is optional and only applies to multicast.

For all commands, the flag `-h` or `-?` will print a short usage summary.

Unless otherwise noted, input is taken from stdin, and output sent to stdout. The extension `.rtp` is suggested for files generated in `rtpdump -F dump` format.

## rtpplay

`rtpplay` [-T] [-v] [-f file] [-p profile] destination/port/[ttl]

`rtpplay` reads RTP session data, recorded by `rtpdump -F dump` from either the file or stdin, if file is not specified, sending it to network address destination and port port with a time-to-live value of ttl. If the flag `-T` is given, the timing between packets corresponds to the arrival timing rather than the RTP timestamps. Otherwise, for RTP data packets, the timing given by the RTP timestamps is used, smoothing interarrival jitter and restoring packet sequence. RTCP packets are still sent with their original timing. This may cause the relative order of RTP and RTCP packets to be changed.

The RTP clock frequency is read from the profile file if given; the default profile (RFC 1890) is used if not. The profile file contains lines with two fields each: the first is the numeric payload type, the second the clock frequency. The values read from the profile file are silently ignored if the `-T` flag is used.

If you want to loop a particular file, it is easiest to put the `rtpplay` command in a shell script.

The `-v` flag has rtpplay display the packets generated on stdout.

`rtpplay` uses the `hsearch (3C)` library, which may not be available on all operating systems.

## rtpdump

`rtpdump` -F format -t duration -x bytes -f file address/port

rtpdump listens on the address and port pair for RTP and RTCP packets and dumps a processed version to stdout. If file is specified, that is used instead. If no network address is given, file input is expected from stdin. The file must have been recorded using the rtpdump `dump` format. Supported formats are:

`format` | text/binary | description
--- | --- | ---
`dump` | binary | dump in binary format, suitable for rtpplay. The format is as follows: The file starts with `#!rtpplay1.0` address/port\n The version number indicates the file format version, not the version of RTP tools used to generate the file. The current file format version is 1.0. This is followed by one binary header (`RD_hdr_t`) and one `RD_packet_t` structure for each received packet. All fields are in network byte order. The RTP and RTCP packets are recorded as-is.
    typedef struct {
      struct timeval start;  /* start of recording (GMT) */
      u_int32 source;        /* network source (multicast address) */
      u_int16 port;          /* UDP port */
    } RD_hdr_t;

    typedef struct {
      u_int16 length;    /* length of packet, including this header (may
                            be smaller than plen if not whole packet recorded) */
      u_int16 plen;      /* actual header+payload length for RTP, 0 for RTCP */
      u_int32 offset;    /* milliseconds since the start of recording */
    } RD_packet_t;
`header` | like "dump", but don't save audio/video payload
`payload` | only audio/video payload
`ascii` | text | parsed packets (default), suitable for `rtpsend`:
    844525628.240592 RTP len=176 from=131.136.234.103:46196 v=2 p=0 x=0
       cc=0 m=0 pt=5 (IDVI,1,8000) seq=28178 ts=954052737 ssrc=0x124e2b58
    844525628.243123 RTCP len=128 from=139.88.27.43:53154
     (RR ssrc=0x125bd36f p=0 count=1 len=7
    (ssrc=bc64b658 fraction=0.503906 lost=4291428375 last_seq=308007791
      jit=17987961 lsr=2003335488 dlsr=825440558)
     )
     (SDES p=0 count=1 len=23
      (src=0x125bd36f CNAME="yywhy@139.88.27.43" NAME="Michael Baldizzi
      (NASA LeRC)" TOOL="vat-4.0a8" EMAIL="mbaldizzi@lerc.nasa.gov" )
     )
`hex` | like `ascii`, but with hex dump of payload
`rtcp` | like `ascii`, but only RTCP packets
`short` | RTP or vat data in tabular form: [-]time ts [seq], where a - indicates a set marker bit. The sequence number seq is only used for RTP packets.
    844525727.800600 954849217 30667
    844525727.837188 954849537 30668
    844525727.877249 954849857 30669
    844525727.922518 954850177 30670

The duration is measured in minutes. From each packet, only the first bytes of the payload are dumped (only applicable for "dump" and "hex" formats).

## rtpsend

rtpsend sends an RTP packet stream with configurable parameters. This is intended to test RTP features. The RTP or RTCP headers are read from a file, generated by hand, a test program or rtpdump (format "header").

`rtpsend [-l]` [-tttl] [-f file] destination/port

Packets are sent with a time-to-live value ttl. If data is read from a file, the `-l` (loop) flag resends the same sequence of packets again and again.

Parameters may appear in any order, without white space around the equal sign. Lines are continued with initial white space on the next line. Comment lines start with #. strings are enclosed in quotation marks.

     RTP v=<version> m=<marker> pt=<payload type> ts=<time stamp>
       seq=<sequence number> cc=<CSRC count> data=<hex payload>
     RTCP (SDES v=<version>
                  (src=<source> cname="..." name="...")
                  (src=<source> ...)
                )
                (RR v=<version>
                )

## rtptrans

`rtptrans` host/port[/ttl] host/port[/ttl] [...]

rtptrans RTP/RTCP packets arriving from one of the addresses to all other addresses. Addresses can be a multicast or unicast. TTL values for unicast addresses are ignored. (Actually, doesn't check whether packets are RTP or not.)

Additionally, the translator can translate VAT packets into RTP packets. VAT control packets are translated into RTCP SDES packets with a CNAME and a NAME entry. However, this is only intended to be used in the following configuration: VAT packets arriving on a multicast connection are translated into RTP and sent over a unicast link. RTP packets are not (yet) translated into VAT packets and and all packets arriving on unicast links are not changed at all. Therefore, currently mainly the following topology is supported: multicast VAT -> translator -> unicast RTP; and on the way back it should lokk like this multicast VAT <- translator <- unicast VAT. This means that the audio agent on the unicast link should be able use both VAT and RTP.

## Authors

The rtptools were written by Henning Schulzrinne. rtptrans was written by Dorgham Sisalem and enhanced by Steve Casner.

Program history

Last modified 1997-08-08 by Henning Schulzrinne
schulzrinne@cs.columbia.edu