live555 streaming media for rtsp rtp/rtcp server

LIVE555 Streaming Media

This code forms a set of C++ libraries for multimedia streaming, using open standard protocols (RTP/RTCP, RTSP, SIP). These libraries - which can be compiled for Unix (including Linux and Mac OS X), Windows, and QNX (and other POSIX-compliant systems) - can be used to build streaming applications. The libraries are already being used to implement applications such as "the " (a RTSP server application), "" and "" (for streaming MP3 audio using RTP/RTCP), and "" (for streaming DVD content using RTP/RTCP/RTSP). The libraries can also be used to stream, receive, and process MPEG, H.263+, DV or JPEG video, and several audio codecs. They can easily be extended to support additional (audio and/or video) codecs, and can also be used to build basic or clients and servers, and have been used to add streaming support to existing media player applications, such as "" and "". (For some specific examples of how these libraries can be used, see the below.)

Source code

The project source code is available - as a ".tar.gz" file - . See for instructions on how to build it.

Mailing list

There is a developers' mailing list: "[e-mail]". Users (or prospective users) of the libraries are encouraged to join this (low-volume) mailing list, and/or to review the mailing list's archives. (You can also search these archives using Google, by adding "site:lists.live555.com" to your search query.) Before posting to the mailing list for the first time, please read the

The primary means of support for these libraries is the "[e-mail]" mailing list described above. (Note that you must first subscribe to the mailing list before you can post to it.)

Are you planning to implement RTP (and/or RTSP or SIP)? Instead of writing your own implementation from scratch, consider using these libraries. They have already been used in many real-world RTP-based applications, and are well-suited for use within embedded systems. The code includes an implementation of RTCP, and can easily be extended (via subclassing) to support new RTP payload types.

1. (including )
4. . (Please read this before posting questions to the mailing list.)

Description

The code includes the following libraries, each with its own subdirectory:

---

UsageEnvironment

The "" and "" classes are used for scheduling deferred events, for assigning handlers for asynchronous read events, and for outputting error/warning messages. Also, the "" class defines the interface to a generic hash table, used by the rest of the code.

These are all abstract base classes; they must be subclassed for use in an implementation. These subclasses can exploit the particular properties of the environment in which the program will run - e.g., its GUI and/or scripting environment.

---

groupsock

The classes in this library encapsulate network interfaces and sockets. In particular, the "" class encapsulates a socket for sending (and/or receiving) multicast datagrams.

---

liveMedia

This library defines a class hierarchy - rooted in the "" class - for a variety of streaming media types and codecs.

---

BasicUsageEnvironment

This library defines (i.e., subclasses) of the "UsageEnvironment" classes, for use in simple, console applications. Read events and delayed operations are handled using a select() loop.

---

testProgs

This directory implements some simple programs that use "BasicUsageEnvironment" to demonstrate how to develop applications using these libraries.

RTSP client

• 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://

SIP client

• is a command-line program (similar to "openRTSP") that makes a call to a SIP session (using a sip: URL), and then (optionally) records the incoming media stream into a file.

RTSP server

• testOnDemandRTSPServer creates a RTSP server that can stream, via RTP unicast, from various types of media file, on demand. (Supported media types include: MPEG-1 or 2 audio or video (elementary stream), including MP3 audio; MPEG-4 video (elementary stream); MPEG Program or Transport streams, including VOB files; DV video; AMR audio; WAV (PCM) audio.) MPEG Transport Streams can also be streamed over raw UDP, if requested - e.g., by a set-top box.

MP3 audio test programs

• testMP3Streamer repeatedly reads from a MP3 audio file (named "test.mp3"), and streams it, using RTP, to the multicast group 239.255.42.42, port 6666 (with RTCP using port 6667). This program also has an (optional) built-in RTSP server.
• testMP3Receiver does the reverse: It reads a MP3/RTP stream (from the same multicast group/port), and outputs the reconstituted MP3 stream to "stdout". It also sends RTCP Reception Reports.
  • Alternatively, the MP3/RTP stream could be played using one of .

MPEG video test programs

• testMPEG1or2VideoStreamer repeatedly reads from a MPEG-1 or 2 video file (named "test.mpg"), and streams it, using RTP, to the multicast group 239.255.42.42, port 8888 (with RTCP using port 8889). This program also has an (optional) built-in RTSP server.
  • By default, the input file is assumed to be a MPEG Video Elementary Stream. If, however, it is a MPEG Program Stream, then you can also insert a demultiplexing filter to extract the Video Elementary Stream. (See "testMPEG1or2VideoStreamer.cpp" for details.)
  • Apple's "" can be used to receive and view this streamed video (provided that it's MPEG-1, not MPEG-2). To use this, have QuickTime Player open the file "testMPEG1or2Video.sdp". (If "testMPEG1or2VideoStreamer's" RTSP server has been enabled, then QuickTime Player can also play the stream using a "rtsp://" URL.)
  • The Open Source "" and "" media players can also be used.
  • RealNetworks' "" can also be used to play the stream. (A recent version is recommended.)
• testMPEG1or2VideoReceiver does the reverse: It reads a MPEG Video/RTP stream (from the same multicast group/port), and outputs the reconstituted MPEG video (elementary) stream to "stdout". It also sends RTCP Reception Reports.
• testMPEG4VideoStreamer repeatedly reads from a MPEG-4 Elementary Stream video file (named "test.m4e"), and streams it using RTP multicast. This program also has a built-in RTSP server.
  • Apple's "" can be used to receive and play this audio stream. To use this, have the player open the session's "rtsp://" URL (which the program prints out as it starts streaming).
  • The Open Source "" and "" media players can also be used.

MPEG audio+video (Program Stream) test programs

• testMPEG1or2AudioVideoStreamer reads a MPEG-1 or 2 Program Stream file (named "test.mpg"), extracts from this an audio and a video Elementary Stream, and streams these, using RTP, to the multicast group 239.255.42.42, port 6666/6667 (for the audio stream) and 8888/8889 (for the video stream). This program also has an (optional) built-in RTSP server.
  • Apple's "" can be used to receive and view this streamed video (provided that it's MPEG-1, not MPEG-2). To use this, have QuickTime Player open the file "testMPEG1or2AudioVideo.sdp". (If "testMPEG1or2VideoStreamer's" RTSP server has been enabled, then QuickTime Player can also play the stream using a "rtsp://" URL.)
  • The Open Source "" and "" media players can also be used.
• testMPEG1or2Splitter reads a MPEG-1 or 2 Program Stream file (named "in.mpg"), and extracts from this an audio and a video Elementary Stream. These two Elementary Streams are written into files named "out_audio.mpg" and "out_video.mpg" respectively.

MPEG audio+video (Transport Stream) test programs

• testMPEG2TransportStreamer reads a MPEG-2 Transport Stream file (named "test.ts"), and streams it, using RTP, to the multicast group 239.255.42.42, port 1234 (with RTCP using port 1235). This program also has an (optional) built-in RTSP server.
  • The Open Source "" media player can be used to play this stream.
• testMPEG1or2ProgramToTransportStream reads a MPEG-1 or 2 Program Stream file (named "in.mpg"), and converts it to an equivalent MPEG Transport Stream file, named "out.ts".

PCM audio test programs

• testWAVAudioStreamer reads from a WAV-format audio file (named "test.wav"), and streams the enclosed PCM audio stream via IP multicast, using a built-in RTSP server.
  • The program supports 8 or 16-bit PCM streams, mono or stereo, at any sampling frequency.
  • Apple's "" can be used to receive and play this audio stream. To use this, have the player open the session's "rtsp://" URL (which the program prints out as it starts streaming).
  • Optionally, 16-bit PCM streams can be converted to 8-bit u-law format prior to streaming. (See "testWAVAudioStreamer.cpp" for instructions on how to do this.)
  • The Open Source "" and "" media players can also be used.

AMR audio test programs

• testAMRAudioStreamer reads from a AMR-format audio file (named "test.amr") - as defined in RFC 3267, section 5 - and streams the enclosed audio stream via IP multicast, using a built-in RTSP server.
  • Apple's "" can be used to receive and play this audio stream. To use this, have the player open the session's "rtsp://" URL (which the program prints out as it starts streaming).

DV video test program

• testDVVideoStreamer reads from a DV video file (named "test.dv"), and streams it via IP multicast, using a built-in RTSP server.
  • At present, we know of no widely-available media player client that can play this stream.

VOB (DVD) streaming test program

• reads one or more ".vob" files (e.g., from a DVD), extracts the audio and video streams, and transmits them using RTP multicast.

Support for server 'trick play' operations on MPEG Transport Stream files

• The applications

Miscellaneous test programs

• testRelay repeatedly reads from a UDP multicast socket, and retransmits ('relays') each packet's payload to a new (multicast or unicast) address and port.
• sapWatch reads and prints SDP/SAP announcements made on the default SDP/SAP directory (224.2.127.254/9875)

---

WindowsAudioInputDevice

This is an implementation of the "liveMedia" library's "AudioInputDevice" abstract class. This can be used by Windows application to read PCM audio samples from an input device.

(This project builds two libraries: "libWindowsAudioInputDevice_mixer.lib", which uses Windows' built-in mixer, and "libWindowsAudioInputDevice_noMixer.lib", which doesn't.)

How to configure and build the code on Unix (including Linux, Mac OS X, QNX, and other Posix-compliant systems)

The source code package can be found (as a ".tar.gz" file) . Use "tar -x" and "gunzip" (or "tar -xz", if available) to extract the package; then cd to the "live" directory. Then run

    ./genMakefiles 

where is your target platform - e.g., "linux" or "solaris" - defined by a "config." file. This will generate a Makefile in the "live" directory and each subdirectory. Then run "make".

• If the "make" fails, you may need to make small modifications to the appropriate "config." file, and then re-run "genMakefiles ". (E.g., you may need to add another "-I" flag to the COMPILE_OPTS definition.)
• If you're using "gcc" version 3.0 or greater: You may also wish to add the -Wno-deprecated flag to CPLUSPLUS_FLAGS.
• Some systems' development tools get upset if the link target name immediately follows the "-o" flag in the Makefile. If this happens to you, you can edit each Makefile to replace each occurrence of ")$" with ") $". You can do this automatically by running

      find . -name 'Makefile' -exec fix-makefile {} \;
  

  (The "fix-makefile" script requires the presence of the "tclsh" shell.)
• Some people (in particular, Solaris users) have reported that the - often called "gmake" - works better than their default, pre-installed version of "make".
• If no "config." file exists for your target platform, then try using one of the existing files as a template.

There's no official 'install' procedure; you can put the "live/" directory wherever you wish - but you must leave it intact. You may wish to do the following:

    rm -rf /usr/lib/live ; cp -r live /usr/lib

How to configure and build the code on Windows

1. Unpack and extract the '.tar.gz' file (using an application such as "WinZip").
2. If the 'tools' directory on your Windows machine is something other than "c:\Program Files\DevStudio\Vc", change the "TOOLS32 =" line in the file "win32config".
3. In a command shell, 'cd' to the "live" directory, and run

       genWindowsMakefiles
   

This will generate - in each subdirectory - a "*.mak" makefile suitable for use by (e.g.) Microsoft Visual Studio.

• Alternatively, if you're starting from a Unix machine, you can generate the Windows Makefiles by running

      ./genWindowsMakefiles
  

  (after - if necessary - changing the "TOOLS32 =" line in the file "win32config", as noted above). Then, copy the "live" directories and its subdirectories (in ASCII mode) to a Windows machine.
• To use these Makefiles from within Visual Studio, use the "Open Workspace" menu command, then (in the file selection dialog) for "Files of type", choose "Makefiles (.mak)". Visual Studio should then prompt you, asking if you want to use this Makefile to set up a new project. Say "OK".
• Note that you will need to build each of the "UsageEnvironment", "groupsock", "liveMedia", and "BasicUsageEnvironment" projects first, before building "testProgs".
• If you wish, you can build the "WindowsAudioInputDevice" project also.
• Doug Kosovic notes: Visual C++ 2003 no longer comes with the old I/O Streams headers iostreams.h et al, or the corresponding library msvcirt.lib. So anybody trying to build the LIVE555 code with VC++ 2003 might find the following useful: A non-sourcecode modification workaround for VC++ 2003 is to copy the missing headers and msvcirt.lib from VC++ 2002. In file 'win32config' add an extra -I switch to COMPILE_OPTS to find the old headers and a -LIBPATH: switch to LINK_OPTS_0 to find msvcirt.lib.
• Eric Flickner contributes some hints for compiling the code under Visual Studio 2005.

If you're using the Borland C++ compiler

The instructions above assume that you use Microsoft Visual Studio (version 5 or greater) as your C++ development environment. If, however, you are using Borland's development tools, then the instructions above are amended as follows:

1. Before running the "genWindowsMakefiles.cmd" script, edit it to replace each occurrence of "win32config" with "win32config.Borland".
2. After running "genWindowsMakefiles", edit each of the new Makefiles by following .

(Please read this before posting questions to the mailing list.)

Source code license

This code is "open source", and is released under the . This allows you to use these libraries (via linking) inside closed-source products. It also allows you to make closed-source binary extensions to these libraries - for instance, to support proprietary media codecs that subclass the existing "liveMedia" class hierarchy. Nonetheless, we hope that subclass extensions of these libraries will also be developed under the LGPL, and contributed for inclusion here. We encourage developers to contribute to the development and enhancement of these libraries.

To do...

• Extend the "liveMedia" library to support even more media types and/or codecs.
• Supply additional "UsageEnvironment" subclassed implementations - e.g., for use with scripted environments, such as Tcl, Python, or Perl.
• Expand the RTCP implementation to support more SDES items (other than just CNAME), and to more completely handle incoming RTCP packets.
• In places the code uses data types such as "unsigned", where instead specific lengths (e.g., 32 bits) are required. The data types should be changed in each such case.
• Fix the "groupsock" implementation so that it could use IPv6 instead of IPv4. (At present, 4-byte addresses are hard-wired into the code in several places.)
• Switch to using ISO-conformant C++ headers (but in such a way that the code can remain portable across both Unix (using gcc) and Windows (using Visual C++)).
• Implement network sockets ("groupsock"s) as "liveMedia" 'sources'. This will make the code for RTP sources more consistent with the rest of the "liveMedia" library, allowing them to be "FramedFilters". (This will make it possible to use synthetic network sockets - e.g., for debugging or simulation.)
• Add support for SRTP ('secure' RTP), and perhaps also RTSP-over-TLS.

Some third-party applications

Several third-party devices and applications have made use of the LIVE555 Streaming Media Software. Here is a list of some of them:

Hardware

• media encoders. (The "" server application - for Linux - can be used to stream from many of these encoders.)
• Elphel (with optional ).
• Network-enabled, RTP-streaming Security Cameras, from RVision
• The , from Linux Media Labs. (A "LIVE555 Streaming Media" software interface to this hardware is available from Live Networks, Inc. For more information, please email "support(at)live555.com".)

Software

• The "" media player.
• The " media player.
• "", from
• "" - a videoconferencing application
• "", from
• " - a SIP IVR application - uses "LIVE555 Streaming Media" code for RTP mixing

If you would like your product (or project) added to this list, please send email to the developers' mailing list.