PHP-FFMpeg 1.4.0 已移除 addWatermark 方法，必须用 addFilter 注入 overlay 滤镜，如 [0:v][1:v]overlay=x=W-w-10:y=H-h-10，且水印图需绝对路径、PNG格式、权限正确，FFmpeg 版本不低于4.0。
PHP-FFMpeg 1.4.0 加水印必须用 addFilter，不是 addWatermark
PHP-FFMpeg 1.4.0 官方已移除 addWatermark 方法，直接调用会报 Call to undefined method 错误。水印必须通过 FFmpeg 原生命令参数实现，核心是用 addFilter 注入 overlay 滤镜。
常见错误是照抄旧版教程、误以为有封装好的水印方法，结果运行就崩。实际三行能跑的前提是：路径对、权限够、FFmpeg 版本 ≥ 4.0（推荐 4.4+）。
-
$video必须是FFMpegMediaVideo实例，不能是文件路径字符串 - 水印图路径需为绝对路径（相对路径在 CLI 环境下极易失效）
-
overlay参数顺序敏感：overlay=x=10:y=10是左上角，overlay=x=W-w-10:y=H-h-10是右下角（W/w/H/h是自动变量）
三行可运行的加水印代码（含关键注释）
以下代码在 PHP-FFMpeg 1.4.0 + FFMpeg 4.4 环境下实测通过，水印居右下角、带 10px 边距：
$video = $ffmpeg->open('/var/www/video/input.mp4');
$video->filters()->addFilter('[0:v][1:v]overlay=x=W-w-10:y=H-h-10', '/var/www/watermark.png');
$video->save(new FFMpegFormatVideoX264(), '/var/www/video/output.mp4');
注意：[0:v][1:v] 表示「主视频流」和「水印图作为第二输入流」，这个双输入结构是硬性要求；如果漏掉 [1:v] 或写成 [0:v] 重复引用，会触发 Stream specifier ':v' in filtergraph description 类错误。
立即学习“PHP免费学习笔记（深入）”；
- 水印图建议用 PNG（支持透明通道），尺寸不宜过大（如 200×80），否则编码卡顿
- 输出格式不强制用
X264，但若改用WebM，需确认 FFmpeg 编译时启用了libvpx - 执行前确保 PHP 进程对
/var/www/watermark.png有读取权限，且磁盘空间充足
位置/缩放/透明度要调参，不能只靠“三行”硬套
所谓“三行代码”只是骨架，实际项目中几乎都要调整滤镜参数。比如加半透明水印，得补 format=rgba,split[bg][fg];[fg]format=rgba,colorchannelmixer=aa=0.6[fga];[bg][fga]overlay —— 这已经远超三行，且必须手动拼 filter 字符串。
-
x/y支持表达式：x='if(gte(t,5),10,NaN)'可实现“5 秒后才出现水印” - 缩放水印要用
scale滤镜前置：[1:v]scale=150:-1[wm];[0:v][wm]overlay=x=W-w-10:y=H-h-10 - Windows 路径要用
str_replace('/', '\', $path)处理反斜杠，否则addFilter会把w当转义符解析
调试失败时优先检查这三件事
90% 的“三行代码不工作”问题，根源不在 PHP 代码本身，而在环境链路断点：
- 运行
ffmpeg -version确认终端里 FFmpeg 版本 ≥ 4.0；PHP 中执行shell_exec('ffmpeg -version')输出为空？说明 PATH 没配对或被禁用 - 打开
FFMpegFFProbe日志：$ffmpeg->getFFProbe()->setLogLevel(FFMpegFFProbe::LOG_DEBUG)，看是否卡在 probe 阶段 - 临时把
addFilter替换为addFilter('drawtext=text="TEST":x=10:y=10:fontsize=24', null)，验证滤镜机制是否通——如果文字能出，说明水印图路径或格式有问题
真正麻烦的从来不是写那三行，而是让 FFmpeg 在你的服务器上安静地读完那张 PNG。
