Skills
skills/yousufjoyian/claude-skills/motion-sampler

motion-sampler

SKILL.md

Motion Sampler Skill

Version: 1.0 Type: Video Frame Extraction Purpose: Extract representative frame samples from dashcam videos to understand motion and trajectory without storing full videos

Overview

The Motion Sampler extracts frames at regular intervals from dashcam videos to create a compact visual summary of vehicle movement and location changes. This achieves 90-95% storage reduction compared to keeping original videos while preserving spatial and temporal context.

Use Cases

  1. Motion trajectory analysis - Understand vehicle path through a sequence of locations
  2. Storage optimization - Reduce dashcam archive size by 90%+ while retaining visual record
  3. Quick visual review - Browse through hours of footage via representative frames
  4. Location identification - Identify where vehicle was at specific times
  5. Event timeline - Create visual timeline of trips without watching full videos

Natural Language Interface

Use natural language to request frame extraction:

Example Requests:

Extract frames every 10 seconds from all Movie_F videos in the CARDV folder.

Sample frames from Movie_R dashcam videos, one frame every 15 seconds.

Create motion samples for all parking camera videos with 5-second intervals.

Extract representative frames from Movie_F and Movie_R for July 27-29, 2025.

Parameters

Required

  • camera (string): Camera type to process

    • Options: Movie_F, Movie_R, Park_F, Park_R, or all
    • Default: Movie_F

  • source_dir (path): Root directory containing camera folders

    • Example: C:\Users\yousu\Desktop\CARDV

Optional

  • sample_interval (float): Seconds between extracted frames

    • Range: 1.0 - 60.0
    • Default: 10.0
    • Examples: 5.0 (dense sampling), 15.0 (sparse sampling)

  • output_dir (path): Where to save extracted frames

    • Default: {source_dir}/MOTION_SAMPLES

  • jpeg_quality (int): JPEG compression quality

    • Range: 50 - 100
    • Default: 92 (visually lossless)
    • Lower = smaller files, slightly reduced quality

  • max_workers (int): Parallel processing threads

    • Range: 1 - 8
    • Default: 4
    • Higher = faster but more CPU usage

  • date_filter (string): Only process videos from specific date(s)

    • Format: YYYYMMDD or YYYYMMDD-YYYYMMDD (range)
    • Example: 20250727 or 20250727-20250729

  • min_duration (float): Skip videos shorter than this (seconds)

    • Default: 3.0

Advanced (Future GPU Enhancement)

  • use_nvdec (bool): Use NVIDIA hardware decoding

    • Default: false (CPU-only in v1.0)
    • Future: true for 3-5x speedup

  • gpu_id (int): CUDA device ID if multiple GPUs

    • Default: 0

Output Format

Directory Structure

{output_dir}/
├── INDEX.csv                                      # Comprehensive metadata
├── 20250727150654_052278A_F001_001000ms.jpg      # Frame 1 at 1s
├── 20250727150654_052278A_F002_011000ms.jpg      # Frame 2 at 11s
├── 20250727150654_052278A_F003_021000ms.jpg      # Frame 3 at 21s
└── ...

Filename Format

{YYYYMMDDHHMMSS}_{FILEIDA/B}_{POSITION}_{TIMESTAMP_MS}ms.jpg

Example: 20250727150654_052278A_F003_021000ms.jpg
         └─────┬─────┘ └──┬──┘  └┬┘   └───┬───┘
           Date/Time   FileID  Pos  Timestamp

Components:
- YYYYMMDDHHMMSS: Video start time
- FILEIDA/B: Camera file ID + suffix (A=front, B=rear)
- F###: Frame position (F001, F002, F003...)
- ######ms: Milliseconds into video

INDEX.csv Schema

original_video,frame_file,camera,date,position,timestamp_ms,timestamp_s,frame_number,file_size_kb
20250727150654_052278A.MP4,20250727150654_052278A_F001_001000ms.jpg,Movie_F,20250727,F001,1000,1.0,24,1713.06

Columns:

  • original_video: Source MP4 filename
  • frame_file: Extracted JPEG filename
  • camera: Camera type (Movie_F/Movie_R/Park_F/Park_R)
  • date: YYYYMMDD
  • position: Frame position (F001, F002...)
  • timestamp_ms: Milliseconds into video
  • timestamp_s: Seconds into video
  • frame_number: Frame number in video (at 24fps)
  • file_size_kb: JPEG file size in KB

Performance Metrics

Current (CPU-only v1.0)

  • Throughput: 6-8 videos/second (4 workers, Intel i7/i9)
  • Speedup: 4x with multi-threading
  • Memory: ~500 MB
  • GPU Usage: 0% (CPU-only)

Projected (GPU-accelerated v2.0)

  • Throughput: 20-30 videos/second (NVDEC + multi-threading)
  • Speedup: 10-15x vs single-threaded CPU
  • Memory: ~1-2 GB
  • GPU Usage: 30-50% (NVDEC decoder only)

Storage Examples

Input: 418 Movie_F/R videos, 60s avg, ~45 GB total

Interval Frames/Video Total Frames Storage Reduction
5s 12 5,016 9 GB 80%
10s 7 2,926 5 GB 89%
15s 5 2,090 3.7 GB 92%
30s 3 1,254 2.2 GB 95%

Assumes 1.7 MB per frame average at 4K resolution

Algorithm Details

Frame Sampling Strategy

For each video:

  1. Skip buffer zones: Start at 1.0s, end at duration-1.0s (avoids black frames)
  2. Calculate sample timestamps: Every N seconds starting from 1.0s
  3. Always include end frame: Last frame at duration-1.0s
  4. Example for 60s video, 10s interval:
    • F001: 1s, F002: 11s, F003: 21s, F004: 31s, F005: 41s, F006: 51s, F007: 59s

Pseudo-code

timestamps = []
current_time = 1.0  # start offset
while current_time < (duration - 1.0):
    timestamps.append(current_time)
    current_time += sample_interval
timestamps.append(duration - 1.0)  # always include end

Error Handling

Automatic Handling

  • Short videos (<3s): Skipped with warning
  • Corrupted files: Logged as error, processing continues
  • Unreadable frames: Frame skipped, next frame attempted
  • Disk full: Graceful termination with partial results saved

Error Messages

SKIP: video.MP4 too short (2.1s)
ERROR: Cannot open corrupted_video.MP4
WARNING: Failed to read frame 120 from video.MP4

Example Usage

Request 1: Standard Extraction

Use the motion-sampler skill to extract frames every 10 seconds from all Movie_F videos
in C:\Users\yousu\Desktop\CARDV. Save to MOTION_SAMPLES folder.

Execution:

  • Camera: Movie_F
  • Source: C:\Users\yousu\Desktop\CARDV\Movie_F\
  • Output: C:\Users\yousu\Desktop\CARDV\MOTION_SAMPLES\
  • Interval: 10.0s
  • Quality: 92

Request 2: Dense Sampling for Specific Date

Extract frames every 5 seconds from Movie_R videos on July 27, 2025.

Execution:

  • Camera: Movie_R
  • Date filter: 20250727
  • Interval: 5.0s
  • Only processes videos matching 20250727*.MP4

Request 3: Sparse Sampling for Long-term Archive

Create motion samples with 30-second intervals for all parking cameras (Park_F and Park_R)
to minimize storage while keeping a visual record.

Execution:

  • Camera: Park_F, Park_R (both)
  • Interval: 30.0s
  • Expected: ~3 frames per 60s video
  • Storage: Minimal (~1-2 GB for thousands of videos)

Troubleshooting

Issue: Processing Very Slow

Solution: Increase max_workers to 6-8 (if you have 8+ CPU cores)

Issue: Large Output Size

Solution: Reduce jpeg_quality to 85 or increase sample_interval to 15-20s

Issue: Missing Some Videos

Cause: Videos shorter than min_duration (default 3s) are skipped Solution: Lower min_duration to 1.0s if you need very short clips

Issue: Out of Memory

Cause: Too many parallel workers on low-RAM system Solution: Reduce max_workers to 2

Future Enhancements (v2.0 Roadmap)

GPU Acceleration

  • NVDEC hardware video decoding (5-10x speedup)
  • GPU-accelerated JPEG encoding
  • Multi-GPU support for massive archives
  • Automatic GPU/CPU fallback

Advanced Features

  • Smart sampling (detect motion, skip static scenes)
  • Face/person detection integration
  • GPS overlay preservation
  • Thumbnail strip generation
  • Web viewer for browsing samples

Optimization

  • Incremental processing (skip already-processed videos)
  • Resume from interruption
  • S3/cloud storage output
  • Real-time progress dashboard

Technical Dependencies

Required

  • Python 3.8+
  • opencv-python (cv2) >= 4.8
  • numpy >= 1.24
  • pandas >= 2.0 (for INDEX.csv)

Optional (for future GPU support)

  • cuda >= 11.0
  • opencv-contrib-python (CUDA build)

File Locations

G:\My Drive\PROJECTS\skills\motion-sampler\
├── skill.md                          # This file
├── README.md                         # Quick start guide
├── SKILL_MANIFEST.md                # File inventory & testing
├── scripts/
│   ├── extract_motion_samples.py    # Main extraction script
│   └── analyze_results.py           # Post-processing analysis
├── assets/
│   ├── config_template.json         # Default configuration
│   └── camera_mapping.json          # Camera ID mapping
└── references/
    ├── SAMPLING_ALGORITHM.md        # Detailed algorithm docs
    └── PERFORMANCE_BENCHMARKS.md    # Speed/storage benchmarks

JSON API Contract

For programmatic invocation:

{
  "camera": "Movie_F",
  "source_dir": "C:\\Users\\yousu\\Desktop\\CARDV",
  "output_dir": "C:\\Users\\yousu\\Desktop\\CARDV\\MOTION_SAMPLES",
  "sample_interval": 10.0,
  "jpeg_quality": 92,
  "max_workers": 4,
  "date_filter": null,
  "min_duration": 3.0,
  "use_nvdec": false
}

Response:

{
  "status": "success",
  "videos_processed": 2146,
  "frames_extracted": 15022,
  "total_size_mb": 26750.5,
  "avg_frames_per_video": 7.0,
  "processing_time_s": 305.2,
  "throughput_videos_per_sec": 7.03,
  "output_dir": "C:\\Users\\yousu\\Desktop\\CARDV\\MOTION_SAMPLES",
  "index_file": "C:\\Users\\yousu\\Desktop\\CARDV\\MOTION_SAMPLES\\INDEX.csv"
}

License & Attribution

Part of the dashcam analysis suite. Designed for personal dashcam archive management and motion trajectory analysis.

Weekly Installs
5
Repository
yousufjoyian/cl…e-skills
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
mcpjam5
codex5
gemini-cli5
antigravity5
windsurf5
zencoder5