Java如何使用FFmpeg为视频添加文字水印？

Question

在使用Java调用FFmpeg为视频添加文字水印时，常见问题是：如何正确构造包含drawtext滤镜的命令参数以确保中文或动态文本正常显示？开发者常因未指定字体文件（fontfile）、忽略URL编码或路径转义导致文字不显示或乱码。此外，在Linux环境下中文字体路径配置不当也易引发文字变方框等问题。如何通过Java ProcessBuilder正确传递含特殊字符的drawtext参数，并确保FFmpeg支持fontconfig以自动查找系统字体，是实现稳定文字水印的关键技术难点。

Answer 1

Java调用FFmpeg实现视频文字水印的深度解析

1. 问题背景与常见误区

在多媒体处理场景中，使用Java调用FFmpeg为视频添加文字水印是常见需求。然而，许多开发者在实现过程中遭遇文字不显示、乱码或出现方框等问题，尤其在涉及中文或动态文本时更为突出。根本原因通常包括：

• 未显式指定字体文件（fontfile），导致系统默认字体不支持中文；
• drawtext滤镜参数构造不当，特殊字符未进行URL编码或转义；
• Linux环境下字体路径配置缺失或错误，FFmpeg无法定位中文字体；
• ProcessBuilder传递参数时未正确分割命令，导致shell解析失败；
• FFmpeg编译时未启用fontconfig，无法自动查找系统字体。

这些问题叠加，使得看似简单的文字水印功能变得复杂且难以调试。

2. drawtext滤镜参数构造规范

FFmpeg的drawtext滤镜通过字符串参数控制文字渲染行为。其基本语法如下：

-vf "drawtext=fontfile=xxx:text='Hello':x=10:y=10"

当文本包含空格、单引号、冒号等特殊字符时，必须进行适当转义。例如动态插入用户昵称“张三's 视频”，若不处理会导致解析中断。

字符类型	处理方式
单引号 '	替换为''（两个单引号）
冒号 :	在参数中需用\进行转义
空格	建议使用双引号包裹整个text值
中文字符	确保终端/环境支持UTF-8编码

3. 字体文件（fontfile）的正确引用

Windows和Linux系统中文字体路径差异显著。以下为常见中文字体路径示例：

# Windows
C:\\\\Windows\\\\Fonts\\\\simhei.ttf

# Linux (Debian/Ubuntu)
/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc

在Java中拼接路径时，应使用File.separator或双反斜杠避免转义问题。推荐将字体文件打包至项目资源目录并复制到运行时临时路径，以增强可移植性。

4. 使用ProcessBuilder安全传递参数

直接拼接字符串命令易引发注入风险和解析错误。应使用List形式逐项添加参数：

List<String> command = new ArrayList<>();
command.add("ffmpeg");
command.add("-i");
command.add("/path/to/input.mp4");
command.add("-vf");
command.add("drawtext=fontfile=/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc:text='中文水印':fontsize=24:fontcolor=white:x=10:y=10");
command.add("-y");
command.add("/path/to/output.mp4");

ProcessBuilder pb = new ProcessBuilder(command);
pb.redirectErrorStream(true);
Process process = pb.start();

该方式避免了shell对特殊字符的误解，提升稳定性。

5. fontconfig机制与系统字体发现

FFmpeg是否支持fontconfig可通过命令检查：

ffmpeg -filters | grep drawtext

若输出包含fontconfig字样，则支持自动字体查找。启用后可省略fontfile参数：

drawtext=text='你好世界':fontfamily='WenQuanYi Zen Hei':fontsize=32

此机制依赖于Linux系统的fontconfig配置（如/etc/fonts/fonts.conf），需确保中文字体已注册。

6. 动态文本的安全编码策略

对于用户输入的动态水印内容，需进行双重防护：

1. 对文本中的单引号进行替换：text.replace("'", "''")；
2. 若使用URL形式传参（如text=expr），需进行URLEncoder.encode(text, "UTF-8")；
3. 建议使用固定字体而非依赖fontfamily，减少环境差异影响。

7. 完整解决方案流程图

graph TD
    A[开始] --> B{输入文本是否含中文?}
    B -- 是 --> C[指定中文字体文件或启用fontconfig]
    B -- 否 --> D[可使用默认字体]
    C --> E[对文本进行特殊字符转义]
    D --> E
    E --> F[构建drawtext滤镜参数]
    F --> G[使用ProcessBuilder传递List参数]
    G --> H[执行FFmpeg进程]
    H --> I[验证输出视频水印显示]
    I --> J[结束]

8. 跨平台兼容性建议

为提升部署灵活性，建议采取以下措施：

• 在Docker镜像中预装wqy-zenhei等开源中文字体；
• 启动时检测FFmpeg是否支持fontconfig；
• 提供字体回退机制，主字体失败时尝试备用字体；
• 日志记录完整命令行以便排查问题。