Skip to content

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.

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.

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:

    --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/
    

  • 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
    

  • 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