Skills
skills/yousufjoyian/claude-skills/dashcam-frame-extraction

dashcam-frame-extraction

SKILL.md

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.

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.

Quick Start

To extract frames from Movie_F videos:

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

How to Use This Skill

Step 1: Read Agent Instructions (First Time)

For the first use or to understand the complete workflow, read the agent instructions:

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

Step 2: Run the Main Extraction Script

Execute the main orchestration script:

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)

Step 3: Monitor Progress

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%
════════════════════════════════════════════════════════════════

Step 4: Verify Results

After completion, check extraction results:

bash scripts/show_results.sh

This displays:

  • Baseline frame count
  • Current frame count
  • New frames extracted
  • Videos processed
  • Success rate

Step 5: Verify Skill Health (Optional)

To verify the skill is properly configured and ready to use:

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

Core Scripts

The skill includes these executable scripts in 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)

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

Reference Documentation

The skill includes comprehensive documentation in references/:

For Agents

  • AGENT_INSTRUCTIONS.md - Complete agent guide with responsibilities, troubleshooting, and workflow
  • START_HERE.md - Quick start entry point for agents

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

Overview

  • SKILL_README.md - Skill overview and features
  • README.md - Project background and history
  • INDEX.md - File navigation and directory structure

Configuration

  • config.json - All settings, paths, and parameters
  • requirements.txt - System dependencies and requirements

Critical Knowledge

1. HEVC CUDA Compatibility Fix

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.

2. Strict Error Handling

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.

3. Filename Pattern Variations

Videos have inconsistent naming:

  • 20250916042109_062060A.MP4
  • 20250916042109_062060_A.MP4
  • 20250916042109_062060.MP4

Solution: Gap analysis checks all variations automatically.

4. Timeout Management

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

Configuration Settings

All settings are in references/config.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

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

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 scripts/verify_skill.sh

Troubleshooting

Issue: 0% success rate

Diagnosis: HEVC fix not applied Solution: Check scripts/extract_frames_worker.py - should NOT have -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

Issue: Videos not found

Diagnosis: Filename pattern mismatch or wrong directory Solution: Verify videos exist in /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

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

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

Emergency Stop

If extraction needs to be stopped:

# Kill all workers
pkill -f extract_frames_worker

# Kill coordinator
pkill -f coordinator

# Kill monitor
pkill -f monitor

# Clean up staging files
rm -rf /home/yousuf/PROJECTS/PeopleNet/Staging/*

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)

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.

Weekly Installs
5
Repository
yousufjoyian/cl…e-skills
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubFail
SocketFail
SnykWarn
Installed on
mcpjam5
codex5
antigravity5
codebuddy5
windsurf5
zencoder5