Configuration File — PySceneDetect 0.6.5-dev1 documentation

# Configuration File

A configuration file path can be specified using the `-c`/`--config` argument. PySceneDetect also looks for a config file named scenedetect.cfg in one of the following locations:

> - Windows:

>     - `C:/Users/%USERNAME%/AppData/Local/PySceneDetect/scenedetect.cfg`

> - Linux:

>     - `~/.config/PySceneDetect/scenedetect.cfg`

>     - `$XDG_CONFIG_HOME/scenedetect.cfg`

> - Mac:

>     - `~/Library/Preferences/PySceneDetect/scenedetect.cfg`

Run scenedetect –help to see the exact path on your system which will be used. Values set on the command line take precedence over those set in the config file. Most (but not all) command line parameters can be set using a configuration file, and some options can only be set using a config file. See the Template below for a `scenedetect.cfg` file that describes each option, which you can use to create a new config file. Note that lines starting with a `#` are comments and will be ignored.

The syntax of a configuration file is:

    [command]
    option_a = value
    #comment
    option_b = 1

## Example

    [global]
    default-detector = detect-content
    min-scene-len = 0.8s

    [detect-content]
    threshold = 26

    [split-video]
    # Use higher quality encoding
    preset = slow
    rate-factor = 17
    filename = $VIDEO_NAME-Clip-$SCENE_NUMBER

    [save-images]
    format = jpeg
    quality = 80
    num-images = 3

## Template

This template shows every possible configuration option and default values. It can be used as a `scenedetect.cfg` file. You can also download it from Github.

    #
    # This file contains every possible PySceneDetect config option.
    #
    # A config file path can be specified via the -c/--config option, or by
    # creating a `scenedetect.cfg` file the following location:
    #
    #   Windows: C:/Users/%USERNAME%/AppData/Local/PySceneDetect/scenedetect.cfg
    #
    #   Linux:   ~/.config/PySceneDetect/scenedetect.cfg
    #            $XDG_CONFIG_HOME/scenedetect.cfg
    #
    #   Mac:     ~/Library/Preferences/PySceneDetect/scenedetect.cfg
    #
    # Run `scenedetect --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).
    #

    #
    # GLOBAL OPTIONS
    #

    [global]
    # Output directory for written files. If unset, defaults to working directory.
    #output = /usr/tmp/scenedetect/

    # Default detector to use.
    # Must be one of: detect-adaptive, detect-content, detect-threshold, detect-hist
    #default-detector = detect-adaptive

    # Video backend interface, must be one of: opencv, pyav.
    #backend = opencv

    # Downscale frame using a ratio of N. Set to 1 for no downscaling. If unset,
    # applied automatically based on input video resolution. Must be an integer value.
    #downscale = 1

    # Method to use for downscaling (nearest, linear, cubic, area, lanczos4).
    #downscale-method = linear

    # Minimum length of a given scene.
    #min-scene-len = 0.6s

    # Merge last scene if it is shorter than min-scene-len (yes/no). This can occur
    # when a cut is detected just before the video ends.
    #merge-last-scene = no

    # Drop scenes shorter than min-scene-len instead of merging (yes/no).
    #drop-short-scenes = no

    # Verbosity of console output (debug, info, warning, error, or none).
    # Set to none for the same behavior as specifying -q/--quiet.
    #verbosity = debug

    # Amount of frames to skip between performing scene detection. Not recommended.
    #frame-skip = 0

    #
    # DETECTOR OPTIONS
    #

    [detect-adaptive]
    # Frame score threshold, refers to the `adaptive_ratio` metric in stats file.
    #threshold = 3

    # Minimum threshold that `content_val` metric from detect-content must exceed.
    #min-content-val = 15

    # Window size (number of frames) before and after each frame to average together.
    #frame-window = 2

    # Minimum length of a given scene (overrides [global] option).
    #min-scene-len = 0.6s

    # The following parameters are the those used to calculate `content_val`.
    # See [detect-content] for detailed descriptions of these parameters.
    #weights = 1.0, 1.0, 1.0, 0.0
    #luma-only = no
    #kernel-size = -1

    [detect-content]
    # Sensitivity threshold from 0 to 255. Lower values are more sensitive.
    #threshold = 27

    # Minimum length of a given scene (overrides [global] option).
    #min-scene-len = 0.6s

    # Mode to use when filtering scenes to comply with min-scene-len:
    #   merge: Consecutive scenes shorter than min-scene-len are combined.
    #   suppress: No new scenes can be generated until min-scene-len passes.
    #filter-mode = merge

    # Weight to place on each component when calculating frame score (the value
    # `threshold` is compared against). The components are in the order
    # (delta_hue, delta_sat, delta_lum, delta_edges). Description of components:
    #  - delta_hue:    Difference between hue values of adjacent frames
    #  - delta_sat:    Difference between saturation values of adjacent frames
    #  - delta_lum:    Difference between luma/brightness values of adjacent frames
    #  - delta_edges:  Difference between calculated edges of adjacent frames
    # The score of each frame ('content_val' in the statsfile) is calculated as
    # the weighted sum of all components.
    #weights = 1.0 1.0 1.0 0.0

    # Discard colour information and only use luminance (yes/no).
    # If yes, overrides weights with (0.0, 0.0, 1.0, 0.0).
    #luma-only = no

    # Size of kernel for expanding detected edges. Must be odd integer greater
    # than or equal to 3. If None, automatically set using video resolution.
    #kernel-size = -1

    # Mode to use for enforcing min-scene-len:
    #   merge: Consecutive scenes shorter than min-scene-len are combined.
    #   suppress: No new scenes can be generated until min-scene-len passes.
    #filter-mode = merge

    [detect-hash]
    # Threshold between 0.0 and 1.0 to set the relative difference between
    # hashes required to trigger a shot change. Lower values are more sensitive.
    #threshold = 0.395

    # The ratio between 1 and 256 of how much low frequency information to keep.
    # Represents highest frequency which will pass the filter. 1 means keep all,
    # 2 means keep lower 1/2 of frequency data, 4 means keep lower 1/4, etc...
    #lowpass = 2

    # Size between 1 and 256 representing size of square of low frequency data to
    # use for the direct cosine transform (DCT).
    #size = 16

    # Minimum length of a given scene (overrides [global] option).
    #min-scene-len = 0.6s

    [detect-hist]
    # Threshold between 0.0 to 1.0 to set the relative difference between Y
    # channel histograms (YUV) required to trigger a shot change. Lower values
    # are more sensitive.
    #threshold = 0.05

    # Number of bins between 1 and 256 to use for the histogram.
    #bins = 256

    # Minimum length of a given scene (overrides [global] option).
    #min-scene-len = 0.6s

    [detect-threshold]
    # Average pixel intensity from 0-255 at which a fade event is triggered.
    #threshold = 12

    # Percent from -100.0 to 100.0 of timecode skew for where cuts should be placed.
    # -100 indicates start frame, +100 indicates end frame, and 0 is the center.
    #fade-bias 0

    # Generate a scene from the end of the last fade out to the end of the video.
    #add-last-scene = yes

    # Discard colour information and only use luminance (yes/no).
    #luma-only = no

    # Minimum length of a given scene (overrides [global] option).
    #min-scene-len = 0.6s

    #
    # COMMAND OPTIONS
    #

    [split-video]
    # Folder to output videos. Overrides [global] output option.
    #output = /usr/tmp/encoded

    # Filename template to use as output.
    #filename = $VIDEO_NAME-Scene-$SCENE_NUMBER

    # Suppress output from split tool.
    #quiet = no

    # Use higher bitrate for better output quality (y/n), equivalent to setting
    # rate-factor = 17 and preset = slow.
    #high-quality = no

    # Use codec copying instead of encoding. Significantly faster, but can result
    # in inaccurate splits due to keyframe positioning.
    #copy = no

    # Use mkvmerge for copying instead of encoding. Has the same drawbacks as copy = yes.
    #mkvmerge = no

    # x264 rate-factor, higher indicates lower quality / smaller filesize.
    # 0 = lossless, 17 = visually identical, 22 = default.
    #rate-factor = 22

    # One of the ffmpeg x264 presets (e.g. veryfast, fast, medium, slow, slower).
    #preset = veryfast

    # Arguments to specify to ffmpeg for encoding. Quotes are not required.
    #args = -map 0:v:0 -map 0:a? -map 0:s? -c:v libx264 -preset veryfast -crf 22 -c:a aac

    [save-images]
    # Folder to output videos. Overrides [global] output option.
    #output = /usr/tmp/images

    # Filename format of created images. Can use $VIDEO_NAME, $SCENE_NUMBER, $IMAGE_NUMBER,
    # $TIMECODE, $FRAME_NUMBER, and $TIMESTAMP_MS. Should not include extension.
    #filename = $VIDEO_NAME-Scene-$SCENE_NUMBER-$IMAGE_NUMBER

    # Image format (jpeg, png, webp).
    #format = jpeg

    # Number of images to generate for each scene.
    #num-images = 3

    # Image quality (jpeg/webp). Default is 95 for jpeg, 100 for webp
    #quality = 95

    # Compression amount for png images (0 to 9). Does not affect quality.
    #compression = 3

    # Number of frames to skip at beginning/end of scene.
    #frame-margin = 1

    # Factor to resize images by (0.5 = half, 1.0 = same, 2.0 = double).
    #scale = 1.0

    # Override image height and/or width. Mutually exclusive with scale.
    #height = 0
    #width = 0

    # Method to use for image scaling (nearest, linear, cubic, area, lanczos4).
    #scale-method = linear

    [export-html]
    # Filename format of created HTML file. Can use $VIDEO_NAME in the name.
    #filename = $VIDEO_NAME-Scenes.html

    # Override <img> element width/height.
    #image-height = 0
    #image-width = 0

    # Do not generate <img> elements in resulting table (yes/no).
    #no-images = no

    [list-scenes]
    # By default, list-scenes will create a CSV file. Enable this option
    # to suppress creating the CSV file.
    #no-output-file = no

    # Folder to output scene list. Overrides [global] output option.
    #output = /usr/tmp/images

    # Filename format to use when saving scene list. $VIDEO_NAME can be used to
    # represent the name of the video being processed.
    #filename = $VIDEO_NAME-Scenes.csv

    # Display a table with the start/end boundaries for each scene (yes/no).
    #display-scenes = yes

    # Display list of cut points generated from scene boundaries (yes/no).
    #display-cuts = yes

    # Format to use for list of cut points (frames, seconds, timecode).
    #cut-format = timecode

    # Skip writing cut points as the first row in the CSV file (yes/no).
    # Set for RFC 4180 compliance.
    #skip-cuts = no

    # Suppress all display output of list-scenes command.
    # Overrides `display-scenes` and `display-cuts`.
    #quiet = no

    [load-scenes]
    # Name of column used to mark scene cut points.
    #start-col-name = Start Frame

    #
    # BACKEND OPTIONS
    #

    [backend-opencv]
    # Number of times to keep reading frames after one fails to decode.
    # If set to 0, processing will stop on the first decode failure.
    #max-decode-attempts = 5

    [backend-pyav]
    # Threading mode to use (none, slice, frame, auto). Slice mode is the
    # PyAV default, and auto/frame are the fastest.
    #threading-mode = auto

    # Suppress ffmpeg log output. Default is `no`.
    #
    # WARNING: When threading-mode is set to auto/frame, setting
    # `suppress-output = yes` can cause the the program to not exit properly
    # on Linux/OSX (press Ctrl+C to quit if this occurs).
    #suppress-output = no