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:

• Verify system requirements (GPU, disk space, FFmpeg)

• Identify new videos needing extraction via gap analysis

• Create batches of 50 videos each

• Launch 4 parallel GPU workers

• Monitor progress with updates every 30 seconds

• 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

run_extraction.sh - Main orchestration script

• Entry point for frame extraction

• Handles pre-flight checks

• Performs gap analysis

• Creates batches

• Launches coordinator and monitor

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)

coordinator.sh - Parallel batch coordinator

• Manages 4 parallel workers

• Monitors disk space (25GB minimum)

• Handles worker lifecycle

• Strict error handling (exits on any failure)

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

show_results.sh - Display extraction results

• Shows baseline vs current frame counts

• Calculates videos processed

• Displays success rate

verify_skill.sh - Skill verification

• Checks all documentation files present

• Verifies scripts are executable

• Tests system requirements

• Validates configured paths

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

• User places videos in Desktop CARDV/Movie_F folder

• Agent invokes skill: Runs scripts/run_extraction.sh

• System identifies new videos via gap analysis

• System creates batches of 50 videos each

• System launches 4 parallel GPU workers

• System monitors progress (updates every 30s)

• System extracts 3 frames per video

• 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.