#Simple Frame

A lightweight command-line tool for extracting unique frames from video files. Built for research workflows where you need to dissect video content into distinct, non-duplicate images with timestamps.

Simple Frame uses perceptual hashing to compare consecutive frames and only saves those that are visually distinct, drastically reducing the manual sorting required when working with extracted video stills.

Written in C following the suckless philosophy.

#Usage

sframe [-v] [-t threshold] [-f png|jpg] [-o outdir] video [video...]

#Options

#Examples

Extract unique frames from a video:

sframe lecture.mp4

Use a stricter threshold with JPEG output:

sframe -t 4 -f jpg documentary.mkv

Process multiple videos into a custom directory:

sframe -o /tmp/research clip1.mp4 clip2.webm

#Output Structure

~/frames/
└── lecture/
    ├── lecture-00-00-01.234.png
    ├── lecture-00-00-15.678.png
    ├── lecture-00-01-02.345.png
    └── ...

Each video gets its own subdirectory. Frames are named as <video-name>-HH-MM-SS.mmm.<ext> where the timestamp corresponds to the frame's position in the video.

#How It Works

1. Decodes every frame of the video using FFmpeg
2. Scales each frame to 8x8 grayscale
3. Computes a 64-bit average perceptual hash
4. Compares the hamming distance against the previously saved frame's hash
5. Saves the frame only if the distance exceeds the threshold

This approach is fast and effective at eliminating duplicate and near-duplicate frames (static shots, slow pans, talking heads with minimal movement) while preserving genuine scene changes and visually distinct content.

#Threshold Guide

#Dependencies

• FFmpeg libraries: libavformat, libavcodec, libavutil, libswscale
• libpng
• libjpeg

#Arch Linux

pacman -S ffmpeg libpng libjpeg-turbo

#Debian/Ubuntu

apt install libavformat-dev libavcodec-dev libavutil-dev libswscale-dev libpng-dev libjpeg-dev

#Building

make
sudo make install

Edit config.mk to change compile-time defaults (output format, default threshold).

#License

MIT