See the documentation for a complete reference to the
scenedetect command with more examples.
Split input video on each fast cut using
scenedetect -i video.mp4 split-video
Save some frames from each cut:
scenedetect -i video.mp4 save-images
Skip the first 10 seconds of the input video:
scenedetect -i video.mp4 time -s 10s
As a concrete example to become familiar with PySceneDetect, let's use the following short clip from the James Bond movie, GoldenEye (Copyright © 1995 MGM):
You can download the clip from here (right-click and save the video in your working directory as
Let's split this scene into clips on each fast cut. This means we need to use content-aware detecton mode (
detect-content) or adaptive mode (
detect-adaptive). If the video instead contains fade-in/fade-out transitions you want to find, you can use
detect-threshold instead. If no detector is specified,
detect-adaptive will be used by default.
Let's first save a scene list in CSV format and generate some images of each scene to check the output:
scenedetect --input goldeneye.mp4 detect-adaptive list-scenes save-images
Running the above command, in the working directory, you should see a file
goldeneye-Scenes.csv, as well as individual frames for the start/middle/end of each scene starting with
goldeneye-Scene-001-01.jpg. The results should appear as follows:
Splitting Video into Clips
split-video command can be used to automatically split the input video using
mkvmerge. For example:
scenedetect -i goldeneye.mp4 split-video
scenedetect split-video --help for a full list of options which can be specified for video splitting, including high quality mode (
-hq/--high-quality) or copy mode (
You can also specify
--high-quality to produces near lossless results, or
scenedetect help split-video for details). If either
--mkvmerge is specified, codec copying mode is used, at the expense of frame accurate cuts. Optionally, you can also specify the x264
scenedetect split-video --help for details).
PySceneDetect can look for fades in/out using
detect-threshold (comparing each frame to a set black level) or find fast cuts using
detect-content (compares each frame looking for changes in content). There also is
detect-adaptive, which uses the same scoring as
detect-content, but compares the ratio of each frame score to its neighbors.
Each mode has slightly different parameters, and is described in detail below. Most detector parameters can also be set with a config file.
In general, use
detect-threshold mode if you want to detect scene boundaries using fades/cuts in/out to black. If the video uses a lot of fast cuts between content, and has no well-defined scene boundaries, you should use the
detect-content modes. Once you know what detection mode to use, you can try the parameters recommended below, or generate a statistics file (using the
--stats flag) in order to determine the correct parameters - specifically, the proper threshold value.
Unlike threshold mode, content-aware mode looks at the difference between each pair of adjacent frames, triggering a scene break when this difference exceeds the threshold value.
The optimal threshold can be determined by generating a stats file (
-s), opening it with a spreadsheet editor (e.g. Excel), and examining the
content_val column (example). This value should be very small between similar frames, and grow large when a big change in content is noticed (look at the values near frame numbers/times where you know a scene change occurs). The threshold value should be set so that most scenes fall below the threshold value, and scenes where changes occur should exceed the threshold value (thus triggering a scene change).
Threshold-based mode is what most traditional scene detection programs use, which looks at the average intensity of the current frame, triggering a scene break when the intensity falls below the threshold (or crosses back upwards). The default threshold when using the
detect-threshold is the same as
detect-threshold --threshold 12 when the
--threshold option is not supplied), which is a good value to try when detecting fade outs to black on most videos.
scenedetect -i my_video.mp4 -s my_video.stats.mp4 detect-threshold
scenedetect -i my_video.mp4 -s my_video.stats.mp4 detect-threshold -t 20
Using values for threshold less than
8 may cause problems with some videos, especially those encoded at lower bitrates or with limited dynamic range.
The optimal threshold can be determined by generating a statsfile (
-s), opening it with a spreadsheet editor (e.g. Excel), and examining the
delta_rgb column. These values represent the average intensity of the pixels for that particular frame (taken by averaging the R, G, and B values over the whole frame). The threshold value should be set so that the average intensity of most frames in content scenes lie above the threshold value, and scenes where scene changes/breaks occur should fall under the threshold value (thus triggering a scene change).
detect-adaptive mode compares each frame's score as calculated by
detect-content with its neighbors. This score is what forms the
adaptive_ratio metric in the statsfile. You can also configure the amount of neighboring frames via the
frame-window option, as well as the minimum change in
content_val score using
Detectors take a variety of parameters, which can be configured via command-line or by using a config file. If the default parameters do not produce correct results, you can generate a stats file using the
For example, with
detect-content, if the default threshold of
27 does not produce correct results, we can determine the proper threshold by first generating a stats file:
scenedetect --input goldeneye.mp4 --stats goldeneye.stats.csv detect-adaptive
We can then plot the values of the
The peaks in values correspond to the scene breaks in the input video. In some cases the threshold may need to be raised or lowered accordingly.
Saving Image Previews of Detected Scenes
PySceneDetect can automatically save the beginning and ending frame of each detected scene by using the
save-images command. If present, the first and last frames of each scene will be saved in the current working directory, using the filename of the input video.
00 represent the starting frame of the scene, and those marked
01 represent the last frame (e.g.
testvideo.mp4.Scene-4-01.jpg). By default, two images are generated.
Coming soon: If more are specified via the
-n flag, they will start from
00 (the first frame) and be evenly spaced throughout the scene until the last frame, which will be numbered
Improving Processing Speed/Performance
The following arguments are global program options, and need to be applied before any commands (e.g.
list-scenes). They can be used to achieve performance gains for some source material with a variable loss of accuracy.
Assuming the input video is of a high enough resolution, a significant performance gain can be achieved by sub-sampling (down-scaling) the input image by a specific integer factor (2x, 3x, 4x, 5x...). This is applied automatically to some degree based on the input video size, but can be overridden manually with the
This factor represents how many pixels are "skipped" in both the x- and y- directions, effectively down-scaling the image (using nearest-neighbor sampling) by the factor specified (the new resolution being
W/factor x H/factor if the old resolution is
W x H).
Another method that can be used to gain a performance boost is frame skipping. This method, however, severely reduces frame-accurate scene cuts, so it should only be used with high FPS material (ideally > 60 FPS), at low values (try not to exceed a value of
2 if using
--frame-skip), in cases where this is acceptable. Using the frame skip option also disallows the use of a stats file, which offsets the speed gain if the same video needs to be processed multiple times (e.g. to determine the optimal threshold).
The option still remains, however, for the set of cases where it is still required. For example, if we skip every other frame (e.g. using
--frame-skip 1), the processing speed should roughly double.
If set too large, enough frames may be skipped each time that the threshold is met during every iteration, continually triggering scene changes. This is because frame skipping essentially raises the threshold between frames in the same scene (making them more likely to appear as cuts) while not affecting the threshold between frames of different scenes.
This makes the two harder to distinguish, and can cause additional false scene cuts to be detected. While this can be compensated for by raising the threshold value, this increases the probability of missing a real/true scene cut - thus, the use of the
--frame-skip option is discouraged.
Seeking, Duration, and Setting Start / Stop Times
time command allows control over what portion of the video PySceneDetect processes. The
time command accepts three options: start time (
-start), end time (
-end), and duration (
--duration). Specifying both end time and duration is redundant, and in this case, duration overrides end time. Timecodes can be given in three formats: exact frame number (e.g.
12345), number of seconds followed by
123.45s), or standard format (HH:MM:SS[.nnn], e.g.
For example, let's say we have a video shot at 30 FPS, and want to analyze only the segment from the 5 to the 6.5 minute mark in the video (we want to analyze the 90 seconds [2700 frames] between 00:05:00 and 00:06:30). The following commands are all thus equivalent in this regard (assuming we are using the content detector):
scenedetect -i my_video.mp4 time --start 00:05:00 --end 00:06:30
scenedetect -i my_video.mp4 time --start 300s --end 390s
scenedetect -i my_video.mp4 time --start 300s --duration 90s
scenedetect -i my_video.mp4 time --start 300s --duration 2700
This demonstrates the different timecode formats, interchanging end time with duration and vice-versa, and precedence of setting duration over end time.
A configuration file path can be specified using the
--config argument. PySceneDetect also looks for a config file named
scenedetect.cfg in one of the following locations:
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). You can click here to download a
scenedetect.cfg config file to use as a template. Note that lines starting with a
# are comments and will be ignored. The
scenedetect.cfg template file is also available in the folder where PySceneDetect is installed.
Specifying a config file path using -c/--config overrides the user config file. Specifying values on the command line will override those values in the config file.
The syntax of a configuration file is:
option_a = value
option_b = 1
default-detector = detect-content
min-scene-len = 0.8s
threshold = 32
weights = 1.0 0.5 1.0 0.2
preset = slow
rate-factor = 17
# Don't need to use quotes even if filename contains spaces
filename = $VIDEO_NAME-Clip-$SCENE_NUMBER
format = jpeg
quality = 80
num-images = 3
scenedetect.cfg file in the location you installed PySceneDetect or download it from Github for a complete listing of all configuration options.
Video Splitting Requirements
PySceneDetect can use either
mkvmerge to split videos automatically.
By default, when specifying the
ffmpeg will be used to split the video. If the
--copy option is also set (e.g.
mkvmerge will be used to split the video instead.
You can download
ffmpeg from: https://ffmpeg.org/download.html
Note that Linux users should use a package manager (e.g.
sudo apt-get install ffmpeg). Windows users may require additional steps in order for PySceneDetect to detect
ffmpeg - see the section Manually Enabling
split-video Support below for details.
You can download and install
mkvmerge as part of the mkvtoolnix package from:
Note that Windows users should use the installer/setup, and Linux users should use their system package manager, otherwise PySceneDetect may not be able to find
mkvmerge. If this is the case, see the section below to enable support for the
split-video --copy command manually.
If PySceneDetect cannot find the respective tool installed on your system, you have three options:
Place the tool in the same location that PySceneDetect is installed (e.g. copy and paste mkvmerge.exe into the same place scenedetect.exe is located). This is the easiest solution for most users.
Add the directory where you installed ffmpeg/mkvmerge to your system's PATH environment variable, ensuring that you can use the ffmpeg/mkvmerge command from any terminal/command prompt. This is the best solution for advanced users.
Place the tool in a location already in your system's PATH variable (e.g. C:/Windows). This is not recommended, but may be the only solution on systems without administrative rights.