ruby_spriter 0.6.6 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6e4b3befadf222f9fe4a13b50eb16a5a39124c45f5dad2769f7c4f9153aae4f
-  data.tar.gz: 9f13e8d5da4c706a3d834f5a8d125ee46a1d7f04e5a643c90bda451bdb7f6e9c
+  metadata.gz: 1cec402c211c4204134f1a9cf6974093c3e36fd46a45301282260454c91ff33d
+  data.tar.gz: 0de0714668911755bc80ac6f0841d4aa2034f03797dcf027ef6a61e495f46936
 SHA512:
-  metadata.gz: 8b05aec242fb65fb3f8745e276f7ec35ce2d05884f62e9b5af8fcef896a8f66ba2050c48d9c6e6c7400ad4ba93215225e5624c04bba25417e32dfff2e255b345
-  data.tar.gz: 97631e37ef5cbe5bb544526d1e696a870dc9cb26759d2838b1af4f77d81e03696f717225f3858ac55bd2a2ecdd3e86dbe6a4e8c91dc4ac8c75f52f7ff1df68e3
+  metadata.gz: 71bbe470ac06aaa1acadf00fba48b911daa6f803010a0e88145a46847078e2db3db25cdeb4462ada7a74e9711b7b36c4b706a36bbd9f04ff53af2087a1882434
+  data.tar.gz: f5f092588802ce4402fe952370f17ba76f59543cdd99b24e83f845e1ca2b2a5cc813481909180ac418d2f34f65dcb4ae5a828794e40abd3164a004ef6695235d

data/CHANGELOG.md

@@ -12,6 +12,144 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.6.7] - 2025-10-24
+
+### 🚀 Batch Processing, Compression, Directory Consolidation & Frame Extraction Release
+
+#### Added
+- **Batch Processing Mode** (`--batch`): Process multiple MP4 files in a directory (Issue #16)
+  - `--dir DIRECTORY`: Specify directory containing MP4 files to process
+  - `--outputdir DIRECTORY`: Optional output directory (defaults to input directory)
+  - `--batch-consolidate`: Automatically consolidate all resulting spritesheets
+  - Supports all existing processing options: `--scale`, `--remove-bg`, `--sharpen`, `--interpolation`, etc.
+  - Enforces unique filenames unless `--overwrite` is specified
+  - Continues processing remaining videos if one fails
+  - Provides detailed summary of successes and failures
+- **Maximum Compression** (`--max-compress`): Apply maximum PNG compression (Issue #14)
+  - Uses ImageMagick with optimal compression settings (level 9, filter 5, strategy 1, quality 95)
+  - Preserves embedded metadata through compression
+  - Works with all processing modes: `--video`, `--image`, `--batch`, `--consolidate`
+  - Displays compression statistics (original size, compressed size, savings, reduction percentage)
+- **Directory-Based Consolidation**: `--consolidate` now supports `--dir` option to automatically consolidate all spritesheets in a directory
+  - Scans directory for PNG files with embedded spritesheet metadata
+  - Automatically filters out non-spritesheet PNG files
+  - Sorts files alphabetically by filename before consolidation
+  - Requires at least 2 valid spritesheets in directory
+  - Works with all existing consolidation options: `--output`, `--outputdir`, `--overwrite`, `--max-compress`, `--no-validate-columns`
+  - Mutual exclusivity validation: Cannot use both comma-separated file list and `--dir` with `--consolidate`
+- **Enhanced Context-Sensitive Help System**: Mode-specific help displays only relevant options
+  - `ruby_spriter --video --help`: Shows video mode options (spritesheet generation, processing, output)
+  - `ruby_spriter --image --help`: Shows image mode options (processing, frame extraction, output)
+  - `ruby_spriter --consolidate --help`: Shows consolidation options (input methods, validation, output)
+  - `ruby_spriter --batch --help`: Shows batch processing options (directory processing, applied options)
+  - `ruby_spriter --split --help`: Shows frame extraction options (split format, metadata behavior, output)
+  - General `--help`: Shows mode-specific help hints and directs users to detailed help
+  - **Parent-Child Option Hierarchy**: Visual hierarchy (└─) shows modifier options grouped under parent options
+    - `--interpolation`, `--sharpen*` modifiers shown under `--scale`
+    - `--fuzzy`, `--threshold`, `--grow` modifiers shown under `--remove-bg`
+    - `--override-md` modifier shown under `--split`
+    - `--validate-columns` modifier shown under `--consolidate --dir`
+  - Organized by function (Image Processing, Output Options) instead of by tool (GIMP Processing Options)
+- **Frame Extraction** (`--extract`): Extract specific frames and create new spritesheet
+  - `--extract FRAMES`: Comma-separated frame numbers (e.g., `1,2,4,5,8`)
+  - `--columns NUM`: Specify output grid columns (default: 4)
+  - Supports duplicate frame numbers for animation sequences
+  - 1-indexed frame numbering (left-to-right, top-to-bottom)
+  - Requires spritesheet metadata (works with `--verify` output)
+  - Works with all `--image` processing options: `--scale`, `--remove-bg`, `--sharpen`, `--max-compress`
+  - Automatic output naming with `_extracted` suffix or custom via `--output`
+  - Temporary frames deleted after reassembly unless `--save-frames` specified
+  - Minimum 2 frames required
+  - Out-of-bounds validation against spritesheet metadata
+  - Mutual exclusivity with `--split`
+- **Metadata Management** (`--add-meta`): Add spritesheet metadata to images without metadata
+  - `--add-meta R:C`: Specify grid layout (rows:columns, e.g., `4:4`)
+  - `--overwrite-meta`: Replace existing metadata
+  - `--frames COUNT`: Custom frame count for partial grids (fewer frames than grid size)
+  - In-place modification by default (respects `--overwrite` flag)
+  - Optional `--output` for copying to new file
+  - Dimension validation: Image dimensions must divide evenly by grid
+  - Enables `--extract`, `--consolidate`, `--verify`, `--split` on external spritesheets
+  - Standalone mode: Cannot combine with `--scale`, `--remove-bg`, `--sharpen`
+- **Enhanced `--save-frames`**: Now works with both `--video` and `--extract`
+- **New Modules**:
+  - `BatchProcessor` (lib/ruby_spriter/batch_processor.rb): Orchestrates batch video processing
+  - `CompressionManager` (lib/ruby_spriter/compression_manager.rb): Handles PNG compression with metadata preservation
+- **New Public Method**: `Consolidator#find_spritesheets_in_directory(directory)` for directory scanning
+- **Comprehensive Test Coverage**: 68 new tests (13 for BatchProcessor, 11 for CompressionManager, 15 for directory consolidation, 7 for context-sensitive help, 22 for frame extraction and metadata management)
+
+#### Changed
+- **CLI**: Updated `--consolidate` description to mention `--dir` option
+- **CLI**: Renamed "GIMP Processing Options" to "Processing Options" for tool-agnostic organization
+- **CLI**: Updated image mode help with Frame Extraction & Reassembly section
+- **CLI**: Added Metadata Management section to image mode help
+- **Processor**: Refactored consolidation workflow to support both file list and directory modes
+- **Test Suite**: Increased from 274 to 365 examples (all passing), 75.8% line coverage
+- **CLI**: Added parent-child visual hierarchy to all context-sensitive help displays
+- **CLI**: Corrected `--sharpen` to show as standalone option (not under `--scale`)
+
+#### Examples
+```bash
+# Get context-sensitive help for specific modes
+ruby_spriter --video --help
+ruby_spriter --image --help
+ruby_spriter --consolidate --help
+ruby_spriter --batch --help
+ruby_spriter --split --help
+
+# Process all videos in directory
+ruby_spriter --batch --dir "videos/"
+
+# Process with output to different directory
+ruby_spriter --batch --dir "videos/" --outputdir "output/"
+
+# Process and consolidate all results
+ruby_spriter --batch --dir "videos/" --batch-consolidate
+
+# Process with scaling and compression
+ruby_spriter --batch --dir "videos/" --scale 50 --max-compress
+
+# Compress video output
+ruby_spriter --video "input.mp4" --max-compress
+
+# Compress image processing output
+ruby_spriter --image "sprite.png" --scale 50 --max-compress
+
+# Directory-based consolidation
+ruby_spriter --consolidate --dir "spritesheets/"
+ruby_spriter --consolidate --dir "spritesheets/" --outputdir "output/"
+ruby_spriter --consolidate --dir "spritesheets/" --max-compress
+
+# File list consolidation still works
+ruby_spriter --consolidate file1.png,file2.png,file3.png
+
+# Extract specific frames and create new spritesheet
+ruby_spriter --image sprite.png --extract 1,2,4,5,8 --columns 3
+
+# Extract with duplicates for animation loops
+ruby_spriter --image sprite.png --extract 1,1,2,2,3,3 --save-frames
+
+# Extract and process
+ruby_spriter --image sprite.png --extract 1,3,5,7 --scale 50 --sharpen
+
+# Add metadata to external spritesheet
+ruby_spriter --image sprite.png --add-meta 4:4
+
+# Add metadata with partial grid
+ruby_spriter --image sprite.png --add-meta 4:4 --frames 14 --output sprite_meta.png
+
+# Replace existing metadata
+ruby_spriter --image existing.png --add-meta 8:8 --overwrite-meta
+
+# Workflow: Add metadata, then extract frames
+ruby_spriter --image external.png --add-meta 4:4
+ruby_spriter --image external.png --extract 1,5,9,13 --columns 2
+```
+
+Closes #14, #16
+
+---
+
 ## [0.6.6] - 2025-10-23
 
 ### 🔒 File Protection & Frame Extraction Release

data/README.md

@@ -1,4 +1,4 @@
-# Ruby Spriter v0.6.6
+# Ruby Spriter v0.6.7
 
 [![Ruby](https://img.shields.io/badge/Ruby-2.7+-red.svg)](https://www.ruby-lang.org/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -16,11 +16,15 @@ A powerful cross-platform Ruby tool for creating high-quality spritesheets from
 - 🎬 **Video to Spritesheet** - Extract frames from MP4 videos using FFmpeg
 - 🖼️ **Advanced Image Processing** - Scale, sharpen, and remove backgrounds with precision
 - 🎨 **Quality Enhancement** - 5 interpolation methods and configurable unsharp masking
-- 📐 **Spritesheet Consolidation** - Merge multiple spritesheets vertically
-- 📊 **Metadata Management** - Embed and verify grid information in PNG files
+- 📐 **Spritesheet Consolidation** - Merge multiple spritesheets vertically (file list or directory)
+- 📊 **Metadata Management** - Embed, verify, and add grid information to PNG files
+- 🎯 **Frame Extraction** - Extract specific frames by number and create new spritesheets
+- 🏷️ **Metadata Addition** - Add spritesheet metadata to external images
 - 🔒 **Automatic File Protection** - Unique timestamped filenames prevent accidental overwrites (v0.6.6+)
+- 📦 **Batch Processing** - Process multiple MP4 files in a directory automatically (v0.6.7+)
+- 🗜️ **Maximum Compression** - Optimal PNG compression while preserving metadata (v0.6.7+)
 - 🌍 **Cross-Platform** - Works seamlessly on Windows, Linux, and macOS
-- 🧪 **Production Ready** - Comprehensive RSpec test coverage
+- 🧪 **Production Ready** - Comprehensive RSpec test coverage (365 tests)
 
 ### Image Processing Features
 
@@ -89,19 +93,82 @@ Ruby Spriter requires these external tools for video and image processing:
 
 #### Installing Prerequisites
 
-**Windows (Chocolatey)**
-```powershell
-choco install ffmpeg imagemagick gimp -y
-```
+**Windows (Chocolatey - Recommended)**
+
+Chocolatey is a package manager for Windows that simplifies software installation. If you don't have Chocolatey installed:
+
+1. **Install Chocolatey** (run PowerShell as Administrator):
+   ```powershell
+   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+   ```
+
+   Verify installation:
+   ```powershell
+   choco --version
+   ```
+
+2. **Install Ruby** (if not already installed):
+   ```powershell
+   choco install ruby -y
+   ```
+
+   Close and reopen PowerShell, then verify:
+   ```powershell
+   ruby --version
+   gem --version
+   ```
+
+3. **Install Ruby Spriter dependencies**:
+   ```powershell
+   choco install ffmpeg imagemagick gimp -y
+   ```
+
+   This installs all required tools:
+   - **FFmpeg** - Video processing
+   - **ImageMagick** - Image manipulation and metadata
+   - **GIMP** - Advanced image processing
+
+4. **Restart your terminal** to ensure all tools are in your PATH
+
+**Alternative: Manual Installation on Windows**
+
+If you prefer not to use Chocolatey:
+- **Ruby**: Download from [rubyinstaller.org](https://rubyinstaller.org/)
+- **FFmpeg**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)
+- **ImageMagick**: Download from [imagemagick.org](https://imagemagick.org/script/download.php#windows)
+- **GIMP**: Download from [gimp.org](https://www.gimp.org/downloads/)
 
 **macOS (Homebrew)**
+
 ```bash
+# Install Homebrew if not already installed
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Ruby (if not already installed)
+brew install ruby
+
+# Install Ruby Spriter dependencies
 brew install ffmpeg imagemagick gimp
 ```
 
 **Linux (Ubuntu/Debian)**
+
+```bash
+# Install Ruby (if not already installed)
+sudo apt update && sudo apt install ruby-full -y
+
+# Install Ruby Spriter dependencies
+sudo apt install ffmpeg imagemagick gimp -y
+```
+
+**Linux (Fedora/RHEL)**
+
 ```bash
-sudo apt update && sudo apt install ffmpeg imagemagick gimp -y
+# Install Ruby (if not already installed)
+sudo dnf install ruby -y
+
+# Install Ruby Spriter dependencies
+sudo dnf install ffmpeg imagemagick gimp -y
 ```
 
 ---
@@ -135,7 +202,7 @@ bundle install
 
 # Build and install gem locally
 gem build ruby_spriter.gemspec
-gem install ruby_spriter-0.6.6.gem
+gem install ruby_spriter-0.6.7.gem
 ```
 
 **Best for**: Contributors, developers wanting latest code
@@ -210,23 +277,79 @@ ruby_spriter --image sprite.png --remove-bg \
   --threshold 1.5 --grow 2
 ```
 
+### Batch Processing (v0.6.7+)
+```bash
+# Process all videos in a directory
+ruby_spriter --batch --dir "videos/"
+
+# Batch process with scaling and compression
+ruby_spriter --batch --dir "videos/" --scale 50 --max-compress
+
+# Batch process with output to different directory
+ruby_spriter --batch --dir "videos/" --outputdir "output/"
+
+# Batch process and consolidate all results
+ruby_spriter --batch --dir "videos/" --batch-consolidate
+```
+
+### Consolidate Spritesheets
+```bash
+# Consolidate specific files (comma-separated)
+ruby_spriter --consolidate file1.png,file2.png,file3.png
+
+# Consolidate all spritesheets in a directory (v0.6.7+)
+ruby_spriter --consolidate --dir "spritesheets/"
+
+# Consolidate with compression
+ruby_spriter --consolidate --dir "spritesheets/" --max-compress
+```
+
+### Frame Extraction (v0.6.8+)
+```bash
+# Extract specific frames by number
+ruby_spriter --image sprite.png --extract 1,2,4,5,8 --columns 3
+
+# Extract with duplicates for animation loops
+ruby_spriter --image sprite.png --extract 1,1,2,2,3,3
+
+# Extract, process, and save frames
+ruby_spriter --image sprite.png --extract 1,3,5,7 \
+  --scale 50 --sharpen --save-frames
+
+# Workflow: Add metadata then extract frames
+ruby_spriter --image external.png --add-meta 4:4
+ruby_spriter --image external.png --extract 1,5,9,13 --columns 2
+```
+
+### Metadata Management (v0.6.8+)
+```bash
+# Add metadata to external spritesheet
+ruby_spriter --image sprite.png --add-meta 4:4
+
+# Add metadata with partial grid (14 frames in 4x4 grid)
+ruby_spriter --image sprite.png --add-meta 4:4 --frames 14
+
+# Replace existing metadata
+ruby_spriter --image existing.png --add-meta 8:8 --overwrite-meta
+
+# Add metadata and copy to new file
+ruby_spriter --image sprite.png --add-meta 4:4 --output sprite_meta.png
+```
+
 ### Advanced Workflows
 ```bash
-# Complete processing pipeline
+# Complete processing pipeline with compression
 ruby_spriter --video input.mp4 \
   --frames 64 --columns 8 \
   --scale 50 --interpolation nohalo \
   --remove-bg \
-  --sharpen --sharpen-gain 0.8
+  --sharpen --sharpen-gain 0.8 \
+  --max-compress
 
 # Process existing image with quality enhancement
 ruby_spriter --image large_sprite.png \
   --scale 50 --interpolation lohalo \
   --sharpen --sharpen-gain 1.2
-
-# Consolidate multiple spritesheets
-ruby_spriter --consolidate file1.png,file2.png,file3.png \
-  --output combined.png
 ```
 
 ---
@@ -239,7 +362,9 @@ ruby_spriter --consolidate file1.png,file2.png,file3.png \
 ```bash
 -v, --video FILE              Input video file (MP4 only)
 -i, --image FILE              Input image file (PNG only)
-    --consolidate FILES       Consolidate multiple spritesheets (PNG only, comma-separated)
+    --batch                   Batch process mode (use with --dir)
+    --dir DIRECTORY           Directory for batch or consolidate operations
+    --consolidate [FILES]     Consolidate spritesheets (comma-separated files or use with --dir)
     --verify FILE             Verify spritesheet metadata (PNG only)
 ```
 
@@ -285,6 +410,34 @@ ruby_spriter --consolidate file1.png,file2.png,file3.png \
 --preset contact              8×? grid, 64 frames, 160px wide
 ```
 
+#### **Batch Processing Options (v0.6.7+)**
+```bash
+    --batch                   Enable batch processing mode
+    --dir DIRECTORY           Directory containing MP4 files to process
+    --outputdir DIRECTORY     Output directory for processed files
+    --batch-consolidate       Consolidate all resulting spritesheets
+```
+
+#### **Compression Options (v0.6.7+)**
+```bash
+    --max-compress            Apply maximum PNG compression (preserves metadata)
+```
+
+#### **Frame Extraction Options (v0.6.8+)**
+```bash
+    --extract FRAMES          Extract specific frames by number (e.g., 1,2,4,5,8)
+    --columns NUM             Output grid columns for extracted spritesheet (default: 4)
+    --save-frames             Keep individual extracted frames on disk
+    --split R:C               Split spritesheet into all individual frames (rows:columns)
+    --override-md             Override embedded metadata when using --split
+```
+
+#### **Metadata Management Options (v0.6.8+)**
+```bash
+    --add-meta R:C            Add spritesheet metadata (rows:columns, e.g., 4:4)
+    --overwrite-meta          Replace existing metadata
+```
+
 #### **Other Options**
 ```bash
     --overwrite               Overwrite existing output files (default: create unique filenames)
@@ -322,11 +475,28 @@ ruby_spriter --video explosion.mp4 \
 
 #### Multiple Character Directions
 ```bash
-# Consolidate walk cycles for 8 directions
+# Consolidate walk cycles for 8 directions (file list)
 ruby_spriter --consolidate \
   walk_n.png,walk_ne.png,walk_e.png,walk_se.png,\
   walk_s.png,walk_sw.png,walk_w.png,walk_nw.png \
   --output character_walk_all.png
+
+# Or consolidate all spritesheets in a directory (v0.6.7+)
+ruby_spriter --consolidate --dir "walk_cycles/" \
+  --output character_walk_all.png
+```
+
+### Batch Processing Workflows (v0.6.7+)
+```bash
+# Process entire animation library
+ruby_spriter --batch --dir "raw_animations/" \
+  --outputdir "game_assets/sprites/" \
+  --scale 50 --remove-bg --sharpen --max-compress
+
+# Create and consolidate multiple character states
+ruby_spriter --batch --dir "character_states/" \
+  --frames 8 --columns 4 \
+  --batch-consolidate
 ```
 
 ### Quality Enhancement
@@ -335,6 +505,7 @@ ruby_spriter --consolidate \
 ruby_spriter --image 4k_sprite.png \
   --scale 25 --interpolation lohalo \
   --sharpen --sharpen-gain 1.0 \
+  --max-compress \
   --output hd_sprite.png
 ```
 
@@ -342,6 +513,91 @@ ruby_spriter --image 4k_sprite.png \
 
 ## 🔧 Advanced Features
 
+### Batch Processing (v0.6.7+)
+
+Process entire directories of MP4 files with consistent settings:
+
+```bash
+# Basic batch processing
+ruby_spriter --batch --dir "animations/"
+# Processes all MP4s with default 4x4 grid
+
+# Batch with processing options
+ruby_spriter --batch --dir "animations/" \
+  --frames 32 --columns 8 \
+  --scale 50 --remove-bg --sharpen \
+  --max-compress
+
+# Batch with output directory
+ruby_spriter --batch --dir "raw_videos/" \
+  --outputdir "game_assets/sprites/"
+
+# Batch and consolidate results
+ruby_spriter --batch --dir "character_states/" \
+  --batch-consolidate \
+  --output character_complete.png
+```
+
+**Features:**
+- Automatically finds all MP4 files in directory
+- Applies consistent processing to all videos
+- Enforces unique output filenames (unless `--overwrite`)
+- Continues processing if one file fails
+- Optional consolidation of all results
+- Supports all video and image processing options
+
+### Maximum Compression (v0.6.7+)
+
+Reduce file sizes while preserving metadata:
+
+```bash
+# Compress during video processing
+ruby_spriter --video input.mp4 --max-compress
+
+# Compress during image processing
+ruby_spriter --image sprite.png --scale 50 --max-compress
+
+# Compress batch output
+ruby_spriter --batch --dir "videos/" --max-compress
+
+# Compress consolidated output
+ruby_spriter --consolidate --dir "sprites/" --max-compress
+```
+
+**Compression Details:**
+- Uses ImageMagick optimal PNG compression settings
+- Compression level 9 (maximum zlib)
+- Paeth filter (compression filter 5)
+- Filtered strategy (compression strategy 1)
+- Quality 95
+- Preserves embedded spritesheet metadata
+- Displays size reduction statistics
+
+### Directory-Based Consolidation (v0.6.7+)
+
+Consolidate all spritesheets in a directory automatically:
+
+```bash
+# Scan directory and consolidate all spritesheets
+ruby_spriter --consolidate --dir "character_animations/"
+
+# With output directory
+ruby_spriter --consolidate --dir "sprites/" \
+  --outputdir "final_assets/"
+
+# With compression
+ruby_spriter --consolidate --dir "sprites/" \
+  --max-compress \
+  --output character_complete.png
+```
+
+**Directory Mode Features:**
+- Automatically scans for PNG files with metadata
+- Filters out non-spritesheet images
+- Sorts files alphabetically before consolidation
+- Requires at least 2 valid spritesheets
+- Cannot mix with comma-separated file list mode
+
 ### File Protection with Unique Filenames (v0.6.6+)
 
 By default, Ruby Spriter protects your existing files by generating unique timestamped filenames when output files already exist:
@@ -433,12 +689,13 @@ ruby_spriter --video input.mp4 --scale 50 --sharpen --debug
 
 ## 🏗️ Architecture
 
-### Four Processing Modes
+### Five Processing Modes
 
 1. **Video Mode** - MP4 → Spritesheet → Optional Processing
 2. **Image Mode** - PNG → Processing → Enhanced PNG
-3. **Consolidate Mode** - Multiple PNGs → Combined Spritesheet
-4. **Verify Mode** - Read and display embedded metadata
+3. **Consolidate Mode** - Multiple PNGs → Combined Spritesheet (file list or directory)
+4. **Batch Mode** (v0.6.7+) - Directory of MP4s → Multiple Spritesheets → Optional Consolidation
+5. **Verify Mode** - Read and display embedded metadata
 
 ### Processing Pipeline
 
@@ -472,7 +729,9 @@ Output PNG with Metadata
 
 **Consolidate Mode:**
 ```
-Multiple Input PNGs
+Multiple Input PNGs (file list or directory scan)
+    ↓
+[Metadata Filter] Find PNGs with spritesheet metadata (directory mode)
     ↓
 [ImageMagick] Read Metadata from Each
     ↓
@@ -482,15 +741,36 @@ Multiple Input PNGs
     ↓
 [ImageMagick] Embed Combined Metadata
     ↓
+[ImageMagick] Optional Max Compression
+    ↓
 Output Consolidated PNG
 ```
 
+**Batch Mode (v0.6.7+):**
+```
+Directory of MP4 Files
+    ↓
+[Scan] Find all MP4 files
+    ↓
+[Loop] For each MP4:
+    ├─ [FFmpeg] Extract frames + create spritesheet
+    ├─ [GIMP] Optional scaling/background removal
+    ├─ [ImageMagick] Optional sharpening
+    └─ [ImageMagick] Optional max compression
+    ↓
+[Optional] Consolidate all results with --batch-consolidate
+    ↓
+Multiple Output PNGs (or one consolidated PNG)
+```
+
 ### Key Components
 
 - **Processor** - Main orchestration
 - **VideoProcessor** - FFmpeg integration
 - **GimpProcessor** - GIMP batch scripting
-- **Consolidator** - Multi-sheet merging
+- **Consolidator** - Multi-sheet merging (file list or directory)
+- **BatchProcessor** (v0.6.7+) - Directory batch processing
+- **CompressionManager** (v0.6.7+) - PNG compression with metadata preservation
 - **MetadataManager** - PNG metadata handling
 - **DependencyChecker** - Tool detection
 - **Platform** - Cross-platform abstraction
@@ -531,12 +811,17 @@ ruby-spriter/
 │       ├── video_processor.rb
 │       ├── gimp_processor.rb
 │       ├── consolidator.rb
+│       ├── batch_processor.rb        # v0.6.7+
+│       ├── compression_manager.rb    # v0.6.7+
 │       ├── metadata_manager.rb
 │       ├── dependency_checker.rb
 │       ├── platform.rb
 │       └── utils/            # Helper modules
-├── spec/                     # RSpec tests
+├── spec/                     # RSpec tests (313 examples)
+├── .claude/
+│   └── agents/               # Custom Claude Code agent config
 ├── CLAUDE.md                 # Developer documentation
+├── CHANGELOG.md              # Version history
 └── README.md                 # This file
 ```
 
@@ -554,15 +839,33 @@ bundle exec ruby_spriter --video test.mp4
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Write tests for your changes
-4. Ensure all tests pass (`bundle exec rspec`)
-5. Commit your changes (`git commit -m 'Add amazing feature'`)
-6. Push to the branch (`git push origin feature/amazing-feature`)
-7. Open a Pull Request
+Contributions are welcome! This project follows strict **Test-Driven Development (TDD)** practices.
+
+### Development Workflow
+
+1. **Fork the repository**
+2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
+3. **Follow TDD Red-Green-Refactor cycle:**
+   - ✅ **Red**: Write ONE test → Run it → Verify it FAILS
+   - ✅ **Green**: Write minimal code → Run test → Verify it PASSES
+   - ✅ **Refactor**: Clean up → Run all tests → Verify still passing
+   - ✅ **Repeat** for each new test
+4. **Ensure all tests pass** (`bundle exec rspec`)
+5. **Update documentation** (README.md, CHANGELOG.md, CLAUDE.md)
+6. **Commit your changes** (`git commit -m 'Add amazing feature'`)
+7. **Push to the branch** (`git push origin feature/amazing-feature`)
+8. **Open a Pull Request**
+
+### Agent Configuration
+
+This project includes a custom Claude Code agent (`.claude/agents/ruby-spriter-architect.md`) that enforces:
+- Strict TDD (Red-Green-Refactor) workflow
+- Architecture consistency
+- Documentation maintenance
+- Cross-platform compatibility
+- Test coverage requirements
+
+The agent configuration is version-controlled and shared across the team.
 
 ---