|
VideoTools
|
|
VideoTools
|
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:
| ––help | shows usage help and exits |
| ––syslog | sends logging to the system log |
| ––daemon | runs in the background |
| ––user | switches to the given user if run as root |
| ––log-time | adds timestamps to the logging output |
| ––pid-file=<path> | records the process id in a pid file |
| ––debug | emits debug-level logging, if compiled in |
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".
vt-alarm [<options>] <event-channel> [<command> [<arg> ...]]
| ––verbose | verbose logging |
| ––threshold=<pixels> | alarm threshold in pixels per image |
| ––shell | use '/bin/sh -c' |
| ––url-decode | treat the command as url-encoded |
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.
vt-channel [<options>] {list|info|purge|delete|peek|read} <channel>| ––all | include info for unused slots |
| ––out=<filename> | output filename |
| ––quiet | fewer warnings |
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.
vt-fileplayer [<options>] <directory>
| ––verbose | verbose logging |
| ––viewer | run a viewer |
| ––interactive | respond to viewer mouse events |
| ––viewer-channel=<channel> | override the default viewer channel name |
| ––channel=<channel> | publish the playback video to the named channel |
| ––sleep=<ms> | inter-frame delay time for slower playback |
| ––skip=<count> | file skip factor for faster playback |
| ––command-socket=<path> | socket for playback commands |
| ––root=<path> | base directory |
| ––rerootable | allow the root to be changed over the command-socket |
| ––stopped | begin in the stopped state |
| ––loop | loop back to the beginning when reaching the end |
| ––scale=<divisor> | reduce the image size |
| ––tz=<hours> | timezone offset for ribbon |
| ––match-name=<prefix> | prefix for matching image files |
| ––monochrome | convert to monochrome |
| ––width=<pixels> | output image width |
| ––height=<pixels> | output image height |
| ––fade | fade image transitions |
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.
vt-httpclient [<options>] <http-url>
| ––verbose | verbose logging |
| ––viewer | run a viewer |
| ––scale=<divisor> | reduce the viewer image size |
| ––viewer-title=<title> | viewer window title |
| ––watchdog-timeout=<seconds> | watchdog timeout (default 20s) |
| ––request-timeout=<ms> | time between http get requests (default 1ms) |
| ––channel=<channel> | publish to the named channel |
| ––connection-timeout=<seconds> | connection timeout |
| ––retry=<seconds> | retry failed connections or zero to exit (default 1s) |
| ––once | exit when the first connection closes |
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.
vt-httpserver [<options>]
| ––port=<port> | listening port |
| ––timeout=<seconds> | network idle timeout (default 60s) |
| ––data-timeout=<seconds> | initial image timeout (default 3s) |
| ––repeat-timeout=<ms> | image repeat timeout (default 1000ms) |
| ––address=<ip> | listening address |
| ––dir=<dir> | serve up static files |
| ––file=<filename> | allow serving the named file |
| ––file-type=<fname:type> | define the content-type of the the named file |
| ––default=<fname-or-channel> | define the default resource |
| ––channel=<name> | serve up named video channel |
| ––gateway=<udp-host> | act as a http-post-to-udp-command-line gateway |
| ––refresh=<seconds> | add a refresh header to http responses by default |
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.
vt-maskeditor [<options>] <mask-file>
| ––verbose | verbose logging |
| ––image-file=<path> | background image file |
| ––image-channel=<channel> | channel for capturing the initial backgound image |
| ––viewer-channel=<channel> | override the default viewer channel name |
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.
vt-recorder [<options>] <input-channel> <base-dir>
| ––verbose | verbose logging |
| ––scale=<divisor> | reduce the image size |
| ––command-socket=<path> | socket for commands |
| ––file-type=<type> | file format: jpg, ppm, or pgm |
| ––timeout=<s> | fast-state timeout |
| ––fast | start in fast state |
| ––state=<state> | state when not fast (slow or stopped, slow by default) |
| ––tz=<hours> | timezone offset |
| ––cache-size=<files> | cache size |
| ––name=<prefix> | prefix for all image files (defaults to the channel name) |
| ––retry=<timeout> | poll for the input channel to appear |
| ––once | exit if the input channel disappears |
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.
vt-rtpserver [<options>]
| ––verbose | verbose logging |
| ––viewer | run a viewer |
| ––scale=<divisor> | reduce the image size (or 'auto') |
| ––monochrome | convert to monochrome |
| ––port=<port> | listening port |
| ––channel=<channel> | publish to the named channel |
| ––address=<ip> | listening address |
| ––multicast=<address> | multicast group address |
| ––format-file=<path> | file to read for the H264 format parameters |
| ––type=<type> | process packets of one rtp payload type (eg. 26 or 96) |
| ––jpeg-table=<ff> | tweak for jpeg quantisation tables (0,1 or 2) |
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.
vt-rtspclient [<options>] <rtsp-url>
| ––verbose | verbose logging |
| ––port=<port-port> | listening port range eg. 8000-8001 |
| ––multicast=<address> | multicast address eg. 224.1.1.1 |
| ––format-file=<path> | a file to use for storing the video format string |
| ––connection-timeout=<seconds> | connection timeout |
| ––retry=<seconds> | retry failed connections or zero to exit (default 1s) |
| ––once | exit when the first session closes |
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.
vt-socket <socket> <command-word> [<command-word> ...]
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.
vt-viewer [<options>] { <channel> | <shmem-fd> <pipe-fd> }| ––verbose | verbose logging |
| ––channel=<channel> | publish interaction events to the named channel |
| ––scale=<divisor> | reduce the image size |
| ––static | view only the first image |
| ––mask=<file> | use a mask file |
| ––title=<title> | sets the window title |
| ––quit | quit on q keypress |
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.
vt-watcher [<options>] <input-channel>
| ––log-threshold | threshold for logging motion detection events |
| ––verbose | verbose logging |
| ––viewer | run a viewer |
| ––viewer-title=<title> | viewer window title |
| ––mask=<file> | use a mask file |
| ––scale=<divisor> | reduce the image size |
| ––event-channel=<channel> | publish analysis events to the named channel |
| ––image-channel=<channel> | publish analysis images to the named channel |
| ––recorder=<path> | recorder socket path |
| ––squelch=<luma> | pixel value change threshold (0 to 255) (default 50) |
| ––threshold=<pixels> | pixel count threshold in changed pixels per image (default 100) |
| ––interval=<ms> | minimum time interval between comparisons (default 250) |
| ––once | exit if the watched channel is unavailable |
| ––equalise | histogram equalisation |
| ––command-socket=<path> | socket for update commands |
| ––plain | do not show changed-pixel highlights in output images |
| ––repeat-timeout=<seconds> | send events repeatedly with the given period |
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.
vt-webcamserver [<options>]
| ––verbose | verbose logging |
| ––port=<port> | listening port |
| ––caption | add a timestamp caption |
| ––caption-text=<text> | defines the caption text in ascii, with t for a timestamp |
| ––timeout=<seconds> | network idle timeout (default 60s) |
| ––data-timeout=<seconds> | initial image timeout (default 3s) |
| ––repeat-timeout=<ms> | image repeat timeout (default 1000ms) |
| ––address=<ip> | listening address |
| ––tz=<hours> | timezone offset for the caption |
| ––device=<device> | webcam video device (eg. /dev/video0) |
| ––refresh=<seconds> | add a refresh header to http responses by default |
| ––retry=<timeout> | poll for the webcam device to appear (default 1s) |
| ––once | exit if the webcam device disappears |
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.
vt-webcamplayer [<options>]
| ––verbose | verbose logging |
| ––device=<device> | video device (eg. /dev/video0) |
| ––caption | add a timestamp caption |
| ––caption-text=<text> | defines the caption text in ascii, with t for a timestamp |
| ––viewer | run a viewer |
| ––channel=<channel> | publish to the named channel |
| ––scale=<divisor> | reduce the image size |
| ––tz=<hours> | timezone offset for the caption |
| ––monochrome | convert to monochrome |
| ––retry=<timeout> | poll for the device to appear |
| ––once | exit if the webcam device disappears |
1.8.6