[docs] Add user guide

docs/docs.md

@@ -2,7 +2,6 @@
 # :fontawesome-solid-book:Documentation
 
 
-
 ## :fontawesome-solid-terminal:`dvr-scan` Options
 
 ### General
@@ -39,7 +38,7 @@ The following options control terminal output:
     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.
 
  * <b><pre>-c settings.cfg, --config settings.cfg</pre></b>
-    Path to config file. If not set, tries to load one automatically from the user settings folder. See the [config file documentation](#config-file) for details.
+    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](#config-file) for what options can be specified.
 
 #### Seeking/Duration
 
@@ -78,14 +77,13 @@ dvr-scan -i video.mp4 --start-time 00:35:52 --duration 00:05:00
     ```
     </span>
 
+!!! warning "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](https://trac.ffmpeg.org/wiki/Concatenate) *before* using DVR-Scan, or [run DVR-Scan in a for-loop](guide.md#processing-multiple-videos)."
+
  * <b><pre>-o video.avi, --output video.avi</pre></b> 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.
 
  * <b><pre>-mo mask.avi, --mask-output mask.avi</pre></b> 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`).
@@ -203,15 +201,7 @@ TODO - This feature is under development in v1.6. More to come here.
 
 ## :fontawesome-regular-file:Config File
 
-Many of DVR-Scan's options and defaults can be set using a config file.  This page describes all possible config options, but you can also download [the `dvr-scan.cfg` config template](https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/dvr-scan.cfg) as a starting point.
-
-A config file path can be specified via the `-c`/`--config` option. 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`
-
-Run `dvr-scan --help` to see the exact path on your system which will be used (it will be listed under the help text for the `-c`/`--config` option).
+Settings are specified one per line as `option = value`. Lines starting with `#` are ignored as comments. The [`dvr-scan.cfg` config template](https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/dvr-scan.cfg) 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:
 
@@ -226,12 +216,6 @@ bounding-box-color = 0xFF0000
 
 ------------------------------------------------
 
-### Template
-
-You can download [the `dvr-scan.cfg` template](https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.6/dvr-scan.cfg) to use as a starting point for creating a config file from scratch.
-
-------------------------------------------------
-
 ### Options
 
 
@@ -267,6 +251,8 @@ You can download [the `dvr-scan.cfg` template](https://raw.githubusercontent.com
     ```
     </span>
 
+!!! warning "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](https://trac.ffmpeg.org/wiki/Concatenate) *before* using DVR-Scan, or [run DVR-Scan in a for-loop](guide.md#processing-multiple-videos)."
+
  * <b><pre>ffmpeg-input-args</pre></b>
     Arguments added before the input to `ffmpeg` when *output-mode* is *ffmpeg* or *copy*. Note that *-y* and *-nostdin* are always added.
     <span class="dvr-scan-default">

docs/faq.md

@@ -32,9 +32,19 @@ dvr-scan -i folder/*.mp4
 
 ```
 
-You can also specify multiple input video paths, which will be processed in the order they are specified.
+You can also specify multiple paths directly.  Multiple inputs are not supported when `-m`/`--output-mode` is set to `ffmpeg` or `copy`. You can use `ffmpeg` to [concatenate all input videos](https://trac.ffmpeg.org/wiki/Concatenate) *before* using DVR-Scan as a workaround.
 
-Note that multiple input videos are not supported when `-m`/`--output-mode` is set to `ffmpeg` or `copy`. You can use `ffmpeg` to [concatenate all input videos](https://trac.ffmpeg.org/wiki/Concatenate) *before* using DVR-Scan as a workaround.
+Note that DVR-Scan will **concatenate** the videos together **in the order they are specified** (or expanded if using wildcards). 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:
+
+   target="/some/folder"
+   for f in "$target"*
+   do
+      dvr-scan -i $f
+   done
 
 
 ----------------------------------------------------------

docs/guide.md

@@ -0,0 +1,76 @@
+
+# :fontawesome-solid-circle-info: User Guide
+
+## :fontawesome-solid-terminal:Running `dvr-scan`
+
+After installation, you can run DVR-Scan from any terminal or command-prompt.  To start, it helps to have a clip with some motion you can use for testing.  If the video is too long, or motion occurs mid-way through, you can [set the start/end/duration](docs.md#seekingduration) for processing.
+
+DVR-Scan should provide good results for most use cases, but can be fine tuned for specific use cases. For example, DVR-Scan includes some footage before/after the motion event, but this can be disabled (or extended) by changing the [motion event parameters](docs.md#events).  Motion detection parameters, including sensitivity and other processing settings, [can also be configured](#tuning-detection).
+
+See [the documentation](docs.md) 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](docs.md#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.
+
+## Processing 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](https://trac.ffmpeg.org/wiki/Concatenate) before processing, or use a for-loop as above.
+
+## Variable Framerate Videos
+
+Variable framerate videos are not well supported, but some functionality does work.  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](https://github.com/Breakthrough/PySceneDetect/issues/168).  If this workflow is required, you can re-encode the source material into fixed framerate before processing.
+
+
+## :fontawesome-solid-crop-simple:Region Editor
+
+DVR-Scan allows defining a region to limit detection.  For example, on a doorbell camera, you may want to limit detection to only your front porch. DVR-Scan includes a region editor which can be started by including `-r`/`--region-editor`:
+
+    dvr-scan -i video.mp4 -r
+
+This should show a window that appears similar to:
+
+<img alt="region editor startup window" src="../assets/region-editor-start.jpg"/>
+
+Press `H` to print a list of all controls.  Press `S` to save the current regions to a file, or `O` to load existing ones.  Regions can also be set, saved, and loaded [from the command line](docs.md#regions). Regions from the command line also appear in the the region editor, and any edits will be applied before processing.
+
+When you are satisfied with the region, press space bar or enter/return to start processing the video.  Hit escape at any time to quit the program.
+
+### Regions
+
+You can use the left mouse button to add a new point to the current region, or drag existing points.  Points can be deleted by middle clicking (or right-click on Windows).  This allows you to create complex shapes, such as:
+
+<img alt="example of non-rectangular region" src="../assets/region-editor-region.jpg"/>
+
+You can hit `M` to view a cutout of the active mask:
+
+<img alt="example of region mask" src="../assets/region-editor-mask.jpg"/>
+
+A new region can be created by pressing `A`, and the selected region can be deleted by pressing `X`.  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).
+
+<img alt="example of region mask" src="../assets/region-editor-multiple.jpg"/>

docs/index.md

@@ -13,7 +13,7 @@ hide:
 
 !!! success "Latest Version: 1.5.1 (August 15, 2022)"
 
-    <div class="buttongrid">[:fontawesome-solid-download: &nbsp; Download](download.md){ .md-button #download-button }[:fontawesome-solid-book: Documentation](docs.md){ .md-button #changelog-button }[:fontawesome-solid-bars: &nbsp; Changelog](changelog.md){ .md-button #documentation-button }[:fontawesome-solid-gear: &nbsp; Resources](resources.md){ .md-button #quickstart-button }</div>
+    <div class="buttongrid">[:fontawesome-solid-download: &nbsp; Download](download.md){ .md-button #download-button }[:fontawesome-solid-book: User Guide](user_guide.md){ .md-button #changelog-button }[:fontawesome-solid-bars: &nbsp; Documentation](docs.md){ .md-button #documentation-button }[:fontawesome-solid-gear: &nbsp; Resources](changelog.md){ .md-button #quickstart-button }</div>
 
 ------------------------------------------------------
 

dvr_scan/__main__.py

@@ -19,15 +19,13 @@
 import sys
 
 from dvr_scan.cli.controller import parse_settings, run_dvr_scan
-from dvr_scan.cli.config import ConfigLoadFailure
 
 from scenedetect import VideoOpenFailure
 from scenedetect.platform import logging_redirect_tqdm, FakeTqdmLoggingRedirect
 
 EXIT_SUCCESS: int = 0
 EXIT_ERROR: int = 1
 
-
 def main():
     """Main entry-point for DVR-Scan."""
     settings = parse_settings()

dvr_scan/cli/config.py

@@ -350,7 +350,7 @@ def from_config(config_value: str, default: 'RGBValue') -> 'RGBValue':
 The types of these values are used when decoding the configuration file. Valid choices for
 certain string options are stored in `CHOICE_MAP`."""
 
-# TODO: This should be a validator.
+# TODO: This should be a validator. These sub- lists should also be constants somewhere.
 CHOICE_MAP: Dict[str, List[str]] = {
     'opencv-codec': ['XVID', 'MP4V', 'MP42', 'H264'],
     'output-mode': ['scan_only', 'opencv', 'copy', 'ffmpeg'],

dvr_scan/region.py

@@ -124,10 +124,11 @@ class SelectionWindowSettings:
 HOVER_DISPLAY_DISTANCE = 260**2
 MAX_DOWNSCALE_AA_LEVEL = 4
 
+# TODO(v1.6): Need to add keyboard alternate for adding/deleting point from current shape.
 KEYBIND_REGION_ADD = 'a'
 KEYBIND_REGION_DELETE = 'x'
-KEYBIND_REGION_NEXT = 'k'
-KEYBIND_REGION_PREV = 'l'
+KEYBIND_REGION_NEXT = 'l'
+KEYBIND_REGION_PREV = 'k'
 KEYBIND_UNDO = 'z'
 KEYBIND_REDO = 'y'
 KEYBIND_MASK = 'm'

website/mkdocs.yml

@@ -70,6 +70,7 @@ nav:
  - 'Home': 'index.md'
  - 'Download': 'download.md'
  - 'Changelog': 'changelog.md'
+ - 'User Guide': 'guide.md'
  - 'Documentation': 'docs.md'
  - 'FAQ': 'faq.md'
  - 'Resources': 'resources.md'