fix: 重构

docs/scenedetect-installation.md

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