ffmpeg-python的run函数本地正常，服务器端加水印时异常

场景与代码 #

我使用ffmpeg-python库给视频添加水印，代码如下：

def set_watermark_to_video(
    video_url: str,
    directory: str,
    filename: str,
    extension: str,
):
    video_input = ffmpeg.input(video_url)
    output_path: str = f"/tmp/{filename}_watermarked.mp4"
    logo_input = ffmpeg.input(vid_mycar_logo_path)
    video_probe = ffmpeg.probe(video_url)
    video_stream = next(
        (
            stream
            for stream in video_probe["streams"]
            if stream["codec_type"] == "video"
        ),
        None,
    )

    logo_probe = ffmpeg.probe("my_logo_path")
    logo_stream = next(
        (stream for stream in logo_probe["streams"] if stream["codec_type"] == "video"),
        None,
    )
    ffmpeg.filter(
        [video_input, logo_input],
        "overlay",
        10,
        video_stream["height"] - logo_stream["height"] - 10,
    ).output(output_path).run(overwrite_output=True)

异常情况 #

调用.run(overwrite_output=True)时触发异常：

ffmpeg._run.Error: ffmpeg error (see stderr output for detail)

打印exc.stderr仅看到警告：

"Unknown cover type: 0x1."

本地运行完全正常，通过Docker构建服务，本地与服务器端依赖、版本一致（ffmpeg版本为5.1.4-0+deb12u1），且已逐行对比服务器端与本地的所有参数和值，完全一致，但服务器端仍报错。

可能的解决思路 #

1. 排查水印文件的路径与权限 #

Docker容器内的文件环境和本地存在差异：

• 确认vid_mycar_logo_path和my_logo_path是容器内的绝对路径，避免相对路径导致文件找不到
• 在容器内执行ls -l [水印文件路径]，验证文件存在且容器进程有读取权限

2. 强制指定水印文件格式 #

"Unknown cover type: 0x1."警告大概率是ffmpeg对水印文件格式识别异常，尝试在读取水印时强制指定格式：

# 假设水印是PNG格式，根据实际文件类型调整
logo_input = ffmpeg.input(vid_mycar_logo_path, format="png")
logo_probe = ffmpeg.probe("my_logo_path", format="png")

3. 打印完整ffmpeg命令调试 #

将ffmpeg-python生成的命令打印出来，在容器内直接执行，获取完整错误输出：

# 在run()前添加代码打印命令
cmd = ffmpeg.filter(
    [video_input, logo_input],
    "overlay",
    10,
    video_stream["height"] - logo_stream["height"] - 10,
).output(output_path).compile()
print(cmd)

复制命令到容器内执行，查看完整stderr，可能会发现隐藏的错误（比如编解码器缺失、视频文件编码问题）

4. 检查容器内ffmpeg编解码器支持 #

虽然版本一致，但Docker镜像可能默认缺少部分编解码器，执行ffmpeg -codecs对比本地与容器内的编解码器列表，确保需要的编解码器（如H.264、PNG解码器）已安装

5. 显式指定输出编码参数 #

尝试在output时强制指定视频、音频编码，规避容器内默认编码设置问题：

ffmpeg.filter(
    [video_input, logo_input],
    "overlay",
    10,
    video_stream["height"] - logo_stream["height"] - 10,
).output(output_path, vcodec="libx264", acodec="aac").run(overwrite_output=True)

内容的提问来源于stack exchange，提问作者Fire Deus