doxygen.h

Go to the documentation of this file.

//
// Copyright (C) 2017 Graeme Walker
// 
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.
// ===
///
/// \file doxygen.h
///
/* \htmlonly */

/*! \mainpage Introduction


What is it?
-----------
VideoTools is software for video surveillance that can record, analyse and
replay images from webcams and network cameras. It runs on Linux and BSD
Unix, and it is licensed as Open Source under the GPLv3.

It can use direcly-attached webcams or network cameras that provide JPEG or
H.264 video streams over HTTP or RTP.

It is not suitable for entertainment or video conferencing applications
because there is no audio or strict time synchronisation.

VideoTools does some of the same things as "ZoneMinder" and other programs,
so check them out too.

How does it work?
-----------------
VideoTools is made up of several co-operating programs that communicate over
the network or through shared-memory channels.

The shared-memory publication channels are used for publishing video from
one program to another running on the same machine. Each channel has one
publisher but any number of subscribers, and once the publisher terminates
the channel is deleted.

The Linux kernel's "V4L" infrastructure is used to communicate with
directly-attached webcams, and standard HTTP or RTSP/RTP protocols are used
to communicate with network cameras. Network cameras must use JPEG or H.264
encoding, and videotools uses the "libav" library to handle the H.264
decoding.

Simple motion detection works by looking for pixels that change by more than
a set amount from one frame to the next, and then counting those pixels to
see if they are more than some threshold number. Motion detection events can
be used to control the recording process, or to raise alarms.

Video streams are recorded to disk with separate files for each video frame,
organised by date and time in a directory hierarchy.

A single "viewer" program is used for displaying video in a window. Web 
browsers can also be used for viewing video served up by the 
`vt-httpserver` web server.

Hardware support
----------------
Hardware support for webcams on Linux is dependent on the V4L framework, and
other websites should give you an idea whether your hardware will work with
V4L. Using the "libv4l" shim library (`./configure --with-libv4l`) might help 
with more obscure webcam data formats.

Network cameras must use either HTTP or RTP. When using HTTP the camera
must return one JPEG image for each HTTP GET, or generate a JPEG image stream 
using the `multipart/x-mixed-replace` content type. When using RTP the camera 
must return video images with JPEG or H.264 encoding.

Build and install
-----------------
The system can be built and installed with the usual rubric:

    ./configure ; make ; sudo make install

Use your favourite package management tool (apt, pkg, or whatever) to install
the following dependencies before running the `configure` script:

+ libav
+ libjpeg
+ xlib
+ libncurses
+ libv4l
+ v4l_compat (BSD)
+ webcamd (BSD)

On some BSD systems you will have to add `CPPFLAGS` and `LDFLAGS` options to the
`configure` command to pick up the header files and libraries installed under
`/usr/local` or `/opt`. Refer to the `INSTALL` file for more information, or
just use the `configure.sh` script instead of `configure`.

If there are missing dependencies the build will still go ahead but some
features will not be available, so please look for warnings in the output
from the `configure` script.

The "start/stop" script, which is normally installed under `/etc/init.d` on
Linux or `/usr/local/etc/rc.d` on BSD, can be used to start up the server
processes, but you must edit its configuration file to tell it exactly what
to run.

On BSD systems enable the start/stop script by adding the following line to
`/etc/rc.conf`:

    videotools_enable="YES"

Instructions for the impatient
------------------------------
+ Use `vt-httpclient` and `vt-webcamplayer` to obtain
video from network cameras and webcams, and send each video stream to its own
publication channel.

+ Forward video streams across the network by running `vt-httpserver`
on one side and `vt-httpclient` on the other. Use
`--channel=<channel>` on the server's command-line and `vt://<address>`
on the client's.

+ Record video to disk by running `vt-recorder` for each channel.
Use a different base directory for each channel, and give each recorder a
control socket.

+ Do motion detection for each channel using `vt-watcher`, and let each
watcher control its channel's recorder via the recorder's control socket.

+ Run `vt-fileplayer` to replay each channel's recordings to a playback
channel. Give each fileplayer a control socket.

+ Run a central `vt-httpserver` web server with `--channel=*` and
`gateway=localhost` on the command-line.

+ Use a web browser with URL paths like `_0`, `_1` etc. to view each channel,
and add `?streaming=1` if your browser supports `multipart/x-mixed-replace`.
Check out the example HTML code for HTML5 streaming techniques and
user-interface ideas.

Getting started
---------------
Once the videotools system is installed you can try out some of the
components by running them from a terminal.

Start with the "fileplayer", and specify a directory that contains some
static picture files:

    vt-fileplayer --fade /usr/share

This should show all the images in succession and then stop. If running
without X Windows then the output will use text characters as pixels filling
the whole terminal, so stand back and squint, and use Control-C to quit.

Then try the "webcamplayer" in its test mode:

    vt-webcamplayer --device=test

This should show window with a test pattern of moving coloured bars.

Next try viewing video from a webcam, or install the Linux "vivi" module if
you do not have a webcam attached:

    sudo modprobe vivi
    vt-webcamplayer --retry=0 --device=/dev/video0

You might need to try different device names (`/dev/video1` etc.) to find the
webcam output. You will need root permissions to install the vivi module.

Then try viewing the webcam video using a web browser. For this you will need
to run the "webcamserver", listening on a free TCP port:

    vt-webcamserver -v --port=8080 --device=/dev/video0

Tell your web browser to connect to the server by putting
`http://127.0.0.1:8080` into the address bar. This should show a static image
from the webcam.

If your web browser supports the `multipart/x-mixed-replace` content type
you can get moving video by adding `/?streaming=1` to the URL in the address 
bar. Alternatively, add `--refresh=1` to the "webcamserver" command-line to 
get a one second refresh:

    vt-webcamserver -v --refresh=1 --port=8080 --device=/dev/video0

Next you can try viewing the output from a network camera, but you will need
to know the full URL for getting JPEG images over HTTP, including any
username and password. If you have this information then just run the
"httpclient" program with the URL on the command-line, eg:

    vt-httpclient -v --viewer http://admin:secret@192.168.0.3/streaming/channels/1/httppreview

Add the `--scale=3` option if the window is too big.

Now try sending video to a publication channel. Use the "httpclient", if
that worked, or use "webcamplayer". In either case add `--channel=camera`:

    vt-httpclient --channel=camera http://...

    vt-webcamplayer --channel=camera --device=demo

View the channel using the "viewer" program:

    vt-viewer camera

Try recording the video from the "camera" channel by running a "recorder",
using `/tmp` as the base directory:

    vt-recorder -v camera /tmp

Check for the recorded images under a sub-directory named after the current
calendar year, and replay the recorded video with the "fileplayer":

    find /tmp/20?? -type f
    vt-fileplayer --loop /tmp/20??

Make sure you kill the recorder before it has a chance to fill up your disk.

Now try doing motion detection on the "camera" channel by running the
"watcher" program:

    vt-watcher -v --viewer camera

You should see a dim, monochrome image with bright green highlights where the
image is changing.

Create a mask file to define which regions of the image are used for motion
detection. Run the "maskeditor" program using the "camera" channel to provide
the base image:

    vt-maskeditor --image-channel=camera /tmp/mask

Use the mouse to define the masked regions and close the window when you
are done. The new mask file can now be used by the "watcher":

    vt-watcher -v --viewer --mask=/tmp/mask camera

You should see the masked areas in dark red, and the motion detection
spots in bright green.

Finally, if you have a network camera that can send over RTP and you know its
URL scheme, try using the "rtspclient" program to encourage it to transmit:

    vt-rtscpclient -v rtsp://admin:secret@192.168.0.3:554/streaming/channels/1

While the "rtspclient" is still running check that you are getting RTP 
packets on UDP port 8000 by using "netcat":

    nc -l -u -4 0 8000 | base64

And then try viewing the RTP video stream using the "rtpserver":

    vt-rtpserver -v --viewer --scale=auto --port=8000

Configuration
-------------
The videotools system is normally configured through the system's `init`
system. For each videotools process that you want to run you should construct
a complete command-line containing all the relevant command-line options.
The options available for each videotools program are described in its `man`
page.

For traditional script-based `init` systems a videotools start/stop script is
installed as `/etc/init.d/videotools` on Linux, and this reads a configuration 
file `/etc/videotools` containing the list of "run" command-lines. Optional
overrides for directory paths etc. are taken from a file
`/etc/defaults/videotools`.

On BSD systems the relevant files are `/etc/rc.d/videotools`,
`/etc/videotools` and `/etc/rc.conf.d/videotools`, but possibly under
`/usr/local` or `/opt`.

As an example, consider a machine with just one webcam that needs to run a
"webcamserver" to capture the video from the webcam and serve it up over
HTTP. Its configuration file would have one "run" line, like this:

    # one webcam serving up jpeg video over http on port 80
    run vt-webcamserver --port 80 /dev/video0

A central file-server machine doing recording, motion detection and
web-serving might look more like this:

    # read from network camera "front" using h.264 encoding over rtp
    run vt-rtspclient --port=8000 --format-file=$RUNDIR/camera.cfg  rtsp://admin:secret@192.168.0.2/streaming/channels/1
    run vt-rtpserver --port=8000 --format-file=$RUNDIR/camera.cfg --scale=auto --channel=front
    
    # read from network camera "rear" using jpeg encoding over http
    run vt-httpclient --channel=rear http://192.168.0.3/streaming/channels/2

    # read from remote webcam "inside" by talking to its webcamserver
    run vt-httpclient --channel=inside vt://rpi.localnet:80

    # record the three video streams to disk
    run vt-recorder --command-socket=$RUNDIR/front.s front $SHAREDIR/front
    run vt-recorder --command-socket=$RUNDIR/rear.s rear $SHAREDIR/rear
    run vt-recorder --command-socket=$RUNDIR/inside.s inside $SHAREDIR/inside

    # motion detection, controlling the recorders
    run vt-watcher --recorder=$RUNDIR/front.s --event-channel=front-events front
    run vt-watcher --recorder=$RUNDIR/rear.s --event-channel=rear-events rear
    run vt-watcher --recorder=$RUNDIR/inside.s --event-channel=inside-events inside

    # alarms from motion detection events
    run vt-alarm front-events /usr/bin/aplay /usr/share/sounds/dog.wav
    run vt-alarm rear-events /usr/local/bin/my-alarm.sh
    run vt-alarm inside-events /usr/bin/wall

    # file players, for replaying recordings
    run vt-fileplayer --channel=front-replay --command-socket=udp://0:3001 $SHAREDIR/front
    run vt-fileplayer --channel=rear-replay --command-socket=udp://0:3002 $SHAREDIR/rear
    run vt-fileplayer --channel=inside-replay --command-socket=udp://0:3003 $SHAREDIR/inside

    # main web server, to allow viewing from a html5 web-browser
    run vt-httpserver --gateway=localhost --port=8080 --dir=$SHAREDIR --channel=*

Viewing
-------
The video passing through a channel can be viewed by simply running the
"viewer" program on the same machine as the channel.

    vt-viewer somechannel

Make sure you are using an account that has permission to access the
channel's shared memory.

If X-Windows is not available then the viewer program will try to display
the images in text mode, using characters as pixels.

To view the video images from a channel on another machine you should use
`ssh -X` (or `ssh -Y` from MacOS).

    ssh -X somebox.localnet vt-viewer somechannel

The "httpserver" program can also be used to serve up video from a channel,
so that it can be viewed using a web browser.

Snapshot images can be extracted from a channel by using the "channel"
utility and then viewed with a graphics program, perhaps after using
ImageMagick tools to change the image format.

    vt-channel --out=temp.dat read somechannel
    convert temp.dat temp.jpg
    gimp temp.jpg

Recording and playback
----------------------
The "recorder" program is used to record video from a publication channel.

For example, to record from the "camera1" channel to a directory tree under
`/data/video`, start up a recorder like this:

    vt-recorder camera1 /data/video/camera1

The "fileplayer" program can be used to play back the recordings for a
particular date:

    vt-fileplayer /data/video/camera1/2017/12/31

Motion detection
----------------
The "watcher" program can be used for motion detection. It monitors video
from one channel and emits motion detection events on another.

The "alarm" program can be used to react to the motion detection events,
perhaps by playing a sound or sending an email.

    vt-watcher --channel=camera1-events camera1
    vt-alarm camera1-events aplay alarm.wav

You will normally need a mask file to inhibit motion detection in certain
parts of the video image.

    vt-maskeditor --image-channel=camera1 camera1-mask.pbm
    vt-watcher --mask=camera1-mask.pbm --viewer --event-channel=camera1-events camera1

The watcher can control the recorder by using the recorder's
`--command-socket` option. Motion detection will then cause the recorder to
start recording in its "fast" mode.

    vt-recorder --command-socket=/var/run/recorder1.s --state=stopped --timeout=20 camera1 /data/video/camera1
    vt-watcher --recorder=/var/run/recorder1.s camera1

There are two main parameters for the motion detection algorithm: "squelch"
and "threshold". Refer to the "watcher" documentation for the details.

Security and privacy
--------------------
Always use firewalls and encrypted tunnels to protect your privacy when
exposed to the public internet. Also consider the following points.

+ Use the `--address` option to restrict the listening ports to a single
network interface.

+ Note that usernames and passwords in URLs on the command-line will be widely
visible on the local machine using `ps`.

+ Operating system resources such as files (excluding pid files), directories,
local-domain sockets, shared memory segments, semaphores etc. are all created
with permissions restricted by the inherited "umask", so make sure that the
umask in the videotools startup script (or equivalent) is set
appropriately.

+ Consider creating a special user group to control access to the videotools
resources more precisely: create a new group and make all the videotools
executables group-suid (for example), and then add user accounts to the group
in order to grant access to the videotools resources. Note that the `--user`
option does not affect resource ownership, although it can indirectly affect
the ownership of files created by an external program run by
`vt-alarm`.

+ Local-domain sockets are created whenever a program subscribes to a
publication channel and these sockets are briefly bound to a filesystem
path of `/tmp/vt-<channel>.<pid>`. However, they can be put in a
more private directory by prefixing the channel name on the subscriber's side
using an extended format of `<dir>/<name>/<channel>`, to give socket paths
of `<dir>/<name>.<pid>`.

+ The `vt-alarm` program uses the `system()` function to execute the program
you specify on the command-line. This provides a lot of flexibility for
output redirection, back-ticks, environment variable substitution etc, but
it also presents a large attack surface if the program's configuration or
run-time environment is compromised.

IPv6
----
IPv6 is used whenever an address uses an IPv6 format or whenever a hostname
resolves to an IPv6 address.

Programs that use the `--port` option for the port number also have an
`--address` option for the network address, so adding `--address=::` will
switch from IPv4 to IPv6 since "::" is the IPv6 wildcard address. Similarly
for programs with a `--command-socket` option the full IPv6 transport address
can be given, so for example using `--command-socket=:::9000` will switch
the socket to IPv6 port 9000.

IPv6 addresses can be used in URLs (eg. `vt-httpclient http://::1:80/x`),
but they will generally also need square brackets to avoid ambiguity with
respect to port numbers, eg.  `http://[fc00::1]/x`.

For hostnames that can resolve to IPv4 or IPv6 addresses the first returned
address is used. (Refer to `getaddrinfo()`'s `AI_ADDRCONFIG` option for more
details.)

RTP multicast features are only relevant to IPv4.

Connections
-----------
When videotools processes start up they usually wait for their primary inputs
to become available, whether that's a webcam device, publication channel, or
network peer; and if that input subsequently disappears then they will go
back to a waiting state. This means that a set of co-operating processes can
be started up without worrying about the order in which they connect to each
other, and it makes is easy to restart individual components without restarting
the whole videotools system.

However, this default behaviour can be modified by `--retry` and `--once`
command-line options: if `--retry=0` is used then the program will exit
immediately if the input resource is not available, and if `--once` is used 
then then any disappearance of a previously active input causes the program to 
exit. These options might be useful if the videotools processes are being 
managed by an "init" system that knows about their resource dependencies, or 
if they are operating in a stable, low-maintenance system where failing fast 
might be desirable.

The connectivity of an established set of local videotools processes can be
deduced from metadata held within publication channels. Each channel has a
small structure describing the publisher process and a set of "slot" 
structures where the channel subscribers register themselves.

Channel metadata can be seen by using the "channel" utility:

    vt-channel -q list | xargs -n1 vt-channel info

The "httpserver" program can also make the channel metadata available across 
the network via the special double-underscore url path ("__"):

    vt-httpserver --port=8080 --channel=\*
    wget -q http://localhost:8080/__ -O channels.json

Troubleshooting
---------------
If you encounter problems then stop all the videotools processes, and then
run only the relevant videotools program from the command-line. Use the the
`--verbose` option to get extra log messages, and do not use the `--daemon`
option. If the problems seem to be related to permissions then run your
tests as "root" by using `sudo` or equivalent.

Add the `--scale` option wherever possible to reduce the image sizes during
your tests. This is particularly important if you see dropped RTP packets or
corrupted H.264 video from the "rtpserver".

Work through the "Getting started" section (above) and vary the steps to get
closer to the problem you are seeing.

Program aborts can cause publication channels to become congested or invalid
in some way. Use the "channel" utility to purge or delete them. As a last
resort carefully remove files from the `/dev/shm` directory (Linux only and
at your own risk), or reboot.

    vt-channel list
    vt-channel purge somechannel
    vt-channel delete somechannel

Problems with USB webcams can sometimes be resolved by unplugging them and
the plugged them back in, particularly if you get weird errors on startup.

Wireshark can be useful for diagnosing network problems and for figuring out
the capabilities of network cameras; the `Analyze->FollowTcpStream` option
can be particularly productive for HTTP.

The "vlc" media player is useful for experimenting with RTSP/RTP.

If you have corruped webcam images then experiment with adding `;fmt=x` to
the device name, where x is a small integer, eg. `/dev/video0;fmt=10`. (Use
a backslash or single-quotes to protect the semi-colon.) Also try building
with and without "libv4l".

If JPEG video over RTP looks really bad then try using the "rtpserver"
program's `--jpeg-table` option.

*/


/*! \page Programs

\tableofcontents

<h1>Programs</h1>

The sections below describe the separate programs that make up the system. Most 
programs support the following common command-line options, and for clarity these are 
listed here only:

<h3>Common options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;help</td><td>shows usage help and exits</td></tr>
    <tr><td>&ndash;&ndash;syslog</td><td>sends logging to the system log</td></tr>
    <tr><td>&ndash;&ndash;daemon</td><td>runs in the background</td></tr>
    <tr><td>&ndash;&ndash;user</td><td>switches to the given user if run as root</td></tr>
    <tr><td>&ndash;&ndash;log-time</td><td>adds timestamps to the logging output</td></tr>
    <tr><td>&ndash;&ndash;pid-file=&lt;path&gt;</td><td>records the process id in a pid file</td></tr>
    <tr><td>&ndash;&ndash;debug</td><td>emits debug-level logging, if compiled in</td></tr>
</table>

\section alarm alarm

Monitors a watcher's output channel and runs an external command on 
each motion-detection event.

For example, an "alarm" process can be used to generate an alarm sound 
when motion detection is triggered, by running an external command 
like "aplay".

If the `--run-as` option is given then the external command runs with
that account's user-id and group-id if possible.

If you need pipes, backticks, file redirection, etc. in your external 
command then add the "--shell" option. Awkward shell escapes can 
avoided by using "--url-decode".

<h3>Usage</h3>
<p><pre class="fragment">vt-alarm [&lt;options&gt;] &lt;event-channel&gt; [&lt;command&gt; [&lt;arg&gt; ...]]</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;threshold=&lt;pixels&gt;</td><td>alarm threshold in pixels per image</td></tr>
    <tr><td>&ndash;&ndash;shell</td><td>use '/bin/sh -c'</td></tr>
    <tr><td>&ndash;&ndash;url-decode</td><td>treat the command as url-encoded</td></tr>
</table>

\section channel channel

A tool for working with publication channels.

The following sub-commands are available: "list" lists all local
publication channels; "info" displays diagnostic information for 
the channel; "read" reads one message from the channel; "peek"
reads the last-available message from the channel without
waiting; "purge" clears subscriber slots if subscribers have 
failed without cleaning up; and "delete" deletes the channel,
in case a publisher fails without cleaning up.

<h3>Usage</h3>
<p><pre class="fragment">vt-channel [&lt;options&gt;] {list|info|purge|delete|peek|read} &lt;channel&gt;</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;all</td><td>include info for unused slots</td></tr>
    <tr><td>&ndash;&ndash;out=&lt;filename&gt;</td><td>output filename</td></tr>
    <tr><td>&ndash;&ndash;quiet</td><td>fewer warnings</td></tr>
</table>

\section fileplayer fileplayer

Plays back recorded video to a publication channel or into a viewer window.

The directory specified on the command-line is a base directory where the 
video images can be found. 

The base directory can also be specified using the `--root` option, in which 
case the directory on the end of the command-line is just the starting point
for the playback. If the `--rerootable` and `--command-socket` options are
used then the root directory can be changed at run-time by sending an
appropriate `move` command.

In interactive mode (`--interactive`) the ribbon displayed at the bottom of 
the viewer window can be used to move forwards and backwards through the 
day's recording. Click on the ribbon to move within the current day, or click
on the left of the main image to go back to the previous day, or on the right
to go forwards to the next.

The `--skip` option controls what proportion of images are skipped during
playback (speeding it up), and the `--sleep` option can be used to add a 
delay between each displayed image (slowing it down). A negative skip value
puts the player into reverse.

A socket interface (`--command-socket`) can be used to allow another program
to control the video playback. Sockets can be local-domain unix sockets or 
UDP sockets; for UDP the socket should be like `udp://<address>:<port>`, eg. 
`udp://0:20001`. 

Command messages are text datagrams in the form of a command-line, with 
commands including `play`, `move {first|last|next|previous|.|<full-path>}`, 
`ribbon <xpos>` and `stop`. The play command can have options of `--sleep=<ms>`, 
`--skip=<count>`, `--forwards` and `--backwards`. The `move` command can 
have options of `--match-name=<name>` and `--root=<root>`, although
the `--root` option requires `--rerootable` on the program command-line.
Multiple commands in one datagram should be separated by a semi-colon.

The timezone option (`--tz`) affects the ribbon at the bottom of the display 
window so that that the marks on the ribbon can span a local calendar day 
even with UTC recordings. It also changes the start time for each new day 
when navigating one day at a time. A positive timezone is typically used for
UTC recordings viewed at western longitudes.

If multiple recorders are using the same file store with different filename
prefixes then the `--match-name` option can be used to disentangle the
different recorder streams. Note that this is not the recommended because 
it does not scale well and it can lead to crazy-slow startup while looking 
for a matching file. The match name can be changed at run-time by using the
`--match-name` option on a `move` command sent to the command socket.

<h3>Usage</h3>
<p><pre class="fragment">vt-fileplayer [&lt;options&gt;] &lt;directory&gt;</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;viewer</td><td>run a viewer</td></tr>
    <tr><td>&ndash;&ndash;interactive</td><td>respond to viewer mouse events</td></tr>
    <tr><td>&ndash;&ndash;viewer-channel=&lt;channel&gt;</td><td>override the default viewer channel name</td></tr>
    <tr><td>&ndash;&ndash;channel=&lt;channel&gt;</td><td>publish the playback video to the named channel</td></tr>
    <tr><td>&ndash;&ndash;sleep=&lt;ms&gt;</td><td>inter-frame delay time for slower playback</td></tr>
    <tr><td>&ndash;&ndash;skip=&lt;count&gt;</td><td>file skip factor for faster playback</td></tr>
    <tr><td>&ndash;&ndash;command-socket=&lt;path&gt;</td><td>socket for playback commands</td></tr>
    <tr><td>&ndash;&ndash;root=&lt;path&gt;</td><td>base directory</td></tr>
    <tr><td>&ndash;&ndash;rerootable</td><td>allow the root to be changed over the command-socket</td></tr>
    <tr><td>&ndash;&ndash;stopped</td><td>begin in the stopped state</td></tr>
    <tr><td>&ndash;&ndash;loop</td><td>loop back to the beginning when reaching the end</td></tr>
    <tr><td>&ndash;&ndash;scale=&lt;divisor&gt;</td><td>reduce the image size</td></tr>
    <tr><td>&ndash;&ndash;tz=&lt;hours&gt;</td><td>timezone offset for ribbon</td></tr>
    <tr><td>&ndash;&ndash;match-name=&lt;prefix&gt;</td><td>prefix for matching image files</td></tr>
    <tr><td>&ndash;&ndash;monochrome</td><td>convert to monochrome</td></tr>
    <tr><td>&ndash;&ndash;width=&lt;pixels&gt;</td><td>output image width</td></tr>
    <tr><td>&ndash;&ndash;height=&lt;pixels&gt;</td><td>output image height</td></tr>
    <tr><td>&ndash;&ndash;fade</td><td>fade image transitions</td></tr>
</table>

\section httpclient httpclient

Pulls video from a remote HTTP server or network camera and sends it to a 
publication channel or a viewer window.

Uses repeated GET requests on a persistent connection, with each GET request
separated by a configurable time delay (`--request-timeout`). A watchdog 
timer tears down the connection if no data is received for some time and 
then the connection is retried. Watchdog timeouts and peer disconnections 
result in connection retries; connection failures will terminate the 
program only if using `--retry=0`.

The server should normally return a mime type of `image/jpeg`, or 
preferably `multipart/x-mixed-replace` with `image/jpeg` sub-parts.
In the latter case the client only needs to make one GET request and
the server determines the frame rate.

When getting video from a network camera the exact form of the URL to use 
will depend on the camera, so please refer to its documentation or
search the internet for help.

To get video from a remote webcam use the `vt-webcamserver` on the remote
maching and use `vt-httpclient` to pull it across the network.

As a convenience, a URL of `vt://<address>` can be used instead of `http://<address>`
and this is equivalent to `http://<address>/_?streaming=1&type=any`.

<h3>Usage</h3>
<p><pre class="fragment">vt-httpclient [&lt;options&gt;] &lt;http-url&gt;</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;viewer</td><td>run a viewer</td></tr>
    <tr><td>&ndash;&ndash;scale=&lt;divisor&gt;</td><td>reduce the viewer image size</td></tr>
    <tr><td>&ndash;&ndash;viewer-title=&lt;title&gt;</td><td>viewer window title</td></tr>
    <tr><td>&ndash;&ndash;watchdog-timeout=&lt;seconds&gt;</td><td>watchdog timeout (default 20s)</td></tr>
    <tr><td>&ndash;&ndash;request-timeout=&lt;ms&gt;</td><td>time between http get requests (default 1ms)</td></tr>
    <tr><td>&ndash;&ndash;channel=&lt;channel&gt;</td><td>publish to the named channel</td></tr>
    <tr><td>&ndash;&ndash;connection-timeout=&lt;seconds&gt;</td><td>connection timeout</td></tr>
    <tr><td>&ndash;&ndash;retry=&lt;seconds&gt;</td><td>retry failed connections or zero to exit (default 1s)</td></tr>
    <tr><td>&ndash;&ndash;once</td><td>exit when the first connection closes</td></tr>
</table>

\section httpserver httpserver

Reads video from one or more publication channels and makes it available 
over the network using HTTP.

The HTTP client can either request individual images ("client-pull") or
receive a continuous JPEG video stream delivered as a 
`multipart/x-mixed-replace` content type ("server-push").

For server-push add a `streaming=1` parameter to the URL, eg. 
`http://localhost:80/?streaming=1`. This should always be used when the 
client is the `vt-httpclient` program, but be careful when using a browser 
because not all of them support `multipart/x-mixed-replace`, and some of 
them go beserk with "save-as" dialog boxes.

The client-pull model works best with a browser that uses JavaScript code
to generate a continuous stream of GET requests, typically using the 
"Fetch" API.

For browsers that do not have JavaScript or support for `multipart/x-mixed-replace`
a `refresh=1` URL parameter can be used so that the server sends
back static images with a HTTP "Refresh" header, causing the browser to 
repeat the GET requests at intervals. This can also be made the default
behaviour using the `--refresh` command-line option on the server.

A `scale` URL parameter can be used to reduce the size of the images, and
a `type` parameter can be used to request an image format (`jpeg`, `pnm`, or
`raw`, with `jpeg` as the default). The type can also be `any`, which means 
that no image conversion or validation is performed; whatever data is 
currently in the publication channel is served up.

Static files can be served up by using the `--dir` option. Normally any file
in the directory will be served up, but a restricted set of files can be 
specified by using the `--file` option. The `--file-type` option can be used
to give the files' content-type, by using the filename and the content-type 
separated by a colon, eg. `--file-type=data.json:application/json`. The default 
file that is served up for an empty path in the url can be modified by the 
`--default` option, eg. `--default=main.html`.

One or more channel names should normally be specified on the command-line
using the `--channel` option. Clients can select a channel by name by
using URL paths with an underscore prefix (eg. `_foo`, `_bar`); or by index 
by using URL paths like `_0`, `_1`, etc. 

If `--channel=*` is specified then any valid channel name can be used in 
the URL path. This also enables the special `/__` url that returns channel 
information as a JSON structure.

The `--gateway=<host>` option can be used to integrate static web pages
with UDP command sockets; HTTP requests with a `send` parameter of the
form `<port> <message>` are sent as UDP messages to the `--gateway` IP 
address and the specified port.

<h3>Usage</h3>
<p><pre class="fragment">vt-httpserver [&lt;options&gt;]</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;port=&lt;port&gt;</td><td>listening port</td></tr>
    <tr><td>&ndash;&ndash;timeout=&lt;seconds&gt;</td><td>network idle timeout (default 60s)</td></tr>
    <tr><td>&ndash;&ndash;data-timeout=&lt;seconds&gt;</td><td>initial image timeout (default 3s)</td></tr>
    <tr><td>&ndash;&ndash;repeat-timeout=&lt;ms&gt;</td><td>image repeat timeout (default 1000ms)</td></tr>
    <tr><td>&ndash;&ndash;address=&lt;ip&gt;</td><td>listening address</td></tr>
    <tr><td>&ndash;&ndash;dir=&lt;dir&gt;</td><td>serve up static files</td></tr>
    <tr><td>&ndash;&ndash;file=&lt;filename&gt;</td><td>allow serving the named file </td></tr>
    <tr><td>&ndash;&ndash;file-type=&lt;fname:type&gt;</td><td>define the content-type of the the named file </td></tr>
    <tr><td>&ndash;&ndash;default=&lt;fname-or-channel&gt;</td><td>define the default resource</td></tr>
    <tr><td>&ndash;&ndash;channel=&lt;name&gt;</td><td>serve up named video channel</td></tr>
    <tr><td>&ndash;&ndash;gateway=&lt;udp-host&gt;</td><td>act as a http-post-to-udp-command-line gateway</td></tr>
    <tr><td>&ndash;&ndash;refresh=&lt;seconds&gt;</td><td>add a refresh header to http responses by default</td></tr>
</table>

\section maskeditor maskeditor

Creates and edits a mask file that can be used by the `vt-watcher` program.

The `vt-watcher` program analyses a video stream for moving objects, and it uses
a mask file to tell it what parts of the image to ignore.

The mask is edited over the top a background image, and that image can come 
from a static image file or from a publication channel (`--image-channel`).

Click and drag the mouse to create masked areas, and hold the shift key to
revert. The mask file is continuously updated in-place; there is no "save" 
operation.

<h3>Usage</h3>
<p><pre class="fragment">vt-maskeditor [&lt;options&gt;] &lt;mask-file&gt;</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;image-file=&lt;path&gt;</td><td>background image file</td></tr>
    <tr><td>&ndash;&ndash;image-channel=&lt;channel&gt;</td><td>channel for capturing the initial backgound image</td></tr>
    <tr><td>&ndash;&ndash;viewer-channel=&lt;channel&gt;</td><td>override the default viewer channel name</td></tr>
</table>

\section recorder recorder

Reads a video stream from a publication channel and records it to disk.

Individual video frames are stored in a directory tree, organised by date
and time.

Images are recorded as fast as they are received, or once a second, or not 
at all. These are the fast, slow and stopped states.

The state can be changed by sending a `fast`, `slow`, or `stopped` command 
over the recorder's command socket (`--command-socket`).

The fast state is temporary unless the `--timeout` option is set to zero; 
after recording in the fast state for a while the state drops back to the 
previous slow or stopped state. 

The recorder enters the fast state on startup (`--fast`) or when it gets a 
`fast` command over its command socket, typically sent by the `vt-watcher` 
program. On entering the fast state any in-memory images from the last few
seconds are also committed to disk.

A sub-directory called `.cache` is used to hold the recent images that have 
not been commited to the main image store. These files are held open, and 
they should not be accessed externally. When the recorder is triggered
by a `fast` command on the command socket the cached files are moved
into the main image store so that they provide a lead-in to the event
that triggered the recording.

On machines with limited memory the cache size should be tuned so that
there is no disk activity when the recorder is in the "stopped" state.
The cache can be completely disabled by setting the cache size to zero, 
but then there will be no lead-in to recordings triggered by an event.

Use `--fast --timeout=0 --cache-size=0` for continuous recording of a 
channel.

The `--tz` option is the number of hours added to UTC when constructing
file system paths under the base directory, so to get local times at western
longitudes the value should be negative (eg. `--tz=-5`). However, if this 
option is used inconsistently then there is a risk of overwriting or 
corrupting old recordings, so it is safer to use UTC recordings and 
add `--tz` adjustments elsewhere.

Loopback filesystems are one way to put a hard limit on disk usage. On 
Linux do something like this as root 
`dd if=/dev/zero of=/usr/share/recordings.img count=20000`,
`mkfs -t ext2 -F /usr/share/recordings.img`, 
`mkdir /usr/share/recordings`,
`mount -o loop /usr/share/recordings.img /usr/share/recordings`,
add add the mount to `/etc/fstab`.

Individual video streams should normally be recorded into their own directory
tree, but the `--name` option allows multiple video streams to share the same
root directory by adding a fixed prefix to every image filename. However,
this approach does not scale well on playback, so only use it for a very
small number of video streams.

<h3>Usage</h3>
<p><pre class="fragment">vt-recorder [&lt;options&gt;] &lt;input-channel&gt; &lt;base-dir&gt;</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;scale=&lt;divisor&gt;</td><td>reduce the image size</td></tr>
    <tr><td>&ndash;&ndash;command-socket=&lt;path&gt;</td><td>socket for commands</td></tr>
    <tr><td>&ndash;&ndash;file-type=&lt;type&gt;</td><td>file format: jpg, ppm, or pgm</td></tr>
    <tr><td>&ndash;&ndash;timeout=&lt;s&gt;</td><td>fast-state timeout</td></tr>
    <tr><td>&ndash;&ndash;fast</td><td>start in fast state</td></tr>
    <tr><td>&ndash;&ndash;state=&lt;state&gt;</td><td>state when not fast (slow or stopped, slow by default)</td></tr>
    <tr><td>&ndash;&ndash;tz=&lt;hours&gt;</td><td>timezone offset</td></tr>
    <tr><td>&ndash;&ndash;cache-size=&lt;files&gt;</td><td>cache size</td></tr>
    <tr><td>&ndash;&ndash;name=&lt;prefix&gt;</td><td>prefix for all image files (defaults to the channel name)</td></tr>
    <tr><td>&ndash;&ndash;retry=&lt;timeout&gt;</td><td>poll for the input channel to appear</td></tr>
    <tr><td>&ndash;&ndash;once</td><td>exit if the input channel disappears</td></tr>
</table>

\section rtpserver rtpserver

Listens for an incoming RTP video stream and sends it to a local publication 
channel. 

Some network cameras use RTP rather than HTTP because it is more suited to 
high resolution video, especially when using H.264 encoding, and it also 
allows for IP multicasting.

Only the "H264/90000" and "JPEG/90000" RTP payload types are supported by this
server. 

The H.264 video format requires plenty of processing power; if the H.264 
decoding is too slow then packets will be missed and the packet stream
will have too many holes to decode anything. The processing load can 
be reduced by handling only RTP packets that match certain criteria by 
using the `--filter` option, or by using `--scale` and `--monochrome`
to reduce the image resolution after decoding.

Cameras that use RTP will normally be controlled by an RTSP client (such as
`vt-rtspclient`); the RTSP client asks the camera to start sending
its video stream to the address that the RTP server is listening on.

The camera responds to the RTSP request with a "fmtp" string, which describes
the video format for the H.264 video packets. If this information is not
available from within the RTP packet stream itself then it can be passed 
to the rtpserver using the `--format-file` option.

The RTCP protocol is not currently used so the rtpserver only opens one
UDP port for listening, not two. Also be aware that if two rtpservers
are listening on the same UDP port then they will steal packets from
one another and it is likely that both will stop working.

<h3>Usage</h3>
<p><pre class="fragment">vt-rtpserver [&lt;options&gt;]</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;viewer</td><td>run a viewer</td></tr>
    <tr><td>&ndash;&ndash;scale=&lt;divisor&gt;</td><td>reduce the image size (or 'auto')</td></tr>
    <tr><td>&ndash;&ndash;monochrome</td><td>convert to monochrome</td></tr>
    <tr><td>&ndash;&ndash;port=&lt;port&gt;</td><td>listening port</td></tr>
    <tr><td>&ndash;&ndash;channel=&lt;channel&gt;</td><td>publish to the named channel</td></tr>
    <tr><td>&ndash;&ndash;address=&lt;ip&gt;</td><td>listening address</td></tr>
    <tr><td>&ndash;&ndash;multicast=&lt;address&gt;</td><td>multicast group address</td></tr>
    <tr><td>&ndash;&ndash;format-file=&lt;path&gt;</td><td>file to read for the H264 format parameters</td></tr>
    <tr><td>&ndash;&ndash;type=&lt;type&gt;</td><td>process packets of one rtp payload type (eg. 26 or 96)</td></tr>
    <tr><td>&ndash;&ndash;jpeg-table=&lt;ff&gt;</td><td>tweak for jpeg quantisation tables (0,1 or 2)</td></tr>
</table>

\section rtspclient rtspclient

Issues RTSP commands to control network cameras that send out their video 
over RTP with H.264 encoding (RTP/AVP).

The RTSP protocol acts as a "remote control" for video devices, so an RTSP
client is used to ask a camera to send its RTP video stream back to a 
particular pair of UDP ports where the RTP server is listening.

The RTSP client also reports on what video format the camera will send, 
encoded as a "fmtp" string. This information can help the RTP server 
decode the video stream. Use the `--format-file` option to make it
available to the RTP server.

The RTSP protocol is similar to HTTP, and it uses the same URL syntax, with
`rtsp://` instead of `http://` , eg. `rtsp://example.com/channel/1`. The 
format of right hand side of the URL, following the network address, will 
depend on the camera, so refer to its documentation.

The camera should send its video stream for as long as the `vt-rtspclient`
program keeps its session open; once it terminates then the video stream from
the camera will stop.

<h3>Usage</h3>
<p><pre class="fragment">vt-rtspclient [&lt;options&gt;] &lt;rtsp-url&gt;</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;port=&lt;port-port&gt;</td><td>listening port range eg. 8000-8001</td></tr>
    <tr><td>&ndash;&ndash;multicast=&lt;address&gt;</td><td>multicast address eg. 224.1.1.1</td></tr>
    <tr><td>&ndash;&ndash;format-file=&lt;path&gt;</td><td>a file to use for storing the video format string</td></tr>
    <tr><td>&ndash;&ndash;connection-timeout=&lt;seconds&gt;</td><td>connection timeout</td></tr>
    <tr><td>&ndash;&ndash;retry=&lt;seconds&gt;</td><td>retry failed connections or zero to exit (default 1s)</td></tr>
    <tr><td>&ndash;&ndash;once</td><td>exit when the first session closes</td></tr>
</table>

\section socket socket

Sends a command string to a local-domain or UDP socket. 

This can be used with the `vt-fileplayer` and `vt-recorder` programs when using 
their `--command-socket` option.

The socket is a local-domain socket by default, but a UDP network socket 
if the socket name looks like a transport address or if it starts 
with `udp://`.

The standard "netcat" utility (`nc`) can also be used to send messages to
UDP and local-domain sockets.

<h3>Usage</h3>
<p><pre class="fragment">vt-socket &lt;socket&gt; &lt;command-word&gt; [&lt;command-word&gt; ...]</pre></p>


\section viewer viewer

Reads images from a publication channel and displays them in a window. 

The viewer is also used when a parent process such as a the `vt-fileplayer`
needs a display window, and in that case the video is sent over a
private pipe rather than a publication channel and the two file descriptors
are passed on the command-line.

If there is no windowing system then the video images are displayed in the 
terminal using text characters for pixels. It looks better if you stand
back and squint.

Mouse events can be sent to a publication channel by using the `--channel` 
option. The `vt-maskeditor` and `vt-fileplayer` programs use this feature, and 
they have a `--viewer-channel` option to override the name of the publication 
channel used for these mouse events.

A pbm-format mask file can be used to dim fixed regions of the image.
The mask is stretched as necessary to fit the image.

<h3>Usage</h3>
<p><pre class="fragment">vt-viewer [&lt;options&gt;] { &lt;channel&gt; | &lt;shmem-fd&gt; &lt;pipe-fd&gt; }</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;channel=&lt;channel&gt;</td><td>publish interaction events to the named channel</td></tr>
    <tr><td>&ndash;&ndash;scale=&lt;divisor&gt;</td><td>reduce the image size</td></tr>
    <tr><td>&ndash;&ndash;static</td><td>view only the first image</td></tr>
    <tr><td>&ndash;&ndash;mask=&lt;file&gt;</td><td>use a mask file</td></tr>
    <tr><td>&ndash;&ndash;title=&lt;title&gt;</td><td>sets the window title</td></tr>
    <tr><td>&ndash;&ndash;quit</td><td>quit on q keypress</td></tr>
</table>

\section watcher watcher

Performs motion detection on a video stream received over a shared-memory 
publication channel.

If motion detection exceeds some threshold then an event is published on the 
`--event-channel` channel as a json formatted text message. These messages are 
normally read by a `vt-alarm` process that can run other external programs.

Motion detection events can also be used to control a `vt-recorder` process
by sending a `fast` command to the recorder's command socket.

The `--viewer` or `--image-channel` options can be used to visualise the 
motion detection. The viewer window shows in green the pixels that change in 
brightness by more than the "squelch" value, and it also shows in red the 
pixels that are ignored as the result of the mask.

The motion detection algorithm is extremely simple; one video frame is 
compared to the next, and pixels that change their brightness more that the 
squelch value (0..255) are counted up, and if the total count is more than 
the given threshold value then a motion detection event is emitted.

The `--scale` option also has an important effect because it increases the
size of the motion detection pixels (by decreasing the resolution of the 
image), and it affects the interpretation of the threshold value.

Histogram equalisation is enabled with the `--equalise` option and this can
be particularly useful for cameras that loose contrast in infra-red mode.

The command socket, enabled with the `--command-socket` option, accepts
`squelch`, `threshold` and `equalise` commands. Multiple commands can
be sent in one datagram by using semi-colon separators.

The squelch and threshold values have default values that will need
fine-tuning for your camera. This can be done interactively by temporarily
using the `--verbose`, `--viewer` and `--command-socket` options, and then 
sending `squelch`, `threshold` and `equalise` commands to the command socket
with the `vt-socket` tool (eg. `vt-watcher -C cmd --viewer -v <channel>`
and `vt-socket cmd squelch=20\;threshold=1\;equalise=off`).
Adjust the squelch value to eliminate the green highlights when there is 
no motion. Repeat in different lighting conditions.

<h3>Usage</h3>
<p><pre class="fragment">vt-watcher [&lt;options&gt;] &lt;input-channel&gt;</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;log-threshold</td><td>threshold for logging motion detection events</td></tr>
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;viewer</td><td>run a viewer</td></tr>
    <tr><td>&ndash;&ndash;viewer-title=&lt;title&gt;</td><td>viewer window title</td></tr>
    <tr><td>&ndash;&ndash;mask=&lt;file&gt;</td><td>use a mask file</td></tr>
    <tr><td>&ndash;&ndash;scale=&lt;divisor&gt;</td><td>reduce the image size</td></tr>
    <tr><td>&ndash;&ndash;event-channel=&lt;channel&gt;</td><td>publish analysis events to the named channel</td></tr>
    <tr><td>&ndash;&ndash;image-channel=&lt;channel&gt;</td><td>publish analysis images to the named channel</td></tr>
    <tr><td>&ndash;&ndash;recorder=&lt;path&gt;</td><td>recorder socket path</td></tr>
    <tr><td>&ndash;&ndash;squelch=&lt;luma&gt;</td><td>pixel value change threshold (0 to 255) (default 50)</td></tr>
    <tr><td>&ndash;&ndash;threshold=&lt;pixels&gt;</td><td>pixel count threshold in changed pixels per image (default 100)</td></tr>
    <tr><td>&ndash;&ndash;interval=&lt;ms&gt;</td><td>minimum time interval between comparisons (default 250)</td></tr>
    <tr><td>&ndash;&ndash;once</td><td>exit if the watched channel is unavailable</td></tr>
    <tr><td>&ndash;&ndash;equalise</td><td>histogram equalisation</td></tr>
    <tr><td>&ndash;&ndash;command-socket=&lt;path&gt;</td><td>socket for update commands</td></tr>
    <tr><td>&ndash;&ndash;plain</td><td>do not show changed-pixel highlights in output images</td></tr>
    <tr><td>&ndash;&ndash;repeat-timeout=&lt;seconds&gt;</td><td>send events repeatedly with the given period</td></tr>
</table>

\section webcamserver webcamserver

Serves up video images from a local webcam or video capture device over HTTP.

The HTTP client can either request individual images ("client-pull") or
receive a continuous JPEG video stream delivered as a 
`multipart/x-mixed-replace` content type ("server-push"). Refer to the
`vt-httpserver` program for more information.

This program is useful for running on satellite machines in the local network 
that have webcams attached; a central monitoring machine can run `vt-httpclient`
to pull the video stream across the network and onto a local publication 
channel. 

Use `--device=test` or `--device=demo` for testing without an attached 
camera, or on linux use the "vivi" kernel module (`sudo modprobe vivi`).
Device-specific configuration options can be added after the device
name, using a semi-colon separator.

The server will normally poll for the webcam device to come on-line, although
`--retry=0` can be used to disable this behaviour. When the device goes 
off-line again the program will go back to polling, or it will terminate if the
`--once` option is used.

The `--tz` option can be used with `--caption` to adjust the timezone for the
caption timestamp. It is typically a negative number for western longitudes 
in order to show local time.

<h3>Usage</h3>
<p><pre class="fragment">vt-webcamserver [&lt;options&gt;]</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;port=&lt;port&gt;</td><td>listening port</td></tr>
    <tr><td>&ndash;&ndash;caption</td><td>add a timestamp caption</td></tr>
    <tr><td>&ndash;&ndash;caption-text=&lt;text&gt;</td><td>defines the caption text in ascii, with %t for a timestamp</td></tr>
    <tr><td>&ndash;&ndash;timeout=&lt;seconds&gt;</td><td>network idle timeout (default 60s)</td></tr>
    <tr><td>&ndash;&ndash;data-timeout=&lt;seconds&gt;</td><td>initial image timeout (default 3s)</td></tr>
    <tr><td>&ndash;&ndash;repeat-timeout=&lt;ms&gt;</td><td>image repeat timeout (default 1000ms)</td></tr>
    <tr><td>&ndash;&ndash;address=&lt;ip&gt;</td><td>listening address</td></tr>
    <tr><td>&ndash;&ndash;tz=&lt;hours&gt;</td><td>timezone offset for the caption</td></tr>
    <tr><td>&ndash;&ndash;device=&lt;device&gt;</td><td>webcam video device (eg. /dev/video0)</td></tr>
    <tr><td>&ndash;&ndash;refresh=&lt;seconds&gt;</td><td>add a refresh header to http responses by default</td></tr>
    <tr><td>&ndash;&ndash;retry=&lt;timeout&gt;</td><td>poll for the webcam device to appear (default 1s)</td></tr>
    <tr><td>&ndash;&ndash;once</td><td>exit if the webcam device disappears</td></tr>
</table>

\section webcamplayer webcamplayer

Displays or publishes video from a local webcam or video capture device.

If no publication channel is specified then the video is just displayed in 
a window. The published video can be recorded by the `vt-recorder` program
and later played back by `vt-fileplayer`, and it can be analysed by a 
`vt-watcher`.

Use `--device=test` or `--device=demo` for testing without an attached 
camera, or on linux use the "vivi" kernel module (`sudo modprobe vivi`).
Device-specific configuration options can be added after the device
name, using a semi-colon separator.

The program will normally poll for the webcam device to come on-line, although
`--retry=0` can be used to disable this behaviour. When the device goes 
off-line again the program will go back to polling, or it will terminate if the
`--once` option is used.

The `--tz` option can be used with `--caption` to adjust the timezone for 
the caption timestamp. It is typically a negative number for western 
longitudes in order to show local time.

<h3>Usage</h3>
<p><pre class="fragment">vt-webcamplayer [&lt;options&gt;]</pre></p>

<h3>Options</h3>
<table class="options_">
    <tr><td>&ndash;&ndash;verbose</td><td>verbose logging</td></tr>
    <tr><td>&ndash;&ndash;device=&lt;device&gt;</td><td>video device (eg. /dev/video0)</td></tr>
    <tr><td>&ndash;&ndash;caption</td><td>add a timestamp caption</td></tr>
    <tr><td>&ndash;&ndash;caption-text=&lt;text&gt;</td><td>defines the caption text in ascii, with %t for a timestamp</td></tr>
    <tr><td>&ndash;&ndash;viewer</td><td>run a viewer</td></tr>
    <tr><td>&ndash;&ndash;channel=&lt;channel&gt;</td><td>publish to the named channel</td></tr>
    <tr><td>&ndash;&ndash;scale=&lt;divisor&gt;</td><td>reduce the image size</td></tr>
    <tr><td>&ndash;&ndash;tz=&lt;hours&gt;</td><td>timezone offset for the caption</td></tr>
    <tr><td>&ndash;&ndash;monochrome</td><td>convert to monochrome</td></tr>
    <tr><td>&ndash;&ndash;retry=&lt;timeout&gt;</td><td>poll for the device to appear</td></tr>
    <tr><td>&ndash;&ndash;once</td><td>exit if the webcam device disappears</td></tr>
</table>

*/

/*! \namespace G
\short
Low-level classes for o/s services.

Key classes are:
- Path
- FatPipe
- Publisher
- GetOpt
- etc

 */

/*! \namespace GSsl
\short
Stubbed-out TLS/SSL classes.

 */

/*! \namespace GNet
\short
Network classes.

Key classes are:
- Address
- EventHandler
- EventLoop
- Server
- Socket
- Timer

*/

/*! \namespace GX
\short
Xlib classes.

Key classes are:
- Window
- Canvas

*/

/*! \namespace Gr
\short
Static image classes.

Key classes are:
- ImageData
- JpegReader
- PngReader
- ImageDecoder
- Image

*/

/*! \namespace Gv
\short
Video classes.

Key classes are:
- AvcReader
- Capture
- Camera
- ImageInputSource
- ImageOutput
- ViewerWindow

*/

/*! \namespace md5
\short
Standalone MD5 implementation.

Key classes are:
- digest_stream
- digest

*/

/* \endhtmlonly */