palantir(1)

NAME
Palantir - a video/audio/data interactive streaming server

SYNOPSIS
palantir [ -d DEV ] [ -c CH ] [ -r FPS ] [ -s NxM ] [ -j QUALITY ] [ -g ] [ -f[FILE] ] [ -a DEV ] [ -m ] [ -x ] [ -C FILE] [ -q ] [ -e ] [ -p BASEPORT[,AUDIOPORT] ] [ -S DEV ] [ -t TIME ] [ -T TIME ] [ -F[FILE] ] [ -V ] [ -P TIME ]

DESCRIPTION
palantir is a streaming server featuring live video, audio and data channels.

The video channel encodes the input of a video4linux device in a sequence of JPEG frames and transmits it as a multipart/x-mixed-replace HTTP stream, which some browsers are able to display natively.

The audio channel is compressed according to the bandwidth-sparing GSM 06.10 standard. Audio communication is bidirectional (clients can talk to the server); only one audio connection at a time is allowed to the server.

Another bidirectional channel is available for user-defined data, which can be used to remotely control devices connected to the server (for example some pan/tilt/zoom hardware) as well as to transmit environmental information to the clients. Again, only one client at a time can send data to the server, but unlike audio, data from the server are available to all connected clients simultaneously. (For a detailed discussion of data input/output see palantir.conf(5).)

Control (i.e. ownership of the bidirectional audio channel and the data transmission channel) is granted on a FIFO basis to clients requesting it; the control period, after which a client is preempted if other requests are pending, has a configurable time length.

Fields of application for palantir range from surveillance to entertainment, industrial process control and site monitoring.

palantir comes with two client applications - a Java applet and a stand-alone Windows client (see "CLIENTS" below). Both can display the live video stream and interact with the server through the data channel. The Windows client can also handle audio communication.

OPTIONS

  VIDEO

-d DEV
    Capture video from device DEV. Default is to capture from /dev/video0.

-c CH
    Capture video from channel CH. The number of available channels depends on the capture device selected; a list of the available channels for a given device is displayed as diagnostic output at startup. For most Bt8x8-based cards, channel 0 is the TV tuner, channel 1 the composite input, and channel 2 the S-Video input. On the other hand, most webcams only provide a single channel; your mileage may vary. Default is to capture from channel 0.

-r FPS
    Set the capture frame rate to FPS frames per second. Currently, this option has only effect with USB cameras supported by the pwc driver.

-s NxM
    Set the frame size to NxM. Due to hardware limitations of the capture device, the actual frame size may differ from the requested one. Most webcams for example allow only a very limited set of capture boxes, while Bt8x8-based cards are usually able to accommodate for a much wider size range. Look for the actual capture size in the diagnostic output, after the first client connection. Default is 320x240.

-j QUALITY
    Set the JPEG compression quality level to QUALITY, expressed on the 0...100 scale recommended by the Independent JPEG Group. Default value is 50.

-g  Capture grayscale frames. This helps reducing video bandwidth (although not dramatically).

-f[FILE]
    Disable video capture. Instead of the video stream, a single JPEG file is sent to clients upon connection, and no further pictures are transmitted. This feature can be used to have clients display some sort of "Camera is offline" notice. Note that audio and data channels are not disabled. Use -F if you want to shut them down too. The name of the JPEG file defaults to '/usr/local/share/palantir/unavail.jpg'. This option allows you to specify an alternate file (note that there must be no space between '-f' and the filename). If -f is specified, all other video options are silently ignored.

  AUDIO

-a DEV
    Capture audio from device DEV (note that the same device is also used for audio playback). Default is to capture from /dev/dsp.

-m  Disable (mute) the audio stream (both directions). The same result can be achieved by specifying Audio Off in the configuration file.

-x  Attempt to set up the sound card mixer automatically. This includes selecting the microphone input as the recording source and setting its volume to 80.

  MISCELLANEOUS

-C FILE
    Read configuration from the given FILE instead of the default configuration file (usually '/usr/local/share/palantir/palantir.conf'). Note that when there is a conflict between the command-line arguments and the arguments in the configuration file, the command-line arguments take precedence.

-q  Run in 'quiet' mode (don't output low-level diagnostic messages).

-e  Force log messages to be written to the standard error output stream even if a log file is specified in the configuration file.

-p BASEPORT,[AUDIOPORT]
    Set the TCP base port to listen on, and optionally the audio port. palantir requires one TCP port for the HTTP stream (which carries video and data channels) and possibly another one for the audio stream. If the audio stream is enabled and the audio port is not explicitly specified, it defaults to the base port + 1. Default base is 3000, which means port 3000 for the HTTP stream and port 3001 for the audio stream.

-S DEV
    Set the serial port device to DEV. palantir will use this serial port to control (and get data from) any external device implementing the Palantir Serial Protocol (typically some pan/tilt/zoom machinery and/or environmental sensors). Default is not to use a serial device.

-t TIME
    Set the duration for control time share. After gaining control, a client will retain it until this timeout period expires. Then, if there is some other control request pending, the client will be preempted. If the control queue is empty, however, the client will keep control indefinitely (until another request occurs). Default is 30 seconds.

-T TIME
    Set the timeout for client connections. After this interval, the client will be forcibly disconnected (regardless of whether it is currently in control or not). Default is to allow indefinitely long connections.

-F[FILE]
    Disable all channels. Instead of the video stream, a single JPEG file is sent to clients upon connection, and no further pictures are transmitted. The name of the JPEG file defaults to '/usr/local/share/palantir/unavail.jpg'. This option allows you to specify an alternate file (note that there must be no space between '-F' and the filename). If -F is specified, all video options are silently ignored. See also -f above (which preserves audio and data channels).

-V  Run the server in "viewer" (or "monitor") mode. A X11 window is displayed, showing the output from the capture source; in this mode, no TCP connections are allowed to the server. Please notice that this feature has to be explicitly requested when compiling the server. If the -V option does not show up among the available ones, and you intend to use the monitor, you will have to recompile the server. Please refer to the source documentation for instructions.

-P TIME
    Performance test mode. Run the server in a tight capture-compress loop of the specified duration (in seconds), log the results and exit. During the test, no client can connect to the server. This option is mainly useful as a diagnostic tool for evaluating the performance of the video capture and compression engine; as such, it is not compatible with other options which disable video capture (-f and -F). Moreover, it forces logging of all levels of diagnostic messages, thus overriding the effect of -q.

CLIENTS
The most basic interface to the video stream is a web browser supporting the multipart/x-mixed-replace HTTP format. The list of such browsers currently includes Netscape, Mozilla and its derivatives, and (on the Macintosh platform only) Internet Explorer. The live stream can be embedded in a HTML page just like any other static image, with something along the line of <IMG SRC="http://hostname:3000">. (Be sure to include the TCP port in the URL - see option -p above, or the TCPPort configuration file directive.)

Keep in mind, however, that this arrangement will likely be prone to latency problems on slow clients: since there is no way for the browser to acknowledge received frames, the server just keeps pushing frames as soon as they are available at the capture device; if the client (due to hardware or connectivity limitations) cannot sustain the server's rate, undelivered frames start accumulating in the server's TCP transmit queue until it gets saturated. From that point on the server is forced to slow its pace, but the queued frames account for an unrecoverable lag between server and client whose extent can be estimated as {TCP transmit queue size in bytes (usually 64K)} / {average frame size in bytes}.

If a connection to palantir is made from a web browser unable to correctly display the stream as an embedded image (e.g. Internet Explorer on the Windows platform), a single frame is delivered and the connection is immediately closed. The same result can be achieved on all browsers by appending "?mode=single" to the server URL, as in <IMG SRC="http://hostname:3000/?mode=single">.

The client applications supplied with palantir acknowledge every frame received from the server, which in turn waits for this confirmation before sending the next frame, in order to keep latency to a minimum. Connections involving these clients are tagged as "closed loop" in the server log.

The Windows client requires no installation; users should be able to download it from the site running palantir and run it at once (possibly after unzipping). It can exploit all the cool features of palantir, including bidirectional audio. The Windows client also allows the video and audio channels to be separately turned on and off, in order to make efficient use of low-bandwith links.

The Java client is somewhat more limited, as it has no audio capabilities, but since it can effectively run on a wide range of Java-enabled platforms it has a much larger potential user base.

The native Linux client pclient, based upon the Qt toolkit, supports the display of multiple streams from different servers in the same window.

The preferred way of deploying the Windows and Java clients to the final user is to have them served by the same host running palantir. (Due to a well-known limitation of Java applets, this is also the only way of having the Java client work.)

The status of the devices connected to the palantir server can be accessed through a web browser by appending the special string "?mode=devices" to the server URL, as in "http://hostname:3000/?mode=devices".

PERFORMANCE
Using a reasonable frame size and quality, a decent frame rate (>1 f/s) can be obtained even on slow analog modem connections, without sacrificing the audio stream.

On a LAN, the maximum achievable frame rate essentially depends on the ability of both server and clients to efficiently compress or uncompress the JPEG frames, and ultimately on the capture hardware speed.

TROUBLESHOOTING
If palantir appears unreachable from outside your LAN, please double-check your firewall configuration. palantir usually listens to ports 3000 and 3001; these can be changed with the -p option or the TCPPort configuration file directive.

SEE ALSO
palantir.conf(5)

AUTHOR
David Santinoli <palantir@santinoli.com>.