mxivideo/docs/scene-detection-cli-tool.md

# 批量场景检测命令行工具

## 🎯 工具概述

开发了一个功能完整的批量场景检测命令行工具，使用带进度条的JSON-RPC Commander，支持多种检测算法、批量处理、实时进度显示和多格式输出。

## 📊 **开发结果**
```
🎉 所有场景检测工具测试通过！

✅ 功能验证:
   1. 模块导入正确 - ✅
   2. 服务创建成功 - ✅
   3. 命令注册完整 - ✅
   4. 参数解析正常 - ✅
   5. 单个检测工作 - ✅
   6. 批量检测工作 - ✅
   7. CLI执行正常 - ✅
   8. 输出格式支持 - ✅
```

## 🏗️ **架构设计**

### **模块化结构**
```
scene_detection/
├── __init__.py      - 统一导入接口
├── types.py         - 数据类型定义
├── detector.py      - 场景检测服务
└── cli.py           - 命令行接口（带进度条）
```

### **核心组件**

#### **1. 数据类型 (types.py)**
```python
@dataclass
class SceneInfo:
    """场景信息"""
    index: int
    start_time: float
    end_time: float
    duration: float
    confidence: float = 0.0

@dataclass
class VideoSceneResult:
    """单个视频的场景检测结果"""
    video_path: str
    filename: str
    success: bool
    total_scenes: int
    scenes: List[SceneInfo]
    detection_time: float

@dataclass
class BatchDetectionResult:
    """批量检测结果"""
    total_files: int
    processed_files: int
    failed_files: int
    total_scenes: int
    results: List[VideoSceneResult]
```

#### **2. 检测服务 (detector.py)**
```python
class SceneDetectionService:
    """场景检测服务"""
    
    def detect_single_video(self, video_path: str, config: BatchDetectionConfig) -> VideoSceneResult:
        """检测单个视频的场景"""
    
    def batch_detect_scenes(self, input_directory: str, config: BatchDetectionConfig,
                           progress_callback: Optional[Callable] = None) -> BatchDetectionResult:
        """批量检测场景"""
    
    def save_results(self, result: BatchDetectionResult, output_path: str) -> bool:
        """保存检测结果"""
```

#### **3. 命令行接口 (cli.py)**
```python
class SceneDetectionCommander(ProgressJSONRPCCommander):
    """场景检测命令行接口 - 支持进度条"""
    
    def _is_progressive_command(self, command: str) -> bool:
        """判断是否需要进度报告的命令"""
        return command in ["batch_detect", "compare"]
```

## 🔧 **核心功能**

### **1. 多种检测算法**
- **Content检测器** - 基于内容变化检测场景
- **Threshold检测器** - 基于阈值的场景检测
- **Adaptive检测器** - 自适应场景检测

### **2. 四个主要命令**

#### **detect - 单个视频检测**
```bash
python -m python_core.services.scene_detection detect video.mp4 \
    --detector content \
    --threshold 30.0 \
    --output results.json
```

**特点**:
- 🎯 单个视频快速检测
- 🔧 可配置检测器和阈值
- 📄 支持多种输出格式

#### **batch_detect - 批量检测（带进度条）**
```bash
python -m python_core.services.scene_detection batch_detect /path/to/videos \
    --detector content \
    --threshold 30.0 \
    --output batch_results.json
```

**特点**:
- 📦 目录级批量处理
- 📊 实时进度显示
- 📈 详细统计信息
- 🛡️ 错误恢复机制

**进度显示示例**:
```
📊 进度: 检测场景: demo_video_1.mp4 (1/3)
📊 进度: 检测场景: demo_video_2.mp4 (2/3)
📊 进度: 检测场景: demo_video_3.mp4 (3/3)
✅ 批量检测完成: 3 成功, 0 失败
```

#### **compare - 检测器比较（带进度条）**
```bash
python -m python_core.services.scene_detection compare video.mp4 \
    --thresholds 20,30,40 \
    --output comparison.json
```

**特点**:
- 🔬 自动测试多种检测器
- 📊 性能对比分析
- 💡 智能推荐最佳参数

**比较结果示例**:
```
📊 比较结果摘要:
   成功测试数: 9
   推荐检测器: content
   建议: 推荐使用 content 检测器

📋 各检测器表现:
   🔧 content 检测器:
      平均场景数: 2.0
      平均检测时间: 0.41秒
   🔧 adaptive 检测器:
      平均场景数: 2.0
      平均检测时间: 0.39秒
```

#### **analyze - 结果分析**
```bash
python -m python_core.services.scene_detection analyze results.json \
    --output stats.json
```

**特点**:
- 📈 统计信息生成
- 📊 数据洞察分析
- 📝 详细报告输出

### **3. 多格式输出支持**

#### **JSON格式** - 结构化数据
```json
{
  "summary": {
    "total_files": 3,
    "processed_files": 3,
    "total_scenes": 13,
    "average_scenes_per_video": 4.3
  },
  "results": [
    {
      "filename": "video.mp4",
      "total_scenes": 3,
      "scenes": [
        {
          "index": 0,
          "start_time": 0.0,
          "end_time": 4.04,
          "duration": 4.04
        }
      ]
    }
  ]
}
```

#### **CSV格式** - 表格数据
```csv
filename,video_path,scene_index,start_time,end_time,duration,confidence
video.mp4,/path/to/video.mp4,0,0.0,4.04,4.04,1.0
video.mp4,/path/to/video.mp4,1,4.04,8.04,4.0,1.0
```

#### **TXT格式** - 人类可读
```
批量场景检测结果
==================================================

总文件数: 3
处理成功: 3
总场景数: 13
平均场景数: 4.3

文件: video.mp4
  场景数: 3
  时长: 10.04秒
    场景 0: 0.00s - 4.04s (4.04s)
    场景 1: 4.04s - 8.04s (4.00s)
```

## 🚀 **进度条集成**

### **智能进度识别**
```python
def _is_progressive_command(self, command: str) -> bool:
    """判断是否需要进度报告的命令"""
    return command in ["batch_detect", "compare"]
```

**需要进度的命令**:
- ✅ `batch_detect` - 批量检测（文件级进度）
- ✅ `compare` - 检测器比较（测试级进度）

**不需要进度的命令**:
- ⚡ `detect` - 单个检测（快速完成）
- ⚡ `analyze` - 结果分析（本地处理）

### **实时进度反馈**
```
JSONRPC:{"jsonrpc":"2.0","method":"progress","params":{
  "step":"scene_detection",
  "progress":0.33,
  "message":"检测场景: demo_video_2.mp4 (2/3)",
  "details":{
    "current":1,
    "total":3,
    "elapsed_time":0.46,
    "estimated_remaining":0.92
  }
}}
```

### **批量处理进度管理**
```python
with self.create_task("批量场景检测", len(video_files)) as task:
    for i, video_path in enumerate(video_files):
        filename = os.path.basename(video_path)
        task.update(i, f"检测场景: {filename} ({i+1}/{len(video_files)})")
        
        # 处理单个文件...
        
    task.finish(f"批量检测完成: {processed} 成功, {failed} 失败")
```

## 📈 **实际演示结果**

### **单个视频检测**
```
✅ 检测成功！
   文件名: 1752038614561.mp4
   场景数量: 3
   视频时长: 10.04秒
   检测时间: 0.86秒
   检测器类型: content
   检测阈值: 30.0

📋 场景详情:
   场景 1: 0.00s - 4.04s (4.04s)
   场景 2: 4.04s - 8.04s (4.00s)
   场景 3: 8.04s - 10.04s (2.00s)
```

### **批量检测**
```
✅ 批量检测完成！
   总文件数: 3
   处理成功: 3
   处理失败: 0
   总场景数: 13
   总时长: 30.12秒
   平均场景数: 4.3
   检测时间: 1.29秒
```

### **检测器比较**
```
✅ 检测器比较完成！
   总测试数: 9
   推荐检测器: content
   建议: 推荐使用 content 检测器

📋 各检测器表现:
   🔧 content 检测器: 平均2.0场景, 0.41秒
   🔧 adaptive 检测器: 平均2.0场景, 0.39秒
   🔧 threshold 检测器: 平均0.0场景, 0.40秒
```

## 💡 **应用场景**

### **1. 视频内容分析**
- 📹 自动识别视频中的场景变化
- 🎬 为视频建立时间轴索引
- 📊 分析视频内容结构

### **2. 影视后期制作**
- ✂️ 快速定位剪辑点
- 🎞️ 自动生成场景列表
- 🔍 辅助内容审核

### **3. 视频库管理**
- 📚 为大量视频建立场景索引
- 🗂️ 批量处理视频库
- 📈 生成统计报告

### **4. 研究和开发**
- 🔬 比较不同检测算法效果
- 📊 性能基准测试
- 💡 算法参数优化

## 🎯 **技术特点**

### **1. 模块化设计**
- 🧩 清晰的模块分离
- 🔌 可扩展的架构
- 📦 独立的功能组件

### **2. 进度可视化**
- 📊 实时进度反馈
- ⏱️ 时间估算
- 📈 处理统计

### **3. 错误处理**
- 🛡️ 单个失败不影响整体
- 📝 详细错误信息
- 🔄 自动恢复机制

### **4. 多格式支持**
- 📄 JSON/CSV/TXT输出
- 🔧 灵活的配置选项
- 📊 丰富的统计信息

## 🎉 **总结**

### **开发成果**
- ✅ **功能完整** - 4个主要命令，覆盖所有使用场景
- ✅ **进度可视** - 批量操作实时进度显示
- ✅ **算法多样** - 支持3种检测算法
- ✅ **格式丰富** - 3种输出格式
- ✅ **性能优秀** - 快速检测，智能比较

### **技术亮点**
- 🎯 **智能化** - 自动识别进度命令
- 🔄 **可靠性** - 完善的错误处理
- 📊 **可视化** - JSON-RPC进度协议
- 🔧 **灵活性** - 丰富的配置选项

### **实用价值**
- 💡 **提升效率** - 批量处理大量视频
- 🚀 **降低成本** - 自动化场景分析
- 📈 **数据洞察** - 详细的统计分析
- 🔍 **质量保证** - 多算法对比验证

通过这个工具，用户可以高效地进行大规模视频场景检测，获得详细的分析结果，并通过进度条实时了解处理状态！

---

*批量场景检测工具 - 让视频分析变得简单、高效、可视化！*