|
|
openRTSPTMA 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.)
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.)
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.)
You can change this duration using the "-d <duration>" option. If <duration> is positive, it is the total number of seconds of the stream to be played before closing down the session and exiting. If <duration> is negative, then -<duration> 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 <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 "-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 <duration>" and/or "-D <maximum-inter-packet-gap>". 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."
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.)
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.) 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: <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, 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 <control>-C, otherwise the output file will not get written properly.
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'.
Use the "-s <initial-seek-time>" option to request that the stream be started at the <initial-seek-time> second mark (default: 0.0). Use the "-z <scale>" option to request fast-forward play (<scale> > 1.0), slow play (0 < <scale> < 1.0), or reverse play (<scale> < 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 <initial-seek-time> and <scale> chosen by the server will be shown in the server's response to the RTSP "PLAY" command.
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.)
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).
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).
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".
If, however, you see this error message, you can increase the output file buffer size using the "-b <buffer-size>" option.
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.
| -4 | output a '.mp4'-format file (to 'stdout', unless the "-P <interval-in-seconds>" option is also given) |
| -a | play only the audio stream (to 'stdout', unless the "-P <interval-in-seconds>" option is also given) |
| -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 |
| -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 <duration> | specify an explicit duration |
| -D <maximum-inter-packet-gap> | specify a maximum period of inactivity to wait before exiting |
| -E <absolute-seek-end-time> | request that the server end streaming at the specified absolute time (format: "YYYYMMDDTHHMMSSZ" or "YYYYMMDDTHHMMSS.<frac>Z") (used only with -U<initial-absolute-seek-time> |
| -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 |
| -g <user-agent-name> | specify a user agent name to use in outgoing requests |
| -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', unless the "-P <interval-in-seconds>" option is also given) |
| -I <interface-name-or-address> | specify a particular network interface on which to receive data (currently, IPv4 only) |
| -k <username> <password> | 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 <interval-in-seconds>" option is also given) |
| -m | output each incoming frame into a separate file |
| -M <MIME-subtype> | 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 <starting-port-number> | specify the client port number(s) |
| -P <interval-in-seconds> | write new output files every <interval-in-seconds> seconds |
| -q | output a QuickTime '.mov'-format file (to 'stdout', unless the "-P <interval-in-seconds>" 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 <port-number>) | 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 <initial-seek-time> | request that the server seek to the specified time (in seconds) before streaming |
| -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 |
| -U <initial-absolute-seek-time> | request that the server seek to the specified absolute time (format: "YYYYMMDDTHHMMSSZ" or "YYYYMMDDTHHMMSS.<frac>Z") before streaming |
| -v | play only the video stream (to 'stdout', unless the "-P <interval-in-seconds>" option is also given) |
| -V | print less verbose diagnostic output |
| -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") |
| -z <scale> | request that the server scale the stream (fast-forward, slow, or reverse play) |