docs: Add 24 files

squashthumbnailmaker/README.txt

@@ -0,0 +1,75 @@
+Squash Thumbnail Maker
+======================
+
+A Docker-based utility for generating high-quality thumbnails from MP4 videos using intelligent frame detection.
+
+Features:
+---------
+- Smart thumbnail generation using YOLOv8 pose detection to find frames with both players visible
+- Fallback to simple thumbnail extraction if smart detection fails
+- Process single videos or entire directories
+- Configurable thumbnail quality and size
+- Low priority execution to avoid system impact
+
+Usage:
+------
+After installation, use the Docker container to process videos:
+
+# Process a single video file
+docker run --rm -v /path/to/videos:/data squashthumbnailmaker_image:latest /data/video.mp4
+
+# Process all videos in a directory
+docker run --rm -v /path/to/videos:/data squashthumbnailmaker_image:latest /data
+
+# With custom settings
+docker run --rm \
+  -e ENABLE_SMART_DETECTION=false \
+  -e THUMBNAIL_WIDTH=1280 \
+  -e THUMBNAIL_QUALITY=90 \
+  -v /path/to/videos:/data \
+  squashthumbnailmaker_image:latest /data
+
+Configuration Options:
+----------------------
+The following environment variables can be set in config/service.env or passed with -e flag:
+
+- ENABLE_SMART_DETECTION: Use YOLO for intelligent thumbnail generation (default: true)
+- FALLBACK_TIME: Seconds into video for fallback thumbnail (default: 10)
+- THUMBNAIL_WIDTH: Width of generated thumbnails in pixels (default: 640)
+- THUMBNAIL_QUALITY: JPEG quality 1-100 (default: 95)
+- MAX_SAMPLE_TIME: Maximum seconds to sample in video (default: 180)
+- SAMPLE_INTERVAL: Interval between samples in seconds (default: 1)
+- NICE_LEVEL: Process priority 0-19, 19 is lowest (default: 19)
+
+How It Works:
+-------------
+1. Smart Detection Mode (if enabled):
+   - Samples frames throughout the video
+   - Uses YOLOv8 pose model to detect players
+   - Scores frames based on:
+     * Number of players visible (ideally 2)
+     * Face visibility (crucial for good thumbnails)
+     * Player size and positioning
+     * Players being centered in frame
+   - Fine-tunes around the best frame for optimal result
+
+2. Simple Mode (fallback):
+   - Extracts frame at specified time (default 10 seconds)
+   - Falls back to 1 second if initial extraction fails
+
+Output:
+-------
+Thumbnails are saved as .jpg files in the same directory as the source video with the same base filename.
+Example: video.mp4 → video.jpg
+
+Requirements:
+-------------
+- Docker
+- Videos should be in MP4, MOV, AVI, or MKV format
+- Sufficient disk space for Docker image (~2GB with YOLO model)
+
+Notes:
+------
+- The first run will download the YOLOv8 model (~6MB) if smart detection is enabled
+- Processing time depends on video length and smart detection settings
+- Thumbnails are only generated if they don't already exist (skip existing)