JustMotion/README.md

# Motion Watch #

Motion Watch is a video surveillance application that monitors the video feeds
of an IP camera and records only footage that contains motion. The main
advantage of this is reduced storage requirements as opposed to continuous
recording because only video footage of interest is recorded to storage.
The entire app is designed to operate on just one camera but multiple instances
of this app can be used to operate multiple cameras.

### Usage ###

```
Usage: mow <argument>

 -h : display usage information about this application.
 -c : path to the config file(s).
 -v : display the current version.

note: multiple -c config files can be passed, reading from left
      to right. any conflicting values between the files will
      have the latest value from the latest file overwrite the
      the earliest.
```

### Config File ###

The config file is a simple text file that contain parameters that dictate the
behavior of the application. Below is an example of a config file with all
parameters supported and descriptions of each.
```
# Motion Watch config file
#
# note all lines in this config file that starts with a '#' are ignored.
# also note to avoid using empty lines. if you're going to need an empty
# line, start it with a '#'
#
recording_stream = rtsp://1.2.3.4:554/h264
# this is the url to the main stream of the IP camera that will be used
# to record footage.
#
web_root = /var/www/html
# this is the output directory that will be used to store recorded footage
# from the cameras as well as the web interface for the application.
# warning: this will overwrite any existing index.html files so be sure
# to choose a directory that doesn't have an existing website.
#
buff_dir = /tmp
# this application records small clips of the footage from the camera and
# then stores them into this directory. any clips with motion detected in
# them are moved to web_root; if no motion is detected, they are deleted.
# it is highly recommend to use a ramdisk tempfs for this since this
# directory is used for large amounts of writes.
#
cam_name = cam-1
# this is the optional camera name parameter to identify the camera. this
# name will be used to form the directory structure in the web_root as
# well as buff_dir. if not defined, the name of the config file will be
# used.
#
pix_thresh = 150
# this value tells the application how far different the pixels need to be
# before the pixels are actually considered different. think of this as
# pixel diff sensitivity, the higher the value the lesser the sensitivity.
#
frame_gap = 20
# this value is used to tell the application how far in between frames to
# check the pixel diffs for motion. the lower the value, the more frames
# will be checked, however with that comes higher cpu usage.
#
img_thresh = 80000
# this indicates how many pixels need to be different in between frame_gap
# before it is considered motion. any video clips found with frames
# exceeding this value will be moved from buff_dir to web_root.
#
clip_len = 20
# this parameter indicate the amount of seconds to record in each video
# clip from the camera that will be stored and then processed in buff_dir.
#
num_of_clips = 3
# this will tell the application how many video clips should be recorded
# to buff_dir from the camera before the recording loop pauses to do some
# house keeping. by house keeping, it will wait until all motion detection
# threads are finished, reload the config file and then call the post_cmd
# if no motion was detected in any of the video clips.
#
post_cmd = move_the_ptz_camera.py
# this an optional command to run after num_of_clips is met. one great use
# for this is to move a ptz camera to the next position of it's patrol
# pattern. note: the call to this command will be delayed if motion was
# detected.
#
max_days = 15
# this defines the maximum amount of days worth of video clips that is
# allowed to be stored in the web_root. whenever this limit is met, the
# oldest day and all of it's associated video clips will be deleted.
#
max_clips = 30
# this is the maximum amount of video clips that is allowed to be stored
# in web_root per day. whenever this limit is met, the oldest clip is
# deleted.
#
max_log_size = 50000
# this is the maximum byte size of all log files that can be stored in
# web_root. whenever this limit is met, the log file will be deleted and
# then eventually recreated blank.
#
vid_container = mp4
# this is the video file format to use for recording footage from the
# camera. the format support depends entirely on the under laying ffmpeg
# installation.
#
vid_codec = copy
# this is the video codec to use when pulling footage from the camera
# via ffmpeg. the default is "copy" meaning it will just match the codec
# from the camera itself without trans-coding.
#
web_text = #dee5ee
# this can be used to customize the color of the text in the web
# interface. it can be defined as any color understood by html5 standard.
#
web_bg = #485564
# this can be used to customize the background color of the web
# interface. just like web_text, it also follows the html5 standard.
#
web_font = courier
# this will customize the text font family to use in the web interface.
# it is recommended to use mono-spaced font because this is also used to
# display logs and logs are best displayed in mono-spaced font.
```

### Setup/Build/Install ###

This application is currently only compatible with a Linux based operating
systems that are capable of installing opencv. The following 3 scripts make
building and then installing convenient.

```
sh ./setup.sh <--- only need to run this once if compiling for the first
sh ./build.sh      time or if upgrading from the ground up.
sh ./install.sh
```
```
note 1: be sure to run setup.sh and install.sh as root (or use sudo).
note 2: if building from scratch the following scripts will need to
        be run in this order - setup.sh -> build.sh -> install.sh.
```