Imagick无法处理视频，必须用FFmpeg抽帧→Imagick逐帧加水印→FFmpeg合成；需注意帧尺寸对齐、色彩空间、权限路径及参数匹配，否则静默失败。
Imagick 无法直接处理视频，必须先抽帧再逐帧加水印
Imagick 是图像处理扩展，不是视频库——它压根不识别 .mp4、.mov 这类容器格式。试图用 new Imagick('video.mp4') 会直接抛出 Unable to open image 错误。真实流程只能是：用 FFmpeg 抽帧 → 对每张 PNG/JPEG 帧图用 Imagick 加水印 → 再用 FFmpeg 合成新视频。
常见错误是跳过 FFmpeg，硬凑 Imagick::readImageFile() 读视频流，结果静默失败或只处理第一帧。
- 抽帧命令示例：
ffmpeg -i input.mp4 -vf fps=25 -q:v 2 frame_%06d.png（25fps，高质量输出） - 水印叠加前务必检查帧图尺寸是否与原始视频一致，否则合成后会出现拉伸或黑边
- 避免在 PHP 中用
exec()同步调用 FFmpeg 抽帧+合成，容易超时；建议拆成异步任务或预生成帧目录
用 Imagick 给 PNG 帧图加文字/图片水印的正确写法
关键在图层顺序和坐标计算：水印必须叠加在帧图顶层，且位置需适配不同分辨率。直接用 annotateImage() 或 compositeImage() 即可，但参数稍有不慎就会偏移或透明度失效。
文字水印示例（居中半透明）：
立即学习“PHP免费学习笔记（深入）”；
$imagick = new Imagick('frame_000001.png');
$draw = new ImagickDraw();
$draw->setFillColor('rgba(255,255,255,0.3)');
$draw->setFont('/path/to/font.ttf');
$draw->setFontSize(48);
$draw->setTextAlignment(Imagick::ALIGN_CENTER);
$metrics = $imagick->queryFontMetrics($draw, '© 2024');
$x = ($imagick->getImageWidth() - $metrics['textWidth']) / 2;
$y = $imagick->getImageHeight() - 40;
$draw->annotation($x, $y, '© 2024');
$imagick->drawImage($draw);
$imagick->writeImage('watermarked_frame_000001.png');
-
setFillColor()的 alpha 值范围是 0.0–1.0，不是 0–255；传整数 128 会变纯黑 - 用
queryFontMetrics()动态算宽高，别写死annotation(500, 300, ...)—— 换个视频分辨率就错位 - 图片水印用
compositeImage()时，确保水印图自身带 alpha 通道，且Imagick::COMPOSITE_OVER模式才支持透明叠加
合成水印帧为视频时，FFmpeg 参数必须匹配原始视频编码特性
加完水印的帧图只是中间产物，最终要靠 FFmpeg 合成。如果参数和源视频不一致（如 GOP、profile、colorspace），会导致播放卡顿、色偏或无法在 iOS Safari 播放。
推荐做法：先用 ffprobe input.mp4 查原始参数，再复用关键项：
- 获取原始帧率：
ffprobe -v quiet -show_entries stream=r_frame_rate -of default=nw=1 input.mp4 - 合成命令必须指定相同帧率：
ffmpeg -framerate 25 -i watermarked_frame_%06d.png -c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" output.mp4 -
scale=trunc(iw/2)*2是硬性要求：x264 要求宽高为偶数，否则报错width not divisible by 2 - 别漏掉
-pix_fmt yuv420p，否则安卓和旧版浏览器可能显示绿屏
PHP 中调用外部命令的权限与路径陷阱
本地开发能跑通，上线后 exec('ffmpeg -i...') 却返回空或 127 错误，90% 是环境问题。
- 确认 PHP 进程用户（如
www-data）对 FFmpeg 二进制和输入/输出目录有执行、读写权限 - 不要依赖
PATH环境变量，始终用绝对路径调用：/usr/bin/ffmpeg而非ffmpeg - 帧图目录建议设在
/tmp外的独立路径（如/var/www/watermark_frames），避免被系统清理导致合成中断 - 用
exec($cmd, $output, $returnCode)捕获$returnCode，非 0 就立即记录$output内容——这是定位 FFmpeg 报错的唯一线索
水印逻辑本身不复杂，真正卡住人的永远是 FFmpeg 和 Imagick 之间的衔接细节：帧尺寸对齐、色彩空间转换、临时文件生命周期管理。这些地方一错，整个流程就静默失败。
