Documentation¶

`dvr-scan` Options¶

General¶

```
-h, --help
```
Show help message and all options and default values. Will also show any options overriden by your user config file, if set.
```
-V, --version
```
Show version information.
```
-L, --license
```
Show copyright information.

The following options control terminal output:

```
--logfile log.txt
```
File to save (append) log output.
```
-q, --quiet
```
Suppress all console output except for final cutting list.

-v, --verbosity

Set verbosity of output messages, must be one of: debug, info, warning, error

--verbosity info

Input¶

```
-i video.mp4, --input video.mp4
```
Path to input video. May specify multiple input videos so long as they have the same resolution and framerate. Wildcards/globs are supported (e.g. -i folder/*.mp4). Extracted motion events use the filename of the first video only as a prefix.
```
-c settings.cfg, --config settings.cfg
```
Path to config file. If not set, tries to load one automatically from the user settings folder (run dvr-scan --help to see the exact path for your system). See the config file documentation for what options can be specified.
```
--use-pts
```
Use presentation time instead of frame number for timestamps. May improve timestamp accuracy with videos and network streams that may skip frames.

Seeking/Duration¶

All time values can be given as a timecode (HH:MM:SS or HH:MM:SS.nnn), in seconds as a number followed by s (123s or 123.45s), or as number of frames (e.g. 1234).

dvr-scan -i video.mp4 --start-time 00:35:52 --duration 00:05:00

```
-st time, --start-time time
```
Timecode in video to start motion detection from
```
-dt time, --duration time
```
Maximum duration of input to process.
```
-et time, --end-time time
```
Timecode to stop processing input.

Output¶

```
-so, --scan-only
```
Do not save/extract events, only perform motion detection and display results.
```
-d path, --output-dir path
```
Write all output files to path. If not specified, files are written in the working directory.
```
-m mode, --output-mode mode
```
Mode to use for saving motion events. Must be one of:
- ```
opencv
```
  : Use OpenCV for saving motion events. Requires .AVI output format.
- ```
ffmpeg
```
  : Use ffmpeg for saving motion events. Ffmpeg encoder args can be set using a config file (see the ffmpeg-input-args and ffmpeg-output-args options).
- ```
copy
```
  : Same as ffmpeg, but using stream copying mode (no reencoding). Can potentially create inaccurate events due to keyframe placement.
```
-m opencv
```

Multiple input files are not supported when -m/--output-mode is set to ffmpeg or copy. You can use ffmpeg to concatenate all input videos before using DVR-Scan, or run DVR-Scan in a for-loop.

```
-o video.avi, --output video.avi
```
Save all motion events to a single file, instead of the default (one file per event). Only supported with the default output mode (opencv). Requires .avi extension.
```
-mo mask.avi, --mask-output mask.avi
```
Save a video containing the calculated motion mask on each frame. Useful for tuning motion detection. Requires .avi extension.
```
--thumbnails highscore
```
Save a thumbnail of the frame with the highest motion score for each event.

Events¶

All time values can be given as a timecode (HH:MM:SS or HH:MM:SS.nnn), in seconds as a number followed by s (123s or 123.45s), or as number of frames (e.g. 1234).

```
-l time, --min-event-length time
```
Amount of time/frames that must have a motion score above the threshold setting before triggering a new event.
```
--min-event-length 2
```

-tb time, --time-before-event time

Maximum amount of time to include before each event.

--time-before-event 1.5s

```
-tp time, --time-post-event time
```
Maximum amount of time to include after each event. The event will end once no motion has been detected for this period of time.
```
--time-post-event time 2.0s
```

Detection¶

Motion detection can be fine-tuned for specific use cases. When modifying detection options, it can be useful to generate a motion mask (-mo mask.avi) to visually see how DVR-Scan processes the input.

Motion Settings¶

```
-b type, --bg-subtractor type
```
The type of background subtractor to use. Must be one of:
- ```
MOG2
```
  : MOG2 Background Subtractor
- ```
CNT
```
  : CNT Background Subtractor, faster than MOG but uses different method, so may need to adjust threshold/kernel size
- ```
MOG2_CUDA
```
  : Nvidia CUDA®-based version of MOG2. Requires an OpenCV installation that was compiled with CUDA support.
```
--bg-subtractor MOG2
```
```
-t value, --threshold value
```
Minimum amount of motion a frame must have to trigger an event. Lower values are more sensitive to motion, and require less movement to trigger an event. If too high, some movement may not be detected. Setting too low of a threshold can result in false detections. May require adjustment if other motion settings are changed.
```
--threshold 0.15
```
```
-k size, --kernel-size size
```
Noise reduction kernel size, in pixels. Kernel size can be increased to filter out smaller movements from a scene. Must be an odd integer at least 3 or greater. Can also be set to 0 to disable, or -1 to select automatically based on input resolution. Auto sizes are 7 for 1080p or higher, 5 for 720p, and 3 for 480p or lower.
```
--kernel-size 5
```

Regions¶

Detection can be limited to specific regions of the frame. This can be done interactively using the -r/--region-editor flag, or by providing a list (-a/--add-region) or file (-R/--load-region) containing polygon data.

Regions are specified as a list of points (X, Y) forming a closed polygon (shape with at least 3 points). For example, a triangle is defined as 0 0 100 0 50 50. Multiple regions can be combined, and the result can also be saved to a file using -s/--save-region.

Setting a smaller region of interest can improve scanning performance.

```
-r, --region-editor
```
Display region editor before processing. Press H to show controls in your terminal. See the user guide for more details.
```
dvr-scan -i video.mp4 -r
```
```
-a, --add-region
```
Add a region to the scan. Regions are defined by a list of points (min. 3) that enclose the scanning region.
```
dvr-scan -i video.mp4 -a 50 50 100 50 75 75
```
```
-s, --save-region
```
Save region data for this scan. Include all regions added or loaded via command line, and any edits made with the region editor if launched.
```
dvr-scan -i video.mp4 -r -s regions.txt
```

-R, --load-region

Load region data an existing file.

dvr-scan -i video.mp4 -R regions.txt

Frame Processing¶

Using these parameters can reduce the accuracy of motion detection if they are set too high.

```
-df factor, --downscale-factor factor
```
Integer factor to shrink video before processing, to improve performance. For example, if input video resolution is 1024 x 400, and -df=2, each frame is reduced to 512 x 200 before processing. Uses subsampling for downscaling.
```
--downscale-factor 2
```
```
-fs num_frames, --frame-skip num_frames
```
Number of frames to skip after processing a given frame. Improves performance, at expense of frame and time accuracy, and may increase probability of missing motion events. If set, -l/--min-event-length, -tb/--time-before-event, and -tp/--time-post-event will all be scaled relative to the source framerate. Values above 1 or 2 are not recommended.

When using the default output mode (opencv), skipped frames are not included. Set -m/--output-mode to ffmpeg or copy to include all frames from the input video when writing motion events to disk.

Although adjusted for frame skipping, bounding box smoothing may be inconsistent when using frame skipping. Set -bb 0 to disable smoothing.
```
--frame-skip 1
```

Overlays¶

overlay example

Overlays are only supported with the default output mode (-m opencv).

```
-bb, --bounding-box
```
Draw a bounding box around the areas where motion is detected.
An optional amount of time for temporal smoothing can also be specified (e.g. -bb 0.1s). The default smoothing amount is 0.1 seconds. If set to 0 (-bb 0), smoothing is disabled.
The color, thickness, and minimum size can be set with a config file.
```
-tc, --time-code
```
Draw time code of each frame on the top left corner.
Text properties (e.g. color, font size, margin) can be set with a config file.
```
-fm, --frame-metrics
```
Draw frame metrics, including motion score, on the top right corner.
Text properties (e.g. color, font size, margin) can be set with a config file.

Config File¶

Settings are specified one per line as option = value. Lines starting with # are ignored as comments. The dvr-scan.cfg config template can be saved and used as a starting point (it includes the information in this section as comments).

Configuration options are set as option = value, and lines starting with # are ignored as comments. For example:

# This is an example of a DVR-Scan config file.
# Lines starting with # are treated as comments.
time-before-event = 0.5s
time-post-event = 2.0s
bounding-box = yes
bounding-box-color = 0xFF0000

Options¶

```
output-dir
```
Directory to output all created files. If unset, files will be created in the current working directory.
```
output-dir = C:/temp/scanned/
```
```
use-pts
```
Use presentation time instead of frame number for timestamps. May improve timestamp accuracy with videos and network streams that may skip frames.
```
use-pts = yes
```
```
output-mode
```
Method of generating output videos: (scan_only, opencv, ffmpeg, copy). Not all features are supported in all modes.
```
output-mode = opencv
```

Multiple input files are not supported when -m/--output-mode is set to ffmpeg or copy. You can use ffmpeg to concatenate all input videos before using DVR-Scan, or run DVR-Scan in a for-loop.

```
ffmpeg-input-args
```
Arguments added before the input to ffmpeg when output-mode is ffmpeg or copy. Note that -y and -nostdin are always added.
```
ffmpeg-input-args = -v error
```
```
ffmpeg-output-args
```
Encoder parameters used when generating output files when output-mode is ffmpeg. These arguments are added after the input and duration.
```
ffmpeg-output-args = -map 0 -c:v libx264 -preset fast -crf 21 -c:a aac -sn
```
```
opencv-codec
```
Four-letter identifier of the encoder/video codec to use when output-mode is opencv. Must be one of: (XVID, MP4V, MP42, H264).
```
opencv-codec = XVID
```
```
verbosity
```
Verbosity of console output: (debug, info, warning, error).
```
verbosity = info
```
```
quiet-mode
```
Suppress all console output: (yes or no). Only a final comma-separated list of timecodes will be printed if set to yes.
```
quiet-mode = no
```

Events¶

All time values can be given as a timecode: (HH:MM:SS or HH:MM:SS.nnn), in seconds as a number followed by s (123s or 123.45s), or as number of frames: (1234).

```
min-event-length
```
Amount of time which must have motion in each frame to trigger an event.
```
min-event-length = 2
```
```
time-before-event
```
Amount of time to include before a motion event.
```
time-before-event = 1.5s
```
```
time-post-event
```
Amount of time to include after an event.
```
time-post-event = 2.0s
```

Detection¶

The following options control motion detection. A more comprehensive description of each option can be found under the respective command line options.

```
bg-subtractor
```
Type of background subtraction to use: (MOG2, CNT, MOG2_CUDA).
```
bg-subtractor = MOG2
```
```
threshold
```
Threshold representing amount of motion in a frame (or the ROI, if set) for a motion event to be triggered.
```
threshold = 0.15
```
```
max-threshold
```
Scores of this amount or higher are ignored. 255.0 is the maximum score, so values greater than 255.0 will disable the filter.
```
max-threshold = 255.0
```
```
variance-threshold
```
Threshold on the distance between the pixel and the model to decide whether a pixel is well described by the background model. This parameter does not affect the background update.
The threshold is not used by the CNT subtractor.
```
variance-threshold = 16
```
```
kernel-size
```
Size (in pixels) of the noise reduction kernel. Size must be an odd number starting from 3, 0 to disable, or -1 to auto-set based on video resolution.
```
kernel-size = -1
```
```
learning-rate
```
The value between 0 and 1 that indicates how fast the background model is learnt. Negative parameter value makes the algorithm to use some automatically chosen learning rate. 0 means that the background model is not updated at all, 1 means that the background model is completely reinitialized from the last frame.
```
learning-rate = -1
```
```
region-of-interest
```
Region of interest of the form (x, y), (w, h), where x, y is the top left corner, and w, h is the width/height in pixels.
```
region-of-interest = (100, 110), (50, 50)
```
```
downscale-factor
```
Integer factor to shrink video before processing. Values <= 1 imply no downscaling.
```
downscale-factor = 2
```
```
frame-skip
```
Number of frames to skip between processing when looking for motion events.
```
frame-skip = 1
```

Overlays¶

Color values can be specified as either (R,G,B) or in hex as 0xFFFFFF. Time values can be given in seconds as a number followed by s (123s or 123.45s), or as number of frames (e.g. 1234).

Bounding Box

```
bounding-box
```
Enable bounding box: (yes or no).
```
bounding-box = yes
```

bounding-box-color

Box edge color specified as R, G, B.

bounding-box-color = 255, 0, 0

```
bounding-box-thickness
```
Thickness of bounding box, relative to largest edge of input video.
```
bounding-box-thickness = 0.0032
```
```
bounding-box-smooth-time
```
Amount of temporal smoothing to apply (seconds or frames).
```
bounding-box-smooth-time = 0.1s
```
```
bounding-box-min-size
```
Minimum side length of bounding box, relative to largest edge of input video.
```
bounding-box-min-size = 0.032
```

Text Overlays

```
time-code
```
Enable timecode overlay: (yes or no). Draws timecode on top left of each frame.
```
time-code = yes
```
```
frame-metrics
```
Enable frame metrics overlay: (yes or no). Draws frame metrics, including motion score, on top right of each frame.
```
frame-metrics = yes
```
```
text-border
```
Margin from edge in pixels.
```
text-margin = 5
```
```
text-margin
```
Margin from edge in pixels.
```
text-margin = 5
```
```
text-font-scale
```
Scale factor for text size.
```
text-font-scale = 2.0
```

text-font-thickness

Thickness of font (integer values only).

text-font-thickness = 2

text-font-color

Text color specified as R, G, B.

text-font-color = 255, 255, 255

```
text-bg-color
```
Background color specified as R, G, B.
```
text-bg-color = 0, 0, 0
```

Documentation¶

dvr-scan Options¶

General¶

Input¶

Seeking/Duration¶

Output¶

Events¶

Detection¶

Motion Settings¶

Regions¶

Frame Processing¶

Overlays¶

Config File¶

Options¶

Events¶

Detection¶

Overlays¶

Bounding Box

Text Overlays

`dvr-scan` Options¶