babayaga b5a9c2dbea pm-media:background/watermark

2025-08-10 12:13:29 +02:00

10 KiB

Raw Blame History

Watermark CLI Documentation

The pm-media watermark command allows you to add watermarks to images using either text or image overlays. This tool supports batch processing and offers extensive customization options for positioning, styling, and opacity.

Installation
Basic Usage
Text Watermarks
Image Watermarks
Command Line Options
API Usage
Examples
Troubleshooting

Installation

npm install @polymech/media

Basic Usage

pm-media watermark --src <input> --dst <output> --watermarkType <type> [options]

Required Parameters

--src: Source files (FILE|FOLDER|GLOB pattern)
--watermarkType: Type of watermark (text or image)

Conditional Requirements

For text watermarks: --text is required
For image watermarks: --logoPath is required

Text Watermarks

Add text overlays to your images with full typography control.

Basic Text Watermark

pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType text \
  --text "© 2024 MyBrand"

Advanced Text Styling

pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType text \
  --text "© 2024 MyBrand" \
  --position bottom-right \
  --fontSize 42 \
  --color "#ffffff" \
  --fontFamily "Arial" \
  --strokeColor "#000000" \
  --strokeWidth 3 \
  --opacity 0.9 \
  --margin 30

Text Watermark Options

Option	Type	Default	Description
`--text`	string	required	Text to display as watermark
`--fontSize`	number	48	Font size in pixels
`--color`	string	"#ffffff"	Text color (hex format)
`--fontFamily`	string	"Arial"	Font family name
`--strokeColor`	string	"#000000"	Text outline color (hex format)
`--strokeWidth`	number	2	Text outline width in pixels

Image Watermarks

Add logo or image overlays with automatic scaling and positioning.

Basic Image Watermark

pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType image \
  --logoPath "logo.png"

Advanced Image Positioning

pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType image \
  --logoPath "watermark.png" \
  --position top-left \
  --sizePct 0.15 \
  --opacity 0.7 \
  --margin 20

Image Watermark Options

Option	Type	Default	Description
`--logoPath`	string	required	Path to logo/watermark image file
`--sizePct`	number	0.2	Size as percentage of base image width (0-1)

Command Line Options

Common Options

Option	Type	Default	Description
`--src`	string	required	Source files (FILE\|FOLDER\|GLOB)
`--dst`	string	-	Destination path
`--watermarkType`	choice	required	"text" or "image"
`--position`	choice	"bottom-right"	Watermark position
`--margin`	number	24	Margin from edges in pixels
`--opacity`	number	0.85	Opacity level (0-1)

Position Options

top-left: Upper left corner
top-right: Upper right corner
bottom-left: Lower left corner
bottom-right: Lower right corner (default)
center: Center of image

Utility Options

Option	Type	Default	Description
`--dry`	boolean	false	Preview mode (no files written)
`--verbose`	boolean	false	Show detailed processing info
`--debug`	boolean	false	Enable debug messages
`--logLevel`	string	"info"	Log level (warn\|info\|debug\|error)

API Usage

Import the Library

import { 
  watermark, 
  addTextWatermark, 
  addLogoWatermark,
  WatermarkOptions,
  TextWatermarkOptions,
  LogoWatermarkOptions 
} from '@polymech/media';

Text Watermark API

import { addTextWatermark } from '@polymech/media';

await addTextWatermark(
  'input.jpg',
  '© 2024 MyBrand',
  'output.jpg',
  {
    position: 'bottom-right',
    fontSize: 48,
    color: '#ffffff',
    opacity: 0.9,
    margin: 24,
    fontFamily: 'Arial',
    strokeColor: '#000000',
    strokeWidth: 2
  }
);

Image Watermark API

import { addLogoWatermark } from '@polymech/media';

await addLogoWatermark(
  'input.jpg',
  'logo.png',
  'output.jpg',
  {
    position: 'bottom-right',
    sizePct: 0.2,
    opacity: 0.85,
    margin: 24,
    blend: 'over'
  }
);

Batch Processing API

import { watermark } from '@polymech/media';

const options: WatermarkOptions = {
  src: 'photos/*.jpg',
  dst: 'output/',
  watermarkType: 'text',
  text: '© 2024 MyBrand',
  textOptions: {
    position: 'bottom-right',
    fontSize: 48,
    color: '#ffffff',
    opacity: 0.9
  },
  // ... other IOptions
};

await watermark(options);

Examples

Example 1: Brand Photos with Logo

# Add company logo to product photos
pm-media watermark \
  --src "products/*.jpg" \
  --dst "branded/" \
  --watermarkType image \
  --logoPath "brand-logo.png" \
  --position bottom-right \
  --sizePct 0.12 \
  --opacity 0.8 \
  --margin 30

Example 2: Copyright Text on Multiple Formats

# Add copyright to various image formats
pm-media watermark \
  --src "gallery/*.{jpg,png,webp}" \
  --dst "copyrighted/" \
  --watermarkType text \
  --text "© 2024 Photography Studio" \
  --position bottom-left \
  --fontSize 28 \
  --color "#ffffff" \
  --strokeColor "#000000" \
  --strokeWidth 1 \
  --opacity 0.85

Example 3: Centered Watermark

# Large central watermark for draft images
pm-media watermark \
  --src "drafts/*.jpg" \
  --dst "review/" \
  --watermarkType text \
  --text "DRAFT - NOT FOR PUBLICATION" \
  --position center \
  --fontSize 72 \
  --color "#ff0000" \
  --opacity 0.3

Example 4: Batch Processing with Dry Run

# Preview changes before applying
pm-media watermark \
  --src "archive/**/*.jpg" \
  --dst "processed/" \
  --watermarkType image \
  --logoPath "watermark.png" \
  --dry \
  --verbose

Example 5: Custom Logo Positioning

# Small logo in top-right corner
pm-media watermark \
  --src "social-media/*.png" \
  --dst "branded/" \
  --watermarkType image \
  --logoPath "social-logo.png" \
  --position top-right \
  --sizePct 0.08 \
  --margin 15 \
  --opacity 0.9

File Format Support

Supported Input Formats

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
TIFF (.tiff, .tif)

Supported Output Formats

Output format is automatically determined by the destination file extension or input format.

Performance Tips

Batch Processing: Process multiple files in one command for better performance
Concurrency: The tool processes files with controlled concurrency (default: 1)
Logo Optimization: Use PNG logos with transparency for best results
Size Optimization: Keep logo files reasonably sized to improve processing speed

Troubleshooting

Common Issues

"Logo file not found"

# Ensure the logo path is correct and file exists
ls -la path/to/logo.png

"Unable to open for write"

# Ensure output directory exists
mkdir -p output/directory

Text appears blurry

Increase --fontSize for better clarity
Adjust --strokeWidth for better contrast
Use appropriate --color contrast against background

Logo appears too large/small

Adjust --sizePct (0.1 = 10% of image width)
Consider image dimensions when setting size

Debug Mode

Enable detailed logging to troubleshoot issues:

pm-media watermark \
  --src "input/*" \
  --dst "output/" \
  --watermarkType text \
  --text "Debug Test" \
  --debug \
  --verbose

File Permissions

Ensure you have:

Read access to source files
Write access to destination directory
Execute permissions on the tool

Advanced Usage

Using Environment Variables

export WATERMARK_TEXT="© 2024 MyCompany"
export WATERMARK_LOGO="./assets/logo.png"

pm-media watermark \
  --src "batch/*.jpg" \
  --dst "output/" \
  --watermarkType text \
  --text "$WATERMARK_TEXT"

Integration with Scripts

#!/bin/bash
# Automated watermarking script

INPUT_DIR="$1"
OUTPUT_DIR="$2"
WATERMARK_TYPE="$3"

if [ "$WATERMARK_TYPE" = "logo" ]; then
  pm-media watermark \
    --src "$INPUT_DIR/*.jpg" \
    --dst "$OUTPUT_DIR/" \
    --watermarkType image \
    --logoPath "./branding/logo.png" \
    --position bottom-right
else
  pm-media watermark \
    --src "$INPUT_DIR/*.jpg" \
    --dst "$OUTPUT_DIR/" \
    --watermarkType text \
    --text "© $(date +%Y) MyBrand" \
    --position bottom-right
fi

TypeScript Definitions

type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center";

interface LogoWatermarkOptions {
  position?: Corner;
  margin?: number;
  sizePct?: number;
  opacity?: number;
  blend?: OverlayOptions["blend"];
}

interface TextWatermarkOptions {
  position?: Corner;
  margin?: number;
  fontSize?: number;
  opacity?: number;
  color?: string;
  fontFamily?: string;
  strokeColor?: string;
  strokeWidth?: number;
}

interface WatermarkOptions extends IOptions {
  watermarkType: 'text' | 'image';
  text?: string;
  textOptions?: TextWatermarkOptions;
  logoPath?: string;
  imageOptions?: LogoWatermarkOptions;
}

Contributing

For bug reports, feature requests, or contributions, please visit the project repository.

License

This tool is part of the @polymech/media package. Please refer to the package license for usage terms.

10 KiB Raw Blame History