PySceneDetect

0.6.7.1 · active · verified Sat Apr 11

PySceneDetect is a Python library and command-line tool for automatic scene detection in videos. It can detect hard cuts, gradual transitions (fades, dissolves), and more using various algorithms. The current version is 0.6.7.1, and the project maintains an active release cadence with frequent minor updates and occasional major versions introducing significant features or breaking changes.

Warnings

breaking Version 0.6 introduced significant breaking changes to the API, including module reorganizations and revised class structures. Code written for pre-0.6 versions will not work without modification.
Fix: Consult the official 'Migration Guide' (e.g., manual.scenedetect.com/en/v0.6/api/migration_guide.html) to update your codebase to the new API.
breaking PySceneDetect versions 0.6.2 and later require Python 3.7 or newer. Attempts to install or run the library on older Python versions will fail.
Fix: Ensure your Python environment is version 3.7 or higher. Upgrade Python if necessary.
gotcha While the core library works with a basic `pip install scenedetect`, many video formats or optimal performance require optional video backends (e.g., PyAV, OpenCV). Without them, certain video files might not be processed correctly or efficiently.
Fix: Install with recommended extras: `pip install scenedetect[opencv,pyav]`. For specific needs, refer to the documentation for other available extras.
gotcha Versions of PySceneDetect prior to 0.6.7 had an off-by-one frame error when generating EDL (Edit Decision List) files, potentially causing end timestamps to be slightly too short when imported into video editors like DaVinci Resolve.
Fix: Upgrade to PySceneDetect v0.6.7 or newer to ensure correct EDL output. If using older versions, manually adjust EDL end timestamps if issues arise in your video editor.

Install

pip install scenedetect Core library
pip install scenedetect[opencv,pyav] With optional video backends (recommended)

Imports

VideoManager
```
from scenedetect import VideoManager
```
SceneManager
```
from scenedetect import SceneManager
```

ContentDetector

from scenedetect.detectors import ContentDetector

save_csv

from scenedetect.scene_manager import save_csv

Quickstart

This quickstart demonstrates how to initialize PySceneDetect, add a ContentDetector (the most common type), process a video, and save the detected scenes to a CSV file. Remember to replace 'path/to/your/video.mp4' with a valid video file path. For full functionality and broader video format support, it's recommended to install with optional backends like OpenCV and PyAV (`pip install scenedetect[opencv,pyav]`).

import os
from scenedetect import VideoManager
from scenedetect import SceneManager
from scenedetect.detectors import ContentDetector
from scenedetect.stats_manager import StatsManager
from scenedetect.scene_manager import save_csv

# IMPORTANT: Replace 'path/to/your/video.mp4' with an actual video file.
# For local testing without providing a video, this will create a dummy file,
# but actual scene detection requires a valid video.
VIDEO_PATH = os.environ.get('SCENEDETECT_TEST_VIDEO', 'dummy_video.mp4')
OUTPUT_DIR = '.' # Current directory for output CSV

# Create a dummy file if the video path doesn't exist, to make code runnable
# without a real video for initial syntax checks. 
# A real video is required for meaningful scene detection.
if not os.path.exists(VIDEO_PATH) or not os.path.getsize(VIDEO_PATH) > 0:
    print(f"Warning: Video file '{VIDEO_PATH}' not found or empty. Creating a dummy file.")
    print("For actual scene detection, set SCENEDETECT_TEST_VIDEO or provide a real video.")
    with open(VIDEO_PATH, 'w') as f:
        f.write("This is a dummy file. Replace with a real video for scene detection.")

video_manager = VideoManager([VIDEO_PATH])
stats_manager = StatsManager()
scene_manager = SceneManager(stats_manager)

# Add ContentDetector (default detector)
scene_manager.add_detector(ContentDetector())

try:
    # Set downscale factor for faster processing (e.g., 1/2 resolution)
    video_manager.set_downscale_factor()

    # Start video processing (loads frames or prepares for frame-by-frame)
    video_manager.start()

    # Perform scene detection
    scene_manager.detect_scenes(frame_source=video_manager)

    # Obtain list of scenes
    scene_list = scene_manager.get_scene_list()
    print(f'Detected {len(scene_list)} scenes.')

    # Example: Save detected scenes to a CSV file
    output_csv_path = os.path.join(OUTPUT_DIR, 'scenes.csv')
    save_csv(output_csv_path, scene_list, output_dir=OUTPUT_DIR) # output_dir argument added for clarity
    print(f'Scene list saved to {output_csv_path}')

except Exception as e:
    print(f"An error occurred during scene detection: {e}")
finally:
    video_manager.release()

view raw JSON →