Image processing plugin for mediaproc - powered by Sharp
npm install @mediaproc/imageProfessional image processing CLI powered by Sharp. Fast, efficient, and feature-rich image manipulation toolkit with 47 comprehensive commands.
- Features
- Installation & Usage
- Quick Start
- Global Options & Common Flags
- Commands Overview
- Detailed Command Reference
- Transform & Resize
- Color & Tone
- Effects & Filters
- Advanced Operations
- Smart/AI Operations
- Utility Commands
- Real-World Workflows
- Usage Tips
- Troubleshooting
---
- 🚀 High Performance - Built on libvips for blazing fast processing
- 🎨 51 Commands - Comprehensive image manipulation toolkit covering all Sharp operations
- 🔧 Professional Features - Quality control, dry-run mode, verbose logging
- 📦 Modern Formats - WebP, AVIF, JPEG, PNG, TIFF, GIF support
- 🎯 Simple CLI - Intuitive command-line interface
- 💡 Helpful Documentation - Built-in help for every command
- 🤖 Smart Operations - AI-like auto-enhance, smart crop, batch processing
Install the universal CLI and add the image plugin:
``bashInstall universal CLI
npm install -g @mediaproc/cli
Note: All commands use the
namespace: mediaproc image $3
Install and use the image plugin independently:
bash
Install standalone
npm install -g @mediaproc/imageUse commands directly (no "image" prefix)
mediaproc-image resize photo.jpg -w 800 -h 600
mediaproc-image convert photo.jpg -f webp
`Note: Standalone mode uses
command without the image prefix.---
🎯 Quick Start
With Universal CLI:
`bash
Resize an image
mediaproc image resize photo.jpg -w 800 -h 600Convert to WebP
mediaproc image convert photo.jpg -f webp -q 85Generate thumbnail
mediaproc image thumbnail photo.jpg -s 150Optimize for web
mediaproc image optimize photo.jpg -q 85Get help for any command
mediaproc image resize --help
`With Standalone Plugin:
bash
Same commands, different prefix
mediaproc-image resize photo.jpg -w 800 -h 600
mediaproc-image convert photo.jpg -f webp -q 85
mediaproc-image thumbnail photo.jpg -s 150
`---
🌐 Global Options & Common Flags
All image commands share a consistent set of common flags for unified behavior:
$3
| Flag | Alias | Description | Default |
| ------------------- | ----- | --------------------------------- | ------------------------- |
|
| -o | Output file path | - |
| --quality <1-100> | -q | Output quality (1-100) | 90 |
| --dry-run | - | Preview changes without executing | false |
| --verbose | -v | Show detailed processing output | false |
| --help | - | Display command-specific help | - |$3
1. Input Processing:
`bash
Commands accept file paths (relative or absolute)
mediaproc image resize photo.jpg -w 800
mediaproc image resize /path/to/photo.jpg -w 800
mediaproc image resize ../images/photo.jpg -w 800
`2. Output Naming:
bash
Default: -.
mediaproc image blur photo.jpg # → photo-blur.jpgCustom output path:
mediaproc image blur photo.jpg -o soft.jpgPreserve format or change:
mediaproc image blur photo.jpg -o output.webp # Changes format
`3. Quality Control:
bash
High quality (larger file size)
mediaproc image resize photo.jpg -w 1920 -q 95Balanced (default)
mediaproc image resize photo.jpg -w 1920 -q 90Compressed (smaller file size)
mediaproc image resize photo.jpg -w 1920 -q 75Note: Quality applies to lossy formats (JPEG, WebP)
`4. Dry-Run Mode:
bash
Preview what will happen without processing
mediaproc image resize photo.jpg -w 1920 --dry-runShows: input, output paths, and operation details
Useful for testing commands before batch processing
`5. Verbose Output:
bash
Show detailed processing information
mediaproc image resize photo.jpg -w 1920 -vDisplays:
- Configuration settings
- Processing steps
- Metadata information
- File size comparisons
`$3
Each command has unique options for its specific operation:
Transform Commands:
- Resize:
, --height, --fit, --position, --kernel
- Rotate: , --background
- Crop: , --top, --extract-strategyColor Commands:
- Modulate:
, --saturation, --hue
- Gamma:
- Tint: Effect Commands:
- Blur:
- Sharpen: , --mode
- Threshold: Advanced Commands:
- Composite:
, --blend, --gravity
- Boolean: , --operand
- Recomb: $3
View all available commands:
bash
Universal CLI
mediaproc image --helpStandalone plugin
mediaproc-image --help
`Get command-specific help:
bash
Shows detailed usage, options, examples
mediaproc image resize --help
mediaproc image blur --help
mediaproc image composite --help
`Help includes:
- 📝 Description and purpose
- 🎯 Usage syntax
- ⚙️ Available options and flags
- 💡 Practical examples
- 📚 Use cases and workflows
- 💪 Tips and best practices
$3
Input Formats:
- JPEG (
, .jpeg)
- PNG (.png)
- WebP (.webp)
- AVIF (.avif)
- TIFF (.tiff, .tif)
- GIF (.gif)
- SVG (.svg)
- HEIF (.heic, .heif)Output Formats:
- JPEG - Best for photos (lossy)
- PNG - Best for graphics with transparency (lossless)
- WebP - 25-35% smaller than JPEG (lossy/lossless)
- AVIF - 50% smaller than JPEG (lossy/lossless)
- TIFF - Best for professional/print (lossless)
- GIF - Best for simple animations (limited colors)
$3
1. Format Selection:
`bash
Use WebP for web (smaller, fast)
mediaproc image convert photo.jpg -f webp -q 85Use PNG for graphics with transparency
mediaproc image convert logo.jpg -f pngUse AVIF for maximum compression (slower encoding)
mediaproc image convert photo.jpg -f avif -q 80
`2. Quality vs Size:
bash
High quality (minimal compression)
-q 95 # Large file, excellent qualityBalanced (recommended)
-q 85 # Good file size, great qualityAggressive (maximum compression)
-q 70 # Small file, acceptable quality
`3. Chaining Operations:
bash
Instead of multiple commands:
mediaproc image resize input.jpg -w 1920 -o step1.jpg
mediaproc image blur step1.jpg -o step2.jpg
mediaproc image sharpen step2.jpg -o final.jpgConsider using pipeline/batch features:
mediaproc image batch images/ --operation "resize -w 1920"
`4. Batch Processing:
bash
Process multiple files efficiently
for file in *.jpg; do
mediaproc image optimize "$file" -q 85
done
`---
📋 Commands Overview
All 46 commands organized by category:
$3
- resize - Resize images with advanced fit modes (cover, contain, fill, inside, outside)
- crop - Extract rectangular regions with positioning options
- rotate - Rotate by any angle with background control
- flip - Vertical mirroring (top-to-bottom flip)
- flop - Horizontal mirroring (left-to-right flip)
- affine - Apply affine transformation matrix (scale, shear, reflect)
- trim - Auto-remove uniform borders from edges
- extend - Add padding/borders with custom colors
- thumbnail - Generate thumbnails (64px to 512px)
$3
- modulate - Adjust brightness, saturation, and hue
- gamma - Apply gamma correction for midtones (0.1-3.0)
- tint - Apply color tint overlay (RGB hex colors)
- grayscale - Convert to black & white
- negate - Create negative/inverted image
- normalize - Auto-enhance contrast and brightness
- linear - Apply linear formula: output = (a \* input) + b
- recomb - Recombine RGB channels using transformation matrix
- flatten - Remove alpha transparency with background color
- unflatten - Add alpha channel (RGB→RGBA)
$3
- blur - Gaussian blur effect (0.3-1000 sigma)
- sharpen - Enhance image details and edges
- median - Noise reduction filter (1-50 size)
- sepia - Vintage sepia tone effect
- vignette - Darken edges for artistic focus
- pixelate - Retro pixel art effect with custom pixel size
- threshold - Binary black/white conversion (0-255)
- dilate - Morphological dilation (expand bright regions)
- erode - Morphological erosion (expand dark regions)
$3
- composite - Layer images with blend modes (overlay, multiply, screen)
- extract - Extract color channels (R, G, B, alpha) or regions
- border - Add decorative frames with custom colors
- clahe - Contrast-limited adaptive histogram equalization
- convolve - Apply custom convolution kernels (sharpen, emboss, edge)
- boolean - Perform boolean operations between images (AND, OR, XOR)
$3
- palette - Extract dominant color palettes (2-256 colors)
- dominant-color - Quick dominant color extraction
- batch - Process multiple images at once with any operation
$3
- convert - Format conversion (JPG, PNG, WebP, AVIF, TIFF, GIF)
- optimize - Size optimization (up to 70% reduction)
- compress - Advanced compression with quality control
- watermark - Add watermarks with positioning and opacity
- info - Display comprehensive image information
- stats - Detailed technical image statistics
- split - Split image into grid tiles
- mirror - Create mirror/kaleidoscope effects (horizontal, vertical, quad)
- metadata - View, export, or remove EXIF data
---
📚 Detailed Command Reference
$3
Resize images with advanced options for fit modes, aspect ratio control, and quality settings.
Usage:
bash
mediaproc image resize [options]
`Options:
-
- Target width in pixels
- -h, --height - Target height in pixels
- --fit - Fit mode: cover, contain, fill, inside, outside (default: cover)
- --position - Position for cover/contain: center, top, bottom, left, right, etc.
- --kernel - Resampling kernel: nearest, cubic, mitchell, lanczos2, lanczos3 (default: lanczos3)
- --no-enlarge - Don't enlarge if image is smaller than target
- --no-reduce - Don't reduce if image is larger than target
- -q, --quality - Quality 1-100 (default: 90)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Resize to 800x600 (crop to fit)
mediaproc image resize photo.jpg -w 800 -h 600Resize to fit within 1920x1080 (no cropping)
mediaproc image resize photo.jpg -w 1920 -h 1080 --fit containResize width only (maintain aspect ratio)
mediaproc image resize photo.jpg -w 1000High-quality resize with lanczos3 kernel
mediaproc image resize photo.jpg -w 2000 --kernel lanczos3 -q 95
`Fit Modes:
- cover - Fill entire area, crop if needed (default)
- contain - Fit inside with padding
- fill - Stretch to fill (may distort)
- inside - Shrink if larger
- outside - Enlarge to cover
---
$3
Convert images between formats with quality control and compression options.
Usage:
bash
mediaproc image convert [options]
`Options:
-
- Output format: jpg, png, webp, avif, tiff, gif (default: webp)
- -q, --quality - Quality 1-100 (default: 90)
- --compression - PNG compression level 0-9 (default: 9)
- --progressive - Use progressive/interlaced format
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Convert to WebP
mediaproc image convert photo.jpg -f webpConvert to AVIF with quality 80
mediaproc image convert image.png -f avif -q 80Convert to progressive JPEG
mediaproc image convert photo.png -f jpg --progressiveConvert to PNG with max compression
mediaproc image convert photo.jpg -f png --compression 9
`Format Guide:
- WebP - Modern format, 25-35% smaller than JPG/PNG
- AVIF - Newest format, even smaller than WebP
- JPG - Best for photos, lossy compression
- PNG - Best for graphics/transparency, lossless
- TIFF - Professional/print, very large files
- GIF - Animations, limited colors
---
$3
Convert images to grayscale (black and white).
Usage:
bash
mediaproc image grayscale [options]
`Options:
-
- Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Convert to grayscale
mediaproc image grayscale photo.jpgGrayscale with custom output
mediaproc image grayscale photo.jpg -o bw-photo.jpgAlso works with UK spelling
mediaproc image greyscale photo.jpg
`Use Cases:
- Artistic black and white photography
- Document scanning
- Reducing file size
- Accessibility (colorblind-friendly)
- Classic/vintage aesthetic
---
$3
Apply Gaussian blur effect with configurable strength.
Usage:
bash
mediaproc image blur [options]
`Options:
-
- Blur strength 0.3-1000 (default: 5)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Default blur
mediaproc image blur photo.jpgStrong blur
mediaproc image blur photo.jpg -s 20Subtle blur
mediaproc image blur photo.jpg -s 2
`Blur Strength Guide:
- 1-5 - Light blur (slight softness)
- 5-15 - Medium blur (noticeable effect)
- 15-30 - Strong blur (heavy softness)
- 30+ - Heavy blur (abstract effect)
---
$3
Sharpen images to enhance details and edges.
Usage:
bash
mediaproc image sharpen [options]
`Options:
-
- Sharpening strength 0.01-10 (default: 1)
- --flat - Sharpening for flat areas (default: 1)
- --jagged - Sharpening for jagged areas (default: 2)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Default sharpening
mediaproc image sharpen photo.jpgStrong sharpening
mediaproc image sharpen image.png -s 2Custom parameters
mediaproc image sharpen photo.jpg -s 1.5 --flat 1.5 --jagged 2.5
`Sharpening Guide:
- 0.3-0.7 - Subtle enhancement
- 1.0-1.5 - Normal sharpening
- 2.0-3.0 - Strong sharpening
- 3.0+ - Extreme (risk of artifacts)
---
$3
Rotate images by any angle with background color control.
Usage:
bash
mediaproc image rotate [options]
`Options:
-
- Rotation angle in degrees (default: 90)
- --background - Background color (default: black)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Rotate 90° clockwise
mediaproc image rotate photo.jpg -a 90Rotate 180° (upside down)
mediaproc image rotate photo.jpg -a 180Rotate 45° with white background
mediaproc image rotate photo.jpg -a 45 --background whiteCounter-clockwise rotation
mediaproc image rotate photo.jpg -a -90
`Common Angles:
- 90 - Rotate right (clockwise)
- -90 or 270 - Rotate left (counter-clockwise)
- 180 - Upside down
- 45 - Diagonal tilt
---
$3
Mirror images horizontally, vertically, or both.
Usage:
bash
mediaproc image flip [options]
`Options:
-
- Direction: horizontal, vertical, both (default: horizontal)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Flip horizontally (mirror left-right)
mediaproc image flip photo.jpgFlip vertically (mirror up-down)
mediaproc image flip photo.jpg -d verticalFlip both ways (180° rotation)
mediaproc image flip photo.jpg -d both
`---
$3
Extract rectangular regions from images.
Usage:
bash
mediaproc image crop [options]
`Options:
-
- X coordinate (left position, required)
- -y - Y coordinate (top position, required)
- -w, --width - Crop width (required)
- -h, --height - Crop height (required)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Crop 800x600 region from top-left (0,0)
mediaproc image crop photo.jpg -x 0 -y 0 -w 800 -h 600Crop from specific position
mediaproc image crop photo.jpg -x 100 -y 50 -w 500 -h 400Extract center region
mediaproc image crop photo.jpg -x 400 -y 300 -w 800 -h 600
`---
$3
Optimize image file size with minimal quality loss.
Usage:
bash
mediaproc image optimize [options]
`Options:
-
- Quality 1-100 (default: 85)
- --aggressive - More aggressive compression (quality 70)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Optimize with quality 85
mediaproc image optimize photo.jpgLight optimization (high quality)
mediaproc image optimize image.png -q 90Aggressive compression
mediaproc image optimize pic.jpg --aggressive
`Quality Guide:
- 90-100 - Minimal compression, large files
- 85-89 - Balanced (recommended for web)
- 70-84 - Good compression, slight quality loss
- 50-69 - High compression, noticeable quality loss
---
$3
Add watermarks to images with position and opacity control.
Usage:
bash
mediaproc image watermark [options]
`Options:
-
- Position: center, top-left, top-right, bottom-left, bottom-right (default: bottom-right)
- --opacity - Opacity 0-1 (default: 0.5)
- --scale - Watermark scale 0.1-1 (default: 0.2)
- -q, --quality - Quality 1-100 (default: 90)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Add watermark to bottom-right
mediaproc image watermark photo.jpg logo.pngCenter watermark
mediaproc image watermark image.jpg mark.png --position centerSubtle watermark
mediaproc image watermark photo.jpg logo.png --opacity 0.3Larger watermark in top-right
mediaproc image watermark photo.jpg brand.png --scale 0.3 --position top-right
`Opacity Guide:
- 0.1-0.3 - Very subtle
- 0.4-0.6 - Balanced (recommended)
- 0.7-0.9 - Clearly visible
- 1.0 - Fully opaque
---
$3
Generate thumbnails with configurable sizes.
Usage:
bash
mediaproc image thumbnail [options]
`Options:
-
- Thumbnail size in pixels (default: 150)
- --fit - Fit mode: cover, contain, fill, inside, outside (default: cover)
- -q, --quality - Quality 1-100 (default: 85)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Generate 150x150 thumbnail
mediaproc image thumbnail photo.jpgGenerate 200x200 thumbnail
mediaproc image thumbnail image.png -s 200Thumbnail with padding
mediaproc image thumbnail pic.jpg -s 100 --fit contain
`Common Sizes:
- 64x64 - Favicon, small icons
- 150x150 - Default thumbnail
- 200x200 - Medium thumbnails
- 300x300 - Large thumbnails
- 512x512 - App icons
---
$3
Apply color tint overlay to images.
Usage:
bash
mediaproc image tint [options]
`Options:
-
- Tint color (hex, rgb, or name, default: #0000ff)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Apply blue tint
mediaproc image tint photo.jpg -c blueApply sepia tint
mediaproc image tint image.png -c "#704214"Apply custom RGB tint
mediaproc image tint pic.jpg -c "rgb(255, 100, 50)"
`Common Tints:
- Sepia (#704214) - Vintage/warm look
- Blue (#0066cc) - Cool/cold mood
- Orange (#ff6600) - Warm/sunset effect
- Purple (#9933cc) - Creative/artistic
- Green (#00cc66) - Nature/fresh feel
---
$3
Create negative/inverted images.
Usage:
bash
mediaproc image negate [options]
`Options:
-
- Also negate alpha/transparency channel
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Create negative
mediaproc image negate photo.jpgNegate with alpha channel
mediaproc image negate image.png --alpha
`Use Cases:
- Artistic effects
- X-ray style images
- Film negatives
- High contrast viewing
- Dark mode alternatives
---
$3
Normalize images by auto-enhancing contrast.
Usage:
bash
mediaproc image normalize [options]
`Options:
-
- Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Auto-enhance contrast
mediaproc image normalize photo.jpgFix underexposed image
mediaproc image normalize dark-image.pngFix washed out image
mediaproc image normalize overexposed.jpg
`Best For:
- Underexposed photos
- Overexposed photos
- Low contrast images
- Scanned documents
- Poor lighting conditions
---
$3
Adjust brightness, saturation, and hue.
Usage:
bash
mediaproc image modulate [options]
`Options:
-
- Brightness multiplier 0.1-10 (default: 1)
- -s, --saturation - Saturation multiplier 0.1-10 (default: 1)
- --hue - Hue rotation -360 to 360 (default: 0)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Increase brightness by 20%
mediaproc image modulate photo.jpg -b 1.2Boost saturation by 50%
mediaproc image modulate image.png -s 1.5Rotate hue by 180 degrees
mediaproc image modulate pic.jpg --hue 180Adjust all three
mediaproc image modulate photo.jpg -b 1.2 -s 1.3 --hue 30
`Brightness:
- 0.5 - 50% darker
- 1.0 - No change (default)
- 1.5 - 50% brighter
- 2.0 - Double brightness
Saturation:
- 0.0 - Grayscale
- 1.0 - No change (default)
- 1.5 - 50% more vibrant
- 2.0 - Double saturation
---
$3
Apply gamma correction to adjust midtones.
Usage:
bash
mediaproc image gamma [options]
`Options:
-
- Gamma value 1-3 (default: 2.2)
- --gamma-out - Output gamma value (optional)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Standard sRGB gamma
mediaproc image gamma photo.jpg -g 2.2Brighten midtones
mediaproc image gamma image.png -g 1.5Darken midtones
mediaproc image gamma pic.jpg -g 2.8
`Gamma Values:
- 1.0 - Linear (no correction)
- 1.5 - Lighter midtones
- 2.2 - Standard sRGB
- 2.4 - Rec. 709 (video)
- 2.8 - Darker midtones
---
$3
Auto-trim/remove border edges from images.
Usage:
bash
mediaproc image trim [options]
`Options:
-
- Edge detection threshold 1-100 (default: 10)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Auto-trim with default threshold
mediaproc image trim photo.jpgGentle trim
mediaproc image trim image.png -t 5Aggressive trim
mediaproc image trim pic.jpg -t 20
`Threshold Guide:
- 1-5 - Very sensitive
- 10 - Default (balanced)
- 15-25 - Aggressive
- 25+ - Very aggressive
Best For:
- Scanned documents
- Screenshots
- Solid color borders
- Product photos
- Auto-cropping
---
$3
Add padding/borders around images.
Usage:
bash
mediaproc image extend [options]
`Options:
-
- Padding on all sides (shortcut)
- --top - Top padding
- --bottom - Bottom padding
- --left - Left padding
- --right - Right padding
- --background - Background color (default: white)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Add 50px padding on all sides
mediaproc image extend photo.jpg --all 50Add black border
mediaproc image extend image.png --all 20 --background blackAdd padding top/bottom only
mediaproc image extend pic.jpg --top 100 --bottom 100Custom color border
mediaproc image extend photo.jpg --all 30 --background "#ff0000"
`Use Cases:
- Adding borders/frames
- Letterbox/pillarbox effect
- Preparing for specific dimensions
- Space for text overlay
- Social media formatting
---
$3
Apply median filter for noise reduction.
Usage:
bash
mediaproc image median [options]
`Options:
-
- Filter size 1-50 (default: 3)
- -o, --output - Output file path
- -q, --quality - Quality 1-100 (default: 90)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed output
- --help - Display helpExamples:
`bash
Default median filter
mediaproc image median photo.jpgStronger noise reduction
mediaproc image median noisy-image.png -s 5Remove scanner artifacts
mediaproc image median scan.jpg -s 7
`Filter Size:
- 1 - Minimal smoothing
- 3 - Default (balanced)
- 5-7 - Strong noise reduction
- 10+ - Heavy smoothing
Best For:
- Salt-and-pepper noise
- Scanner artifacts
- JPEG compression noise
- Old photo restoration
- Low-light camera noise
---
$3
Composite/blend multiple images together with various blend modes and positioning.
Usage:
bash
mediaproc image composite [options]
`Options:
-
- Blend mode: over, add, multiply, screen, overlay (default: over)
- --gravity - Position: center, north, south, east, west, northeast, northwest, southeast, southwest (default: center)
- --opacity - Overlay opacity 0-1 (default: 1)
- -x - X offset from gravity position
- -y - Y offset from gravity position
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Overlay image on top
mediaproc image composite base.jpg overlay.pngBlend with multiply mode
mediaproc image composite photo.jpg texture.jpg --blend multiplyPosition in top-right with opacity
mediaproc image composite bg.jpg logo.png --gravity northeast --opacity 0.7Precise positioning
mediaproc image composite base.jpg watermark.png -x 50 -y 50
`Blend Modes:
- over - Normal overlay (default)
- add - Additive blend
- multiply - Darken blend
- screen - Lighten blend
- overlay - Enhanced contrast blend
---
$3
Extract specific color channels or regions from images.
Usage:
bash
mediaproc image extract [options]
`Options:
-
- Channel: red, green, blue, alpha (default: red)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Extract red channel
mediaproc image extract photo.jpg --channel redExtract alpha channel (transparency)
mediaproc image extract image.png --channel alphaExtract green channel
mediaproc image extract pic.jpg --channel green -o green-channel.jpg
`Use Cases:
- Channel analysis
- Alpha mask extraction
- Color correction workflows
- Special effects
- Debugging image issues
---
$3
Add colored borders/frames around images.
Usage:
bash
mediaproc image border [options]
`Options:
-
- Border width (default: 10)
- -c, --color - Border color (default: black)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Default black border
mediaproc image border photo.jpgWhite border
mediaproc image border image.png -w 20 -c whiteCustom color border
mediaproc image border pic.jpg -w 15 -c "#ff6600"Instagram-style border
mediaproc image border photo.jpg -w 30 -c "#f0f0f0"
`Popular Border Styles:
- Black 10px - Classic frame
- White 20-30px - Instagram style
- Gray 5px - Subtle separation
- Colored borders - Branding/themes
---
$3
Display detailed technical information about images.
Usage:
bash
mediaproc image stats [options]
`Options:
-
- Show extended metadata and channel statistics
- --help - Display helpExamples:
`bash
Basic stats
mediaproc image stats photo.jpgDetailed analysis
mediaproc image stats image.png -v
`Information Displayed:
- Format and dimensions
- Color space and channels
- File size and compression
- DPI/density
- Bit depth
- EXIF metadata (if present)
- Color profile information
- Channel statistics (with -v)
Use Cases:
- Pre-processing analysis
- Quality verification
- Format identification
- Troubleshooting
- Metadata inspection
---
$3
Apply vintage sepia tone effect for classic photography look.
Usage:
bash
mediaproc image sepia [options]
`Options:
-
- Sepia intensity 0-100 (default: 80)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Classic sepia
mediaproc image sepia photo.jpgStrong vintage effect
mediaproc image sepia old-photo.png -i 100Subtle warmth
mediaproc image sepia modern.jpg -i 40
`Intensity Guide:
- 20-40 - Subtle warm tint
- 60-80 - Classic sepia (recommended)
- 80-100 - Strong vintage effect
---
$3
Apply Contrast Limited Adaptive Histogram Equalization for advanced contrast enhancement.
Usage:
bash
mediaproc image clahe [options]
`Options:
-
- Region width (default: 8)
- -h, --height - Region height (default: 8)
- --max-slope - Maximum contrast slope 0-100 (default: 2.5)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Default CLAHE
mediaproc image clahe photo.jpgStrong enhancement
mediaproc image clahe underexposed.jpg --max-slope 4Fine-grained adjustment
mediaproc image clahe medical.png -w 16 -h 16
`Best For:
- Medical imaging
- Scientific photography
- Underwater photos
- Low-light images
- X-ray enhancement
---
$3
Apply custom convolution kernels for advanced image filtering.
Usage:
bash
mediaproc image convolve [options]
`Options:
-
- Preset kernel: sharpen, emboss, edge-detect, box-blur, gaussian-blur, laplacian, high-pass
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Edge detection
mediaproc image convolve photo.jpg -k edge-detectEmboss effect
mediaproc image convolve image.png -k embossHigh-pass filter
mediaproc image convolve pic.jpg -k high-pass
`Preset Kernels:
- sharpen - Enhance edges
- emboss - 3D relief effect
- edge-detect - Detect edges
- box-blur - Simple blur
- gaussian-blur - Smooth blur
- laplacian - Edge enhancement
- high-pass - Detail extraction
---
$3
Add vignette effect (darkened edges) for artistic focus.
Usage:
bash
mediaproc image vignette [options]
`Options:
-
- Vignette intensity 0-100 (default: 50)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Default vignette
mediaproc image vignette photo.jpgSubtle vignette
mediaproc image vignette portrait.png -i 30Strong dramatic effect
mediaproc image vignette landscape.jpg -i 80
`Intensity Guide:
- 20-40 - Subtle focus
- 40-60 - Balanced (recommended)
- 60-80 - Dramatic effect
- 80-100 - Heavy darkening
---
🔧 Global Options
All commands support these global options:
-
- Custom output file path
- -q, --quality - Output quality (1-100)
- --dry-run - Preview changes without executing
- -v, --verbose - Show detailed processing information
- --help - Display command-specific help💡 Usage Tips
$3
- 90-100: Maximum quality, larger files
- 85-90: Recommended for web (best balance)
- 70-85: Good compression, slight quality loss
- Below 70: High compression, noticeable quality loss
$3
- WebP: Best for web, 25-35% smaller than JPG/PNG
- AVIF: Newest format, smaller than WebP
- JPG: Best for photos
- PNG: Best for graphics with transparency
$3
`bash
Process multiple files
for file in *.jpg; do
mediaproc image resize "$file" -w 1920 -h 1080
doneConvert all images to WebP
for file in *.{jpg,png}; do
mediaproc image convert "$file" -f webp -q 85
done
`$3
Use dry-run to test, then execute:
bash
Test first
mediaproc image resize photo.jpg -w 800 --dry-runThen execute
mediaproc image resize photo.jpg -w 800
`🚀 Performance
- Built on libvips for high performance
- Processes 4-5x faster than ImageMagick
- Low memory footprint
- Efficient multi-threading
- Optimized for batch processing
📝 Examples
$3
bash
1. Resize for web
mediaproc image resize photo.jpg -w 1920 -h 10802. Optimize
mediaproc image optimize photo-1920x1080.jpg -q 853. Convert to WebP
mediaproc image convert photo-1920x1080-optimized.jpg -f webp
`$3
bash
1. Normalize contrast
mediaproc image normalize photo.jpg2. Adjust colors
mediaproc image modulate photo-normalized.jpg -b 1.1 -s 1.23. Sharpen
mediaproc image sharpen photo-normalized-modulated.jpg -s 1.5
`$3
bash
Generate multiple sizes
mediaproc image thumbnail photo.jpg -s 64 -o thumb-64.jpg
mediaproc image thumbnail photo.jpg -s 150 -o thumb-150.jpg
mediaproc image thumbnail photo.jpg -s 300 -o thumb-300.jpg
`---
🤖 Custom/Smart Commands
$3
Process multiple images in a directory with any operation.
Usage:
bash
mediaproc image batch --operation [options]
`Options:
-
- Operation to apply: resize, convert, optimize, grayscale, etc. (required)
- -o, --output - Output directory (default: ./output)
- -r, --recursive - Process subdirectories
- --width - Width for resize
- --height - Height for resize
- -f, --format - Output format for convert
- -q, --quality - Quality settingExamples:
`bash
Resize all images
mediaproc image batch ./photos --operation resize --width 1920Convert all to WebP
mediaproc image batch ./images -op convert --format webp -q 90Optimize all images
mediaproc image batch ./pics -op optimize -q 85 -o ./optimizedGenerate thumbnails
mediaproc image batch ./gallery -op thumbnail --width 200 --height 200
`Supported Operations: resize, convert, optimize, grayscale, blur, sharpen, thumbnail, sepia, normalize
---
$3
Automatically crop to target dimensions while preserving important content.
Usage:
bash
mediaproc image smart-crop -w -h [options]
`Options:
-
- Target width (required)
- -h, --height - Target height (required)
- -s, --strategy - Strategy: entropy (edges/details) or attention (center-weighted) (default: entropy)
- -o, --output - Output file pathExamples:
`bash
Social media banner
mediaproc image smart-crop photo.jpg -w 1200 -h 630Square crop for Instagram
mediaproc image smart-crop portrait.jpg -w 800 -h 800 --strategy attentionProduct thumbnail
mediaproc image smart-crop product.png -w 600 -h 600 -o thumbnail.png
`Common Dimensions:
-
- Facebook/LinkedIn posts
- 1024x512 - Twitter cards
- 1080x1080 - Instagram square
- 800x800 - General thumbnails---
$3
Apply pixelate/mosaic effect for artistic or privacy purposes.
Usage:
`bash
mediaproc image pixelate [options]
`Options:
-
- Pixel size 2-50 (default: 10) - larger = more pixelated
- -o, --output - Output file pathExamples:
`bash
Default pixelation
mediaproc image pixelate photo.jpgHeavy pixelation for privacy
mediaproc image pixelate face.jpg --pixels 208-bit retro gaming style
mediaproc image pixelate game.jpg --pixels 8 -o retro.jpg
`Use Cases:
- Retro gaming aesthetics (8-12 pixel size)
- Privacy protection (15-25 pixel size)
- Artistic effects
- Censorship/redaction
---
$3
Extract and display dominant colors from images.
Usage:
bash
mediaproc image palette [options]
`Options:
-
- Number of colors 1-10 (default: 5)
- -v, --verbose - Show hex codes and RGB valuesExamples:
`bash
Extract 5 dominant colors
mediaproc image palette photo.jpgGet brand colors
mediaproc image palette logo.png --colors 3 -vFull palette analysis
mediaproc image palette artwork.jpg --colors 10
`Output Includes:
- Dominant colors ranked by prevalence
- RGB and hex values
- Color temperature (warm/cool)
- Brightness analysis
- Saturation levels
Use Cases:
- Design inspiration
- Brand color extraction
- Theme generation
- UI/UX color matching
---
$3
Automatically crop to target dimensions while preserving important content using edge detection.
Usage:
bash
mediaproc image smart-crop -w -h [options]
`Options:
-
- Target width (required)
- -h, --height - Target height (required)
- -s, --strategy - Strategy: entropy (edges/details) or attention (center-weighted) (default: entropy)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Social media banner
mediaproc image smart-crop photo.jpg -w 1200 -h 630Square crop for Instagram
mediaproc image smart-crop portrait.jpg -w 800 -h 800 --strategy attentionProduct thumbnail
mediaproc image smart-crop product.png -w 600 -h 600
`Strategies:
- entropy - Focus on edges and details (best for landscapes)
- attention - Center-weighted (best for portraits)
Common Social Media Dimensions:
- 1200x630 - Facebook/LinkedIn posts
- 1024x512 - Twitter cards
- 1080x1080 - Instagram square
- 1080x1350 - Instagram portrait
- 800x800 - General thumbnails
---
$3
Apply pixelate/mosaic effect for artistic or privacy purposes.
Usage:
bash
mediaproc image pixelate [options]
`Options:
-
- Pixel size 2-50 (default: 10) - larger = more pixelated
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Default pixelation
mediaproc image pixelate photo.jpgHeavy pixelation for privacy
mediaproc image pixelate face.jpg --pixels 208-bit retro gaming style
mediaproc image pixelate game.jpg --pixels 8
`Pixel Size Guide:
- 2-5 - Subtle texture
- 8-12 - Retro gaming aesthetics
- 15-25 - Privacy protection
- 30+ - Abstract art
---
$3
Extract and display dominant colors with detailed analysis.
Usage:
bash
mediaproc image palette [options]
`Options:
-
- Number of colors 1-10 (default: 5)
- -v, --verbose - Show hex codes and RGB values
- --help - Display helpExamples:
`bash
Extract 5 dominant colors
mediaproc image palette photo.jpgGet brand colors
mediaproc image palette logo.png --colors 3 -vFull palette analysis
mediaproc image palette artwork.jpg --colors 10
`Output Includes:
- Dominant colors ranked by prevalence
- RGB and hex values
- Color temperature (warm/cool)
- Brightness analysis
- Saturation levels
- Channel statistics
---
$3
Process multiple images in a directory with any supported operation.
Usage:
bash
mediaproc image batch --operation [options]
`Options:
-
- Operation: resize, convert, optimize, grayscale, etc. (required)
- -o, --output - Output directory (default: ./output)
- -r, --recursive - Process subdirectories
- --width - Width for resize operations
- --height - Height for resize operations
- -f, --format - Output format for convert
- -q, --quality - Quality setting 1-100
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Resize all images
mediaproc image batch ./photos --operation resize --width 1920Convert all to WebP
mediaproc image batch ./images -op convert --format webp -q 90Optimize all recursively
mediaproc image batch ./pics -op optimize -q 85 -o ./optimized -rGenerate thumbnails
mediaproc image batch ./gallery -op thumbnail --width 200
`Supported Operations:
resize, convert, optimize, grayscale, blur, sharpen, thumbnail, sepia, normalize, modulate, rotate, flip
---
$3
Intelligently enhance images with automatic color, contrast, and sharpness adjustments.
Usage:
bash
mediaproc image auto-enhance [options]
`Options:
-
- Enhancement level: low, medium, high (default: medium)
- -o, --output - Output file path
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputEnhancement Levels:
- low - Normalize + Light sharpen (subtle, ~10% improvement)
- medium - Normalize + Color boost + Sharpen (balanced, ~30% improvement)
- high - Normalize + CLAHE + Strong color boost + Heavy sharpen (aggressive, ~50% improvement)
Examples:
`bash
Default enhancement
mediaproc image auto-enhance photo.jpgStrong enhancement for dark images
mediaproc image auto-enhance dark.jpg --level highSubtle enhancement
mediaproc image auto-enhance good-photo.jpg -l low
`What Gets Enhanced:
- ✅ Color normalization and balance
- ✅ Contrast enhancement (CLAHE for high level)
- ✅ Sharpness and clarity
- ✅ Brightness optimization
- ✅ Saturation boost
- ✅ Detail preservation
Best For:
- Quick photo fixes
- Batch photo processing
- Underexposed images
- Low-contrast photos
- Dull/flat images
---
$3
Intelligently enhance images with one command.
Usage:
bash
mediaproc image auto-enhance [options]
`Options:
-
- Enhancement level: low, medium, high (default: medium)
- -o, --output - Output file pathEnhancement Levels:
- low - Normalize + Light sharpen (subtle)
- medium - Normalize + Color boost + Sharpen (recommended)
- high - Normalize + CLAHE + Strong color boost + Heavy sharpen (aggressive)
Examples:
`bash
Default enhancement
mediaproc image auto-enhance photo.jpgStrong enhancement for dark images
mediaproc image auto-enhance dark.jpg --level highSubtle enhancement
mediaproc image auto-enhance good-photo.jpg -l low
`What Gets Enhanced:
- Color normalization
- Sharpness
- Contrast
- Brightness
- Clarity
- Detail preservation
---
$3
Combine multiple images into professional grid/collage layouts with full control over spacing, sizing, and background.
Usage:
bash
mediaproc image grid [options]
`Options:
-
- Number of columns (auto-calculated if not specified)
- -r, --rows - Number of rows (auto-calculated if not specified)
- -w, --width - Width of each cell (default: 300)
- -h, --height - Height of each cell (default: 300)
- -g, --gap - Gap between images in pixels (default: 10)
- -b, --background - Background color (default: white)
- -o, --output - Output file path (default: grid.png)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Auto 2x2 grid
mediaproc image grid img1.jpg img2.jpg img3.jpg img4.jpg3-column layout (auto rows)
mediaproc image grid photos/*.jpg -c 3 -w 400 -h 400Instagram multi-post (3x3 square grid)
mediaproc image grid *.png -c 3 -w 400 -h 400 -g 0 -o instagram.jpgPhoto album with spacing
mediaproc image grid family*.jpg -c 4 -g 20 -b "#f5f5f5"Portfolio grid
mediaproc image grid portfolio/*.jpg -r 2 -c 5 -w 300 -h 300 -g 15
`Auto Layout:
- If no columns/rows specified: Auto-calculates square-ish grid
- If only columns specified: Auto-calculates rows
- If only rows specified: Auto-calculates columns
- 4 images → 2x2, 6 images → 2x3, 9 images → 3x3
Cell Sizing:
- All images resized to cell dimensions
- Uses "cover" fit mode (maintains aspect ratio, crops if needed)
- Images centered in cells
- Quality preserved during resize
Common Grid Sizes:
- 2x2 - Four image collage (1200x1200 typical)
- 3x3 - Instagram multi-post (1200x1200 or 1800x1800)
- 1x3 - Horizontal trio (900x300 typical)
- 3x1 - Vertical trio (300x900 typical)
- 4x4 - Photo album page (1600x1600)
Social Media Presets:
bash
Instagram post (3x3)
grid *.jpg -c 3 -w 400 -h 400 -g 0 -o insta.jpgFacebook cover
grid *.jpg -c 5 -r 2 -w 200 -h 200 -g 10Pinterest board
grid *.jpg -c 4 -w 250 -h 350 -g 15
`Use Cases:
- 📱 Instagram multi-image posts
- 📸 Photo albums and galleries
- 🎨 Portfolio presentations
- 📊 Before/after comparisons
- 🏠 Real estate property showcases
- 👗 Product variation displays
- 🎬 Video thumbnails/previews
- 📚 Magazine-style layouts
Background Colors:
- white - Clean, professional
- black - Dramatic, artistic
- #f5f5f5 - Subtle gray
- transparent - For PNG overlays
- #hex or rgb() - Custom brand colors
Tips:
- Use zero gap (-g 0) for seamless grids
- Larger cells (400-500px) for high quality
- Consistent cell sizes look more professional
- Match background to destination (white for web)
- Use -g 20-30 for print layouts
---
$3
_See command #20 above for full composite documentation_
---
🎯 Command Quick Reference
| Category | Commands | Count |
| ------------- | -------------------------------------------------------------- | ------ |
| Transform | resize, crop, rotate, flip, trim, extend, thumbnail | 7 |
| Color | modulate, gamma, tint, grayscale, negate, normalize | 6 |
| Effects | blur, sharpen, median, sepia, vignette, pixelate | 6 |
| Advanced | composite, extract, border, clahe, convolve, watermark | 6 |
| Smart/AI | smart-crop, auto-enhance, palette, dominant-color, grid, batch | 6 |
| Utility | convert, optimize, stats, split, stack, mirror, metadata | 7 |
| TOTAL | | 40 |
---
Combine multiple images into a grid/collage layout with customizable spacing and background.
Usage:
bash
mediaproc image grid [options]
`Options:
-
- Number of columns (auto-calculated if not specified)
- -r, --rows - Number of rows (auto-calculated if not specified)
- -w, --width - Width of each cell (default: 300)
- -h, --height - Height of each cell (default: 300)
- -g, --gap - Gap between images (default: 10)
- -b, --background - Background color (default: white)
- -o, --output - Output file path (default: grid.png)Examples:
`bash
Create 2x2 grid
mediaproc image grid img1.jpg img2.jpg img3.jpg img4.jpg3-column layout with custom cell size
mediaproc image grid photos/*.jpg -c 3 -w 400 -h 400Instagram post with black background
mediaproc image grid *.png -c 3 -g 20 -b black
`---
$3
Divide large images into smaller tiles, perfect for Instagram carousels or large format printing.
Usage:
bash
mediaproc image split [options]
`Options:
-
- Grid pattern (e.g., "3x3", "1x10")
- -r, --rows - Number of rows
- -c, --columns - Number of columns
- -o, --output - Output directory (default: ./tiles)Examples:
`bash
Split into 3x3 grid
mediaproc image split photo.jpg --tiles 3x3Instagram carousel (10 horizontal slices)
mediaproc image split panorama.jpg -t "1x10"Large poster into 4x4 tiles for printing
mediaproc image split poster.jpg -r 4 -c 4 -o ./poster-tilesVertical split for comparison
mediaproc image split before-after.jpg --tiles "1x2"
`Tile Naming:
- Output files named:
(e.g., tile_0_0.jpg, tile_0_1.jpg)
- Zero-indexed coordinates
- Preserves original formatCommon Patterns:
- 1x10 - Instagram carousel (panorama)
- 2x2 - Four-way comparison
- 3x3 - Nine-tile puzzle
- 4x4 - Large format printing
- 1x2 - Before/after split
Use Cases:
- Instagram carousel posts
- Large format printing on small printers
- Image puzzles
- Tiled backgrounds
- Progressive image loading
---
$3
View, export, or remove image metadata including EXIF, IPTC, and XMP data.
Usage:
`bash
mediaproc image metadata [options]
`Options:
-
- Remove all metadata (create clean copy)
- --export - Export metadata to JSON file
- -o, --output - Output file path (when removing metadata)
- -v, --verbose - Show detailed metadata information
- --help - Display helpExamples:
`bash
View basic metadata
mediaproc image metadata photo.jpgView detailed metadata
mediaproc image metadata photo.jpg -vRemove all metadata for privacy
mediaproc image metadata photo.jpg --removeExport metadata to JSON
mediaproc image metadata photo.jpg --export metadata.jsonClean copy without GPS data
mediaproc image metadata photo.jpg --remove -o clean.jpg
`Metadata Types:
- EXIF - Camera settings, date, GPS location, device info
- IPTC - Copyright, caption, keywords, author
- XMP - Extended metadata, Adobe properties
- ICC - Color profile information
- Orientation - Image rotation data
Information Displayed:
- File size and modified date
- Image dimensions and format
- Color space and channels
- DPI/density settings
- Complete EXIF tags (camera, lens, settings)
- GPS coordinates (if present)
- Copyright and attribution
Why Remove Metadata:
- 🔒 Privacy - Remove GPS location data
- 📉 File Size - Metadata can add 10-50KB
- 🛡️ Security - Remove camera/device info
- 🌐 Web Optimization - Smaller files load faster
- 🤝 Clean Sharing - Remove personal data
File Size Impact:
- Metadata typically: 10-50KB
- GPS data: ~500 bytes
- Thumbnails in EXIF: 5-30KB
- Total savings: 5-15% of file size
---
$3
Stack multiple images horizontally or vertically with alignment and spacing control.
Usage:
bash
mediaproc image stack [options]
`Options:
-
- Stack direction: horizontal, vertical (default: horizontal)
- -a, --align - Alignment: start, center, end (default: center)
- -g, --gap - Gap between images in pixels (default: 0)
- -b, --background - Background color for gaps (default: transparent)
- -o, --output - Output file path (default: stacked.png)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Horizontal before/after comparison
mediaproc image stack before.jpg after.jpgVertical stack with white gaps
mediaproc image stack img1.jpg img2.jpg img3.jpg -d vertical -g 20 -b whiteCreate panorama
mediaproc image stack panorama1.jpg panorama2.jpg panorama3.jpg -d horizontal -o panorama.jpgRight-aligned horizontal stack
mediaproc image stack photo1.jpg photo2.jpg -a endInstagram story sequence
mediaproc image stack story*.jpg -d vertical -g 10 -b black
`Direction & Alignment:
- horizontal + start - Images aligned to top
- horizontal + center - Images centered vertically (default)
- horizontal + end - Images aligned to bottom
- vertical + start - Images aligned to left
- vertical + center - Images centered horizontally (default)
- vertical + end - Images aligned to right
Use Cases:
- Before/after comparisons
- Image sequences and timelines
- Panorama creation
- Portfolio layouts
- Tutorial step-by-step guides
- Product variation displays
- Comparison charts
- Story sequences
Tips:
- Use gaps (10-20px) for visual separation
- Transparent background works best with PNG output
- Horizontal for wide comparisons
- Vertical for tall/portrait layouts
- Center alignment usually looks best
---
$3
Create stunning mirror and kaleidoscope effects by reflecting images in various ways.
Usage:
bash
mediaproc image mirror [options]
`Options:
-
- Mirror mode: horizontal, vertical, both, quad (default: horizontal)
- -o, --output - Output file path (default: -mirror-.ext)
- --dry-run - Preview without executing
- -v, --verbose - Show detailed outputExamples:
`bash
Horizontal mirror (left-right symmetry)
mediaproc image mirror photo.jpgVertical mirror (water reflection)
mediaproc image mirror landscape.jpg --mode verticalBoth axes (4-way symmetry)
mediaproc image mirror portrait.jpg --mode bothKaleidoscope effect (quad mirror)
mediaproc image mirror photo.jpg --mode quad
`Mirror Modes:
- horizontal - Mirror left to right (creates left-right symmetry)
- Output: 2x original width
- Perfect for face symmetry experiments
- vertical - Mirror top to bottom (creates top-bottom symmetry)
- Output: 2x original height
- Perfect for water reflections, sky mirrors
- both - Mirror on both axes (creates 4-way symmetry)
- Output: 2x width × 2x height
- Creates complete symmetry
- quad - Kaleidoscope effect (mirrors center quadrant)
- Output: Original size with center mirrored 4 ways
- Creates mandala-like patterns
Creative Uses:
- 🪞 Water reflections (vertical mode)
- 👤 Symmetrical portraits
- 🎨 Kaleidoscope art (quad mode)
- 🌀 Abstract patterns
- 🦋 Rorschach test style images
- 🏛️ Architectural symmetry
- 🌸 Mandala-like designs
- 🎭 Surreal art effects
Best Practices:
- Works best with asymmetric input images
- Quad mode creates most dramatic effects
- Combine with other effects for unique results
- Try different modes on the same image
---
$3
Quickly extract the most dominant colors from an image for instant palette generation.
Usage:
bash
mediaproc image dominant-color [options]
`Options:
-
- Number of dominant colors to extract (default: 5, max: 10)
- --export - Export color palette to JSON file
- -v, --verbose - Show detailed RGB/HSL values
- --help - Display helpExamples:
`bash
Extract top 5 dominant colors
mediaproc image dominant-color photo.jpgGet top 3 colors
mediaproc image dominant-color logo.png --count 3Export palette to JSON
mediaproc image dominant-color photo.jpg --export palette.jsonDetailed color info
mediaproc image dominant-color artwork.jpg -c 5 -v
`Output Format:
- 🎨 Visual Preview - Colored blocks in terminal
- 🔢 Hex Codes - #RRGGBB format
- 📊 Coverage Percentage - How much of image uses each color
- 🌈 RGB Values - (r, g, b) with -v flag
- 🎨 HSL Values - (hue, saturation, lightness) with -v flag
Color Analysis:
- Colors sorted by dominance (most to least)
- Percentage shows coverage in image
- Bucketed to reduce near-identical colors
- Automatically filters similar shades
Use Cases:
- 🎨 Generate color palettes for design projects
- 🏢 Brand color extraction from logos
- 🌐 Website theme generation
- 📱 App UI color schemes
- 🎬 Video/film color grading reference
- 🖌️ Digital art inspiration
- 👗 Fashion color matching
- 🏠 Interior design palettes
Export JSON Format:
json
{
"source": "photo.jpg",
"imageSize": { "width": 1920, "height": 1080 },
"colors": [
{
"hex": "#3a5f7d",
"rgb": { "r": 58, "g": 95, "b": 125 },
"hsl": { "h": 207, "s": 37, "l": 36 },
"percentage": 23.5
}
]
}
`Tips:
- Use fewer colors (2-3) for minimalist palettes
- 5-7 colors ideal for comprehensive palettes
- Export to JSON for use in design tools
- Smaller images process faster (auto-optimized)
- Works best with high-contrast images
---
$3
Instagram carousel (10 horizontal slices)
mediaproc image split panorama.jpg -t "1x10"
Large poster into 4x4 tiles
mediaproc image split poster.jpg -r 4 -c 4 -o ./poster-tiles
---
$3
View, export to JSON, or remove EXIF/IPTC/XMP metadata from images.
Usage:
bash
mediaproc image metadata [options]
``Options:
-
- Remove all metadata (create clean copy)
- --export - Export metadata to JSON file
- -o, --output - Output file (when removing metadata)
- -v, --verbose - Show detailed metadataExamples:
`bash
View metadata
mediaproc image metadata photo.jpgRemove all metadata for privacy
mediaproc image metadata photo.jpg --removeExport metadata to JSON
mediaproc image metadata photo.jpg --export data.jsonClean copy without GPS data
mediaproc image metadata photo.jpg --remove -o clean.jpg
`---
$3
Stack multiple images horizontally or vertically with customizable alignment and spacing.
Usage:
bash
mediaproc image stack [options]
`Options:
-
- Stack direction: horizontal, vertical (default: horizontal)
- -a, --align - Alignment: start, center, end (default: center)
- -g, --gap - Gap between images (default: 0)
- -b, --background - Background color for gaps (default: transparent)
- -o, --output - Output file pathExamples:
`bash
Horizontal before/after comparison
mediaproc image stack before.jpg after.jpgVertical stack with white gaps
mediaproc image stack img1.jpg img2.jpg img3.jpg -d vertical -g 20 -b whiteCreate panorama
mediaproc image stack panorama*.jpg -d horizontal -o panorama.jpg
`---
$3
Create mirror and kaleidoscope effects by reflecting images horizontally, vertically, or in quadrants.
Usage:
bash
mediaproc image mirror [options]
`Options:
-
- Mirror mode: horizontal, vertical, both, quad (default: horizontal)
- -o, --output - Output file pathExamples:
`bash
Horizontal mirror (left-right symmetry)
mediaproc image mirror photo.jpgVertical mirror (water reflection)
mediaproc image mirror landscape.jpg --mode verticalKaleidoscope effect
mediaproc image mirror photo.jpg --mode quad
`---
$3
Quickly extract the most dominant colors from an image for palette generation.
Usage:
bash
mediaproc image dominant-color [options]
`Options:
-
- Number of colors to extract (default: 5, max: 10)
- --export - Export color palette to JSON file
- -v, --verbose - Show detailed RGB/HSL valuesExamples:
`bash
Extract top 5 colors
mediaproc image dominant-color photo.jpgGet top 3 colors
mediaproc image dominant-color logo.png --count 3Export to JSON for design tools
mediaproc image dominant-color photo.jpg --export palette.json
`---
� Real-World Workflows
$3
bash
1. Resize for responsive web
mediaproc image resize photo.jpg -w 1920 --fit inside -o web-large.jpg2. Optimize with quality 85
mediaproc image optimize web-large.jpg -q 853. Convert to modern WebP format
mediaproc image convert web-large-optimized.jpg -f webp -q 854. Generate thumbnail
mediaproc image thumbnail web-large.jpg -s 300 -o thumb.jpgResult: web-large-optimized.webp (smallest), thumb.jpg (preview)
``