mxivideo/docs/scenedetect-installation.md

PySceneDetect 依赖安装指南

📦 依赖添加

已添加到 requirements.txt

scenedetect[opencv]

这个版本包含了OpenCV支持，提供最佳的场景检测性能。

🚀 安装方法

方法1: 使用pip直接安装 (推荐)

pip install scenedetect[opencv]

方法2: 使用requirements.txt安装

pip install -r python_core/requirements.txt

方法3: 使用提供的脚本

Windows:

scripts\install_scenedetect.bat

Linux/macOS:

chmod +x scripts/install_scenedetect_simple.sh
./scripts/install_scenedetect_simple.sh

Python脚本:

python scripts/install_dependencies.py

🧪 验证安装

1. 检查导入

import scenedetect
print(f"PySceneDetect版本: {scenedetect.__version__}")

2. 测试基本功能

from scenedetect import VideoManager, SceneManager
from scenedetect.detectors import ContentDetector

# 创建管理器
video_manager = VideoManager([])
scene_manager = SceneManager()
scene_manager.add_detector(ContentDetector())

print("✅ PySceneDetect功能正常")

🔧 集成状态

media_manager.py 中的集成

• ✅ 主要方法: _detect_scene_changes() 优先使用PySceneDetect
• ✅ 备用方案: 如果PySceneDetect不可用，自动回退到OpenCV方法
• ✅ 错误处理: 完善的异常处理和日志记录

使用流程

# 在media_manager.py中
def _detect_scene_changes(self, file_path: str, threshold: float = 30.0) -> List[float]:
    if SCENEDETECT_AVAILABLE:
        try:
            # 使用PySceneDetect进行高精度检测
            return self._detect_with_pyscenedetect(file_path, threshold)
        except Exception as e:
            logger.error(f"PySceneDetect failed: {e}")
            # 回退到OpenCV方法
            return self._detect_scene_changes_opencv(file_path, threshold)
    else:
        # 直接使用OpenCV方法
        return self._detect_scene_changes_opencv(file_path, threshold)

📊 性能对比

方法	准确性	速度	资源占用	推荐场景
PySceneDetect	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	高质量分镜
OpenCV	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	快速处理

🎯 配置参数

PySceneDetect 参数

# 在_detect_scene_changes中
scene_manager.add_detector(ContentDetector(threshold=threshold))

threshold 参数说明:

• 10-20: 高敏感度，检测更多场景变化
• 25-35: 中等敏感度，适合大多数情况 (默认30.0)
• 40-50: 低敏感度，只检测明显的场景变化

使用建议

# 高质量视频，需要精确分镜
scene_changes = media_manager._detect_scene_changes(video_path, threshold=25.0)

# 快速预览，粗略分镜
scene_changes = media_manager._detect_scene_changes(video_path, threshold=40.0)

🔍 故障排除

常见问题

1. 安装失败

ERROR: Could not find a version that satisfies the requirement scenedetect

解决方案:

# 更新pip
pip install --upgrade pip

# 重新安装
pip install scenedetect[opencv]

2. 导入失败

ImportError: No module named 'scenedetect'

解决方案:

# 检查Python环境
which python
pip list | grep scenedetect

# 重新安装
pip install --force-reinstall scenedetect[opencv]

3. OpenCV依赖问题

ImportError: No module named 'cv2'

解决方案:

# 安装OpenCV
pip install opencv-python

# 或者重新安装完整版本
pip install scenedetect[opencv]

检查安装状态

# 检查PySceneDetect
try:
    import scenedetect
    print(f"✅ PySceneDetect {scenedetect.__version__}")
except ImportError:
    print("❌ PySceneDetect 未安装")

# 检查OpenCV
try:
    import cv2
    print(f"✅ OpenCV {cv2.__version__}")
except ImportError:
    print("❌ OpenCV 未安装")

📚 相关文档

• PySceneDetect 官方文档
• PySceneDetect GitHub
• 场景检测测试脚本

🎉 安装完成后

安装成功后，系统将：

1. 自动使用PySceneDetect: 新导入的视频将使用更准确的场景检测
2. 保持兼容性: 如果PySceneDetect不可用，自动回退到OpenCV
3. 提升分镜质量: 更准确的场景边界检测
4. 支持多种视频格式: 更好的格式兼容性

验证效果

重新导入视频文件，观察日志输出：

INFO: PySceneDetect found 5 scene changes in video
DEBUG: Scene change timestamps: [0.0, 15.2, 32.8, 48.1, 65.3, 78.9]

---

PySceneDetect 依赖安装完成，享受更准确的视频场景检测！