# breakthrough/pyscenedetect architecture

> Architecture diagram of the GitHub repository breakthrough/pyscenedetect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/breakthrough/pyscenedetect
- Repository: https://github.com/breakthrough/pyscenedetect

## Overview

PySceneDetect detects video cuts and turns them into scene boundaries, through either its Python API or CLI. The main workflow opens a video, processes frames with selected detection algorithms, and returns scene timecodes; CLI commands and API helpers can then save images, split video, or export scene data. The graph also shows video backends and stats support. Some links reflect documented or indexed dependencies rather than inspected call sites, so those are dashed and unverified.

Main entry points: [`scenedetect/scene_manager.py`](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/scene_manager.py) (Scene manager), [`scenedetect/video_stream.py`](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/video_stream.py) (Video stream API), [`scenedetect/__init__.py`](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/__init__.py) (Python API), [`scenedetect/_cli/controller.py`](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/controller.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_cli["CLI<br/>[controller.py]"]
  node_cli_config["CLI config<br/>[config.py]"]
  node_cli_context["CLI context<br/>[context.py]"]
  node_cli_commands["CLI commands<br/>[commands.py]"]
end

subgraph group_detection["Video detection"]
  node_scene_manager["Scene manager<br/>[scene_manager.py]"]
  node_detectors["Detection algorithms"]
  node_detector_base["Detector interface<br/>[detector.py]"]
  node_timecodes["Timecodes<br/>[common.py]"]
  node_stats[("Frame statistics<br/>[stats_manager.py]")]
end

subgraph group_media["Media I/O"]
  node_video_stream["Video stream API<br/>[video_stream.py]"]
  node_opencv["OpenCV backend<br/>[opencv.py]"]
  node_pyav["PyAV backend<br/>[pyav.py]"]
  node_moviepy["MoviePy backend<br/>[moviepy.py]"]
  node_concat["Concatenated video<br/>[concat.py]"]
end

subgraph group_results["Scene results"]
  node_image_output["Image output<br/>[image.py]"]
  node_video_output["Video output<br/>[video.py]"]
  node_output_formats["Scene exports<br/>[__init__.py]"]
end

node_user(("User"))
node_ffmpeg["ffmpeg / mkvmerge"]

node_user -->|"calls"| node_python_api
node_user -->|"runs"| node_cli
node_python_api -->|"runs detection"| node_scene_manager
node_python_api -.->|"opens video"| node_video_stream
node_python_api -.->|"selects detector"| node_detectors
node_cli -.->|"uses context"| node_cli_context
node_cli_context -.->|"reads config"| node_cli_config
node_cli -->|"runs detection"| node_scene_manager
node_cli -->|"dispatches commands"| node_cli_commands
node_scene_manager -->|"reads frames"| node_video_stream
node_scene_manager -.->|"processes frames"| node_detector_base
node_detectors -.->|"implements"| node_detector_base
node_scene_manager -.->|"records metrics"| node_stats
node_scene_manager -.->|"tracks boundaries"| node_timecodes
node_video_stream -.->|"backend"| node_opencv
node_video_stream -.->|"backend"| node_pyav
node_video_stream -.->|"backend"| node_moviepy
node_video_stream -.->|"backend"| node_concat
node_cli_commands -.->|"saves frames"| node_image_output
node_cli_commands -.->|"splits video"| node_video_output
node_cli_commands -.->|"exports scenes"| node_output_formats
node_user -->|"requests images"| node_image_output
node_user -->|"requests split"| node_video_output
node_video_output -.->|"invokes tool"| node_ffmpeg

click node_python_api "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/__init__.py"
click node_cli "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/controller.py"
click node_cli_config "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/config.py"
click node_cli_context "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/context.py"
click node_cli_commands "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/commands.py"
click node_scene_manager "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/scene_manager.py"
click node_detectors "https://github.com/breakthrough/pyscenedetect/tree/main/scenedetect/detectors"
click node_detector_base "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/detector.py"
click node_timecodes "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/common.py"
click node_stats "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/stats_manager.py"
click node_video_stream "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/video_stream.py"
click node_opencv "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/opencv.py"
click node_pyav "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/pyav.py"
click node_moviepy "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/moviepy.py"
click node_concat "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/concat.py"
click node_image_output "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/output/image.py"
click node_video_output "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/output/video.py"
click node_output_formats "https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/output/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_api,node_cli,node_cli_config,node_cli_context,node_cli_commands,node_user toneBlue
class node_scene_manager,node_detectors,node_detector_base,node_timecodes,node_stats toneAmber
class node_video_stream,node_opencv,node_pyav,node_moviepy,node_concat toneMint
class node_image_output,node_video_output,node_output_formats toneRose
class node_ffmpeg toneIndigo
```

## Components

### User entry points

- [Python API](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/__init__.py): `scenedetect/__init__.py`
- [CLI](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/controller.py): `scenedetect/_cli/controller.py`
- [CLI config](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/config.py): `scenedetect/_cli/config.py`
- [CLI context](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/context.py): `scenedetect/_cli/context.py`
- [CLI commands](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/_cli/commands.py): `scenedetect/_cli/commands.py`

### Video detection

- [Scene manager](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/scene_manager.py): `scenedetect/scene_manager.py`
- [Detection algorithms](https://github.com/breakthrough/pyscenedetect/tree/main/scenedetect/detectors): `scenedetect/detectors`
- [Detector interface](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/detector.py): `scenedetect/detector.py`
- [Timecodes](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/common.py): `scenedetect/common.py`
- [Frame statistics](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/stats_manager.py): `scenedetect/stats_manager.py`

### Media I/O

- [Video stream API](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/video_stream.py): `scenedetect/video_stream.py`
- [OpenCV backend](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/opencv.py): `scenedetect/backends/opencv.py`
- [PyAV backend](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/pyav.py): `scenedetect/backends/pyav.py`
- [MoviePy backend](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/moviepy.py): `scenedetect/backends/moviepy.py`
- [Concatenated video](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/backends/concat.py): `scenedetect/backends/concat.py`

### Scene results

- [Image output](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/output/image.py): `scenedetect/output/image.py`
- [Video output](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/output/video.py): `scenedetect/output/video.py`
- [Scene exports](https://github.com/breakthrough/pyscenedetect/blob/main/scenedetect/output/__init__.py): `scenedetect/output/__init__.py`

### Other components

- **User**
- **ffmpeg / mkvmerge**

## Connections

- User → Python API: calls
- User → CLI: runs
- Python API → Scene manager: runs detection (evidence: `scenedetect/__init__.py`)
- Python API → Video stream API: opens video (evidence: `scenedetect/__init__.py`)
- Python API → Detection algorithms: selects detector (evidence: `scenedetect/__init__.py`)
- CLI → CLI context: uses context (evidence: `scenedetect/_cli/controller.py`)
- CLI context → CLI config: reads config (evidence: `scenedetect/_cli/context.py`)
- CLI → Scene manager: runs detection (evidence: `scenedetect/_cli/controller.py`)
- CLI → CLI commands: dispatches commands (evidence: `scenedetect/_cli/controller.py`)
- Scene manager → Video stream API: reads frames (evidence: `scenedetect/scene_manager.py`)
- Scene manager → Detector interface: processes frames (evidence: `scenedetect/scene_manager.py`)
- Detection algorithms → Detector interface: implements (evidence: `scenedetect/detectors/__init__.py`)
- Scene manager → Frame statistics: records metrics (evidence: `scenedetect/scene_manager.py`)
- Scene manager → Timecodes: tracks boundaries (evidence: `scenedetect/scene_manager.py`)
- Video stream API → OpenCV backend: backend (evidence: `scenedetect/backends/opencv.py`)
- Video stream API → PyAV backend: backend (evidence: `scenedetect/backends/pyav.py`)
- Video stream API → MoviePy backend: backend (evidence: `scenedetect/backends/moviepy.py`)
- Video stream API → Concatenated video: backend (evidence: `scenedetect/backends/concat.py`)
- CLI commands → Image output: saves frames (evidence: `scenedetect/_cli/commands.py`)
- CLI commands → Video output: splits video (evidence: `scenedetect/_cli/commands.py`)
- CLI commands → Scene exports: exports scenes (evidence: `scenedetect/_cli/commands.py`)
- User → Image output: requests images
- User → Video output: requests split
- Video output → ffmpeg / mkvmerge: invokes tool
