universal-watermark

中文文档

A code-first multi-format watermarking Agent Skill and Python CLI for Word, PDF, PowerPoint, Excel, images, and GIFs.

universal-watermark automatically detects file types, chooses the correct processor, applies visible text watermarks, and writes new output files without overwriting the original files.

Why this project?

Most watermark tools focus on one format, usually PDF or images. This project is built for mixed real-world files:

• Word, PDF, PowerPoint, Excel, images, and GIFs;
• automatic file type detection;
• repeated, diagonal, semi-transparent text watermarks;
• batch processing from one command;
• safe output rules that keep the original file unchanged;
• reusable Agent Skill installation through npm.

Preview

The following preview shows watermark effects on PDF, Word, image, Excel, and PowerPoint files.

Quick Start

Install Python dependencies:

pip install pillow lxml python-docx pymupdf python-pptx

Add a watermark to one file:

python scripts/universal_watermark.py input.pdf --text "CONFIDENTIAL"

Batch process multiple files:

python scripts/universal_watermark.py a.docx b.pdf c.pptx table.xlsx image.jpg --output-dir watermarked --text "INTERNAL USE"

Use a Chinese font when needed:

python scripts/universal_watermark.py input.pdf --text "试用水印" --font-path "C:\Windows\Fonts\msyh.ttc"

Install as an Agent Skill

This repository can be installed as a local Skill for Codex, Claude Code, or other agent workflows.

npm install -g @czhanp/universal-watermark-skill
universal-watermark-skill install --all

Default installation targets:

~/.codex/skills/universal-watermark
~/.claude/skills/universal-watermark
~/.agents/skills/universal-watermark

Install for one target only:

universal-watermark-skill install --target codex
universal-watermark-skill install --target claude
universal-watermark-skill install --target agents

Run the installer once without keeping the npm package globally:

npm exec --yes --package=@czhanp/universal-watermark-skill -- universal-watermark-skill install --all

The npm package is used to distribute the Skill files. The actual watermarking logic is implemented in Python, so Python dependencies still need to be installed separately.

Supported Formats

Category	Formats
Word	.docx, .doc, .rtf, .odt
PDF	.pdf
PowerPoint	.pptx, .ppt
Excel	.xlsx, .xlsm, .xltx, .xltm, .xls, .ods, .csv
Images	.png, .jpg, .jpeg, .webp, .bmp, .tif, .tiff
Animated images	.gif

Legacy Office and non-OOXML formats such as .doc, .ppt, .xls, .rtf, .odt, .ods, and .csv may require LibreOffice conversion before watermarking.

Common CLI Examples

Word / DOCX

python scripts/universal_watermark.py report.docx --text "Trial Watermark" --angle 45 --opacity 0.18

PDF

python scripts/universal_watermark.py paper.pdf --text "Internal Use" --opacity 0.15

PowerPoint

python scripts/universal_watermark.py slides.pptx --text "Draft" --angle -45

Excel

Use worksheet background watermark:

python scripts/universal_watermark.py table.xlsx --text "Trial Watermark" --excel-mode background

Use transparent overlay watermark for printing or PDF export:

python scripts/universal_watermark.py table.xlsx --text "Trial Watermark" --excel-mode overlay --opacity 0.12

Use both modes:

python scripts/universal_watermark.py table.xlsx --text "Trial Watermark" --excel-mode both --opacity 0.10

Images

python scripts/universal_watermark.py image.jpg --text "Trial Watermark"

GIF

python scripts/universal_watermark.py animation.gif --text "Trial Watermark"

Legacy Office Files

Convert to editable modern Office format before watermarking:

python scripts/universal_watermark.py old.doc --legacy-target editable
python scripts/universal_watermark.py old.ppt --legacy-target editable
python scripts/universal_watermark.py old.xls --legacy-target editable

Convert to PDF before watermarking:

python scripts/universal_watermark.py old.doc --legacy-target pdf

Watermark Layouts

checkerboard

checkerboard is the recommended visual layout. It alternates text slots and empty slots to avoid overly dense repeated watermarks.

python scripts/universal_watermark.py input.pdf \
  --text "Trial Watermark" \
  --layout checkerboard \
  --spacing-x-font-multiplier 2.0 \
  --spacing-y-font-multiplier 3.0 \
  --empty-slot-multiplier 1.0

staggered

staggered is the traditional tiled watermark layout where every other row is shifted horizontally.

python scripts/universal_watermark.py input.pdf --text "Trial Watermark" --layout staggered

Common Options

Option	Description	Example
--text	Watermark text	--text "Trial Watermark"
--angle	Rotation angle	--angle 45
--opacity	Watermark opacity, from 0 to 1	--opacity 0.18
--color	RGB color or hex color	--color "#808080"
--font-path	Path to a font file	--font-path "C:\Windows\Fonts\msyh.ttc"
--layout	Watermark layout	--layout checkerboard
--output-dir	Output directory	--output-dir watermarked
--suffix	Output filename suffix	--suffix "_watermarked"
--legacy-target	Legacy file conversion target	--legacy-target editable
--excel-mode	Excel watermark mode	--excel-mode background

Check the current CLI help before using advanced options:

python scripts/universal_watermark.py --help

Excel Watermark Modes

Excel does not provide a native watermark layer like Word. This project provides practical alternatives:

Mode	Description	Best for
background	Adds a worksheet background image	Viewing and editing
overlay	Adds transparent image overlays	Printing and PDF export
both	Uses both background and overlay	Strongest visible effect

Recommended default:

--excel-mode background

For printing or exporting to PDF:

--excel-mode overlay --opacity 0.12

Output Rules

The tool never overwrites the original file by default.

report.docx    -> report_watermarked.docx
paper.pdf      -> paper_watermarked.pdf
slides.pptx    -> slides_watermarked.pptx
table.xlsx     -> table_watermarked.xlsx
image.jpg      -> image_watermarked.jpg

If the output file already exists, a numeric suffix is added automatically:

report_watermarked.docx
report_watermarked_1.docx
report_watermarked_2.docx

Project Structure

universal-watermark/
  SKILL.md
  README.md
  README_zh-CN.md
  LICENSE
  package.json
  bin/
    install.js
  scripts/
    universal_watermark.py
    watermark/
      cli.py
      detector.py
      dispatcher.py
      word.py
      pdf.py
      ppt.py
      excel.py
      image.py
      gif.py
      converters.py
      common.py
      options.py
      constants.py
      svg.py
  example/

Notes and Limitations

• Legacy Office files such as .doc, .ppt, and .xls require conversion before watermarking.
• LibreOffice conversion may cause slight layout differences.
• PDF watermarking overlays watermark content onto pages, so low opacity is recommended.
• Excel background mode usually does not appear in printing.
• Excel overlay mode is more suitable for printing but may affect cell selection.
• GIF output may have slight quality changes because of palette limitations.
• Very large images or multi-page TIFF files may require more memory.
• Encrypted PDFs require appropriate permission before processing.

Development

Check Python syntax:

python -m compileall scripts

Show CLI help:

python scripts/universal_watermark.py --help

Suggested maintenance areas:

Module	Purpose
scripts/watermark/word.py	Word / DOCX watermarking
scripts/watermark/pdf.py	PDF watermarking
scripts/watermark/ppt.py	PowerPoint / PPTX watermarking
scripts/watermark/excel.py	Excel / XLSX / XLSM watermarking
scripts/watermark/image.py	Static image watermarking
scripts/watermark/gif.py	Animated GIF watermarking
scripts/watermark/common.py	Shared watermark layer, font, and OOXML utilities
scripts/watermark/options.py	Watermark option definitions

License

MIT License.