gdt-auto/docs/WATERMARK_USAGE.md

图片/视频水印功能使用文档

功能概述

本项目提供了在图片和视频左上角添加剧名水印的功能，支持：

• ✅ 图片水印：支持 JPG、PNG、GIF、BMP 等常见格式
• ✅ 视频水印：支持 MP4 等常见视频格式
• ✅ 自定义样式：可调整字体大小、位置、颜色
• ✅ 图片压缩：支持添加水印同时压缩图片
• ✅ 视频帧提取：可提取视频第一帧作为预览图

依赖库

图片处理

• Thumbnailator 0.4.20：轻量级图片处理库，支持压缩和缩放
• Java AWT：内置图形库，用于绘制文字水印

视频处理

• JavaCV 1.5.10：Java 视频处理库
• FFmpeg 6.1.1：强大的音视频处理工具

使用方法

1. 图片水印

基本使用

import com.moka.gdtauto.util.ImageWatermarkUtil;

// 基本用法：在左上角（50, 50）位置添加水印，字体大小40
ImageWatermarkUtil.addWatermark(
    "input.jpg",           // 输入图片路径
    "output.jpg",          // 输出图片路径
    "《绝世龙王》"          // 水印文字
);

自定义位置和字体

// 自定义字体大小和位置
ImageWatermarkUtil.addWatermark(
    "input.jpg",           // 输入图片路径
    "output.jpg",          // 输出图片路径
    "《绝世龙王》",         // 水印文字
    60,                    // 字体大小
    100,                   // X坐标（从左边距）
    100                    // Y坐标（从顶部距）
);

带压缩功能

// 添加水印并压缩图片到80%大小
ImageWatermarkUtil.addWatermarkWithCompression(
    "input.jpg",           // 输入图片路径
    "output.jpg",          // 输出图片路径
    "《绝世龙王》",         // 水印文字
    0.8                    // 缩放比例（0.8 = 80%）
);

2. 视频水印

基本使用

import com.moka.gdtauto.util.VideoWatermarkUtil;

// 基本用法：在左上角（50, 50）位置添加水印，字体大小40
VideoWatermarkUtil.addWatermark(
    "input.mp4",           // 输入视频路径
    "output.mp4",          // 输出视频路径
    "《绝世龙王》"          // 水印文字
);

自定义位置和字体

// 自定义字体大小和位置
VideoWatermarkUtil.addWatermark(
    "input.mp4",           // 输入视频路径
    "output.mp4",          // 输出视频路径
    "《绝世龙王》",         // 水印文字
    60,                    // 字体大小
    100,                   // X坐标（从左边距）
    100                    // Y坐标（从顶部距）
);

提取视频第一帧

// 提取视频第一帧作为预览图
VideoWatermarkUtil.extractFirstFrame(
    "video.mp4",           // 视频路径
    "preview.jpg"          // 输出图片路径
);

水印样式

• 字体：微软雅黑（Microsoft YaHei），粗体
• 颜色：白色文字 + 黑色描边，提供良好的可读性
• 透明度：文字透明度 230/255，描边透明度 180/255
• 抗锯齿：启用文字抗锯齿，确保清晰显示

运行测试

图片水印测试

# 编译
javac -cp "$(mvn dependency:build-classpath -q -DincludeScope=compile -Dmdep.outputFile=/dev/stdout):target/classes" \
  -d target/test-classes \
  src/test/java/com/moka/gdtauto/util/ImageWatermarkSimpleTest.java

# 运行
java -cp "target/classes:target/test-classes:$(mvn dependency:build-classpath -q -DincludeScope=compile -Dmdep.outputFile=/dev/stdout)" \
  com.moka.gdtauto.util.ImageWatermarkSimpleTest

视频水印测试

# 编译
javac -cp "$(mvn dependency:build-classpath -q -DincludeScope=compile -Dmdep.outputFile=/dev/stdout):target/classes" \
  -d target/test-classes \
  src/test/java/com/moka/gdtauto/util/VideoWatermarkSimpleTest.java

# 运行
java -cp "target/classes:target/test-classes:$(mvn dependency:build-classpath -q -DincludeScope=compile -Dmdep.outputFile=/dev/stdout)" \
  com.moka.gdtauto.util.VideoWatermarkSimpleTest

测试结果

运行测试后，结果文件会保存在以下目录：

• 图片测试：target/test-output/watermark/
• 视频测试：target/test-output/video-watermark/

注意事项

1. 视频处理较慢：视频水印需要逐帧处理，处理时间较长，请耐心等待
2. 内存占用：处理大文件时可能需要较多内存
3. 字体支持：确保系统中有中文字体支持，否则可能显示乱码
4. 格式兼容性：
   • 图片：支持 JPG、PNG、GIF、BMP
   • 视频：推荐使用 MP4 格式

常见问题

Q: 水印文字显示乱码？

A: 确保系统安装了中文字体，特别是"微软雅黑"或"宋体"。

Q: 视频处理失败？

A: 检查视频编码格式是否支持，推荐使用 H.264 编码的 MP4 格式。

Q: 如何调整水印透明度？

A: 在工具类中修改 Color 对象的第四个参数（alpha 值），范围 0-255。

Q: 能否在其他位置添加水印？

A: 可以通过修改 x、y 参数来调整水印位置，或修改工具类支持更多位置选项。

扩展开发

如需扩展功能，可以：

1. 在 ImageWatermarkUtil.java 中添加图片相关功能
2. 在 VideoWatermarkUtil.java 中添加视频相关功能
3. 参考测试用例了解使用方法

性能参考

在测试环境中（macOS，JDK 21）：

• 图片处理：1920x1080 图片约 50-100ms
• 视频处理：3秒 720p 视频（10fps）约 1-2秒
• 帧提取：单帧提取约 50ms

实际性能取决于硬件配置和文件大小。