mxivideo/docs/scenedetect-installation.md

# PySceneDetect 依赖安装指南

## 📦 依赖添加

### 已添加到 requirements.txt
```
scenedetect[opencv]
```

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

## 🚀 安装方法

### 方法1: 使用pip直接安装 (推荐)
```bash
pip install scenedetect[opencv]
```

### 方法2: 使用requirements.txt安装
```bash
pip install -r python_core/requirements.txt
```

### 方法3: 使用提供的脚本

#### Windows:
```cmd
scripts\install_scenedetect.bat
```

#### Linux/macOS:
```bash
chmod +x scripts/install_scenedetect_simple.sh
./scripts/install_scenedetect_simple.sh
```

#### Python脚本:
```bash
python scripts/install_dependencies.py
```

## 🧪 验证安装

### 1. 检查导入
```python
import scenedetect
print(f"PySceneDetect版本: {scenedetect.__version__}")
```

### 2. 测试基本功能
```python
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方法
- ✅ **错误处理**: 完善的异常处理和日志记录

### 使用流程
```python
# 在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 参数
```python
# 在_detect_scene_changes中
scene_manager.add_detector(ContentDetector(threshold=threshold))
```

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

### 使用建议
```python
# 高质量视频，需要精确分镜
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
```

**解决方案**:
```bash
# 更新pip
pip install --upgrade pip

# 重新安装
pip install scenedetect[opencv]
```

#### 2. 导入失败
```
ImportError: No module named 'scenedetect'
```

**解决方案**:
```bash
# 检查Python环境
which python
pip list | grep scenedetect

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

#### 3. OpenCV依赖问题
```
ImportError: No module named 'cv2'
```

**解决方案**:
```bash
# 安装OpenCV
pip install opencv-python

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

### 检查安装状态
```python
# 检查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 官方文档](https://pyscenedetect.readthedocs.io/)
- [PySceneDetect GitHub](https://github.com/Breakthrough/PySceneDetect)
- [场景检测测试脚本](../scripts/test_scene_detection.py)

## 🎉 安装完成后

安装成功后，系统将：

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 依赖安装完成，享受更准确的视频场景检测！*