comi-logic/mxivideo
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix

Browse Source
This commit is contained in:
root
2025-07-11 22:00:47 +08:00
parent d0881dc16e
commit d74ae45416
6 changed files with 1556 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

383
docs/scene-detection-cli-tool.md Normal file
View File

@@ -0,0 +1,383 @@
# 批量场景检测命令行工具
## 🎯 工具概述
开发了一个功能完整的批量场景检测命令行工具，使用带进度条的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进度协议
- 🔧 **灵活性** - 丰富的配置选项
### **实用价值**
- 💡 **提升效率** - 批量处理大量视频
- 🚀 **降低成本** - 自动化场景分析
- 📈 **数据洞察** - 详细的统计分析
- 🔍 **质量保证** - 多算法对比验证
通过这个工具，用户可以高效地进行大规模视频场景检测，获得详细的分析结果，并通过进度条实时了解处理状态！
---
*批量场景检测工具 - 让视频分析变得简单、高效、可视化！*