一个完整的视频质量评估与内容过滤系统。通过五个专业的视频分析模块，对视频进行逐步处理和质量筛选，具有断点续传、多进程并行处理和完善的错误恢复机制。
- 五阶段处理管道：格式标准化 → 场景分割 → 人脸检测 → 文字遮挡检测 → 音视频同步检测
- 断点续传支持：通过 JSON 状态文件记录处理进度，支持从中断点恢复
- 高效并行处理：支持高达 127 个并发进程，可根据硬件配置调整
- 智能错误恢复：详细的失败日志和错误追踪，允许流水线在单个模块失败时继续运行
- 灵活运行模式：完整流水线编排或独立模块运行
- 综合日志记录：自定义 TqdmLoggingHandler 防止进度条与日志冲突
╔══════════════════════════════════════════════════════════════════════╗
║ 输入视频集合 ║
╚════════════════════════════╤═════════════════════════════════════════╝
│
┌────────────────────▼────────────────────┐
│ 阶段 1: 格式转换 (H.264/AAC) │
│ • ffmpeg 转码为统一格式 │
│ • 保留原始分辨率和帧率 │
│ • 支持多格式输入 (MP4/MOV/AVI/MKV等) │
│ • 依赖: ffmpeg, ffprobe │
└────────────────┬─────────────────────────┘
│
┌────────────────▼────────────────────┐
│ 阶段 2: 快速场景检测 │
│ • HSV 直方图相关性检测 │
│ • 自适应阈值 (mean + 1.5*std) │
│ • 均匀采样处理 (默认10帧) │
│ • 帧缩放至 320x180 提升速度 │
│ • 生成场景边界 (start_frame, end_frame) │
└────────────────┬─────────────────────────┘
│
┌────────────────▼────────────────────┐
│ 阶段 3: Haar级联人脸检测 │
│ • 随机采样视频帧 (可配置采样数) │
│ • 线程安全的级联分类器检测 │
│ • 片段合并和持续时间管理 │
│ • FFmpeg 基于帧范围剪裁 │
│ • ProcessPoolExecutor 并行处理 │
└────────────────┬─────────────────────────┘
│
┌────────────────▼────────────────────┐
│ 阶段 4: EAST 文字检测 │
│ • EAST 深度学习文字检测模型 │
│ • 320x320 输入处理 │
│ • 置信度阈值过滤 (默认 0.5) │
│ • NMS 去重 (阈值 0.4) │
│ • GPU 支持 (CUDA 自动检测) │
│ • 与人脸检测结果加权融合 │
└────────────────┬─────────────────────────┘
│
┌────────────────▼────────────────────┐
│ 阶段 5: 语音同步检测 │
│ • librosa 语音活动检测 │
│ • Haar 口部运动检测 │
│ • 自适应能量阈值 │
│ • 口型-音频匹配分析 │
│ • 同步片段提取 │
│ • 支持无音频处理 (仅视觉) │
└────────────────┬─────────────────────────┘
│
╔════════════════════════╤═════════════════════════════════════════════╗
║ 最终处理结果集合 ║
║ (每个阶段输出都保存在独立目录) ║
╚══════════════════════════════════════════════════════════════════════╝
- Python: 3.7+
- FFmpeg: 必需（用于视频编解码）
- CUDA (可选): GPU 加速支持
# 1. 克隆仓库
git clone https://github.com/bohyy/-pipeline.git
cd -pipeline
# 2. 安装 FFmpeg (根据系统选择)
# Ubuntu/Debian
sudo apt-get install ffmpeg
# macOS
brew install ffmpeg
# Windows - 从 https://ffmpeg.org/download.html 下载
# 3. 安装 Python 依赖
pip install -r requirements.txtpython pipeline.py \
--input_dir /path/to/videos \
--output_dir /path/to/results \
--temp_dir /path/to/temp \
--workers 8参数说明：
--input_dir: 输入视频目录（支持递归查找）--output_dir: 输出结果基础目录--temp_dir: 临时文件存储位置（每个阶段使用时间戳子目录）--workers: 并发进程数（默认4，最大127，建议为 CPU 核心数的 50-75%）
# 从第 3 阶段 (人脸检测) 开始
python pipeline.py \
--input_dir /path/to/videos \
--output_dir /path/to/results \
--workers 8 \
--start_stage 3python pipeline.py --config pipeline_config.json配置文件示例 (pipeline_config.json):
{
"input_dir": "/data/videos",
"output_dir": "/results",
"temp_dir": "/tmp",
"workers": 8,
"start_stage": 1,
"modules": {
"scene_detector": {
"threshold": 30.0,
"min_scene_length": 10,
"method": "histogram"
},
"face_detector": {
"samples_per_video": 10,
"min_face_duration": 0.5
},
"text_detector": {
"confidence_threshold": 0.5,
"model_path": "path/to/east_model"
},
"audio_sync": {
"min_sync_duration": 0.5,
"enable_audio": true
}
}
}功能：将多种视频格式统一转码为 H.264/AAC 标准格式
核心函数：
get_video_info(file_path)- 使用 ffprobe 获取视频元数据should_convert(input_path, output_path)- 根据时间戳判断是否需要转码process_file(input_file, output_file, quality, preset, bitrate)- 执行 ffmpeg 转码find_video_files(directory)- 递归查找视频文件batch_process(input_dir, output_dir, workers)- 并行处理
支持格式：MP4、MOV、AVI、MKV、FLV、WMV
性能特点：
- 自动检测 CPU 和磁盘空间
- 默认 127 个并发进程（附带安全警告）
- tqdm 进度追踪
- 详细的转码日志和失败记录
命令行用法：
python convert_to_h264_aac_serial.py \
--input_dir /videos \
--output_dir /converted \
--quality 23 \
--preset slow \
--bitrate 2000k \
--workers 8功能：使用 HSV 直方图分析识别视频场景变化
核心类：FastSceneChangeDetector
关键参数：
threshold(默认: 30.0) - 场景变化阈值min_scene_length(默认: 10 帧) - 最小场景长度method('histogram' 或 'pixel') - 检测方法sample_frames(默认: 10) - 均匀采样帧数
检测方法：
- 直方图相关性 (推荐) - 在 HSV 色彩空间计算相邻帧的直方图相关性
- 像素差分 - 灰度图像逐像素比较
实现细节：
- 帧缩放至 320×180 加速处理
- 使用中心 ROI 计算直方图
- 自适应阈值 = 平均值 + 1.5 × 标准差
- 过滤最小距离内的连续场景变化
输出：场景边界列表 [(start_frame, end_frame), ...]
命令行用法：
python scene_change_detector.py \
--input_dir /converted_videos \
--output_dir /scenes \
--threshold 30.0 \
--min_scene_length 10 \
--workers 4功能：使用 Haar 级联分类器检测视频中的人脸并提取包含人脸的片段
核心类：FaceDetector
主要函数：
detect_face_segments_sampled()- 通过随机采样快速检测人脸片段process_single_video()- 处理单个视频的人脸检测和剪裁process_video_with_retry()- 支持重试的处理函数
关键参数：
samples_per_video(默认: 10) - 每个视频采样帧数min_face_duration(默认: 0.5 秒) - 最小人脸片段时长min_output_duration(默认: 1.0 秒) - 最小输出视频时长workers(默认: 4) - 并发工作进程数
特性：
- 线程安全的级联分类器初始化
- 段合并和时长管理
- FFmpeg 基于帧范围精确剪裁
- JSON 格式保存已处理视频记录
- 自适应采样速率 (根据视频长度调整)
命令行用法：
python face_detector.py \
--input_dir /scenes \
--output_dir /faces \
--samples_per_video 15 \
--min_face_duration 0.5 \
--workers 8功能：使用 EAST (Efficient and Accurate Scene Text) 深度学习模型检测视频帧中的文字
核心函数：
load_text_detection_model(model_path)- 加载 EAST 模型，自动选择 CUDA/CPUdetect_text_dnn(frame, net, confidence_threshold)- 图像文字检测decode_predictions(scores, geometry, confidence_threshold)- 解码模型输出
EAST 模型细节：
- 输入尺寸：320×320 像素
- 输出层：
feature_fusion/Conv_7/Sigmoid- 置信度 mapfeature_fusion/concat_3- 几何坐标 map
- 规范化：ImageNet 均值减法 (123.68, 116.78, 103.94)
关键参数：
confidence_threshold(默认: 0.5) - 置信度阈值nms_threshold(默认: 0.4) - 非最大值抑制阈值
特性：
- GPU 支持自动检测和回退到 CPU
- 可选帧缩放提升效率
- 边界框坐标旋转矫正
- 与人脸检测结果的加权融合分析
命令行用法：
python text_detector.py \
--input_dir /faces \
--output_dir /text_results \
--model_path /path/to/frozen_east_text_detection.pb \
--confidence_threshold 0.5 \
--workers 4功能：检测视频中的语音活动和口部运动，分析音视频同步性
核心类：MouthAudioSyncProcessor
主要函数：
extract_audio()- FFmpeg 提取音频为 WAV 格式detect_speech_activity()- librosa 语音活动检测detect_mouth_movement()- Haar 级联口部检测find_sync_segments()- 语音与口部运动匹配create_synced_video()- 生成同步的输出视频
检测原理：
-
语音检测 (librosa):
- 能量谱分析 (Mel-scale)
- 自适应能量阈值 = 平均能量 + 1.5 × 标准差
- 识别语音活跃帧
-
口部检测 (Haar 级联):
- 先检测人脸区域
- 在人脸内部检测口部特征
- 随机采样帧加速处理
-
同步分析:
- 匹配语音段和口部运动段
- 处理时间对齐偏差
- 支持无音频场景 (仅视觉检测)
关键参数：
min_segment_duration(默认: 0.5 秒) - 最小片段时长sample_rate(默认: 16000 Hz) - 音频采样率workers(默认: 127) - 最大并发进程数enable_audio(默认: true) - 是否启用音频检测
特性：
- 段合并和重叠处理
- FFmpeg 复杂滤镜生成输出
- 异常处理和自动回退 (如无音频)
- 详细的处理日志和统计
命令行用法：
python audio_sync_detector.py \
--input_dir /text_results \
--output_dir /audio_sync \
--min_segment_duration 0.5 \
--workers 8-pipeline/
├── pipeline.py # 主流水线编排器
├── convert_to_h264_aac_serial.py # 格式转换模块
├── scene_change_detector.py # 快速场景检测
├── face_detector.py # Haar 级联人脸检测
├── text_detector.py # EAST 文字检测
├── audio_sync_detector.py # 音视频同步检测
├── video_tokenize+prompt/ # 视频分词和提示工程目录
├── requirements.txt # Python 依赖
└── README.md # 项目文档
流水线处理完成后，输出目录结构如下：
output_dir/
├── temp_YYYYMMDD_HHMMSS/ # 时间戳临时目录
│ ├── stage1_converted/ # 阶段1：转码后的视频
│ ├── stage2_scenes/ # 阶段2：场景分割结果
│ ├── stage3_faces/ # 阶段3：人脸检测结果
│ ├── stage4_texts/ # 阶段4：文字检测结果
│ └── stage5_audio_sync/ # 阶段5：音视频同步结果
├── final_output/ # 最终输出目录
│ └── *.mp4 # 最终处理完成的视频
├── pipeline_state.json # 流水线状态跟踪文件
└── logs/
├── pipeline_YYYYMMDD_HHMMSS.log # 主流水线日志
├── convert_YYYYMMDD_HHMMSS.log # 格式转换日志
├── scene_detection_YYYYMMDD_HHMMSS.log # 场景检测日志
├── face_detection_YYYYMMDD_HHMMSS.log # 人脸检测日志
├── text_detection_YYYYMMDD_HHMMSS.log # 文字检测日志
└── audio_sync_YYYYMMDD_HHMMSS.log # 音视频同步日志
记录每个视频的处理状态，支持断点续传：
{
"video_file_1.mp4": {
"stage": 3,
"status": "processing",
"timestamp": "2024-01-15 10:30:45",
"error": null
},
"video_file_2.mp4": {
"stage": 5,
"status": "completed",
"timestamp": "2024-01-15 10:35:20",
"error": null
},
"video_file_3.mp4": {
"stage": 2,
"status": "failed",
"timestamp": "2024-01-15 10:25:30",
"error": "Scene detection failed: frame count = 0"
}
}字段说明：
stage(1-5): 当前处理的阶段编号status('processing', 'completed', 'failed')timestamp: 最后更新时间error: 错误信息（若无错误则为 null）
自定义日志处理器防止 tqdm 进度条与日志消息冲突：
[2024-01-15 10:30:45,123] - pipeline.py:45 - INFO - Processing video: video_1.mp4
[2024-01-15 10:30:46,456] - convert.py:102 - INFO - Conversion complete: 1920x1080 @ 30fps
Stage 1: 100%|██████████| 5/5 [00:30<00:00, 6.12s/it]
- DEBUG: 详细的处理步骤和变量值
- INFO: 处理进度、文件操作、阶段完成
- WARNING: 不兼容的参数、性能建议
- ERROR: 转码失败、文件丢失、权限问题
- CRITICAL: 流水线中断、系统资源耗尽
错误信息：ffmpeg: command not found
# Linux
sudo apt-get install ffmpeg
# macOS
brew install ffmpeg
# 验证安装
ffmpeg -version
ffprobe -version错误信息：CUDA out of memory 或 CUDA initialization failed
# 检查 CUDA 可用性
python -c "import cv2; print(cv2.cuda.getCudaEnabledDeviceCount())"
# 解决方案：回退到 CPU 处理
export CUDA_VISIBLE_DEVICES=""
python pipeline.py --input_dir /videos --output_dir /results错误信息：Permission denied 或 Read-only file system
# 检查目录权限
ls -ld /path/to/directory
# 修复权限
chmod -R 755 /path/to/input
chmod -R 755 /path/to/output
chmod -R 755 /path/to/temp错误信息：MemoryError 或 Killed (进程被系统杀死)
# 解决方案：减少并发进程
python pipeline.py --workers 2 --input_dir /videos --output_dir /results
# 或分批处理
python pipeline.py --workers 4 --input_dir /batch1 --output_dir /results1
python pipeline.py --workers 4 --input_dir /batch2 --output_dir /results2场景：流水线在中途中断，需要恢复
# 从中断点自动恢复
python pipeline.py --input_dir /videos --output_dir /results --resume
# 或指定起始阶段
python pipeline.py --input_dir /videos --output_dir /results --start_stage 3# 启用调试日志级别
python pipeline.py \
--input_dir /videos \
--output_dir /results \
--log_level DEBUG
# 运行单个模块进行测试
python scene_change_detector.py --input_dir /test_videos --output_dir /test_output --threshold 30
# 检查日志文件
tail -f logs/pipeline_*.log| 参数 | 推荐值范围 | 说明 |
|---|---|---|
workers |
CPU 核心数 × 0.5-0.75 | 过高会导致上下文切换开销 |
scene_threshold |
20-40 | 降低阈值提高敏感度，增加片段数 |
text_confidence |
0.4-0.6 | 降低置信度会增加误检 |
sample_frames |
5-20 | 更多采样帧提高准确性但耗时更长 |
- CPU: 6+ 核心 (推荐 8+ 核)
- 内存: 16GB+ (32GB 最佳)
- 存储: SSD (临时目录), HDD (输出目录可接受)
- GPU: NVIDIA GPU (CUDA compute capability 3.0+) 加速文字检测
在 8 核 CPU、32GB RAM、SSD 存储的系统上：
| 视频时长 | 格式转换 | 场景检测 | 人脸检测 | 文字检测 | 音视频同步 | 总耗时 |
|---|---|---|---|---|---|---|
| 5 分钟 | 30s | 5s | 10s | 15s | 20s | ~80s |
| 30 分钟 | 3m | 8s | 30s | 45s | 60s | ~5m |
| 2 小时 | 20m | 15s | 2m | 3m | 4m | ~30m |
实际时间取决于：视频分辨率、帧率、编码复杂度、系统负载
opencv-python>=4.5.0
numpy>=1.19.0
scipy>=1.5.0
librosa>=0.9.0
torch>=1.9.0
torchvision>=0.10.0
tqdm>=4.50.0
- FFmpeg (音视频处理)
- FFprobe (元数据提取)
- GCC/Clang (某些包编译)
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支
git checkout -b feature/your-feature-name
- 在分支上进行开发和测试
- 提交更改
git commit -m "Add detailed description of your changes" - 推送到远程分支
git push origin feature/your-feature-name
- 创建 Pull Request 并描述你的改进
- 使用 PEP 8 代码风格
- 添加单元测试
- 更新相关文档
- 提供清晰的提交信息
本项目采用 MIT 许可证 - 详见 LICENSE 文件
- GitHub: @bohyy
- 项目链接: https://github.com/bohyy/-pipeline
感谢以下项目和库的支持：
- FFmpeg - 音视频处理
- OpenCV - 计算机视觉
- PyTorch - 深度学习框架
- librosa - 音频分析
如果这个项目对你有帮助，请给我们一个 ⭐ Star！