| # openRTSPTM ### A command-line RTSP client

"openRTSP" is a command-line program that can be used to open, stream, receive, and (optionally) record media streams that are specified by a RTSP URL - i.e., an URL that begins with rtsp://

(A related program - "playSIP" - can be used to play/record a SIP session.)

- Basic operation
- Playing without receiving
- Playing-time options
- Streaming access-controlled sessions
- Outputting a ".mov", ".mp4", or ".avi"-format file
- Other options
- A note about RealAudio and RealVideo sessions
- Source code
- Support and customization
- Summary of command-line options

## Basic operation

The simplest way to run this program is:

            openRTSP <url>

where <url> is a RTSP URL to open (i.e., beginning with "rtsp://"). The program will open the given URL (using RTSP's "DESCRIBE" command), retrieve the session's SDP description, and then, for each audio/video subsession whose RTP payload format it understands, "SETUP" and "PLAY" the subsession.

The received data for each subsession is written into a separate output file, named according to its MIME type. For example, if the session contains a MPEG-1 or 2 audio subsession (RTP payload type 14) - e.g., MP3 - and a MPEG-1 or 2 video subsession (RTP payload type 32), then each subsession's data will be extracted from the incoming RTP packets and written to files named "audio-MPA-1" and "video-MPV-2" (respectively). (You will probably then need to rename these files - by giving them an appropriate filename extension (e.g., ".mp3" and ".mpg") - in order to be able to play them using common media player tools.)

You can use the "-F <fileName-prefix>" option to add a prefix to the file name that is written for each subsession. (This can be useful if you are running "openRTSP" several times, in the same directory, to read data from different RTSP sessions.)

### Extracting a single stream (to 'stdout')

To record only the audio stream from a session, use the "-a" command-line option. (Similarly, to record only the video stream, use the "-v" option.) In this case, the output audio (or video) stream will be written to 'stdout', rather than to a file.

### More verbose diagnostic output

For more verbose diagnostic output, use the "-V" (upper-case) option. With this option, the program will print out each complete RTSP request and response. This can be useful for figuring out exactly why a "SETUP" or "PLAY" operation failed.

## Playing without receiving

If you want the program to play the RTSP session, but not actually receive it, you can do so by giving the program the "-r" ('don't receive') option. This is useful if you have a separate application (running on the same host) that actually receives the incoming media session(s). (Note that this separate receiving application should also send back RTCP Reception Reports, to ensure that the session doesn't time out.)

If you use the "-r" option to play a unicast session, you'll probably also want to use the "-p <startingPortNumber>" option. This option tells the program which client port numbers to use in the RTSP "SETUP" commands - i.e., which RTP/RTCP ports the server should send to. (Without the "-r" option, the program receives the streams itself, and uses its own ephemeral port numbers for this.) <startingPortNumber> must be an even number.

For example, if the RTSP session consists of an audio and a video subsession (listed in that order in the returned SDP description), then "-p 6666" will cause ports 6666 and 6667 to be used for the audio subsession (6666 for RTP; 6667 for RTCP), and ports 6668 and 6669 to be used for the video subsession (6668 for RTP; 6669 for RTCP).

(If you use the "-r" option to play a multicast session, then you probably won't also need to use the "-p <startingPortNumber>" option, because the SDP description for multicast sessions usually includes a port number to use.)

## Playing-time options

If the SDP description (from the RTSP server) contains a "a=range:npt= ..." attribute specifying an end time, then the program will close down the session and exit shortly after (by default, 5 seconds after) this time elapses.

You can change this end time using the "-e <endTime>" option. If <endTime> is positive, it is the total number of seconds to delay before closing down the session and exiting. If <endTime> is negative, then -<endTime> gives the number of extra seconds to delay after the time specified in the SDP "a=range" attribute. (As noted above, the default value for this extra time is 5 seconds.)

For example, if the SDP description contains "a=range:npt=0-25", then "-e 10" means "play the stream(s) for 10 seconds, then exit", and "-e -10" means "play the stream(s) for 35 seconds, then exit".

You can also use the "-E <maximum-inter-packet-gap>" option to ask that the program shut down if no new incoming RTP (i.e., data) packets are received within a period of at least <maximum-inter-packet-gap> seconds. This option is useful if you are running the program automatically (e.g., from within a script), and wish to allow for the possibility of servers that die unexpectedly. (Note that "-e" and "-E" are different options, and may both be used.)

Note, however, that if the program receives a RTCP "BYE" packet from the source - for every stream in the session - then the program will close down the session and exit immediately, regardless of the use of the "-e" and/or "-E" options.

You can also use the "-c" option to play the media sessions continuously. I.e., after the end time has elapsed, the program starts all over again, by issuing another set of "PLAY" requests. (Note that if you're receiving data (i.e., you don't use the "-r" option), then this means you'll get multiple copies of the data in the output file(s).)

Note that you can combine "-c" with "-e <endTime>" and/or "-E <maximum-inter-packet-gap>". So, for example, "-c -e 10" means "play the stream(s) for 10 seconds, then go back and play them again for another 10 seconds, etc., etc."

## Streaming access-controlled sessions

Some RTSP servers require user authentication (via a name and password) before a session can be streamed. To stream such a session, use the "-u <username> <password>" option. (To specify an empty password, use "" for <password>.) The program authenticates using RTSP "digest authentication"; the password will not get sent in the clear over the net.

Alternatively, you could try including the user name and password inside the URL, as: "rtsp://<username>:<password>@<hostname>:<etc.>". (In this case, though, the password will be sent in the clear over the net. Also, not all servers will accept this type of URL.)

## Outputting a ".mov", ".mp4", or ".avi"-format file

Use the "-q" option to output the received data to 'stdout' in the form of an Apple QuickTime '.mov'-format file. Each received subsession will be have its own track in the output file.

Similarly, the "-4" option produces a '.mp4'-format (i.e., MPEG-4) file.

At present these options are fully supported for only a limited number of codecs. For those codecs that are not fully supported, the program will still store all of its received data into a movie track, but will use a dummy Media Data Atom (named '????') in the Sample Description. (This track will also be disabled.) Before you can play such a track, you will need to edit the file.

If the session contains a video subsession, you should also use the "-w <width>", "-h <height>" and "-f <frame-rate>" options to specify the width and height (in pixels), and frame rate (per-second) of the corresponding video track. (If these options are omitted, then the values width=240 pixels; height=180 pixels; frame-rate=15 are used.)

Alternatively, if the session's SDP description contains the media-level attribute "a=x-dimensions: <width>,<height>", then these values will be used instead (in which case you won't need to use the "-w" and "-h" options). Similarly, if the session's SDP description contains the media-level attribute "a=x-framerate: <frames-per-second>", then this value will be used instead (in which case you won't need to use the "-f" option).

If the resulting QuickTime movie file contains audio and video tracks that are out-of-sync, then you can use the "-y" option to try to generate synchronized audio/video tracks. (This option works by listening for RTCP "Sender Report" packets - containing time synchronization information - for each stream. Some initial, unsynchronized data may end up being discarded.)

The "-H" option will also generate a QuickTime 'hint track' for each audio or video track. This is useful if you later wish to stream the resulting ".mov" or ".mp4" file.

Note: "openRTSP"s support for creating QuickTime format files is rather limited. At present, only PCM (u-law and a-law), MPEG-4, GSM and QCELP (aka. 'PureVoice') audio is supported, and only MPEG-4 and H.263/H.263+ video is supported. (Also, for creating hinted QuickTime format files, QCELP audio is not currently supported.)

The "-i" option produces a '.avi'-format file. (This functionality is not fully-supported. MPEG-1, 2 or 4, JPEG and H.263 video is supported, along with raw PCM or u-law audio. However, MPEG and other audio codecs are not yet supported.)

## Other options

### Notification of data arrival

Use the "-n" option if you wish to be 'notified' (with a console message) when the first data (RTP) packets begin arriving.

### Receiving streamed data via TCP instead of UDP

If you're not receiving any data packets (you can test this using "-n"), then you may be behind a firewall that (stupidly) blocks UDP packets. If this is the case, you can use the "-t" option to request that the RTSP server stream RTP and RTCP data packets over its TCP connection, instead of using UDP packets. (Note that not all RTSP servers support TCP streaming, and that TCP cannot be used to receive multicast streams.)

You should use this option only if you are unable to receive UDP packets, or if you are recording the stream for later playback, and need to do so without packet loss. Streaming over TCP can cause incoming data to be excessively delayed, which is inappropriate if the data is being processed in real time.

Alternatively, you can use the "-T <http-port-number>" option to request that the stream be sent (using TCP) over a "RTSP-over-HTTP tunnel", using the specified HTTP port number. RTSP-over-HTTP tunneling can be useful if you are behind a HTTP-only firewall. (Note, however, that not all RTSP servers support this.)

### Receiving unsupported RTP payload formats

Note: An "RTP payload format" for a codec is a set of rules that define how the codec's media frames are packed within RTP packets. This is usually defined by an IETF RFC (or, for newer payload formats, an IETF Internet-Draft).

By default, the program will ignore any subsession whose RTP payload format it doesn't understand (because, if it doesn't know the RTP payload format, it doesn't know how to extract data from the incoming RTP stream).

However, if an input stream uses a RTP payload format that the program does not support, then you may still be able to receive this data, by using the "-s <byte-offset>" option. This option tells the program to assume that any such unsupported stream uses a very 'simple' RTP payload format, in which the stream's data is packed contiguously into RTP packets, following the RTP header. (In particular, the payload format must not use interleaving.) <byte-offset> specifies the size (in bytes) of any special header that follows the standard RTP header. (This special header is skipped over, and is not interpreted at all.)

For example, if the program didn't already handle PCM u-law audio ("audio/PCMU"; RTP payload format code 0), then you could receive it using the option "-s 0". If the program didn't already handle MPEG audio ("audio/MPEG"; RTP payload format code 14), then you could receive it using the option "-s 4" (because the RTP payload format for MPEG audio, defined in RFC 2250, specifies a (basically useless) 4-byte header at the start of the RTP payload).

### Outputting QOS statistics

Use the "-Q" option to output QOS ("quality of service") statistics about the data stream (when the program exits). These statistics include the (minimum, average, maximum) bitrate, packet loss rate, and inter-packet gap.

The "-Q" option takes an optional <measurement-interval> parameter, which specifies the length of the time intervals - in multiples of 100ms - over which the "minimum, average, maximum" statistics are computed. The default value of this parameter is "10", meaning that these statistics are measured every 1 second (i.e., 10x100ms).

### Outputting server options

By default, the program sends an "OPTIONS" command before sending "DESCRIBE". The purpose of the "OPTIONS" command is ask the server to respond with the list of commands that it supports.

If the "-o" option is given, then the program sends the "OPTIONS" command only. If the "-o" option is given, then all other command-line options - except "-V" (verbose output) - are ignored.

The "-O" option has the opposite effect: It tells the program to not send an "OPTIONS" command prior to sending "DESCRIBE".

### Outputting each frame into a separate file

If the "-m" option is given, each incoming 'frame' will be written into a separate output file. (Note that 'frame' in this case is a discrete unit of data that comes from a 'RTPSource'. For some RTP payload formats (such as motion-JPEG), each file will contain a complete image. For other RTP payload formats (such as MPEG video), each file will contain a smaller unit of data, such as a video header structure, or a frame 'slice'.) To distinguish the output files, each 'frame's presentation time is used in the suffix of the corresponding output file.

### Changing the output file buffer size

If you see an error message "The total received frame size exceeds the client's buffer size", then this indicates that incoming RTP data formed a frame that was too large for this program's output file buffer. By default, a 20 kByte buffer is used, so this situation usually does not occur. (It occurs only for codecs - such as JPEG - that can have very large frames.)

If, however, you see this error message, you can increase the output file buffer size using the "-b <buffer-size>" option.

### Changing the input network socket buffer size

You can also use the "-B <buffer-size>" option to change the size of the input buffer that the underlying operating system uses for network sockets. (You probably won't need to use this option, because the operating system's default buffer size is usually sufficient.)

## A note about RealAudio and RealVideo sessions

Note that this program cannot be used to receive RealAudio and/or RealVideo sessions - even those described by a "rtsp://" URL - because these sessions do not use RTP for transport. (Instead, these sessions use RealNetworks' proprietary "RDT" protocol.)

## Source code

This program uses the "RTSPClient", "MediaSession", "FileSink", "QuickTimeFileSink", and several "*RTPSource" modules from the "liveMedia" library, which is distributed as part of the "LIVE555 Streaming Media" source code package. (Other RTSP clients could readily be built from this code.)

The source code for the program itself is also bundled with this package, as the files "openRTSP.cpp" and "playCommon.cpp", in the "testProgs" directory. See the "LIVE555 Streaming Media" documentation for instructions on how to build this program from source.

Note: If you are looking for an example of how to use the "LIVE555 Streaming Media" code to build your own RTSP/RTP media player client, then the "openRTSP" source code is not the best example to use, because it includes lots of extra 'bells and whistles'. Instead, you should look at the RTSP/RTP client support in the "MPlayer" media player. (Note, in particular, the files "demux_rtp*" in the "libmpdemux" directory.)

## Support and customization

If you are interested in seeing new features added to the program (e.g., support for additional RTP payload formats or QuickTime Media Types), or are interested in customizing this program's functionality and/or embedding it within your own application, please email support(at)live555.com

## Summary of command-line options

(for "openRTSP" and "playSIP")

-4 | output a '.mp4'-format file (to 'stdout')
-a | play only the audio stream
-A <codec-number> | specify the static RTP payload format number of the audio codec to request from the server ("playSIP" only)
-b <buffer-size> | change the output file buffer size
-B <buffer-size> | change the input network socket buffer size
-c | play continuously
-D <MIME-subtype> | specify the MIME subtype of a dynamic RTP payload format for the audio codec to request from the server ("playSIP" only)
-e <endTime> | specify an explicit end time
-E <maximum-inter-packet-gap> | specify a maximum period of inactivity to wait before exiting
-f <frame-rate> | specify the video frame rate (used only with "-q", "-4", or "-i")
-F <fileName-prefix> | specify a prefix for each output file name
-h <height> | specify the video image height (used only with "-q", "-4", or "-i")
-H | output a QuickTime 'hint track' for each audio/video track (used only with "-q" or "-4")
-i | output a '.avi'-format file (to 'stdout')
-l | try to compensate for packet losses (used only with "-q", "-4", or "-i")
-m | output each incoming frame into a separate file
-n | be notified when RTP data packets start arriving
-o | request the server's command options, without sending "DESCRIBE" ("openRTSP" only)
-O | don't request the server's command options; just send "DESCRIBE" ("openRTSP" only)
-p <startingPortNumber> | specify the client port number(s)
-Q | output 'QOS' statistics about the data stream (when the program exits)
-q | output a QuickTime '.mov'-format file (to 'stdout')
-r | play the RTP streams, but don't receive them ourself
-s <byte-offset> | assume a simple RTP payload format (skipping over a special header of the specified size)
-t | stream RTP/RTCP data over TCP, rather than (the usual) UDP. ("openRTSP" only)
-T <http-port-number> | like "-t", except using RTSP-over-HTTP tunneling. ("openRTSP" only)
-u <username> <password> | specify a user name and password for digest authentication
-V | print more verbose diagnostic output
-v | play only the video stream
-w <width> | specify the video image width (used only with "-q", "-4", or "-i")
-y | try to synchronize the audio and video tracks (used only with "-q" or "-4")

"LIVE555", "openRTSP", "playSIP", and the Live Networks logo are trademarks of Live Networks, Inc.