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. The Sections reference below lists every key with its default and the matching command-line option. 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
Sample File¶
[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
Sections¶
Every section of the config file, its keys and defaults, and the part of the scenedetect.cfg template that documents them. The complete template can be downloaded from Github and used as a config file as-is (every key is commented out). Values shown in the template are the defaults, or an example where the default is unset.
[global]¶
Options of the scenedetect command; detectors and commands inherit min-scene-len and output from here.
Key |
Default |
CLI option |
|---|---|---|
|
|
Used if no |
|
none |
|
|
|
|
|
none |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
config file only |
|
|
[global]
# Default detector to use.
# Must be one of: detect-adaptive, detect-content, detect-hash, detect-hist,
# detect-threshold
#default-detector = detect-adaptive
# Output directory for written files. Defaults to working directory.
#output = /usr/tmp/scenedetect/
# Verbosity of console output (debug, info, warning, error, or none).
# Set to none for the same behavior as specifying -q/--quiet.
#verbosity = info
# Crop input video to area. Specified as two points in the form X0 Y0 X1 Y1 or
# as (X0 Y0), (X1 Y1). Coordinate (0, 0) is the top-left corner.
#crop = 100 100 200 250
# Video backend interface, must be one of: opencv, pyav, moviepy.
#backend = opencv
# 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
# Downscale frame before processing. Set to 1 for no downscaling, or 0 to
# calculate the downscale factor automatically from the video resolution.
#downscale = 0
# Method to use for downscaling (nearest, linear, cubic, area, lanczos4).
#downscale-method = linear
# Amount of frames to skip between performing scene detection. Not recommended.
#frame-skip = 0
[detect-adaptive]¶
Options of detect-adaptive (Python API: AdaptiveDetector, option table).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
[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]¶
Options of detect-content (Python API: ContentDetector, option table).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
[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
[detect-hash]¶
Options of detect-hash (Python API: HashDetector, option table).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
[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.35
# 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 = 8
# Minimum length of a given scene (overrides [global] option).
#min-scene-len = 0.6s
[detect-hist]¶
Options of detect-hist (Python API: HistogramDetector, option table).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
|
|
|
[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.20
# Number of bins between 1 and 256 to use for the histogram.
#bins = 128
# Minimum length of a given scene (overrides [global] option).
#min-scene-len = 0.6s
[detect-threshold]¶
Options of detect-threshold (Python API: ThresholdDetector, option table).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
[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
# Minimum time faded out before a cut is allowed, including a final fade-out.
# Accepts frames, seconds (e.g. 0.4s), or timecode (e.g. 00:00:00.400).
# The Python API default remains 0.
#min-out-length = 0.1s
# Minimum length of a given scene (overrides [global] option).
#min-scene-len = 0.6s
[list-scenes]¶
Options of list-scenes (Python API: write_scene_list()).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
none |
|
|
|
|
|
|
config file only |
|
|
config file only |
|
|
config file only |
|
|
config file only |
|
|
config file only |
|
|
|
|
|
[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
# Separator to use between columns in output file. Must be single (escaped)
# ASCII character.
#col-separator = ,
# Separator to use between rows in output file. Must be (escaped) ASCII
# characters.
#row-separator = \n
# 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]¶
Options of load-scenes.
Key |
Default |
CLI option |
|---|---|---|
|
|
[load-scenes]
# Name of column used to mark scene cut points.
#start-col-name = Start Frame
[save-edl]¶
Options of save-edl (Python API: write_scene_list_edl()).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
none |
|
|
|
|
|
|
|
|
none |
[save-edl]
# Filename format of EDL file. Can use $VIDEO_NAME macro.
#filename = $VIDEO_NAME.edl
# Folder to output EDL file to. Overrides [global] output option.
#output = /usr/tmp/images
# Reel/tape name to use.
#reel = AX
# Title to use for the EDL information. Can use $VIDEO_NAME macro.
#title = $VIDEO_NAME
# Start timecode added to every event so the EDL aligns with the source
# media's on-screen timecode. Non-drop-frame SMPTE HH:MM:SS:FF or 8 digits
# (HHMMSSFF).
#start-timecode = 01:00:00:00
[save-fcp]¶
Options of save-fcp (Python API: write_scene_list_fcpx(), write_scene_list_fcp7()).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
|
|
|
none |
[save-fcp]
# Filename format of XML file. Can use $VIDEO_NAME macro.
#filename = $VIDEO_NAME.xml
# Format of the XML file. Must be one of:
# - fcpx: Final Cut Pro X (FCPXML, default)
# - fcp7: Final Cut Pro 7 (xmeml)
#format = fcpx
# Folder to output XML file to. Overrides [global] output option.
#output = /usr/tmp/images
[save-html]¶
Options of save-html (Python API: write_scene_list_html()).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[save-html]
# Filename format of created HTML file. Can use $VIDEO_NAME in the name.
#filename = $VIDEO_NAME-Scenes.html
# Automatically open resulting HTML when processing is complete.
#show = no
# Override <img> element width/height.
#image-height = 0
#image-width = 0
# Do not generate <img> elements in resulting table (yes/no).
#no-images = no
[save-images]¶
Options of save-images (Python API: save_images()).
Key |
Default |
CLI option |
|---|---|---|
|
none |
|
|
|
|
|
|
|
|
|
|
|
none |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
config file only |
|
|
config file only |
[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. Cannot be used with interval.
#num-images = 3
# Generate one image per DURATION of each scene instead of num-images, so longer
# scenes get more images: floor(length / DURATION) + 1 per scene. DURATION accepts
# frames (24), seconds with `s` suffix (1.5s), or timecode (00:00:01.500).
# Cannot be used with num-images.
#interval = 2s
# Minimum and maximum number of images per scene with interval (ignored without
# interval). Set max-images to 0 for no limit.
#min-images = 1
#max-images = 0
# Image quality (jpeg/webp). Default is 95 for jpeg, 100 for webp
#quality = 95
# Compression amount for png images (0 to 9). Only affects size, not quality.
#compression = 3
# Padding around each scene cut when selecting frames. Accepts a number of frames (1),
# seconds with `s` suffix (0.1s), or timecode (00:00:00.100).
#frame-margin = 1
# Resize by scale factor (0.5 = half, 1.0 = same, 2.0 = double).
#scale = 1.0
# Resize to specified height, width, or both. Mutually exclusive with scale.
#height = 0
#width = 0
# Method to use for scaling (nearest, linear, cubic, area, lanczos4).
#scale-method = linear
# Use separate threads for encoding and disk IO. Can improve performance.
#threading = yes
[save-keyframes]¶
Options of save-keyframes.
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
none |
[save-keyframes]
# Filename format of keyframe file. Can use $VIDEO_NAME macro.
#filename = $VIDEO_NAME-keyframes.txt
# Folder to output keyframe file to. Overrides [global] output option.
#output = /usr/tmp/keyframes
[save-otio]¶
Options of save-otio (Python API: write_scene_list_otio()).
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
none |
|
|
|
|
|
|
[save-otio]
# Filename format of OTIO file. Can use $VIDEO_NAME macro.
#filename = $VIDEO_NAME.otio
# Folder to output OTIO file to. Overrides [global] output option.
#output = /usr/tmp/images
# Name to use for the OTIO timeline. Can use $VIDEO_NAME macro.
#name = $VIDEO_NAME (PySceneDetect)
# Include audio track (yes/no).
#audio = yes
[save-qp]¶
Options of save-qp.
Key |
Default |
CLI option |
|---|---|---|
|
|
|
|
none |
|
|
|
[save-qp]
# Filename format of QP file. Can use $VIDEO_NAME macro.
#filename = $VIDEO_NAME.qp
# Folder to output QP file to. Overrides [global] output option.
#output = /usr/tmp/images
# Disable shifting frame numbers by start time (yes/no).
#disable-shift = no
[split-video]¶
Options of split-video (Python API: split_video_ffmpeg(), split_video_mkvmerge()).
Key |
Default |
CLI option |
|---|---|---|
|
none |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[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
# Extend the first/last output clips to cover the full input video, even if
# `time -s/-e` limited the analysis window. Useful for keeping content outside
# the analyzed region attached to the adjacent split.
#expand = no
[backend-opencv]¶
Settings of the -b opencv backend (Python API: VideoStreamCv2). These keys have no command-line option.
Key |
Default |
CLI option |
|---|---|---|
|
|
config file only |
[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]¶
Settings of the -b pyav backend (Python API: VideoStreamAv). These keys have no command-line option.
Key |
Default |
CLI option |
|---|---|---|
|
|
config file only |
|
|
config file only |
[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
