PySceneDetect

https://www.scenedetect.com
Admin
PySceneDetect is a Python library and command-line tool for automatically detecting scene cuts and...
Tokens:30,207
Snippets:394
Trust Score:7.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Split Video CLI Examples

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Examples for splitting video files using different modes and naming conventions.

```bash
scenedetect -i video.mp4 split-video
```

```bash
scenedetect -i video.mp4 split-video --copy
```

```bash
scenedetect -i video.mp4 split-video --filename $VIDEO_NAME-Clip-$SCENE_NUMBER
```

--------------------------------

### Install Headless PySceneDetect

Source: https://www.scenedetect.com/faq

Installation command for server environments that do not require GUI libraries.

```bash
pip install scenedetect-headless
```

--------------------------------

### Save Images CLI Examples

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Examples for extracting images from a video file using various configuration options.

```bash
scenedetect -i video.mp4 save-images --num-images 5
```

```bash
scenedetect -i video.mp4 save-images --width 1024
```

```bash
scenedetect -i video.mp4 save-images --filename $SCENE_NUMBER-img$IMAGE_NUMBER
```

--------------------------------

### Configuration File Example

Source: https://www.scenedetect.com/docs/latest/_sources/cli/config_file.rst.txt

A practical example of a scenedetect.cfg file defining global defaults and specific settings for detectors and video processing commands.

```ini
[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
```

--------------------------------

### Example configuration file

Source: https://www.scenedetect.com/cli

A sample configuration file demonstrating global settings and command-specific overrides.

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

[detect-content]
threshold = 32
weights = 1.0 0.5 1.0 0.2

[split-video]
preset = slow
rate-factor = 17
# Don't need to use quotes even if filename contains spaces
filename = $VIDEO_NAME-Clip-$SCENE_NUMBER

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

--------------------------------

### Install PySceneDetect

Source: https://www.scenedetect.com/faq

Standard installation command for PySceneDetect including the bundled OpenCV dependency.

```bash
pip install scenedetect
```

--------------------------------

### Split video using CLI

Source: https://www.scenedetect.com/docs/latest/cli.html

Examples for splitting video files with different configurations using the split-video command.

```bash
scenedetect -i video.mp4 split-video
```

```bash
scenedetect -i video.mp4 split-video --copy
```

```bash
scenedetect -i video.mp4 split-video --filename \$VIDEO_NAME-Clip-\$SCENE_NUMBER
```

--------------------------------

### Install PySceneDetect via pip

Source: https://www.scenedetect.com/download

Use these commands to install the standard or headless version of PySceneDetect.

```bash
pip install --upgrade scenedetect
```

```bash
pip install --upgrade scenedetect-headless
```

--------------------------------

### Run detect-threshold command

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Examples for using the detect-threshold command to find fade-in/out events.

```bash
scenedetect -i video.mp4 detect-threshold
```

```bash
scenedetect -i video.mp4 detect-threshold --threshold 15
```

--------------------------------

### Install PySceneDetect Dependencies

Source: https://www.scenedetect.com/download

Commands to manually install required Python packages if not handled automatically.

```bash
pip install opencv-python
```

```bash
pip install numpy
```

```bash
pip install click
```

```bash
pip install tqdm
```

```bash
pip install platformdirs
```

```bash
pip install av
```

--------------------------------

### Run detect-hash command

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Examples for using the detect-hash command to find cuts via perceptual hashing.

```bash
scenedetect -i video.mp4 detect-hash
```

```bash
scenedetect -i video.mp4 detect-hash --size 32 --lowpass 3
```

--------------------------------

### Install Custom OpenCV Variant

Source: https://www.scenedetect.com/faq

Commands to install a specific OpenCV variant while ensuring version compatibility with the bundled dependency.

```bash
pip install scenedetect
pip install "opencv-contrib-python==$(pip show opencv-python | grep ^Version | cut -d' ' -f2)"
```

--------------------------------

### Specify video processing time segments

Source: https://www.scenedetect.com/cli

Use the time command to define start, end, or duration for video analysis. These examples demonstrate equivalent ways to process a 90-second segment.

```bash
scenedetect -i my_video.mp4 time --start 00:05:00 --end 00:06:30
```

```bash
scenedetect -i my_video.mp4 time --start 300s --end 390s
```

```bash
scenedetect -i my_video.mp4 time --start 300s --duration 90s
```

```bash
scenedetect -i my_video.mp4 time --start 300s --duration 2700
```

--------------------------------

### Verify Python Dependencies

Source: https://www.scenedetect.com/download

Run these commands in a Python interpreter to ensure OpenCV and Numpy are correctly installed.

```python
import numpy
import cv2
```

--------------------------------

### Run detect-hist command

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Examples for using the detect-hist command to find cuts via YUV histogram differencing.

```bash
scenedetect -i video.mp4 detect-hist
```

```bash
scenedetect -i video.mp4 detect-hist --threshold 0.1 --bins 240
```

--------------------------------

### Set Video Processing Time Range

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Examples of using the time command to limit video processing by duration, end time, or frame range.

```bash
scenedetect -i video.mp4 time --end 00:01:00
```

```bash
scenedetect -i video.mp4 time --duration 60.0
```

```bash
scenedetect -i video.mp4 time --start 0 --end 1000
```

--------------------------------

### Detect scenes and split video using Python API

Source: https://www.scenedetect.com/docs/latest/_sources/api.rst.txt

Uses ContentDetector to identify scene cuts and ffmpeg to split the video file. Requires ffmpeg to be installed and available in the system path for the split operation.

```python
from scenedetect import detect, ContentDetector, split_video_ffmpeg
scene_list = detect("my_video.mp4", ContentDetector())
split_video_ffmpeg("my_video.mp4", scenes)
```

--------------------------------

### Manually construct a backend

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Directly instantiate a specific backend class if manual control over the video stream implementation is required.

```python
# Manually importing and constructing a backend:
from scenedetect.backends.opencv import VideoStreamCv2
video = VideoStreamCv2("video.mp4")
```

--------------------------------

### Basic Scene Detection Usage

Source: https://www.scenedetect.com/docs/latest/api/scene_manager.html

Demonstrates initializing a SceneManager, adding a ContentDetector, and processing a video to retrieve a list of scenes.

```python
from scenedetect import open_video, SceneManager, ContentDetector
video = open_video(video_path)
scene_manager = SceneManager()
scene_manager.add_detector(ContentDetector())
# Detect all scenes in video from current position to end.
scene_manager.detect_scenes(video)
# `get_scene_list` returns a list of start/end timecode pairs
# for each scene that was found.
scenes = scene_manager.get_scene_list()
```

--------------------------------

### Full Configuration Template

Source: https://www.scenedetect.com/docs/latest/cli/config_file.html

A comprehensive template containing all available configuration options and their default values.

```ini
#
# 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]

# Default detector to use.
# Must be one of: detect-adaptive, detect-content, detect-threshold, detect-hist
#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 = debug

# 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.
# By default, downscale will be calculated automatically.
#downscale = 1

# 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


#
# 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
```

--------------------------------

### expand_scenes_to_bounds(scenes, start, end)

Source: https://www.scenedetect.com/docs/latest/api/scene_manager.html

Returns a new scene list whose first scene starts at the specified start time and last scene ends at the specified end time. This is useful for adjusting scene boundaries to cover content outside the original analysis window.

```APIDOC
## expand_scenes_to_bounds(scenes, start, end)

### Description
Returns a new scene list whose first scene starts at start and last scene ends at end. The input list is not modified.

### Parameters
- **scenes** (list[tuple[FrameTimecode, FrameTimecode]]) - Required - List of (start, end) FrameTimecode pairs.
- **start** (FrameTimecode) - Required - Desired start of the first scene.
- **end** (FrameTimecode) - Required - Desired end of the last scene.

### Returns
- **list[tuple[FrameTimecode, FrameTimecode]]** - A new scene list with the outer endpoints replaced.
```

--------------------------------

### get_scene_list

Source: https://www.scenedetect.com/docs/latest/api/scene_manager.html

Returns a list of tuples containing start and end FrameTimecodes for each detected scene.

```APIDOC
## get_scene_list(start_in_scene=False)

### Description
Return a list of tuples of start/end FrameTimecodes for each detected scene.

### Parameters
- **start_in_scene** (bool) - Optional - Assume the video begins in a scene.
```

--------------------------------

### scenedetect.platform.init_logger(show_stdout=False, log_file=None, verbosity=None)

Source: https://www.scenedetect.com/docs/latest/_sources/api.rst.txt

Initializes the pyscenedetect logger with optional handlers.

```APIDOC
## scenedetect.platform.init_logger(show_stdout=False, log_file=None, verbosity=None)

### Description
Attaches common handlers to the 'pyscenedetect' logger.

### Parameters
- **show_stdout** (bool) - Optional - If True, attaches a handler to output logs to stdout.
- **log_file** (str) - Optional - Path to a file to store logs.
- **verbosity** (int) - Optional - Sets the logging verbosity level.
```

--------------------------------

### VideoStreamConcat.map_span(start, end)

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Maps a time span on the global timeline to the input video(s) covering it.

```APIDOC
## VideoStreamConcat.map_span(start, end)

### Description
Map a time span on the global timeline to the input video(s) covering it. A span which straddles one or more file boundaries yields multiple entries.

### Parameters
- **start** (FrameTimecode) - Required - Start of the span.
- **end** (FrameTimecode) - Required - End of the span.

### Returns
- **list[SourceSpan]** - A list of SourceSpan objects covering the requested time range.
```

--------------------------------

### Open and read a video file

Source: https://www.scenedetect.com/docs/latest/api/video_stream.html

Use open_video to initialize a video stream and iterate through frames until the end of the file.

```python
from scenedetect import open_video
video = open_video('video.mp4')
while True:
    frame = video.read()
    if frame is False:
        break
print("Read %d frames" % video.frame_number)
```

--------------------------------

### Scene Detection with Callback

Source: https://www.scenedetect.com/docs/latest/api/scene_manager.html

Shows how to provide a callback function to be executed whenever a new scene is detected during processing.

```python
from scenedetect import open_video, SceneManager, ContentDetector

# Callback to invoke on the first frame of every new scene detection.
def on_new_scene(frame_img: numpy.ndarray, frame_num: int):
    print("New scene found at frame %d." % frame_num)

video = open_video(test_video_file)
scene_manager = SceneManager()
scene_manager.add_detector(ContentDetector())
scene_manager.detect_scenes(video=video, callback=on_new_scene)
```

--------------------------------

### Basic detect-content Usage

Source: https://www.scenedetect.com/docs/latest/cli.html

Run scene detection on a video file using default settings or a custom threshold.

```bash
scenedetect -i video.mp4 detect-content
```

```bash
scenedetect -i video.mp4 detect-content --threshold 27.5
```

--------------------------------

### Run project tests and formatting checks

Source: https://www.scenedetect.com/contributing

Commands to verify code quality and compliance with project standards before submission.

```bash
pytest
```

```bash
ruff check
```

```bash
ruff format
```

--------------------------------

### Configuration File Syntax

Source: https://www.scenedetect.com/docs/latest/_sources/cli/config_file.rst.txt

The configuration file uses an INI-style format where sections correspond to commands and options are defined as key-value pairs.

```ini
[command]
option_a = value
#comment
option_b = 1
```

--------------------------------

### VideoStreamCv2 Constructor

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Initializes a new instance of the VideoStreamCv2 backend to open a video source.

```APIDOC
## VideoStreamCv2(path=None, frame_rate=None, max_decode_attempts=5, path_or_device=None, framerate=None)

### Description
Opens a video file, image sequence, or network stream using the OpenCV backend.

### Parameters
- **path** (str | PathLike | None) - Optional - Path to the video file, image sequence, or network stream.
- **frame_rate** (float | Fraction | None) - Optional - Overrides the detected frame rate.
- **max_decode_attempts** (int) - Optional - Number of attempts to continue decoding after a frame failure.
- **path_or_device** (str | PathLike | int | None) - Optional - [DEPRECATED] Use path instead.
- **framerate** (float | None) - Optional - [DEPRECATED] Use frame_rate instead.
```

--------------------------------

### Run PySceneDetect with Docker

Source: https://www.scenedetect.com/download

Commands for pulling the official image and executing video processing tasks within a container.

```bash
docker pull ghcr.io/breakthrough/pyscenedetect
docker run --rm ghcr.io/breakthrough/pyscenedetect version
```

```bash
docker run --rm -v "$(pwd):/files" ghcr.io/breakthrough/pyscenedetect \
    -i /files/video.mp4 detect-adaptive split-video -o /files
```

--------------------------------

### Initialize FrameTimecode Objects

Source: https://www.scenedetect.com/docs/latest/api/common.html

Create FrameTimecode instances using frame counts, seconds, or timecode strings.

```python
frames = FrameTimecode(29, 29.97)
seconds_float = FrameTimecode(10.0, 10.0)
timecode_str = FrameTimecode("00:00:10.000", 10.0)
```

--------------------------------

### Run benchmark commands

Source: https://www.scenedetect.com/benchmarks

Commands to evaluate a specific detector on a dataset or perform a parameter grid sweep.

```bash
# Score one detector on one dataset:
python -m benchmark --detector detect-content --dataset BBC

# Grid sweep over detector parameters:
python -m benchmark.sweep --detector detect-content --dataset BBC \
    --params "threshold=15:35:1;min_scene_len=0.0:1.0:0.1"
```

--------------------------------

### HistogramDetector.__init__

Source: https://www.scenedetect.com/docs/latest/api/detectors.html

Initializes the HistogramDetector with specific sensitivity and scene length constraints.

```APIDOC
## HistogramDetector(threshold=0.05, bins=256, min_scene_len=15)

### Description
Initializes a new instance of the HistogramDetector to compare the difference in the Y channel of YUV histograms for adjacent frames.

### Parameters
- **threshold** (float) - Optional - Maximum relative difference (0.0 to 1.0) between histograms. Higher values are less sensitive.
- **bins** (int) - Optional - Number of bins to use for the histogram.
- **min_scene_len** (int/float/str/Timecode/FrameTimecode) - Optional - Minimum time required between detected cuts.
```

--------------------------------

### open_video(path, backend=None, **kwargs)

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Opens a video file or list of files for scene detection. Automatically selects the specified backend or falls back to OpenCV if the backend is unavailable.

```APIDOC
## open_video(path, backend=None, **kwargs)

### Description
Opens a video file or a list of video files to create a VideoStream object. If a backend is specified, it attempts to use it; otherwise, it defaults to OpenCV.

### Parameters
- **path** (str or list) - Required - A path to a video file or a list of paths to concatenate.
- **backend** (str) - Optional - The name of the backend to use (e.g., "opencv").
- **kwargs** (dict) - Optional - Additional keyword arguments forwarded to the backend constructor.

### Example
```python
from scenedetect import open_video
# Open a single file
video = open_video("video.mp4")
# Open multiple files as a continuous stream
video = open_video(["part1.mp4", "part2.mp4"])
```
```

--------------------------------

### Generate Stats File for Threshold Tuning

Source: https://www.scenedetect.com/cli

Use this command to generate a CSV stats file for an input video, which helps in identifying optimal detection thresholds.

```bash
scenedetect --input goldeneye.mp4 --stats goldeneye.stats.csv detect-adaptive
```

--------------------------------

### Construct a VideoStreamConcat

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Create a continuous video stream from a list of file paths using open_video.

```python
from scenedetect import open_video
video = open_video(["part1.mp4", "part2.mp4"])
```

--------------------------------

### Perform adaptive scene detection

Source: https://www.scenedetect.com/cli

Runs adaptive detection on a video file, generating a CSV scene list and saving preview images.

```bash
scenedetect --input goldeneye.mp4 detect-adaptive list-scenes save-images
```

--------------------------------

### VideoCaptureAdapter(cap, frame_rate=None, max_read_attempts=5)

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Constructor for the VideoCaptureAdapter class. Initializes the adapter with an existing OpenCV VideoCapture object.

```APIDOC
## Constructor: VideoCaptureAdapter

### Description
Creates an adapter for an existing OpenCV VideoCapture object. This is useful for processing inputs like webcams or pipes that may not support seeking.

### Parameters
- **cap** (cv2.VideoCapture) - Required - The opened VideoCapture object to wrap.
- **frame_rate** (float | Fraction | None) - Optional - Overrides the detected frame rate.
- **max_read_attempts** (int) - Optional - Number of attempts to continue decoding after a frame failure.
```

--------------------------------

### VideoStreamMoviePy(path, frame_rate=None, print_infos=False, framerate=None)

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Constructor for the VideoStreamMoviePy backend. Opens a video or device for processing.

```APIDOC
## VideoStreamMoviePy(path, frame_rate=None, print_infos=False, framerate=None)

### Description
Initializes a new instance of the MoviePy FFMPEG_VideoReader backend to open a video or device.

### Parameters
- **path** (str | PathLike) - Required - Path to the video file.
- **frame_rate** (float | Fraction | None) - Optional - Overrides the detected frame rate.
- **print_infos** (bool) - Optional - If True, prints information about the opened video to stdout.
- **framerate** (float | None) - Optional - [DEPRECATED] Use frame_rate instead.
```

--------------------------------

### Split Video into Clips

Source: https://www.scenedetect.com/cli

Splits an input video file into multiple clips using the default settings.

```bash
scenedetect -i goldeneye.mp4 split-video
```

--------------------------------

### Using VideoCaptureAdapter with SceneManager

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Integrate an existing OpenCV VideoCapture object into the PySceneDetect pipeline for live inputs like webcams.

```python
from scenedetect import SceneManager, ContentDetector
from scenedetect.backends import VideoCaptureAdapter
# Open device ID 2.
cap = cv2.VideoCapture(2)
video = VideoCaptureAdapter(cap)
total_frames = 1000
scene_manager = SceneManager()
scene_manager.add_detector(ContentDetector())
scene_manager.detect_scenes(video=video, duration=total_frames)
```

--------------------------------

### VideoStreamAv Constructor

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Initializes a new VideoStreamAv instance to open a video file or stream using the PyAV backend.

```APIDOC
## class VideoStreamAv(path_or_io, frame_rate=None, name=None, threading_mode=None, suppress_output=False, framerate=None)

### Description
Initializes the PyAV video stream backend. Opens a video by path or file-like object.

### Parameters
- **path_or_io** (str | PathLike | BinaryIO) - Required - Path to the video, or a file-like object.
- **frame_rate** (float | Fraction | None) - Optional - Overrides the detected frame rate.
- **name** (str | None) - Optional - Overrides the name property derived from the video path.
- **threading_mode** (str | None) - Optional - The PyAV video stream thread_type ('AUTO', 'FRAME', 'NONE', 'SLICE').
- **suppress_output** (bool) - Optional - If True, suppresses ffmpeg output.
- **framerate** (float | Fraction | None) - Optional - [DEPRECATED] Alias for frame_rate.
```

--------------------------------

### scenedetect.open_video(path)

Source: https://www.scenedetect.com/docs/latest/api/video_stream.html

Opens a video file or device and returns a VideoStream object. This is the primary entry point for accessing video data.

```APIDOC
## scenedetect.open_video(path)

### Description
Opens a video file or device and returns a VideoStream object. By default, it uses the OpenCV backend.

### Parameters
- **path** (str) - Required - The path to the video file or device.

### Response
- **VideoStream** (object) - An instance of a class implementing the VideoStream interface.
```

--------------------------------

### Configure Adaptive Detector Weights

Source: https://www.scenedetect.com/changelog

Sets weights for hue, saturation, luma, and edge detection components with a specified threshold.

```bash
detect-adaptive -w 1.0 0.5 1.0 0.25
```

--------------------------------

### List Scenes CLI Commands

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Commands to generate a scene list CSV file, with an option for RFC 4180 compliance.

```bash
scenedetect -i video.mp4 list-scenes
```

```bash
scenedetect -i video.mp4 list-scenes --skip-cuts
```

--------------------------------

### scenedetect.detect()

Source: https://www.scenedetect.com/docs/latest/_sources/api.rst.txt

The detect function is the primary entry point for performing scene detection on a video file using a specified detection algorithm.

```APIDOC
## scenedetect.detect(path, detector)

### Description
Analyzes a video file to detect scene transitions using the provided detection algorithm and returns a list of timecode pairs.

### Parameters
- **path** (str) - Required - The file path to the video to be analyzed.
- **detector** (Object) - Required - An instance of a detection algorithm (e.g., ContentDetector, AdaptiveDetector).

### Request Example
```python
from scenedetect import detect, ContentDetector
path = "video.mp4"
scenes = detect(path, ContentDetector())
```

### Response
- **scenes** (List[Tuple[FrameTimecode, FrameTimecode]]) - A list of tuples representing the start and end timecodes for each detected scene.
```

--------------------------------

### read()

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Reads and decodes the next frame from the video stream.

```APIDOC
## read(decode=True)

### Description
Reads the next frame from the stream. Returns the frame data or a success indicator.

### Parameters
- **decode** (bool) - Optional - If True, returns the frame as np.ndarray. If False, returns a boolean indicating if the stream advanced.
```

--------------------------------

### read()

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Reads and decodes the next frame from the video stream.

```APIDOC
## read(decode=True)

### Description
Reads and decodes the next frame as a np.ndarray. Returns False when the video ends.

### Parameters
- **decode** (bool) - Optional - If True, returns the frame image. If False, returns a boolean indicating if the stream advanced.
```

--------------------------------

### reset(print_infos=False)

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Closes and re-opens the video stream.

```APIDOC
## reset(print_infos=False)

### Description
Closes and re-opens the VideoStream, effectively seeking back to the start (0).

### Parameters
- **print_infos** (bool) - Optional - If True, prints information about the opened video to stdout.
```

--------------------------------

### Implement CustomDetector class

Source: https://www.scenedetect.com/api

A template for creating a custom scene detection algorithm by extending the SceneDetector base class.

```python
import typing as ty
import numpy as np
from scenedetect import FrameTimecode, SceneDetector


class CustomDetector(SceneDetector):
    """CustomDetector class to implement a scene detection algorithm."""

    def process_frame(
        self,
        timecode: FrameTimecode,
        frame_im: np.ndarray,
    ) -> ty.List[FrameTimecode]:
        # Return a list of timecodes where we found cuts (either on this frame or previously).
        return []

    def post_process(self, timecode: FrameTimecode) -> ty.List[FrameTimecode]:
        # Called after the last frame has been read to handle pending events.
        return []
```

--------------------------------

### reset()

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Closes and re-opens the video stream.

```APIDOC
## reset()

### Description
Resets the stream to the beginning, equivalent to calling seek(0).
```

--------------------------------

### Open a video file with open_video

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Use open_video to load a video file for scene detection. This method automatically handles backend selection and fallback to OpenCV.

```python
from scenedetect import open_video
video = open_video("video.mp4")
```

--------------------------------

### post_process

Source: https://www.scenedetect.com/docs/latest/api/detectors.html

Finalizes scene detection by writing a final cut if applicable.

```APIDOC
## post_process(timecode)

### Description
Writes a final scene cut if the last detected fade was a fade-out and add_final_scene is enabled.

### Parameters
- **timecode** (FrameTimecode) - Required - The final timecode context.

### Response
- **Returns** (list[FrameTimecode]) - List of final scene cuts.
```

--------------------------------

### Detect Scenes with Built-in Detector

Source: https://www.scenedetect.com/docs/latest/_sources/api/migration_guide.rst.txt

High-level detection workflow remains compatible with v0.7.

```python
# This still works in v0.7
from scenedetect import detect, ContentDetector
scenes = detect("video.mp4", ContentDetector())
```

--------------------------------

### detect(video_path, detector, show_progress=False)

Source: https://www.scenedetect.com/docs/latest/_sources/api.rst.txt

Performs scene detection on a video file using a specified detector.

```APIDOC
## detect(video_path, detector, show_progress=False)

### Description
Detects scenes in a video file using the provided detector instance.

### Parameters
- **video_path** (str) - Required - Path to the input video file.
- **detector** (Detector) - Required - An instance of a detector (e.g., ContentDetector).
- **show_progress** (bool) - Optional - If True, displays a progress bar with estimated time remaining.
```

--------------------------------

### VideoStreamConcat(paths, frame_rate=None, backend='opencv', **kwargs)

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Constructor for creating a new VideoStreamConcat instance to concatenate multiple videos.

```APIDOC
## VideoStreamConcat(paths, frame_rate=None, backend='opencv', **kwargs)

### Description
Concatenates multiple videos into a single, contiguous video stream with a monotonic PTS-based global timeline.

### Parameters
- **paths** (Sequence[str | PathLike[str]]) - Required - List of paths of the videos to concatenate, in playback order.
- **frame_rate** (float | Fraction | None) - Optional - If set, overrides the detected frame rate of every input.
- **backend** (str) - Optional - Name of the backend to decode each input with. Defaults to 'opencv'.
- **kwargs** (dict) - Optional - Optional named arguments to pass to every child backend constructor.

### Raises
- **OSError** - A file could not be found or access was denied.
- **VideoOpenFailure** - A video could not be opened, or resolutions don't match.
```

--------------------------------

### list-scenes

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Generates a CSV file containing the list of detected scenes.

```APIDOC
## list-scenes

### Description
Create a scene list CSV file. By default, the file is named $VIDEO_NAME-Scenes.csv.

### Options
- **-o, --output** (DIR) - Output directory to save files to.
- **-f, --filename** (NAME) - Filename format to use. Default: $VIDEO_NAME-Scenes.csv.
- **-n, --no-output-file** - Only print scene list to console.
- **-q, --quiet** - Suppress printing scene list.
- **-s, --skip-cuts** - Skip cutting list as first row in the CSV file.
```

--------------------------------

### scenedetect CLI

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

The primary command-line interface for PySceneDetect. It accepts an input video and a series of detectors and commands to process the video.

```APIDOC
## scenedetect

### Description
Runs scene detection on an input video file and performs specified commands like splitting the video or saving scene lists.

### Usage
`scenedetect -i video.mp4 [detector] [commands]`

### Global Options
- **-i, --input** (string) - Required - Input video file path.
- **-o, --output** (string) - Optional - Output directory for generated files.
- **-c, --config** (string) - Optional - Path to configuration file.
- **-s, --stats** (string) - Optional - Path to CSV file for writing frame metrics.
- **-f, --frame-rate** (float) - Optional - Override video frame rate.
- **-m, --min-scene-len** (timecode) - Optional - Minimum length of a scene (default: 0.6s).
- **-b, --backend** (string) - Optional - Video backend (opencv, pyav, moviepy).
- **-d, --downscale** (integer) - Optional - Downscale factor for processing.
- **-fs, --frame-skip** (integer) - Optional - Number of frames to skip for performance.
- **-v, --verbosity** (string) - Optional - Logging level (debug, info, warning, error, none).
- **-l, --logfile** (string) - Optional - Path to save debug logs.
- **-q, --quiet** (boolean) - Optional - Suppress terminal output.
```

--------------------------------

### Configure Content Detector Weights

Source: https://www.scenedetect.com/changelog

Sets weights for content detection components with a specified threshold, noting that edge detection may require higher threshold values.

```bash
detect-content -w 1.0 0.5 1.0 0.25 -t 32
```

--------------------------------

### HashDetector Constructor

Source: https://www.scenedetect.com/docs/latest/api/detectors.html

Initializes a new HashDetector instance with specific parameters for perceptual hashing and scene cut sensitivity.

```APIDOC
## HashDetector(threshold, size, lowpass, min_scene_len)

### Description
Initializes the detector using a perceptual hashing algorithm. Applies a direct cosine transform (DCT) and lowpass filter, followed by binary thresholding on the median.

### Parameters
- **threshold** (float) - Optional - Value from 0.0 to 1.0 representing the relative hamming distance between perceptual hashes of adjacent frames.
- **size** (int) - Optional - Size of square of low frequency data to use for the DCT.
- **lowpass** (int) - Optional - How much high frequency information to filter from the DCT.
- **min_scene_len** (int/float/str/Timecode/FrameTimecode) - Optional - Minimum time that must pass before a new scene cut can be added.
```

--------------------------------

### ContentDetector Constructor

Source: https://www.scenedetect.com/docs/latest/api/detectors.html

Initializes a new ContentDetector instance to detect fast cuts using changes in color and intensity.

```APIDOC
## ContentDetector(threshold, min_scene_len, weights, luma_only, kernel_size, filter_mode)

### Description
Initializes the detector with specific parameters to identify scene cuts based on frame content differences.

### Parameters
- **threshold** (float) - Required - Threshold the average change in pixel intensity must exceed to trigger a cut.
- **min_scene_len** (int|float|str|Timecode|FrameTimecode) - Required - Minimum time that must pass before a new cut can be added.
- **weights** (Components) - Optional - Weight to place on each component when calculating frame score.
- **luma_only** (bool) - Optional - If True, only considers changes in the luminance channel.
- **kernel_size** (int|None) - Optional - Size of kernel for expanding detected edges.
- **filter_mode** (Mode) - Optional - Mode to use when filtering cuts to meet min_scene_len.
```

--------------------------------

### Update SceneManager.detect_scenes time arguments

Source: https://www.scenedetect.com/docs/latest/_sources/api/migration_guide.rst.txt

Demonstrates the supported types for duration and end_time arguments in detect_scenes, which now include seconds, frames, and timecode strings.

```python
# All of these were always supported at runtime; now they type-check too:
scene_manager.detect_scenes(video, end_time=15.0)         # seconds
scene_manager.detect_scenes(video, end_time=1500)         # frames
scene_manager.detect_scenes(video, end_time="00:01:00")   # timecode
```

--------------------------------

### Split video using Python API

Source: https://www.scenedetect.com/

Programmatically detect scenes using the AdaptiveDetector and split the video file using ffmpeg.

```python
from scenedetect import detect, AdaptiveDetector, split_video_ffmpeg

scene_list = detect("my_video.mp4", AdaptiveDetector())
split_video_ffmpeg("my_video.mp4", scene_list)
```

--------------------------------

### Verifying rational framerate

Source: https://www.scenedetect.com/docs/latest/_sources/api/migration_guide.rst.txt

VideoStream.frame_rate now returns a Fraction object instead of a float.

```python
from fractions import Fraction
video = open_video("video.mp4")
assert isinstance(video.frame_rate, Fraction)
# e.g. Fraction(24000, 1001) instead of 23.976023976...
```

--------------------------------

### save-qp

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Saves cuts as keyframes (I-frames) for video encoding.

```APIDOC
## CLI Command: save-qp

### Description
Generates a QP file containing keyframe information for use with x264/x265 encoders.

### Options
- **-f, --filename** (NAME) - Filename format.
- **-o, --output** (DIR) - Output directory.
- **-d, --disable-shift** (flag) - Disable shifting frame numbers by start time.
```

--------------------------------

### AdaptiveDetector Constructor

Source: https://www.scenedetect.com/docs/latest/api/detectors.html

Initializes a new instance of the AdaptiveDetector class.

```APIDOC
## AdaptiveDetector(adaptive_threshold, min_scene_len, window_width, min_content_val, weights, luma_only, kernel_size)

### Description
Initializes the AdaptiveDetector with specific thresholds and window settings for scene detection.

### Parameters
- **adaptive_threshold** (float) - Optional - Threshold that score ratio must exceed to trigger a new scene.
- **min_scene_len** (int|float|str|Timecode|FrameTimecode) - Optional - Minimum time required between scene cuts.
- **window_width** (int) - Optional - Size of window (number of frames) to average together.
- **min_content_val** (float) - Optional - Minimum threshold that the content_val must exceed to register a new scene.
- **weights** (Components) - Optional - Weight to place on each component when calculating frame score.
- **luma_only** (bool) - Optional - If True, only considers changes in the luminance channel.
- **kernel_size** (int|None) - Optional - Size of kernel to use for post edge detection filtering.
```

--------------------------------

### save-html

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Exports the scene list to an HTML file, optionally including scene images.

```APIDOC
## save-html

### Description
Save scene list to an HTML file. Uses images generated by the save-images command.

### Options
- **-f, --filename** (NAME) - Filename format. Default: $VIDEO_NAME-Scenes.html.
- **-n, --no-images** - Do not include images.
- **-w, --image-width** (pixels) - Width of images in table.
- **-h, --image-height** (pixels) - Height of images in table.
- **-s, --show** - Automatically open HTML file after processing.
```

--------------------------------

### Load Scenes CLI Commands

Source: https://www.scenedetect.com/docs/latest/_sources/cli.rst.txt

Commands to load scene cut information from a CSV file, optionally specifying the column name for cut locations.

```bash
scenedetect -i video.mp4 load-scenes -i scenes.csv
```

```bash
scenedetect -i video.mp4 load-scenes -i scenes.csv --start-col-name "Start Timecode"
```

--------------------------------

### write_scene_list_otio

Source: https://www.scenedetect.com/docs/latest/api/output.html

Writes a list of scenes to an OTIO (OpenTimelineIO) JSON document, which can be imported by various video editing software.

```APIDOC
## write_scene_list_otio

### Description
Writes the given list of scenes to output_path as an OTIO Timeline.1 JSON document.

### Parameters
- **output_path** (str|Path) - Required - Path to write the OTIO file to.
- **scene_list** (list[tuple[FrameTimecode, FrameTimecode]]) - Required - List of scenes as pairs of FrameTimecodes.
- **video_path** (str|Path) - Required - Path to the source video file.
- **frame_rate** (Fraction) - Required - Source frame rate as a rational Fraction.
- **name** (str|None) - Optional - Timeline name.
- **audio** (bool) - Optional - If True (default), include an audio track alongside the video track.
```

--------------------------------

### get_scenes_from_cuts(cut_list, start_pos, end_pos)

Source: https://www.scenedetect.com/docs/latest/api/scene_manager.html

Generates a list of start/end FrameTimecodes for each scene based on a provided list of detected scene cuts.

```APIDOC
## get_scenes_from_cuts(cut_list, start_pos, end_pos)

### Description
Returns a list of tuples of start/end FrameTimecodes for each scene based on a list of detected scene cuts/breaks.

### Parameters
- **cut_list** (list[FrameTimecode]) - Required - List of FrameTimecode objects where scene cuts/breaks occur.
- **start_pos** (int | FrameTimecode) - Required - The start position.
- **end_pos** (int | FrameTimecode) - Required - The end position.

### Returns
- **list[tuple[FrameTimecode, FrameTimecode]]** - List of tuples in the form (start_time, end_time).
```

--------------------------------

### VideoStreamCv2(path)

Source: https://www.scenedetect.com/docs/latest/api/backends.html

Directly constructs an OpenCV-based video stream.

```APIDOC
## VideoStreamCv2(path)

### Description
Manually constructs a video stream using the OpenCV backend.

### Parameters
- **path** (str) - Required - The path to the video file.

### Example
```python
from scenedetect.backends.opencv import VideoStreamCv2
video = VideoStreamCv2("video.mp4")
```
```
Tokens:
Raw