Watermark

Option	Alias	Type	Default	Description
`--position <position>`		string	`bottom-right`	Position: center, top-left, top-right, bottom-left, bottom-right
`--opacity <opacity>`		number	`0.5`	Watermark opacity (0-1)
`--scale <scale>`		number	`0.2`	Watermark scale (0.1-1, relative to image width)
`--output <path>`	`-o`	string	-	Output file path (default: `<input>-watermarked.<ext>`)
`--quality <quality>`	`-q`	number	`90`	Output quality (1-100)
`--dry-run`		boolean	`false`	Preview without making changes
`--verbose`	`-v`	boolean	`false`	Show detailed output
`--help`		boolean	`false`	Display help information

Positions

Position	Description	Best For
center	Middle of image	Logos, stamps
top-left	Upper left corner	Credit attribution
top-right	Upper right corner	Brand logos
bottom-left	Lower left corner	Alternative copyright
bottom-right	Lower right corner (default)	Copyright marks

Position Visual Guide

┌─────────────────────┐
│ top-left  top-right │
│                     │
│      center         │
│                     │
│ bottom-left  bottom-│
│              right  │
└─────────────────────┘

Opacity Guide

Opacity	Effect	Use Case
0.1-0.3	Very subtle	Barely visible, non-intrusive
0.4-0.5	Balanced	Recommended, visible but not dominant
0.6-0.7	Clearly visible	Strong protection
0.8-0.9	Very visible	Maximum visibility
1.0	Fully opaque	No transparency

Opacity Behavior

Lower opacity (0.1-0.4):

Subtle presence
Doesn't distract from image
Best for: Professional photography, portfolios

Middle opacity (0.5-0.7):

Balanced visibility
Clear protection
Best for: General use, social media

Higher opacity (0.8-1.0):

Very obvious
Maximum protection
Best for: Preview images, strong branding

Scale Guide

Scale	Size	Use Case
0.1	10% of width	Small, discrete marks
0.15	15% of width	Moderate logos
0.2	20% of width (default)	Standard size
0.3	30% of width	Larger branding
0.5	50% of width	Very large, central marks
1.0	Full width	Maximum coverage

Examples

1. Default Watermark

Standard bottom-right placement:

mediaproc image watermark photo.jpg logo.png

Copyright: Standard copyright mark

2. Center Logo

Brand logo in center:

mediaproc image watermark image.jpg brand.png --position center --opacity 0.3

Branding: Central brand presence

3. Subtle Watermark

Barely visible protection:

mediaproc image watermark photo.png mark.png --opacity 0.25 --scale 0.15

Discrete: Non-intrusive protection

4. Top-Right Brand

Brand in corner:

mediaproc image watermark pic.jpg logo.png --position top-right --scale 0.25

Branding: Corner brand mark

5. Strong Copyright

Visible copyright mark:

mediaproc image watermark photo.jpg copyright.png --opacity 0.7 --position bottom-right

Protection: Clear ownership

6. Large Center Mark

Dominant watermark:

mediaproc image watermark preview.jpg watermark.png --position center --scale 0.5 --opacity 0.6

Preview: Prevent unauthorized use

7. Batch Watermarking

Watermark collection:

mediaproc image watermark "portfolio/*.jpg" logo.png --opacity 0.4 --position bottom-right

Portfolio: Consistent protection

8. Top-Left Credit

Attribution in corner:

mediaproc image watermark image.jpg credit.png --position top-left --opacity 0.5 --scale 0.2

Attribution: Photo credit

9. Small Discrete Mark

Tiny watermark:

mediaproc image watermark photo.jpg tiny-mark.png --scale 0.1 --opacity 0.3

Discrete: Minimal visual impact

10. Full-Width Watermark

Maximum coverage:

mediaproc image watermark preview.jpg watermark.png --scale 0.8 --position center --opacity 0.4

Security: Maximum protection

11. Professional Portfolio

Subtle professional mark:

mediaproc image watermark portfolio.jpg signature.png --position bottom-right --opacity 0.35 --scale 0.18

Professional: Elegant protection

Social media watermark:

mediaproc image watermark social.jpg brand.png --position bottom-left --opacity 0.5 --scale 0.22

Social: Platform protection

13. Verbose Watermarking

See processing details:

mediaproc image watermark photo.jpg logo.png --verbose

Info: Configuration details

14. Preview Watermark

Check before processing:

mediaproc image watermark image.jpg mark.png --dry-run

Safety: Verify settings

15. High Quality Output

Maximum quality watermark:

mediaproc image watermark photo.jpg logo.png -q 95 -o final.jpg

Quality: Preserve image quality

Use Cases

1. Copyright Protection

Protect your photography:

# Copyright mark
mediaproc image watermark "photos/*.jpg" copyright.png --position bottom-right --opacity 0.5

# Clear ownership

Protection: Prevent unauthorized use

2. Brand Identity

Add brand logos:

# Company logo
mediaproc image watermark product.jpg logo.png --position top-right --scale 0.25 --opacity 0.6

# Consistent branding

Branding: Brand presence

3. Photo Attribution

Credit photographers:

# Photo credit
mediaproc image watermark image.jpg credit.png --position bottom-left --opacity 0.4

# Attribution visible

Attribution: Proper credit

Protect social content:

# Instagram/Facebook
mediaproc image watermark post.jpg handle.png --position bottom-right --opacity 0.5 --scale 0.2

# Account watermark

Social Media: Content protection

5. Portfolio Images

Professional portfolio marks:

# Portfolio watermark
mediaproc image watermark "portfolio/*.jpg" signature.png --opacity 0.35 --scale 0.18

# Elegant protection

Portfolio: Professional presentation

6. Preview Images

Prevent misuse of previews:

# Preview watermark
mediaproc image watermark preview.jpg "PREVIEW".png --position center --scale 0.6 --opacity 0.5

# Strong deterrent

Previews: Discourage theft

7. Stock Photography

Stock image watermarks:

# Stock watermark
mediaproc image watermark stock.jpg watermark.png --position center --scale 0.4 --opacity 0.4

# Clear stock marking

Stock: Identify unpurchased images

8. Event Photography

Event watermarks:

# Event photos
mediaproc image watermark "event/*.jpg" studio-logo.png --position bottom-right --opacity 0.5

# Studio branding

Events: Studio identification

9. Product Photography

E-commerce watermarks:

# Product protection
mediaproc image watermark product.jpg store-logo.png --position top-left --opacity 0.4 --scale 0.15

# Store branding

E-commerce: Product protection

10. Real Estate

Property photo watermarks:

# Listing photos
mediaproc image watermark "property/*.jpg" agency-logo.png --position bottom-right --opacity 0.5

# Agency branding

Real Estate: Agency protection

Combining with Other Commands

Resize + Watermark

Size then watermark:

# Resize for web
mediaproc image resize large.jpg -w 1920 -o web.jpg

# Add watermark
mediaproc image watermark web.jpg logo.png --opacity 0.4

Workflow: Optimized watermarking

Watermark + Border

Watermark with frame:

# Add watermark
mediaproc image watermark photo.jpg logo.png -o marked.jpg

# Add border
mediaproc image border marked.jpg --width 20 --color white

Presentation: Framed and protected

Batch Process + Watermark

Enhance then watermark:

# Enhance images
mediaproc image auto-enhance "photos/*.jpg"

# Watermark enhanced
mediaproc image watermark "*-enhanced.jpg" logo.png

Pipeline: Enhanced and protected

Watermark + Optimize

Watermark then compress:

# Add watermark
mediaproc image watermark photo.jpg logo.png -o watermarked.jpg

# Optimize file size
mediaproc image optimize watermarked.jpg -q 85

Efficiency: Protected and optimized

Technical Details

Watermark Process

Steps:

Load base image and watermark
Calculate target watermark width (image_width × scale)
Resize watermark to target size
Apply opacity to watermark
Position watermark using gravity
Composite watermark onto base image
Output watermarked image

Positioning (Gravity)

Sharp Gravity Values:

center - Middle of image
northwest - Top-left
northeast - Top-right
southwest - Bottom-left
southeast - Bottom-right (default)

Opacity Application

Method: Alpha channel manipulation

new_alpha = original_alpha × opacity

Example:

Watermark PNG with alpha
Opacity 0.5
Result: 50% of original alpha

Scale Calculation

Formula:

watermark_width = base_image_width × scale
watermark_height = scaled proportionally

Example:

Image: 2000px wide
Scale: 0.2
Watermark: 400px wide

Performance

Small watermarks: ~150-250ms per image
Large watermarks: ~200-350ms
Batch processing: ~200ms average per image
Includes watermark resize + composite

Format Support

Watermark Formats:

PNG: Best (transparency support)
WebP: Good (smaller, transparent)
JPEG: Works (no transparency)

Base Image Formats:

All standard formats supported
Output format from input or specified

Best Practices

1. Use PNG Watermarks

PNG supports transparency:

# PNG watermark best
mediaproc image watermark photo.jpg logo.png

2. Balance Opacity

50% usually optimal:

# Balanced visibility
mediaproc image watermark photo.jpg logo.png --opacity 0.5

3. Appropriate Scale

20% standard for logos:

# Standard logo size
mediaproc image watermark photo.jpg logo.png --scale 0.2

4. Bottom-Right for Copyright

Standard copyright position:

# Copyright standard
mediaproc image watermark photo.jpg © logo.png --position bottom-right

5. Center for Prevention

Strong protection in center:

# Prevent misuse
mediaproc image watermark preview.jpg mark.png --position center --scale 0.4

6. Batch with Consistency

Same settings for collections:

# Consistent watermarking
mediaproc image watermark "collection/*.jpg" logo.png --opacity 0.4 --position bottom-right

7. Test on Sample

Try different settings:

# Test variations
mediaproc image watermark test.jpg logo.png --opacity 0.3 -o test-30.jpg
mediaproc image watermark test.jpg logo.png --opacity 0.5 -o test-50.jpg
mediaproc image watermark test.jpg logo.png --opacity 0.7 -o test-70.jpg

Troubleshooting

Issue: Watermark Too Visible

Problem: Watermark too obvious

Cause: Opacity too high

Solution: Lower opacity

# More subtle
mediaproc image watermark photo.jpg logo.png --opacity 0.3

Issue: Watermark Not Visible

Problem: Can't see watermark

Cause: Opacity too low or watermark color blends

Solution: Increase opacity or use contrasting watermark

# More visible
mediaproc image watermark photo.jpg logo.png --opacity 0.7

Issue: Watermark Too Large

Problem: Watermark covers too much

Cause: Scale too high

Solution: Reduce scale

# Smaller watermark
mediaproc image watermark photo.jpg logo.png --scale 0.15

Issue: Watermark Too Small

Problem: Watermark tiny or unreadable

Cause: Scale too low

Solution: Increase scale

# Larger watermark
mediaproc image watermark photo.jpg logo.png --scale 0.3

Issue: Watermark Quality Loss

Problem: Watermark looks pixelated

Cause: Watermark source too small

Solution: Use higher resolution watermark

# Use large source watermark PNG
# Will be scaled down with good quality

Issue: Watermark Not Transparent

Problem: White/colored box around watermark

Cause: Watermark not PNG or no transparency

Solution: Use PNG watermark with transparency

# Convert watermark to PNG with transparency first

Issue: Wrong Position

Problem: Watermark in unexpected location

Cause: Wrong position value

Solution: Verify position spelling

# Valid positions:
# center, top-left, top-right, bottom-left, bottom-right
mediaproc image watermark photo.jpg logo.png --position bottom-right

composite - Advanced image layering
resize - Resize before watermarking
border - Add borders with watermark
optimize - Optimize after watermarking