{"id":3798,"library":"scenedetect","title":"PySceneDetect","description":"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.","status":"active","version":"0.6.7.1","language":"en","source_language":"en","source_url":"https://github.com/Breakthrough/PySceneDetect/","tags":["video","scene detection","computer vision","video editing","ffmpeg"],"install":[{"cmd":"pip install scenedetect","lang":"bash","label":"Core library"},{"cmd":"pip install scenedetect[opencv,pyav]","lang":"bash","label":"With optional video backends (recommended)"}],"dependencies":[{"reason":"Requires Python 3.7 or newer. Older versions will cause installation errors.","package":"python","optional":false}],"imports":[{"symbol":"VideoManager","correct":"from scenedetect import VideoManager"},{"symbol":"SceneManager","correct":"from scenedetect import SceneManager"},{"symbol":"ContentDetector","correct":"from scenedetect.detectors import ContentDetector"},{"symbol":"save_csv","correct":"from scenedetect.scene_manager import save_csv"}],"quickstart":{"code":"import os\nfrom scenedetect import VideoManager\nfrom scenedetect import SceneManager\nfrom scenedetect.detectors import ContentDetector\nfrom scenedetect.stats_manager import StatsManager\nfrom scenedetect.scene_manager import save_csv\n\n# IMPORTANT: Replace 'path/to/your/video.mp4' with an actual video file.\n# For local testing without providing a video, this will create a dummy file,\n# but actual scene detection requires a valid video.\nVIDEO_PATH = os.environ.get('SCENEDETECT_TEST_VIDEO', 'dummy_video.mp4')\nOUTPUT_DIR = '.' # Current directory for output CSV\n\n# Create a dummy file if the video path doesn't exist, to make code runnable\n# without a real video for initial syntax checks. \n# A real video is required for meaningful scene detection.\nif not os.path.exists(VIDEO_PATH) or not os.path.getsize(VIDEO_PATH) > 0:\n    print(f\"Warning: Video file '{VIDEO_PATH}' not found or empty. Creating a dummy file.\")\n    print(\"For actual scene detection, set SCENEDETECT_TEST_VIDEO or provide a real video.\")\n    with open(VIDEO_PATH, 'w') as f:\n        f.write(\"This is a dummy file. Replace with a real video for scene detection.\")\n\nvideo_manager = VideoManager([VIDEO_PATH])\nstats_manager = StatsManager()\nscene_manager = SceneManager(stats_manager)\n\n# Add ContentDetector (default detector)\nscene_manager.add_detector(ContentDetector())\n\ntry:\n    # Set downscale factor for faster processing (e.g., 1/2 resolution)\n    video_manager.set_downscale_factor()\n\n    # Start video processing (loads frames or prepares for frame-by-frame)\n    video_manager.start()\n\n    # Perform scene detection\n    scene_manager.detect_scenes(frame_source=video_manager)\n\n    # Obtain list of scenes\n    scene_list = scene_manager.get_scene_list()\n    print(f'Detected {len(scene_list)} scenes.')\n\n    # Example: Save detected scenes to a CSV file\n    output_csv_path = os.path.join(OUTPUT_DIR, 'scenes.csv')\n    save_csv(output_csv_path, scene_list, output_dir=OUTPUT_DIR) # output_dir argument added for clarity\n    print(f'Scene list saved to {output_csv_path}')\n\nexcept Exception as e:\n    print(f\"An error occurred during scene detection: {e}\")\nfinally:\n    video_manager.release()\n","lang":"python","description":"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]`)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.6"},{"fix":"Ensure your Python environment is version 3.7 or higher. Upgrade Python if necessary.","message":"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.","severity":"breaking","affected_versions":">=0.6.2"},{"fix":"Install with recommended extras: `pip install scenedetect[opencv,pyav]`. For specific needs, refer to the documentation for other available extras.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.6.7"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}