User Guide¶
Running DVR-Scan¶
After downloading, you should have the dvr-scan
command available on your system from a terminal or command prompt. Try running dvr-scan --help
.
For portable versions, replace dvr-scan
with the path to dvr-scan.exe
in the extracted files on your system.
To extract all motion events from a video, you can start with:
dvr-scan -i video.mp4
This will produce output events in your working directory starting with the prefix video.DSME_
(e.g. video.DSME_0001.avi
). If you want to limit scanning to a particular part of the video frame, you can use the region editor:
dvr-scan -i video.mp4 -r
DVR-Scan should provide good results for most use cases, but can be fine tuned for specific use cases. There are two main categories of these settings: detection and sensitivity, and event parameters.
See the documentation for a complete list of all command-line and configuration file options which can be set. You can also type dvr-scan --help
for an overview of command line options. Lastly, most program options can be set using a config file. DVR-Scan also looks for a dvr-scan.cfg
file in the following locations:
- Windows:
C:/Users/%USERNAME%/AppData/Local/DVR-Scan/dvr-scan.cfg
- Linux:
~/.config/DVR-Scan/dvr-scan.cfg
or$XDG_CONFIG_HOME/dvr-scan.cfg
- OSX:
~/Library/Preferences/DVR-Scan/dvr-scan.cfg
These settings will be used by default each time you run DVR-Scan, unless you override them.
Multiple Videos¶
You can specify multiple input videos as long as they have the same resolution and framerate:
dvr-scan -i video1.mp4 video2.mp4 video*.mp4
Wildcards are also supported:
dvr-scan -i video*.mp4
Note that this will concatenate the videos together in the order they are specified.
This can be undesirable for some types of footage being analyzed. For example, if a folder contains different dashcam footage clips, a significant amount of time can pass between clips (e.g. when the vehicle is shut off). This can result in DVR-Scan generating false events between videos.
To avoid this, you can run DVR-Scan on each video in a loop. For example, on Windows:
for /F %i in ('dir *.mp4 /b') do dvr-scan -i %i
Or on Linux/OSX:
for f in /mnt/videos/*.mp4
do
dvr-scan -i $f
done
Note that multiple inputs also do not support other output modes. You can use ffmpeg
to concatenate all input videos before processing, or use a for-loop as above.
Output Format¶
By default, DVR-Scan uses the OpenCV VideoWriter for video output. This usually requires the output files be in .AVI format of some kind.
DVR-Scan also supports using ffmpeg
to extract motion events. This is done by setting -m
/--output-mode
to ffmpeg
(reencode) or copy
(codec copy mode, may not be frame accurate). For example:
dvr-scan -i video.mp4 -m ffmpeg
You can customize the options passed to ffmpeg
using a config file (see the ffmpeg-input-args
and ffmpeg-output-args
) settings).
Setting output mode to ffmpeg
or copy
has the following caveats:
- inputs that have a variable framerate (VFR) may not be extracted reliably
- input concatenation is not supported
- overlays are not supported
You can customize the options passed to ffmpeg
using a config file (see the ffmpeg-input-args
and ffmpeg-output-args
) settings).
VFR (Variable Framerate)¶
Variable framerate (VFR) video support is still under development and may produce incorrect results.
Variable framerate (VFR) videos are not well supported, but basic functionality does work. Motion detection and event extraction should work correctly with default settings. Note however that calculated timestamps may be incorrect, and extracted footage may playback at the wrong speed.
Frame numbers will be accurate, but timestamps will not. This can yield incorrect results when setting output mode to ffmpeg
or copy
, as well as inaccurate timestamps when using overlays. This issue is tracked on Github. If this workflow is required, you can re-encode the source material into fixed framerate before processing.
Region Editor¶
With the Region Editor, you can limit motion detection to specific areas of the frame. You can launch the region editor by by adding -r
/--region-editor
to the DVR-Scan command:
dvr-scan -i video.mp4 -r
The region editor will open and display a rectangle over the first frame:
You can use the mouse to add or move points when editing regions. Left click to add a new point, or to drag an existing one. Right click (middle on Linux) can be used to delete a point. See controls below for all mouse and keyboard inputs.
Press S
to save the current regions to a file, or O
to load existing ones. When you are ready, press space bar or enter to start processing.
Regions¶
Regions are a set of points creating a closed shape. A rectangle will be created by default for you to modify.
You can use the left mouse button to add a new point (keyboard: A
) and right/middle mouse button (keyboard X
) to delete a point. You can left click to drag existing points. This allows creating complex shapes, such as:
Regions can be created by pressing T
and deleted by pressing G
.
Regions can be selected using the number keys 1
-9
, or by pressing k
/l
to select the previous/next region. Note that only one region can be active at a time (you must select an existing shape to modify it).
Lastly, you can hit M
to view a cutout of the active mask:
Controls¶
Regions¶
Command | Keyboard | Mouse |
---|---|---|
Add Point | A |
Left |
Delete Point | X |
Right Middle |
Add Region | T |
|
Delete Region | G |
|
Select Region | 1 - 9 |
|
Next Region | L |
|
Previous Region | K |
Editor¶
Command | Keyboard | Alt |
---|---|---|
Mask On/Off | M |
|
Start Scan | Space, Enter |
|
Quit | Escape | |
Save | S |
|
Load | O |
|
Undo | Z |
Ctrl + Z |
Redo | Y |
Ctrl + Y |
Print Points | C |
Display¶
Command | Keyboard | Mouse |
---|---|---|
Downscale Increase | W |
|
Downscale Decrease | E |
|
Antialiasing | Q |
|
Window Mode | R |
|
Window Menu | Right |