Live Networks logo openRTSP^TM 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 <#basic> * Playing without receiving <#no-receive> * Playing-time options <#playing-time> * Streaming access-controlled sessions <#access-control> * Outputting a ".mov", ".mp4", or ".avi"-format file <#quicktime> * Periodic file output <#periodic-file-output> * 'Trick play' options <#trick-play> * Other options <#other-options> * A note about RealAudio and RealVideo sessions <#real-media> * Source code <#source-code> * Support and customization <#support> * Summary of command-line options <#option-summary> Basic operation The simplest way to run this program is: openRTSP // where // 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 //*" 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 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. To record only the 'application' (e.g., 'metadata') stream, use the "*-L*" option.) In this case, the output audio (or video, or 'application') stream will be written to 'stdout', rather than to a file (unless the "*-P //*" option (see below) is given). Less verbose diagnostic output By default, the program will print out (to 'stderr') each complete RTSP request and response. For /less/ verbose output, use the "*-V*" (upper-case) option. ------------------------------------------------------------------------ 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 //*" 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.) // 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 //" 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 a duration for the stream, then the program will close down the session and exit shortly after (by default, 5 seconds after) this duration elapses. You can change this duration using the "*-d //*" option. If // is positive, it is the total number of seconds of the stream to be played before closing down the session and exiting. If // is negative, then -// 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 "-d 10" means "play the stream(s) for 10 seconds, then exit", and "-d -10" means "play the stream(s) for 35 seconds, then exit". You can also use the "*-D //*" 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 // 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 "-d" and "-D" 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 "-d" and/or "-D" 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 "-d //" and/or "-D //". So, for example, "-c -d 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 // //*" option. (To specify an empty password, use /""/ for //.) 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:////://@//://". (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 //*", "*-h //*" and "*-f //*" 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.) These values are important; if they are not correct, your file might not play at all! Alternatively, if the session's SDP description contains the media-level attribute "a=x-dimensions: //,//", 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: //", 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, H.263/H.263+, and H.264 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.) *Important note:* If you are outputting a ".mov", ".mp4", or ".avi"-format file, you /must/ let "openRTSP" run to completion, or else terminate it cleanly, by signalling it with SIGHUP or SIGUSR1. You /must not/ terminate it using -C, otherwise the output file will not get written properly. ------------------------------------------------------------------------ Periodic file output If the "*-P //*" option is given, than "openRTSP" will output a new file every // seconds. (Each output file's name will include the time range (in seconds) that it represents.) This option can also be used with the "*-q*", "*-4*", and "*-i*" options (for outputting '.mov', '.mp4', and '.avi' files, respectively). In this case, the output files will be written separately, rather than to 'stdout'. ------------------------------------------------------------------------ 'Trick play' options RTSP servers may optionally support 'trick play' operations on a stream - specifically, the ability to seek to a specific time within the stream, and/or the ability to play the stream in fast-forward, slow, or reverse play. Use the "*-s //*" option to request that the stream be started at the // second mark (default: 0.0). Use the "*-z //*" option to request fast-forward play (// > 1.0), slow play (0 < // < 1.0), or reverse play (// < 0.0). (The default value is 1.0: normal play.) It's important to note that many, if not most RTSP servers will not support 'trick play' operations, or may support them for some media types only. The /actual/ // and // chosen by the server will be shown in the server's response to the RTSP "PLAY" command. ------------------------------------------------------------------------ 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 //*" 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 //*" 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.) // 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 // 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" (less 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 input frame data was too large for our 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 100,000 buffer is used, so this situation usually does not occur. (It occurs only for codecs that can have very large frames.) If, however, you see this error message, you can increase the output file buffer size using the "*-b //*" option. Changing the input network socket buffer size You can also use the "*-B //*" 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.) Sending 'keep-alives' to satisfy buggy servers RTSP servers should listen for incoming RTSP "RR" packets (which are sent by all standards-compliant RTSP clients) as an indication that the client is still alive (and therefore, that the session should not be timed-out). Some buggy servers, however, do not do this; they can time out (and close) the session prematurely. To overcome this, you can use the "*-K*" option, which tells the program to periodically send RTSP "OPTIONS" commands to the server, to try to keep it alive. Playing a stream without knowing its "rtsp://" URL Instead of giving the program a "rtsp://" URL on the command line, you can use the "*-R*" or "*-R //*" option. This option tells the program to wait - on the specified port number - for an incoming "REGISTER" RTSP command that specifies the "rtsp://" URL of a stream to play. (If no // is given, then the program will choose a random available port number, and announce it (to 'stderr').) Once the program receives an appropriate request - specifying a "rtsp://" URL - then it will open and stream from that URL, as usual. * As a special feature - if the "reuse_connection" parameter was set in the "REGISTER" command's "Transport:" header - the program will reuse the TCP connection on which it received the "REGISTER" command. This can be useful if the stream's server is behind a firewall or NAT, but this program is run on the public Internet. (In this case, you may also wish to use the *-t* option, to request that the server also send its RTP/RTCP packets on this same TCP connection.) * "REGISTER" is a custom RTSP commands, developed by Live Networks, Inc. It is currently non-standard, but is described in an IETF Internet-Draft . * If you use the "-R" option, then you /should/ also use the "*-k // //*" option, which specifies a username and password that should be used to authenticate the incoming "REGISTER" command. ------------------------------------------------------------------------ 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. 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 options, most of which you probably won't need. (Also, the "openRTSP" code was designed to be a standalone application - rather than being embedded within some other application.) Instead, you should use the "testRTSPClient " application code (also in the "testProgs" directory) as a model. ------------------------------------------------------------------------ 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', unless the "-P //" option is also given) -a play only the audio stream (to 'stdout', unless the "-P //" option is also given) -A // specify the static RTP payload format number of the audio codec to request from the server /("playSIP" only)/ -b // change the output file buffer size -B // change the input network socket buffer size -c play continuously -C Explicitly ask for a multicast stream even if the server's "DESCRIBE" response doesn't specift a multicast address. (Note that not all servers will support this.) /("openRTSP" only)/ -d // specify an explicit duration -D // specify a maximum period of inactivity to wait before exiting -E // request that the server end streaming at the specified absolute time (format: "YYYYMMDDTHHMMSSZ" or "YYYYMMDDTHHMMSS.//Z") (used only with -U// -f // specify the video frame rate (used only with "-q", "-4", or "-i") -F // specify a prefix for each output file name -g // specify a user agent name to use in outgoing requests -h // 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', unless the "-P //" option is also given) -I // specify a particular network interface on which to receive data (currently, IPv4 only) -k // // specify a user name and password that's required to authenticate an incoming "REGISTER" command (used with "-R" only) -K Periodically send a RTSP "OPTIONS" command, to keep the connection alive. (This is useful with buggy servers that don't listen to our periodic RTCP "RR" packets instead.) -l try to compensate for packet losses (used only with "-q", "-4", or "-i") -L play only the 'application' (e.g., 'metadata') stream (to 'stdout', unless the "-P //" option is also given) -m output each incoming frame into a separate file -M // specify the MIME subtype of a dynamic RTP payload format for the audio codec to request from the server /("playSIP" only)/ -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 // specify the client port number(s) -P // write new output files every // seconds -q output a QuickTime '.mov'-format file (to 'stdout', unless the "-P //" option is also given) -Q output 'QOS' statistics about the data stream (when the program exits) -r play the RTP streams, but don't receive them ourself -R (or -R //) Waits for an incoming "REGISTER" command, specifying a "rtsp://" URL to play. This option is used instead of a "rtsp://" URL on the command line. /("openRTSP" only)/ -s // request that the server seek to the specified time (in seconds) before streaming -S // 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 // like "-t", except using RTSP-over-HTTP tunneling. /("openRTSP" only)/ -u // // specify a user name and password for digest authentication -U // request that the server seek to the specified absolute time (format: "YYYYMMDDTHHMMSSZ" or "YYYYMMDDTHHMMSS.//Z") before streaming -v play only the video stream (to 'stdout', unless the "-P //" option is also given) -V print less verbose diagnostic output -w // 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") -z // request that the server scale the stream (fast-forward, slow, or reverse play) ------------------------------------------------------------------------ "LIVE555", "openRTSP", "playSIP", and the Live Networks logo are trademarks of Live Networks, Inc. Valid HTML 4.01!