Modulate

Adjust brightness, saturation, and hue of images in a single operation. Modulate provides fine-grained control over image appearance, allowing you to brighten/darken, enhance/reduce color intensity, and shift colors for creative effects.

Installation

Usage

Basic Usage

Options

Understanding Parameters

Brightness Multiplier

The brightness value is a multiplier applied to pixel lightness:

• < 1.0: Darker (0.5 = 50% brightness)
• = 1.0: No change (default)
• > 1.0: Brighter (1.5 = 150% brightness)

Formula: output_brightness = input_brightness × multiplier

Saturation Multiplier

The saturation value controls color intensity:

• = 0.0: Completely desaturated (grayscale)
• < 1.0: Muted colors (0.5 = half saturation)
• = 1.0: No change (default)
• > 1.0: More vibrant (1.5 = 50% more saturated)

Formula: output_saturation = input_saturation × multiplier

Hue Rotation

The hue value rotates colors around the color wheel:

• 0°: No change (default)
• 30°: Subtle color shift
• 90°: Quarter rotation (blue → magenta)
• 180°: Opposite colors (blue → yellow)
• 360°: Full circle (back to original)

Formula: output_hue = (input_hue + rotation) % 360

Examples

1. Basic Brightness Adjustment

Make image 20% brighter:

mediaproc image modulate photo.jpg -b 1.2

Effect: All pixels become lighter while maintaining color relationships.

2. Darken Image

Reduce brightness by 30%:

mediaproc image modulate bright-photo.jpg -b 0.7

Result: Outputs bright-photo-modulated.jpg that is darker and more dramatic.

3. Boost Saturation

Make colors 50% more vibrant:

mediaproc image modulate dull-photo.png -s 1.5

Effect: Colors become more vivid and eye-catching without changing brightness.

4. Mute Colors

Reduce saturation by 50% for subtle, muted look:

mediaproc image modulate vibrant-photo.jpg -s 0.5

Style: Creates pastel, vintage, or minimalist aesthetic.

5. Create Grayscale Effect

Remove all color saturation:

mediaproc image modulate color-photo.jpg -s 0

Alternative: Using modulate for grayscale allows combining with brightness/hue adjustments.

6. Rotate Hue 180°

Create color-inverted effect:

mediaproc image modulate landscape.jpg --hue 180

Result: Blue sky becomes yellow, green grass becomes magenta - creative artistic effect.

7. Subtle Hue Shift

Shift colors slightly for mood:

mediaproc image modulate photo.jpg --hue 30

Effect: Adds warm or cool tone depending on original colors.

8. Combined Adjustments

Brighten and enhance colors simultaneously:

mediaproc image modulate underexposed.jpg -b 1.3 -s 1.4

Benefit: Single operation performs multiple adjustments efficiently.

9. Dark and Saturated

Create moody, high-contrast look:

mediaproc image modulate photo.jpg -b 0.8 -s 1.5

Style: Popular for portrait and product photography.

10. Bright and Muted

Create light, airy aesthetic:

mediaproc image modulate image.jpg -b 1.3 -s 0.7

Look: Soft, dreamy, high-key photography style.

11. All Three Parameters

Maximum creative control:

mediaproc image modulate photo.jpg -b 1.2 -s 1.3 --hue 30 -o stylized.jpg

Effect: Comprehensive color grading in one command.

12. Batch Color Correction

Apply consistent adjustments to multiple images:

mediaproc image modulate "photos/*.jpg" -b 1.15 -s 1.2

Use Case: Consistent look across photo series or product images.

13. Extreme Brightness

Create high-key look:

mediaproc image modulate photo.jpg -b 2.0

Effect: Very bright, washed-out aesthetic with maximum lightness.

14. Extreme Darkness

Create low-key, dramatic effect:

mediaproc image modulate photo.jpg -b 0.3

Result: Very dark with only highlights visible.

15. Custom Output Location

Specify exact output path:

mediaproc image modulate input.jpg -b 1.2 -s 1.3 -o output/enhanced.jpg -q 95

Control: Full control over output location and quality.

Brightness Guide

Common Values

# Much darker (50% brightness)
mediaproc image modulate photo.jpg -b 0.5

# Slightly darker
mediaproc image modulate photo.jpg -b 0.8

# No change (default)
mediaproc image modulate photo.jpg -b 1.0

# Slightly brighter
mediaproc image modulate photo.jpg -b 1.2

# Much brighter (150%)
mediaproc image modulate photo.jpg -b 1.5

# Double brightness
mediaproc image modulate photo.jpg -b 2.0

Visual Effects

• 0.3-0.5: Very dark, low-key, dramatic
• 0.6-0.8: Darker, moody, cinematic
• 0.9-1.1: Subtle adjustment
• 1.2-1.5: Brighter, cheerful, airy
• 1.6-2.0: Very bright, high-key, ethereal

Saturation Guide

Common Values

# Completely desaturated (grayscale)
mediaproc image modulate photo.jpg -s 0

# Half saturation (muted)
mediaproc image modulate photo.jpg -s 0.5

# Subtle reduction
mediaproc image modulate photo.jpg -s 0.8

# No change (default)
mediaproc image modulate photo.jpg -s 1.0

# 50% more vibrant
mediaproc image modulate photo.jpg -s 1.5

# Double saturation (very vivid)
mediaproc image modulate photo.jpg -s 2.0

Visual Effects

• 0.0: Complete grayscale
• 0.3-0.5: Desaturated, vintage, muted
• 0.6-0.8: Slightly muted, elegant
• 0.9-1.1: Subtle adjustment
• 1.2-1.6: Enhanced, vivid, vibrant
• 1.7-2.0: Very intense, pop art style

Hue Rotation Effects

Rotation Guide

# No change
mediaproc image modulate photo.jpg --hue 0

# Subtle warm shift
mediaproc image modulate photo.jpg --hue 30

# Noticeable shift
mediaproc image modulate photo.jpg --hue 60

# Quarter rotation (blue → magenta)
mediaproc image modulate photo.jpg --hue 90

# Opposite colors (blue → yellow)
mediaproc image modulate photo.jpg --hue 180

# Three-quarter rotation
mediaproc image modulate photo.jpg --hue 270

# Full circle (back to original)
mediaproc image modulate photo.jpg --hue 360

Color Wheel Transformations

• 0°: Original colors
• 30°: Slight warm/cool shift
• 60°: Moderate shift (red → orange, blue → cyan)
• 90°: Quarter wheel (red → yellow, blue → magenta)
• 120°: Major shift (red → green, blue → red)
• 180°: Complementary colors (red → cyan, yellow → blue)
• 240°: Inverse shift (red → magenta, green → blue)
• 360°/-0°: Back to original

Negative Rotations

# Rotate backwards 30°
mediaproc image modulate photo.jpg --hue -30

# Rotate backwards 90°
mediaproc image modulate photo.jpg --hue -90

# Rotate backwards 180° (same as forward 180°)
mediaproc image modulate photo.jpg --hue -180

Use Cases

1. Exposure Correction

Fix underexposed photos:

mediaproc image modulate underexposed.jpg -b 1.4

Benefit: Quick brightness correction without complex curves.

2. Color Grading

Apply consistent color style:

mediaproc image modulate "photos/*.jpg" -b 1.1 -s 1.3 --hue 15

Professional: Create signature look across portfolio.

3. Product Photography

Enhance product appeal:

mediaproc image modulate product.jpg -b 1.15 -s 1.4

Marketing: Make products look brighter and more colorful.

4. Vintage Effect

Create retro, faded look:

mediaproc image modulate modern-photo.jpg -b 1.1 -s 0.6

Style: Instagram-style vintage filter.

5. Cinematic Look

Create movie-like color grading:

mediaproc image modulate footage.jpg -b 0.9 -s 1.2 --hue 10

Atmosphere: Moody, professional film appearance.

6. High-Key Photography

Create bright, minimalist look:

mediaproc image modulate portrait.jpg -b 1.5 -s 0.8

Fashion: Popular in fashion and beauty photography.

7. Low-Key Photography

Create dark, dramatic effect:

mediaproc image modulate portrait.jpg -b 0.6 -s 1.3

Drama: Emphasizes shadows and contrast.

8. Landscape Enhancement

Boost nature colors:

mediaproc image modulate landscape.jpg -b 1.1 -s 1.5 --hue -5

Nature: Makes skies bluer, grass greener.

9. Portrait Warmth

Add warm, flattering tones:

mediaproc image modulate portrait.jpg -b 1.1 -s 1.2 --hue 20

Skin Tones: Creates warm, inviting feeling.

10. Creative Color Shifts

Artistic recoloring:

mediaproc image modulate photo.jpg --hue 180 -s 1.5

Art: Surreal, psychedelic effects.

Common Combinations

Natural Enhancement

Subtle, realistic improvements:

mediaproc image modulate photo.jpg -b 1.1 -s 1.2

Use: Everyday photo enhancement.

Instagram-Style

Popular social media look:

mediaproc image modulate photo.jpg -b 1.2 -s 0.7 --hue 25

Trend: Warm, faded aesthetic.

Professional Product

E-commerce ready:

mediaproc image modulate product.jpg -b 1.15 -s 1.4 -q 95

Commercial: Bright, appealing, accurate.

Moody Portrait

Dramatic, artistic:

mediaproc image modulate portrait.jpg -b 0.85 -s 1.3 --hue -10

Style: Editorial, fashion photography.

Summer Vibes

Bright and warm:

mediaproc image modulate photo.jpg -b 1.3 -s 1.4 --hue 30

Mood: Cheerful, energetic, tropical.

Winter Tones

Cool and muted:

mediaproc image modulate photo.jpg -b 1.1 -s 0.9 --hue -20

Atmosphere: Cold, crisp, nordic.

Advanced Techniques

Incremental Adjustments

Make small, controlled changes:

# Step 1: Brightness
mediaproc image modulate photo.jpg -b 1.1 -o step1.jpg

# Step 2: Saturation
mediaproc image modulate step1.jpg -s 1.2 -o step2.jpg

# Step 3: Hue
mediaproc image modulate step2.jpg --hue 15 -o final.jpg

Control: Fine-tune each parameter separately.

A/B Testing

Compare different settings:

# Version A
mediaproc image modulate photo.jpg -b 1.2 -s 1.3 -o version-a.jpg

# Version B
mediaproc image modulate photo.jpg -b 1.1 -s 1.5 -o version-b.jpg

Decision: Choose best result by comparison.

Batch Consistency

Apply same adjustments to series:

mediaproc image modulate "series/*.jpg" -b 1.15 -s 1.25 --hue 10

Professional: Consistent look across photo sets.

Performance Considerations

Processing Speed

Modulate is very fast:

• Typical image (under 5MP): ~50-100ms
• Large image (greater than 10MP): ~100-200ms
• Batch processing: ~100-150ms per image

Memory Usage

Minimal memory overhead:

• Small images: under 50MB
• Large images: under 200MB
• Multiple parameters: No additional memory

Quality Impact

• Brightness: No quality loss
• Saturation: No quality loss
• Hue: No quality loss
• Operations are lossless until final output encoding

Combining with Other Commands

Modulate + Contrast

Color adjustment followed by contrast:

# Adjust colors
mediaproc image modulate photo.jpg -b 1.2 -s 1.3 -o adjusted.jpg

# Increase contrast
mediaproc image linear adjusted.jpg -a 1.2

Enhancement: Better color and tonal range.

Modulate + Sharpen

Color then detail enhancement:

mediaproc image modulate photo.jpg -b 1.1 -s 1.2 -o colored.jpg
mediaproc image sharpen colored.jpg

Professional: Complete photo enhancement.

Auto-Enhance + Modulate

Automatic then manual adjustments:

# Auto adjust
mediaproc image auto-enhance photo.jpg -o auto.jpg

# Fine-tune
mediaproc image modulate auto.jpg -s 1.2 --hue 10

Workflow: Quick base + manual creative control.

Modulate + Vignette

Color grading with vignette:

mediaproc image modulate photo.jpg -b 1.1 -s 1.3 -o graded.jpg
mediaproc image vignette graded.jpg

Cinematic: Professional film look.

Troubleshooting

Issue: Colors Look Unnatural

Problem: Excessive saturation or hue shift

Solution: Use more subtle values:

# Instead of
mediaproc image modulate photo.jpg -s 2.0 --hue 90

# Try
mediaproc image modulate photo.jpg -s 1.2 --hue 15

Issue: Image Too Dark/Bright

Problem: Extreme brightness values

Solution: Stay within reasonable range:

# Avoid extremes
mediaproc image modulate photo.jpg -b 0.5  # Too dark
mediaproc image modulate photo.jpg -b 2.5  # Too bright

# Use moderate values
mediaproc image modulate photo.jpg -b 0.8  # Darker
mediaproc image modulate photo.jpg -b 1.3  # Brighter

Issue: Lost Detail in Shadows/Highlights

Problem: Brightness pushed too far

Solution: Combine with other adjustments:

# Instead of just brightness
mediaproc image modulate dark-photo.jpg -b 1.8

# Use moderate brightness + other tools
mediaproc image modulate dark-photo.jpg -b 1.3 -o step1.jpg
mediaproc image normalize step1.jpg

Issue: Color Casts

Problem: Unwanted color tints after hue rotation

Solution: Fine-tune hue rotation:

# Adjust rotation incrementally
mediaproc image modulate photo.jpg --hue 10 -o test1.jpg
mediaproc image modulate photo.jpg --hue 20 -o test2.jpg
# Compare and choose best

Issue: Inconsistent Batch Results

Problem: Different images need different adjustments

Solution: Group by similarity:

# Bright images
mediaproc image modulate "bright/*.jpg" -b 0.9 -s 1.2

# Dark images
mediaproc image modulate "dark/*.jpg" -b 1.3 -s 1.1

Best Practices

1. Start with Small Adjustments

Begin with subtle changes:

mediaproc image modulate photo.jpg -b 1.1 -s 1.1 --dry-run

Gradually increase if needed.

2. Use Dry Run for Testing

Preview before processing:

mediaproc image modulate photo.jpg -b 1.3 -s 1.5 --dry-run

Verify settings and output path.

3. Maintain Realism

Keep adjustments natural (unless creating artistic effects):

• Brightness: 0.7-1.3 range
• Saturation: 0.8-1.5 range
• Hue: ±30° for subtle effects

4. Document Settings

Record successful combinations:

# Portraits: warm and bright
mediaproc image modulate portraits/*.jpg -b 1.15 -s 1.2 --hue 20

# Landscapes: vivid colors
mediaproc image modulate landscapes/*.jpg -b 1.1 -s 1.4 --hue -5

5. Consider Original Quality

Higher quality inputs allow more aggressive adjustments:

# RAW/high-quality
mediaproc image modulate high-quality.jpg -b 1.3 -s 1.5

# Compressed/low-quality
mediaproc image modulate compressed.jpg -b 1.1 -s 1.2

6. Test on Representative Samples

Before batch processing:

# Test on one image
mediaproc image modulate sample.jpg -b 1.2 -s 1.3

# If good, apply to all
mediaproc image modulate "all/*.jpg" -b 1.2 -s 1.3

7. Save High Quality

Preserve quality for important work:

mediaproc image modulate photo.jpg -b 1.2 -s 1.3 -q 95

Related Commands

• linear - Precise brightness/contrast with mathematical control
• auto-enhance - Automatic brightness and color adjustments
• normalize - Automatic brightness normalization
• grayscale - Remove all color (saturation to zero)
• sepia - Apply sepia tone color effect

Further Reading

• HSL Color Space
• Color Grading Techniques
• Brightness in Photography