"wis-streamer": An Open Source Streaming Server for the WIS GO7007 Encoder Driver

"wis-streamer" is a standards-compliant RTSP/RTP server application that streams encoded video and audio from the Linux WIS GO7007 driver. This driver supports several low-cost, off-the-shelf hardware video encoder devices, including: The "wis-streamer" application can stream video in MPEG-4 (default), MPEG-1, MPEG-2 or motion-JPEG format, and can stream audio in raw PCM, 8-bit u-law, or MPEG-2 audio format. (It can also, as an option, stream MPEG-2 video and audio in a combined MPEG Transport Stream.)

For open source software for streaming from other hardware encoders - or from pre-encoded files - see the "LIVE555 Streaming Media" software.

-----

Building "wis-streamer" from source code

Note: This application currently requires a Linux version 2.6 (or greater) kernel.

  1. First, download, build and install the WIS GO7007 driver.
  2. Download and build the "LIVE555 Streaming Media" libraries.
  3. Download the "wis-streamer" source code package, and store it in the same directory as the "live" directory that you unpacked and built in the previous step. (I.e., don't store it in the "live" directory, but store it in the directory that contains "live".)
  4. Run:
        cd live
        tar -xzf wis-streamer.tar.gz
        cd wis-streamer
        make
    

-----

Downloading a pre-built "wis-streamer" binary

A pre-built "wis-streamer" executable binary for Linux/x86 is also available. This binary was built for "Fedora" Linux kernel version 2.6.9, and may or may not work on other Linux versions. No support is provided for this binary; if it doesn't work for you, then build the application from source instead.

-----

Running "wis-streamer"

Run
    ./wis-streamer
and the server will initialize with default parameters: unicast streaming; MPEG-4 video (640x480, up to 1.5 Mbps); raw PCM audio (16 bit, 48000 Hz); RTSP server port 8554; assuming a NTSC input source, on input device number 0 (composite video). (See below for how to change these parameters.) If the server initializes correctly, it will then print out a "rtsp://" URL that can be used - by a media player client - to play the stream.

-----

Playing the stream

The stream can be played by a standards-compliant RTSP/RTP media player application. The VLC media player is recommended. On Windows and Mac OS, you can also run QuickTime Player. (Also, the "openRTSP" command-line application can be used to examine the RTSP protocol exchange, and/or record the stream's audio and video data.)

-----

Support

For questions about the "LIVE555 Streaming Media" libraries, and/or the "wis-streamer" source code, use the developers' mailing list: "live-devel@lists.live555.com". (Note that you must subscribe to this mailing list before you can post to it.)

Note, however, that no support is currently provided for the WIS GO70007 encoder driver; please refer to the source code.

-----

Copyright Notice

Note that the "wis-streamer" application uses the "LIVE555 Streaming Media" libraries, whose source code is licensed under the GNU LGPL. Therefore, the "wis-streamer" application is a "Combined Work" that is subject to the conditions of the LGPL, even though the "wis-streamer" source code itself is not licensed under the LGPL. For more information about your obligations under the LGPL, see here.

-----

Command-line options

Input device selection

When "wis-streamer" initializes, it prints out the available input devices. By default, "wis-streamer" reads from 'composite input' (device number 0). To have it read instead from another input device, use the "-i <input-device-number>" option.

By default, the input video source is assumed to be in NTSC format. For other formats, you can specify the input video type using the "-t <video-input-type>" option, e.g. "-t pal". (To see a list of valid video input types, use "-t help".)

If the selected input device is a TV tuner, then add the option "-c <band-name>:<channel-name>" to select a TV channel. (To see a list of valid <band-name>s, use "-c help". To see a list of valid <channel-name>s for a given <band-name>, use "-c <band-name>:help".)


Video output format

The video encoding format can be specified using one of options "-mpeg1", "-mpeg2", "-mpeg4" (the default), or "-mjpeg". Alternatively, use the "-nv" (i.e., 'no video') option to disable video encoding/streaming entirely.

To specify the width and height - in pixels - of the captured video, use the "-w <width>" and "-h <height>" options. (The default values are: <width>=640; <height>=480.)

The "-r <bitrate>" option can be used to specify a maximum video bitrate (in bits-per-second). (The default maximum video bitrate is 1500000 bps - i.e, 1.5 Mbps.)

The "-R <frame-rate>" option can be used to set the video frame rate (in frames-per-second) generated by the encoder hardware. The <frame-rate> parameter can be either a positive integer, or a fraction of the form <numerator>/<denominator> (where <numerator> and <denominator> are both positive integers). The default frame rate is 30000/1001 fps for NTSC, and 25 fps for PAL or SECAM. When it initializes, "wis-streamer" will display the actual frame rate generated by the encoder (which might not be exactly the same as the value that was asked for).


Audio output format

The "-f <sampling-frequency>" option specifies the audio sampling frequency (in Hz). The default value is 48000 Hz.

The streamed audio format can be specified using one of the following options:

By default, the server's audio stream is stereo. To stream in mono instead (thereby halving the audio bitrate), use the "-M" option.

Special notes:


MPEG Transport streaming

As a special case, instead of using the video and audio format options noted above, you can use the "-mpegtransport <audio-bitrate-in-kpbs>" option to specify that the streamed data will be a MPEG Transport Stream, containing MPEG-2 video, and MPEG-2 audio (with the specified bitrate). (If the <audio-bitrate-in-kpbs> parameter is zero, then no audio will be included in the Transport Stream.)


Unicast or multicast streaming

By default, the server streams via unicast. This means that each request (from a client media player) to play the stream causes a new stream to be transmitted, directly to the client. Note, therefore, that the maximum possible number of concurrent clients is limited by your network bandwidth.

Alternatively, if the "-m" option is given, then the server will stream via IP multicast. This means that the server transmits the stream only once, regardless of how many clients have asked to play it. The benefit of IP multicast is that it allows a potentially unlimited number of concurrent clients. The drawback of IP multicast, however, is that most routers do not support multicast by default, so that - in many cases - multicast streaming will not work outside a single LAN.

Special note:

By default, the server uses
source-specific multicast (SSM), using a randomly-chosen SSM IP multicast address. To specify a different multicast address, use the "-A <multicast-address>" option (where <multicast-address> is an IPv4 multicast address, in 'dotted quad' form; IPv6 is not yet supported). If the "-A" option is used without "-m", then 'any-source multicast (ASM)' is used instead of SSM.

By default, when streaming via multicast, the server uses RTP port number 6000 for video, and 6002 for audio. These port numbers can, however, be changed using the "-v <video-RTP-port-number>" and/or "-a <audio-RTP-port-number>" numbers. (When streaming via unicast, arbitrary (ephemeral) RTP port numbers are used.)


Client user authentication

By default, there are no restrictions on who can request to play the stream. However, one or more "-u <username>:<password>" options can be used to specify valid username-password pairs. If this option is used, then the media player client must enter a valid username and password before it can play the stream.

Special note:


Miscellaneous options

-----

Summary of command-line options

-a <audio-RTP-port-number>specify the audio RTP port number (for multicast streaming only)
-A <multicast-address>specify multicast streaming (to the given multicast address)
-aac <bitrate-in-kbps>encode and stream audio as MPEG-4 AAC, with the specified bitrate
-amrencode and stream audio as AMR, with the specified bitrate
-brightness <value>specify the video input brightness
-c <band-name>:<channel-name>specify a TV channel (for a TV tuner input device)
-contrast <value>specify the video input contrast
-D <stream-description-string>specify the stream's textual description (for SDP)
-f <sampling-frequency>specify the audio sampling frequency (in Hz) [default: 48000 Hz]
-h <height>specify the video image height (in pixels) [default: 480]
-hue <value>specify the video input hue
-i <input-device-number>specify the input device number (0: composite video [default]; 1: S-Video; 2: tuner (if present))
-mspecify multicast streaming (using source-specific multicast)
-Mstream audio in mono
-mjpegencode and stream video as motion-JPEG
-mpeg1encode and stream video as MPEG-1
-mpeg2encode and stream video as MPEG-2
-mpeg4encode and stream video as MPEG-4 [default]
-mpegaudio <bitrate-in-kbps>encode and stream audio as MPEG-2, with the specified bitrate
-mpegtransport <audio-bitrate-in-kbps>encode and stream video and audio as MPEG-2 (with the specified audio bitrate), combined into a MPEG Transport Stream
-nadon't stream audio
-nvdon't stream video
-p <RTSP-port-number>specify the RTSP server port number [default: 8554]
-pcmstream audio as raw, 16-bit PCM [default]
-r <bitrate>specify the maximum streamed video bitrate (in bits-per-second) [default: 1500000 bps]
-R <frame-rate>specify the video frame rate (in frames-per-second) [default: 30000/1001 fps for NTSC; 25 fps for PAL or SECAM]
-saturation <value>specify the video input hue
-t <video-input-type>specify the video input type [default: ntsc]
-u <username>:<password>specify a username-password pair for client authentication
-ulawstream audio as 8-bit µ-law PCM
-v <video-RTP-port-number>specify the video RTP port number (for multicast streaming only)
-w <width>specify the video image width (in pixels) [default: 640]

-----


Live Networks, Inc. (LIVE555.COM)