Back to Details

dashcam-frame-extraction

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dashcam Frame Extraction Skill

行车记录仪视频帧提取工具

Purpose

工具用途

This skill provides automated GPU-accelerated frame extraction for Movie_F dashcam videos. It extracts 3 frames per video (BEGIN at 1s, MIDDLE at 50%, END at duration-1s) using NVIDIA CUDA hardware acceleration, processes videos in parallel batches, and handles HEVC-encoded videos with the critical fixes required for successful extraction.
本工具可为Movie_F类行车记录仪视频提供自动化GPU加速帧提取功能。它采用NVIDIA CUDA硬件加速技术，每个视频提取3帧（开始帧：第1秒、中间帧：50%时长位置、结束帧：时长-1秒位置），支持批量并行处理视频，并针对HEVC编码视频应用了确保提取成功的关键修复。

When to Use This Skill

适用场景

Use this skill when:
  • User requests frame extraction from Movie_F dashcam videos
  • User places new videos in 
    /mnt/windows/Users/yousu/Desktop/CARDV/Movie_F/
  • User asks to "extract frames from Movie_F videos" or similar requests
  • User needs to process dashcam footage for analysis or sampling
Important: This skill is specifically for Movie_F category only. Do not use for Park_F, Park_R, or other categories.
在以下场景中使用本工具：
  • 用户请求提取Movie_F类行车记录仪视频的帧
  • 用户将新视频放入
    /mnt/windows/Users/yousu/Desktop/CARDV/Movie_F/
    路径
  • 用户提出“提取Movie_F类视频的帧”或类似请求
  • 用户需要处理行车记录仪视频以进行分析或采样
注意：本工具仅适用于Movie_F类视频。请勿用于Park_F、Park_R或其他类别视频。

Quick Start

快速开始

To extract frames from Movie_F videos:
bash
cd /home/yousuf/GoogleDrive/PROJECTS/skills/Dashcam/scripts
bash run_extraction.sh
The script will:
  1. Verify system requirements (GPU, disk space, FFmpeg)
  2. Identify new videos needing extraction via gap analysis
  3. Create batches of 50 videos each
  4. Launch 4 parallel GPU workers
  5. Monitor progress with updates every 30 seconds
  6. Extract 3 frames per video to Google Drive
要提取Movie_F类视频的帧：
bash
cd /home/yousuf/GoogleDrive/PROJECTS/skills/Dashcam/scripts
bash run_extraction.sh
该脚本将执行以下操作：
  1. 验证系统要求（GPU、磁盘空间、FFmpeg）
  2. 通过间隙分析识别需要提取帧的新视频
  3. 将视频按每批50个分组
  4. 启动4个并行GPU工作进程
  5. 每30秒更新一次进度
  6. 将每个视频的3帧提取至Google Drive

How to Use This Skill

使用步骤

Step 1: Read Agent Instructions (First Time)

步骤1：阅读Agent指令（首次使用）

For the first use or to understand the complete workflow, read the agent instructions:
bash
cat references/AGENT_INSTRUCTIONS.md
This provides comprehensive guidance on:
  • Your role as the extraction agent
  • Expected workflow and user interaction
  • Troubleshooting common issues
  • Performance expectations
  • Error handling
首次使用或需了解完整工作流时，请阅读Agent指令：
bash
cat references/AGENT_INSTRUCTIONS.md
该文档提供以下全面指导：
  • 作为提取Agent的角色
  • 预期工作流与用户交互方式
  • 常见问题排查
  • 性能预期
  • 错误处理方法

Step 2: Run the Main Extraction Script

步骤2：运行主提取脚本

Execute the main orchestration script:
bash
cd scripts
bash run_extraction.sh
This script handles the entire pipeline automatically:
  • Pre-flight checks (GPU, FFmpeg, Python, disk space)
  • Gap analysis (compares source videos vs existing frames)
  • Batch creation (splits videos into batches of 50)
  • Coordinator launch (manages parallel workers)
  • Progress monitoring (displays updates every 30 seconds)
执行主编排脚本：
bash
cd scripts
bash run_extraction.sh
该脚本将自动处理整个流程：
  • 预检查（GPU、FFmpeg、Python、磁盘空间）
  • 间隙分析（对比源视频与已提取帧）
  • 创建视频批次
  • 启动协调器管理并行工作进程
  • 每30秒显示进度更新

Step 3: Monitor Progress

步骤3：监控进度

Progress updates appear automatically every 30 seconds showing:
  • Videos processed / Total
  • Batches completed
  • Active workers
  • Processing speed (videos/min)
  • GPU utilization
  • Estimated time remaining
Example output:
════════════════════════════════════════════════════════════════
📊 EXTRACTION PROGRESS - 02:15:30 PM
Videos: 45/150 (30%) | Batches: 1/3 | Workers: 4
Speed: 18.5 vids/min | 55.5 fps | ETA: 0.2h | GPU: 85%
════════════════════════════════════════════════════════════════
系统会每30秒自动显示进度更新，内容包括：
  • 已处理视频数 / 总视频数
  • 已完成批次数
  • 活跃工作进程数
  • 处理速度（视频/分钟）
  • GPU利用率
  • 预计剩余时间
示例输出：
════════════════════════════════════════════════════════════════
📊 提取进度 - 02:15:30 PM
视频：45/150 (30%) | 批次：1/3 | 工作进程：4
速度：18.5 vids/min | 55.5 fps | 预计剩余时间：0.2h | GPU：85%
════════════════════════════════════════════════════════════════

Step 4: Verify Results

步骤4：验证结果

After completion, check extraction results:
bash
bash scripts/show_results.sh
This displays:
  • Baseline frame count
  • Current frame count
  • New frames extracted
  • Videos processed
  • Success rate
提取完成后，检查提取结果：
bash
bash scripts/show_results.sh
该脚本将显示：
  • 基准帧数量
  • 当前帧数量
  • 新提取的帧数量
  • 已处理视频数
  • 成功率

Step 5: Verify Skill Health (Optional)

步骤5：验证工具状态（可选）

To verify the skill is properly configured and ready to use:
bash
bash scripts/verify_skill.sh
This checks:
  • All required files present
  • Scripts are executable
  • System requirements (GPU, FFmpeg, Python, disk space)
  • Source and output directories accessible
要验证工具是否配置正确且可正常使用：
bash
bash scripts/verify_skill.sh
该脚本将检查：
  • 所有必需文件是否存在
  • 脚本是否可执行
  • 系统要求（GPU、FFmpeg、Python、磁盘空间）
  • 源目录与输出目录是否可访问

Core Scripts

核心脚本

The skill includes these executable scripts in 
scripts/
:
本工具在
scripts/
目录下包含以下可执行脚本：

Main Scripts

主脚本

  1. run_extraction.sh - Main orchestration script
    • Entry point for frame extraction
    • Handles pre-flight checks
    • Performs gap analysis
    • Creates batches
    • Launches coordinator and monitor
  2. extract_frames_worker.py - GPU worker process
    • Processes individual video batches
    • Uses CUDA for GPU-accelerated decoding
    • Extracts 3 frames per video
    • Critical HEVC fix applied (no CUDA output format)
    • Handles timeouts (30 seconds per frame)
  3. coordinator.sh - Parallel batch coordinator
    • Manages 4 parallel workers
    • Monitors disk space (25GB minimum)
    • Handles worker lifecycle
    • Strict error handling (exits on any failure)
  4. monitor.sh - Progress monitoring
    • Displays progress updates every 30 seconds
    • Calculates processing speed and ETA
    • Shows GPU utilization
    • Non-intrusive (doesn't clear screen)
  1. run_extraction.sh - 主编排脚本
    • 帧提取的入口
    • 处理预检查
    • 执行间隙分析
    • 创建视频批次
    • 启动协调器和监控进程
  2. extract_frames_worker.py - GPU工作进程
    • 处理单个视频批次
    • 使用CUDA进行GPU加速解码
    • 每个视频提取3帧
    • 应用关键HEVC修复（不使用CUDA输出格式）
    • 处理超时（每帧30秒超时限制）
  3. coordinator.sh - 并行批次协调器
    • 管理4个并行工作进程
    • 监控磁盘空间（最低25GB可用）
    • 处理工作进程生命周期
    • 严格的错误处理（任何失败即退出）
  4. monitor.sh - 进度监控脚本
    • 每30秒显示进度更新
    • 计算处理速度和预计剩余时间
    • 显示GPU利用率
    • 非侵入式（不清除屏幕）

Utility Scripts

实用脚本

  1. show_results.sh - Display extraction results
    • Shows baseline vs current frame counts
    • Calculates videos processed
    • Displays success rate
  2. verify_skill.sh - Skill verification
    • Checks all documentation files present
    • Verifies scripts are executable
    • Tests system requirements
    • Validates configured paths
  3. auto_extract_movie_f.sh - Legacy script
    • Original all-in-one script (kept for reference)
    • Use 
      run_extraction.sh
      instead
  1. show_results.sh - 显示提取结果
    • 显示基准帧数量与当前帧数量对比
    • 计算已处理视频数
    • 显示成功率
  2. verify_skill.sh - 工具验证脚本
    • 检查所有文档文件是否存在
    • 验证脚本是否可执行
    • 测试系统要求
    • 验证配置路径
  3. auto_extract_movie_f.sh - 遗留脚本
    • 原始一体化脚本（仅作参考保留）
    • 请使用
      run_extraction.sh
      替代

Reference Documentation

参考文档

The skill includes comprehensive documentation in 
references/
:
本工具在
references/
目录下包含全面的文档：

For Agents

面向Agent的文档

  • AGENT_INSTRUCTIONS.md - Complete agent guide with responsibilities, troubleshooting, and workflow
  • START_HERE.md - Quick start entry point for agents
  • AGENT_INSTRUCTIONS.md - 完整的Agent指南，包含职责、故障排查和工作流
  • START_HERE.md - Agent快速入门入口

Technical Documentation

技术文档

  • DOCUMENTATION.md - Complete technical details, architecture, and fixes
  • CRITICAL_FIXES_CHECKLIST.md - Pre-flight verification and troubleshooting guide
  • QUICK_REFERENCE.md - One-page command reference
  • DOCUMENTATION.md - 完整的技术细节、架构和修复说明
  • CRITICAL_FIXES_CHECKLIST.md - 预检查和故障排查指南
  • QUICK_REFERENCE.md - 单页命令参考

Overview

概述文档

  • SKILL_README.md - Skill overview and features
  • README.md - Project background and history
  • INDEX.md - File navigation and directory structure
  • SKILL_README.md - 工具概述和功能介绍
  • README.md - 项目背景和历史
  • INDEX.md - 文件导航和目录结构

Configuration

配置文档

  • config.json - All settings, paths, and parameters
  • requirements.txt - System dependencies and requirements
  • config.json - 所有设置、路径和参数
  • requirements.txt - 系统依赖和要求

Critical Knowledge

关键知识

1. HEVC CUDA Compatibility Fix

1. HEVC CUDA兼容性修复

Problem: Videos are HEVC (H.265) encoded. Using 
-hwaccel_output_format cuda
breaks JPEG conversion.
Solution: The worker script uses 
-hwaccel cuda
for decoding ONLY, not output format.
Location: 
scripts/extract_frames_worker.py
lines 46-48
Impact: Without this fix, 0% of videos will succeed.
问题：视频为HEVC（H.265）编码。使用
-hwaccel_output_format cuda
会导致JPEG转换失败。
解决方案：工作进程脚本仅在解码时使用
-hwaccel cuda
，不使用CUDA输出格式。
位置：
scripts/extract_frames_worker.py
第46-48行
影响：若无此修复，视频提取成功率为0%。

2. Strict Error Handling

2. 严格错误处理

Configuration: Pipeline exits immediately on ANY failure.
Coordinator: Uses 
set -euo pipefail
(strict mode)
Worker: Returns exit code 1 if any videos fail
Why: All videos must succeed. If any fail, investigate before continuing.
配置：流程在任何失败发生时立即退出。
协调器：使用
set -euo pipefail
（严格模式）
工作进程：若任何视频处理失败，返回退出码1
原因：所有视频必须处理成功。若有失败，需先排查问题再继续。

3. Filename Pattern Variations

3. 文件名格式差异

Videos have inconsistent naming:
  • 20250916042109_062060A.MP4
  • 20250916042109_062060_A.MP4
  • 20250916042109_062060.MP4
Solution: Gap analysis checks all variations automatically.
视频文件名格式不一致：
  • 20250916042109_062060A.MP4
  • 20250916042109_062060_A.MP4
  • 20250916042109_062060.MP4
解决方案：间隙分析会自动检查所有格式变体。

4. Timeout Management

4. 超时管理

Each frame extraction has a 30-second timeout. Videos that timeout are marked as failed and stop the pipeline.
Configuration: 
extract_frames_worker.py
line 62
每帧提取有30秒超时限制。超时的视频会被标记为失败并终止流程。
配置：
extract_frames_worker.py
第62行

Configuration Settings

配置设置

All settings are in 
references/config.json
:
json
{
  "num_workers": 4,          // Parallel GPU workers
  "batch_size": 50,          // Videos per batch
  "min_free_gb": 25,         // Minimum disk space required
  "timeout_seconds": 30      // Timeout per frame extraction
}
Paths:
  • Source: 
    /mnt/windows/Users/yousu/Desktop/CARDV/Movie_F
  • Output: 
    /home/yousuf/GoogleDrive/PROJECTS/INVESTIGATION/DASHCAM/FRAMES_CLIPS/Movie_F&R_MotionSamples
  • Work Dir: 
    /home/yousuf/PROJECTS/PeopleNet/FrameExtraction
  • Staging: 
    /home/yousuf/PROJECTS/PeopleNet/Staging
所有设置均在
references/config.json
中：
json
{
  "num_workers": 4,          // 并行GPU工作进程数
  "batch_size": 50,          // 每批视频数量
  "min_free_gb": 25,         // 最低可用磁盘空间要求
  "timeout_seconds": 30      // 每帧提取超时时间
}
路径：
  • 源目录：
    /mnt/windows/Users/yousu/Desktop/CARDV/Movie_F
  • 输出目录：
    /home/yousuf/GoogleDrive/PROJECTS/INVESTIGATION/DASHCAM/FRAMES_CLIPS/Movie_F&R_MotionSamples
  • 工作目录：
    /home/yousuf/PROJECTS/PeopleNet/FrameExtraction
  • 暂存目录：
    /home/yousuf/PROJECTS/PeopleNet/Staging

Performance Expectations

性能预期

  • Speed: 15-20 videos/minute
  • GPU Utilization: 60-90%
  • Success Rate: 100% (stops on any failure)
  • Frames per Video: 3 (BEGIN, MIDDLE, END)
  • Batch Size: 50 videos
  • Parallel Workers: 4
  • 速度：15-20个视频/分钟
  • GPU利用率：60-90%
  • 成功率：100%（任何失败即停止）
  • 每视频提取帧数：3（开始帧、中间帧、结束帧）
  • 批次大小：50个视频
  • 并行工作进程：4个

System Requirements

系统要求

  • NVIDIA GPU with CUDA support
  • FFmpeg compiled with CUDA hardware acceleration
  • Python 3.7+ (uses standard library only - no pip packages)
  • 25GB minimum free disk space
  • Linux OS (tested on Ubuntu)
Verify requirements:
bash
bash scripts/verify_skill.sh
  • 支持CUDA的NVIDIA GPU
  • 编译了CUDA硬件加速的FFmpeg
  • Python 3.7+（仅使用标准库 - 无需pip包）
  • 最低25GB可用磁盘空间
  • Linux操作系统（已在Ubuntu上测试）
验证系统要求：
bash
bash scripts/verify_skill.sh

Troubleshooting

故障排查

Issue: 0% success rate

问题：成功率为0%

Diagnosis: HEVC fix not applied Solution: Check 
scripts/extract_frames_worker.py
- should NOT have 
-hwaccel_output_format cuda
诊断：未应用HEVC修复 解决方案：检查
scripts/extract_frames_worker.py
- 不应包含
-hwaccel_output_format cuda
参数

Issue: Process exits immediately

问题：流程立即退出

Diagnosis: Failure in first batch Solution: Check logs in 
/home/yousuf/PROJECTS/PeopleNet/FrameExtraction/logs/
, identify failed video, investigate
诊断：第一批视频处理失败 解决方案：查看
/home/yousuf/PROJECTS/PeopleNet/FrameExtraction/logs/
目录下的日志，识别失败的视频并排查问题

Issue: Videos not found

问题：未找到视频

Diagnosis: Filename pattern mismatch or wrong directory Solution: Verify videos exist in 
/mnt/windows/Users/yousu/Desktop/CARDV/Movie_F/
诊断：文件名格式不匹配或目录错误 解决方案：验证视频是否存在于
/mnt/windows/Users/yousu/Desktop/CARDV/Movie_F/
路径中

Issue: Low disk space error

问题：磁盘空间不足错误

Diagnosis: Less than 25GB free space Solution: Free up disk space or increase staging cleanup
For complete troubleshooting, see 
references/CRITICAL_FIXES_CHECKLIST.md
诊断：可用磁盘空间不足25GB 解决方案：释放磁盘空间或增加暂存目录清理频率
如需完整故障排查指南，请查看
references/CRITICAL_FIXES_CHECKLIST.md

Workflow Summary

工作流概述

  1. User places videos in Desktop CARDV/Movie_F folder
  2. Agent invokes skill: Runs 
    scripts/run_extraction.sh
  3. System identifies new videos via gap analysis
  4. System creates batches of 50 videos each
  5. System launches 4 parallel GPU workers
  6. System monitors progress (updates every 30s)
  7. System extracts 3 frames per video
  8. Agent reports completion to user
  1. 用户放置视频到桌面CARDV/Movie_F文件夹
  2. Agent调用工具：运行
    scripts/run_extraction.sh
  3. 系统识别新视频通过间隙分析
  4. 系统创建视频批次每批50个视频
  5. 系统启动4个并行GPU工作进程
  6. 系统监控进度每30秒更新一次
  7. 系统提取每视频3帧
  8. Agent向用户报告完成情况

Frame Naming Convention

帧命名规则

Frames are named: 
{video_name}_{position}_{timestamp}ms.jpg
Example:
20250916042109_062060A_BEGIN_001000ms.jpg
20250916042109_062060A_MIDDLE_030450ms.jpg
20250916042109_062060A_END_059900ms.jpg
帧文件命名格式：
{video_name}_{position}_{timestamp}ms.jpg
示例：
20250916042109_062060A_BEGIN_001000ms.jpg
20250916042109_062060A_MIDDLE_030450ms.jpg
20250916042109_062060A_END_059900ms.jpg

Emergency Stop

紧急停止

If extraction needs to be stopped:
bash
undefined
如需停止提取流程：
bash
undefined

Kill all workers

终止所有工作进程

pkill -f extract_frames_worker
pkill -f extract_frames_worker

Kill coordinator

终止协调器

pkill -f coordinator
pkill -f coordinator

Kill monitor

终止监控进程

pkill -f monitor
pkill -f monitor

Clean up staging files

清理暂存文件

rm -rf /home/yousuf/PROJECTS/PeopleNet/Staging/*
undefined
rm -rf /home/yousuf/PROJECTS/PeopleNet/Staging/*
undefined

Version Information

版本信息

  • Version: 1.0
  • Category: Movie_F ONLY
  • Status: Production Ready
  • Last Updated: 2025-01-14
  • Tested On: Movie_F (1,426 videos, 85% success rate in initial run)
  • 版本：1.0
  • 适用类别：仅Movie_F
  • 状态：已就绪可投入生产
  • 最后更新：2025-01-14
  • 测试情况：Movie_F类视频（1426个视频，初始运行成功率85%）

Future Enhancements

未来增强计划

The skill is designed for expansion:
  • Auto-trigger via inotify when videos appear
  • Email notifications on completion
  • Multi-GPU support
  • Retry mechanism for failed videos
  • Frame verification (check for corruption)
Keep all scripts as additional features will be added in the near future.
本工具设计支持扩展：
  • 当视频出现时通过inotify自动触发提取
  • 完成时发送邮件通知
  • 多GPU支持
  • 失败视频重试机制
  • 帧验证（检查是否损坏）
请保留所有脚本，近期将添加更多功能。