FFmpeg 视频生成推理 Pipeline：Python 版常用函数封装（可直接集成）

前言

在 AI 视频生成、批量推理等工程化场景中，我们常常面临一个核心痛点：AI 模型负责生成素材（图片序列、音频片段），但无法直接输出可用的成品视频，而 FFmpeg 作为音视频处理的行业标准工具，却难以直接嵌入 Python Pipeline，导致 "模型推理与后期处理脱节"，增加了开发成本和部署难度。

尤其是在企业级落地场景中，需要实现 "AI 推理→素材预处理→视频合成→优化输出" 的自动化流转，零散的 FFmpeg 命令行调用不仅难以维护，还容易出现异常未捕获、参数不兼容、跨平台适配差等问题。

基于此，本文将 FFmpeg 核心操作封装成可直接嵌入 Pipeline 的 Python 函数，每个函数对应一个视频生成推理节点，包含完善的异常处理、参数配置和日志输出，模块化设计可独立调用、可串联集成，适配绝大多数视频生成场景（AI 图片序列合成、单张封面 + 配音短视频、批量视频优化等），新手也能快速集成到项目中，省去重复编码和调试的时间。

本文所有函数均（仅使用 Python 内置模块），复制即可复用，同时附带完整的 Pipeline 调用示例和常见问题排查，贴合开发者实战需求，助力大家快速实现视频生成推理的工程化落地。

一、前置依赖（必看）

1. 环境要求

• 操作系统：Windows/Mac/Linux（跨平台兼容，函数已做路径适配）
• Python 版本：3.7+（无需额外安装第三方库，仅使用内置模块）
• FFmpeg：需提前安装并配置环境变量（确保终端输入ffmpeg -version能正常显示版本信息）
  • Windows：下载解压后，将 FFmpeg 的 bin 目录添加到系统环境变量
  • Mac：brew install ffmpeg
  • Linux：sudo apt install ffmpeg

2. 核心依赖模块

仅依赖 Python 内置模块，无需pip install任何第三方库：

• subprocess：执行 FFmpeg 命令，实现与 FFmpeg 的交互
• os：处理文件路径、创建目录，适配跨平台路径格式
• logging：输出日志，便于 Pipeline 调试和问题排查（可根据需求配置日志输出方式）

二、基础工具函数（Pipeline 核心依赖）

封装 2 个基础工具函数，作为所有功能函数的底层支撑，统一处理 FFmpeg 命令执行、异常捕获和目录创建，避免重复编码，确保 Pipeline 稳定运行。

import subprocess
import os
import logging

# 配置日志（适配Pipeline调试，可输出到控制台或文件）
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    handlers=[logging.StreamHandler()]  # 如需输出到文件，可添加FileHandler
)

def run_ffmpeg_command(command: list) -> bool:
    """
    基础工具函数：执行FFmpeg命令，统一处理异常和日志输出
    :param command: FFmpeg命令列表（推荐用列表，避免空格问题，适配跨平台）
    :return: 执行成功返回True，失败返回False
    """
    try:
        # 执行FFmpeg命令，隐藏控制台冗余输出（stdout/stderr重定向）
        subprocess.run(
            command,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=True,
            shell=False  # 禁止shell=True，避免安全风险，适配跨平台
        )
        logging.info(f"FFmpeg命令执行成功：{' '.join(command)}")
        return True
    except subprocess.CalledProcessError as e:
        logging.error(f"FFmpeg命令执行失败：{' '.join(command)}，错误信息：{str(e)}")
        return False
    except Exception as e:
        logging.error(f"FFmpeg命令执行异常：{' '.join(command)}，异常信息：{str(e)}")
        return False

def create_dir(path: str) -> bool:
    """
    辅助函数：创建目录（支持多级目录），避免Pipeline中路径不存在报错
    :param path: 要创建的目录路径
    :return: 创建成功/已存在返回True，失败返回False
    """
    try:
        if not os.path.exists(path):
            os.makedirs(path, exist_ok=True)  # exist_ok=True避免目录已存在报错
            logging.info(f"目录创建成功：{path}")
        return True
    except Exception as e:
        logging.error(f"目录创建失败：{path}，异常信息：{str(e)}")
        return False

关键说明

• run_ffmpeg_command：所有 FFmpeg 操作都通过该函数执行，统一捕获异常（命令错误、文件不存在等），并输出日志，便于调试；使用列表传递命令，避免空格问题，适配 Windows/Mac/Linux。
• create_dir：自动创建输出目录（支持多级目录），解决 Pipeline 中 "输出路径不存在" 的常见报错，减少重复的路径判断代码。

三、Pipeline 核心 Python 函数（按推理流程封装）

按 "推理前预处理→推理中合成→推理后优化" 的视频生成全流程，封装 6 个高频核心函数，每个函数可独立调用，也可串联成完整 Pipeline，参数可根据实际推理场景灵活调整，覆盖 80% 以上的视频生成需求。

1. 图片预处理函数（推理前）

批量转换 AI 推理输出的图片格式（如 PNG→JPG）、统一分辨率，避免后续合成视频时出现格式不兼容、尺寸错乱等问题，适配 AI 图片序列推理场景（如 AI 绘画、PPT 推理转视频）。

def preprocess_images(
    input_dir: str,
    output_dir: str,
    target_format: str = "jpg",
    quality: int = 1,
    target_size: tuple = None
) -> bool:
    """
    推理前图片预处理：批量转换格式、统一分辨率
    :param input_dir: AI推理输出的图片目录（如./inference_output/images）
    :param output_dir: 预处理后图片保存目录
    :param target_format: 目标图片格式（默认jpg，支持png、jpeg，jpg更节省体积）
    :param quality: 图片质量（1-31，越小越清晰，默认1，兼顾清晰度和体积）
    :param target_size: 目标分辨率（如(1920, 1080)，None表示不调整）
    :return: 批量预处理成功返回True，失败返回False
    """
    # 1. 创建输出目录
    if not create_dir(output_dir):
        return False
    
    # 2. 遍历输入目录的图片文件，过滤非图片文件
    image_extensions = [f".{target_format.lower()}", ".png", ".jpeg", ".jpg"]
    for filename in os.listdir(input_dir):
        if not any(filename.lower().endswith(ext) for ext in image_extensions):
            logging.warning(f"跳过非图片文件：{filename}")
            continue
        
        # 构建输入输出路径（适配跨平台路径格式）
        input_path = os.path.join(input_dir, filename)
        name = os.path.splitext(filename)[0]
        output_path = os.path.join(output_dir, f"{name}.{target_format.lower()}")
        
        # 构建FFmpeg命令
        command = ["ffmpeg", "-i", input_path]
        # 调整图片质量（仅jpg/jpeg格式有效）
        if target_format.lower() in ["jpg", "jpeg"]:
            command.extend(["-q:v", str(quality)])
        # 调整分辨率（若指定目标尺寸）
        if target_size and len(target_size) == 2:
            command.extend(["-s", f"{target_size[0]}x{target_size[1]}"])
        # 覆盖输出，避免手动确认
        command.extend(["-y", output_path])
        
        # 执行命令，单个图片失败不中断整个批量处理
        if not run_ffmpeg_command(command):
            logging.warning(f"单个图片预处理失败：{input_path}")
    
    logging.info(f"图片批量预处理完成，输出目录：{output_dir}")
    return True

2. 音频预处理函数（推理前）

转换 AI 推理输出的音频格式（如 WAV→AAC）、调整比特率，适配视频合成的音频要求，避免出现音视频不同步、音频格式不兼容等问题（AAC 是视频通用音频编码，兼容性更强、体积更小）。

def preprocess_audio(
    input_path: str,
    output_path: str,
    bitrate: str = "192k",
    target_format: str = "aac"
) -> bool:
    """
    推理前音频预处理：转换格式、调整比特率
    :param input_path: AI推理输出的音频路径（如./inference_output/audio/original.wav）
    :param output_path: 预处理后音频保存路径
    :param bitrate: 音频比特率（默认192k，兼顾音质和体积，短视频推荐192k-256k）
    :param target_format: 目标音频格式（默认aac，视频通用编码，兼容性最强）
    :return: 预处理成功返回True，失败返回False
    """
    # 1. 检查输入文件是否存在
    if not os.path.exists(input_path):
        logging.error(f"音频输入文件不存在：{input_path}")
        return False
    
    # 2. 创建输出目录（若输出路径包含多级目录）
    output_dir = os.path.dirname(output_path)
    if not create_dir(output_dir):
        return False
    
    # 3. 构建FFmpeg命令
    command = [
        "ffmpeg", "-i", input_path,
        "-c:a", target_format,  # 音频编码（aac通用）
        "-b:a", bitrate,        # 音频比特率
        "-y",                   # 覆盖输出
        output_path
    ]
    
    # 执行命令并返回结果
    return run_ffmpeg_command(command)

3. 图片序列 + 音频合成视频函数（推理中核心）

将 AI 推理输出的图片序列（如 1.jpg、2.jpg...）与预处理后的音频合成标准视频，支持轮播时长、帧率、分辨率自定义，是 AI 视频生成推理的核心函数（适配 AI 绘画、分镜推理等场景）。

def images_audio_to_video(
    image_dir: str,
    audio_path: str,
    output_video: str,
    frame_duration: float = 3.0,  # 每张图片显示时长（秒）
    fps: int = 25,                # 视频帧率（短视频通用25帧，高清视频可设30帧）
    video_size: tuple = (1920, 1080),  # 视频分辨率（默认1080P横屏）
    pix_fmt: str = "yuv420p"      # 像素格式，兼容所有播放器（必选）
) -> bool:
    """
    推理中核心：图片序列+音频合成视频（适配AI推理图片序列场景）
    :param image_dir: 预处理后的图片序列目录（图片命名需为1.jpg、2.jpg...连续数字）
    :param audio_path: 预处理后的音频路径
    :param output_video: 合成视频输出路径（如./inference_result/video.mp4）
    :param frame_duration: 每张图片显示时长（默认3秒，可根据推理素材数量调整）
    :param fps: 视频帧率（默认25，推理生成推荐25/30帧，避免画面卡顿）
    :param video_size: 视频分辨率（竖屏短视频可设为(1080, 1920)）
    :param pix_fmt: 像素格式（默认yuv420p，避免视频在手机/电脑上无法播放）
    :return: 合成成功返回True，失败返回False
    """
    # 1. 检查输入文件/目录是否存在
    if not os.path.exists(image_dir):
        logging.error(f"图片序列目录不存在：{image_dir}")
        return False
    if not os.path.exists(audio_path):
        logging.error(f"音频文件不存在：{audio_path}")
        return False
    
    # 2. 创建输出目录
    output_dir = os.path.dirname(output_video)
    if not create_dir(output_dir):
        return False
    
    # 3. 计算图片帧率（1张图显示frame_duration秒，帧率=1/frame_duration）
    image_fps = 1.0 / frame_duration
    
    # 4. 构建FFmpeg命令（按数字顺序读取图片序列）
    command = [
        "ffmpeg",
        "-framerate", str(image_fps),  # 图片帧率（控制单张显示时长）
        "-i", os.path.join(image_dir, "%d.jpg"),  # 按1.jpg、2.jpg...顺序读取
        "-i", audio_path,              # 输入音频
        "-c:v", "libx264",            # 视频编码（MP4通用，兼容性最强）
        "-r", str(fps),                # 视频最终帧率
        "-s", f"{video_size[0]}x{video_size[1]}",  # 视频分辨率
        "-pix_fmt", pix_fmt,           # 兼容所有播放器
        "-shortest",                   # 视频时长与音频保持一致（避免视频过长/过短）
        "-c:a", "aac",                 # 音频编码
        "-b:a", "192k",                # 音频比特率
        "-y",                          # 覆盖输出
        output_video
    ]
    
    # 执行命令并返回结果
    return run_ffmpeg_command(command)

4. 单张图片 + 音频合成短视频函数（推理中高频）

适配 AI 推理生成单张封面图 + 配音的场景（如 AI 封面生成 + AI 配音），快速生成竖屏 / 横屏短视频，可直接用于抖音、视频号等平台发布，是轻量化视频生成的高频函数。

def single_image_audio_to_video(
    image_path: str,
    audio_path: str,
    output_video: str,
    video_size: tuple = (1080, 1920),  # 默认竖屏9:16，适配短视频平台
    pix_fmt: str = "yuv420p"
) -> bool:
    """
    推理中高频：单张图片（AI封面）+ 音频合成短视频
    :param image_path: AI推理生成的封面图路径（如./inference_output/cover.jpg）
    :param audio_path: 预处理后的配音/背景音乐路径
    :param output_video: 短视频输出路径
    :param video_size: 视频分辨率（默认竖屏1080x1920，横屏可设为(1920, 1080)）
    :param pix_fmt: 像素格式，兼容播放器（必选）
    :return: 合成成功返回True，失败返回False
    """
    # 1. 检查输入文件是否存在
    if not os.path.exists(image_path):
        logging.error(f"封面图文件不存在：{image_path}")
        return False
    if not os.path.exists(audio_path):
        logging.error(f"音频文件不存在：{audio_path}")
        return False
    
    # 2. 创建输出目录
    output_dir = os.path.dirname(output_video)
    if not create_dir(output_dir):
        return False
    
    # 3. 构建FFmpeg命令（单张图片循环播放）
    command = [
        "ffmpeg",
        "-loop", "1",                  # 单张图片循环播放（核心参数）
        "-i", image_path,              # 输入封面图
        "-i", audio_path,              # 输入音频
        "-c:v", "libx264",            # 视频编码
        "-tune", "stillimage",         # 针对静态图片优化编码（提升画质、减少体积）
        "-s", f"{video_size[0]}x{video_size[1]}",  # 视频分辨率
        "-pix_fmt", pix_fmt,           # 兼容播放器
        "-shortest",                   # 视频时长与音频一致
        "-c:a", "aac",                 # 音频编码
        "-b:a", "192k",                # 音频比特率
        "-y",                          # 覆盖输出
        output_video
    ]
    
    # 执行命令并返回结果
    return run_ffmpeg_command(command)

5. 视频批量优化函数（推理后）

批量压缩推理生成的视频、调整分辨率，解决视频体积过大、尺寸不符等问题，适配 Pipeline 后续部署或平台发布需求（如短视频平台尺寸限制、服务器存储优化）。

def batch_optimize_video(
    input_dir: str,
    output_dir: str,
    crf: int = 23,                  # 画质控制（18-28，越小越清晰，体积越大）
    preset: str = "medium",         # 编码速度（medium/ slow/ fast）
    target_size: tuple = None,      # 目标分辨率（None表示不调整）
    audio_bitrate: str = "192k"     # 音频比特率
) -> bool:
    """
    推理后优化：批量压缩视频、调整分辨率
    :param input_dir: 推理生成的视频目录（批量处理）
    :param output_dir: 优化后视频保存目录
    :param crf: 画质控制参数（默认23，兼顾画质和体积，短视频推荐23-25）
    :param preset: 编码速度（默认medium，slow体积更小、速度慢；fast速度快、体积略大）
    :param target_size: 目标分辨率（如(1080, 1920)，None不调整）
    :param audio_bitrate: 音频比特率（默认192k，无需过高，避免增加体积）
    :return: 批量优化成功返回True，失败返回False
    """
    # 1. 创建输出目录
    if not create_dir(output_dir):
        return False
    
    # 2. 遍历输入目录的视频文件，过滤非视频文件
    video_extensions = [".mp4", ".mov", ".avi", ".mkv"]
    for filename in os.listdir(input_dir):
        if not any(filename.lower().endswith(ext) for ext in video_extensions):
            logging.warning(f"跳过非视频文件：{filename}")
            continue
        
        # 构建输入输出路径
        input_path = os.path.join(input_dir, filename)
        output_path = os.path.join(output_dir, filename)
        
        # 构建FFmpeg命令（压缩+调整尺寸）
        command = [
            "ffmpeg", "-i", input_path,
            "-c:v", "libx264", "-crf", str(crf), "-preset", preset,
            "-c:a", "aac", "-b:a", audio_bitrate,
            "-y", output_path
        ]
        # 调整分辨率（若指定目标尺寸）
        if target_size and len(target_size) == 2:
            command.extend(["-s", f"{target_size[0]}x{target_size[1]}"])
        
        # 执行命令，单个视频失败不中断批量处理
        if not run_ffmpeg_command(command):
            logging.warning(f"单个视频优化失败：{input_path}")
    
    logging.info(f"视频批量优化完成，输出目录：{output_dir}")
    return True

6. 多视频拼接函数（推理后）

将 AI 分片段推理生成的多个视频（如长视频分批次推理）拼接成完整成品，适配长视频生成场景，支持无损快速拼接（前提是所有视频格式、分辨率、帧率一致）。

def concat_videos(
    input_dir: str,
    output_video: str,
    video_ext: str = "mp4"
) -> bool:
    """
    推理后拼接：将多个推理生成的视频片段拼接成完整视频
    :param input_dir: 推理生成的视频片段目录（按文件名顺序拼接）
    :param output_video: 拼接后完整视频输出路径
    :param video_ext: 视频文件后缀（默认mp4，需确保所有片段格式一致）
    :return: 拼接成功返回True，失败返回False
    """
    # 1. 检查输入目录是否存在
    if not os.path.exists(input_dir):
        logging.error(f"视频片段目录不存在：{input_dir}")
        return False
    
    # 2. 筛选目标格式的视频文件，按文件名排序（确保拼接顺序正确）
    video_files = [
        os.path.join(input_dir, f)
        for f in os.listdir(input_dir)
        if f.lower().endswith(f".{video_ext.lower()}")
    ]
    if not video_files:
        logging.error(f"未找到{video_ext}格式的视频片段：{input_dir}")
        return False
    # 按文件名排序（确保AI推理片段顺序正确，如1.mp4、2.mp4...）
    video_files.sort()
    
    # 3. 创建临时拼接列表文件（FFmpeg concat功能必需）
    list_file = os.path.join(input_dir, "video_list.txt")
    try:
        with open(list_file, "w", encoding="utf-8") as f:
            for video in video_files:
                f.write(f"file '{video}'\n")  # 写入视频路径，格式必须正确
        logging.info(f"拼接列表文件创建成功：{list_file}")
    except Exception as e:
        logging.error(f"拼接列表文件创建失败：{str(e)}")
        return False
    
    # 4. 创建输出目录
    output_dir = os.path.dirname(output_video)
    if not create_dir(output_dir):
        os.remove(list_file)  # 失败时删除临时文件，避免残留
        return False
    
    # 5. 构建FFmpeg拼接命令（无损拼接，需确保所有视频格式一致）
    command = [
        "ffmpeg", "-f", "concat", "-safe", "0",
        "-i", list_file, "-c", "copy", "-y", output_video
    ]
    
    # 6. 执行命令，完成后删除临时列表文件（无论成功与否）
    try:
        success = run_ffmpeg_command(command)
        return success
    finally:
        if os.path.exists(list_file):
            os.remove(list_file)
            logging.info(f"临时拼接列表文件已删除：{list_file}")

四、完整视频生成推理 Pipeline（Python 调用示例）

将上述所有函数串联，实现 "AI 推理素材→预处理→合成→优化→拼接" 的全自动化 Pipeline，可直接嵌入你的 AI 视频生成项目中，只需修改路径和参数即可运行。

def video_generation_pipeline(
    # AI推理输出路径（需根据你的项目实际路径修改）
    ai_image_dir: str = "./inference_output/images",
    ai_audio_path: str = "./inference_output/audio/original.wav",
    # 预处理输出路径
    pre_image_dir: str = "./preprocessed/images",
    pre_audio_path: str = "./preprocessed/audio/processed.aac",
    # 合成视频路径
    infer_video_path: str = "./inference_result/infer_video.mp4",
    # 优化后视频路径
    optimized_dir: str = "./optimized_result",
    # 最终拼接视频路径（多片段推理时启用）
    final_video_path: str = "./final_result/full_video.mp4",
    # 可配置参数（适配你的推理场景）
    frame_duration: float = 3.0,    # 每张图片显示时长（秒）
    video_size: tuple = (1080, 1920),  # 视频分辨率（竖屏短视频）
    crf: int = 23                   # 视频画质控制
) -> bool:
    """
    完整视频生成推理Pipeline：串联所有函数，实现自动化流转
    :return: 整个Pipeline执行成功返回True，失败返回False
    """
    logging.info("=" * 50)
    logging.info("开始执行视频生成推理Pipeline")
    logging.info("=" * 50)
    
    # 步骤1：图片预处理（AI推理图片序列→统一格式、尺寸）
    logging.info("【步骤1/5】开始图片预处理...")
    if not preprocess_images(
        input_dir=ai_image_dir,
        output_dir=pre_image_dir,
        target_format="jpg",
        target_size=video_size
    ):
        logging.error("【步骤1/5】图片预处理失败，Pipeline中断")
        return False
    
    # 步骤2：音频预处理（AI推理音频→转AAC格式）
    logging.info("【步骤2/5】开始音频预处理...")
    if not preprocess_audio(
        input_path=ai_audio_path,
        output_path=pre_audio_path,
        bitrate="192k"
    ):
        logging.error("【步骤2/5】音频预处理失败，Pipeline中断")
        return False
    
    # 步骤3：图片序列+音频合成视频（推理核心步骤）
    # 若为单张图片，替换为 single_image_audio_to_video 函数
    logging.info("【步骤3/5】开始合成推理视频...")
    if not images_audio_to_video(
        image_dir=pre_image_dir,
        audio_path=pre_audio_path,
        output_video=infer_video_path,
        frame_duration=frame_duration,
        video_size=video_size,
        fps=25
    ):
        logging.error("【步骤3/5】视频合成失败，Pipeline中断")
        return False
    
    # 步骤4：视频优化（压缩体积、调整尺寸）
    logging.info("【步骤4/5】开始视频优化...")
    if not batch_optimize_video(
        input_dir=os.path.dirname(infer_video_path),
        output_dir=optimized_dir,
        crf=crf,
        target_size=video_size
    ):
        logging.error("【步骤4/5】视频优化失败，Pipeline中断")
        return False
    
    # 步骤5：多视频拼接（若为单片段推理，可注释该步骤）
    logging.info("【步骤5/5】开始视频拼接...")
    if not concat_videos(
        input_dir=optimized_dir,
        output_video=final_video_path,
        video_ext="mp4"
    ):
        logging.error("【步骤5/5】视频拼接失败，Pipeline中断")
        return False
    
    logging.info("=" * 50)
    logging.info("视频生成推理Pipeline执行完成！")
    logging.info(f"最终成品视频：{final_video_path}")
    logging.info("=" * 50)
    return True

# 调用Pipeline（直接运行，适配你的项目路径和参数）
if __name__ == "__main__":
    # 可根据你的AI推理场景，修改以下参数
    pipeline_success = video_generation_pipeline(
        ai_image_dir="./inference_output/images",  # AI推理图片序列目录
        ai_audio_path="./inference_output/audio/original.wav",  # AI推理音频路径
        video_size=(1080, 1920),  # 竖屏短视频（可改为(1920, 1080)横屏）
        frame_duration=2.5,        # 每张图片显示2.5秒（根据素材数量调整）
        crf=24                     # 略压缩，减小体积（不影响视觉效果）
    )
    # 根据Pipeline执行结果，做后续处理（如通知、上传、存储等）
    if not pipeline_success:
        logging.error("Pipeline执行失败，请检查日志排查问题")

调用说明

1. 修改video_generation_pipeline函数中的路径参数，适配你的 AI 推理输出路径（如ai_image_dir、ai_audio_path）。
2. 根据需求调整可配置参数（如video_size、frame_duration、crf），无需修改函数内部逻辑。
3. 若为单张图片合成视频，将步骤 3 的images_audio_to_video替换为single_image_audio_to_video，并修改对应参数。
4. 若为单片段推理（无需拼接），注释步骤 5 的concat_videos调用即可。

五、Pipeline 集成注意事项（关键！）

1. 参数适配：所有函数的参数（分辨率、帧率、画质）需与你的 AI 推理模型输出匹配，避免出现 "图片分辨率与视频尺寸不匹配""音频格式不兼容" 等问题。
2. 异常处理：函数内置异常捕获，单个操作失败（如单个图片预处理失败）不会中断整个 Pipeline，但会输出警告日志，便于调试和问题定位。
3. 跨平台兼容：函数使用os.path处理路径（避免硬编码斜杠），适配 Windows/Mac/Linux 环境；FFmpeg 命令不使用shell=True，避免安全风险和跨平台兼容性问题。
4. 批量场景优化：若需批量处理 100 + 视频 / 图片，可在preprocess_images和batch_optimize_video函数中加入多线程（需注意 FFmpeg 并发资源占用，避免 GPU/CPU 过载）。
5. 日志配置：可修改logging.basicConfig，添加文件日志输出（如FileHandler），便于 Pipeline 长期运行后的问题排查和日志追溯。
6. 格式一致性：多视频拼接时，需确保所有视频的编码、分辨率、帧率一致（可通过预处理和优化步骤统一格式），否则会出现拼接失败。

六、常见问题排查（Pipeline 部署必看）

Q1：函数调用时报 "FFmpeg 命令执行失败"？

• 现象：日志输出 "FFmpeg 命令执行失败"，未生成目标文件。
• 原因：① FFmpeg 未安装或环境变量未配置；② 输入路径错误（AI 推理未生成素材）；③ 参数错误（如分辨率格式错误）。
• 解决方案：
  1. 终端输入ffmpeg -version，确认 FFmpeg 安装成功。
  2. 检查输入路径（如ai_image_dir、ai_audio_path），确保文件 / 目录存在。
  3. 核对参数格式（如分辨率需为(宽, 高)，如(1080, 1920)）。

Q2：合成的视频没有声音？

• 现象：视频生成成功，但播放时无声音。
• 原因：① 音频路径错误；② 音频格式未转为 AAC；③ 合成命令缺少音频编码参数。
• 解决方案：
  1. 检查preprocess_audio函数的输出路径，确保音频转换成功。
  2. 确认合成函数（images_audio_to_video/single_image_audio_to_video）包含-c:a aac参数。
  3. 用ffmpeg -i 音频路径检查音频文件是否正常。

Q3：图片序列合成视频时顺序混乱？

• 现象：视频中图片顺序与 AI 推理输出的顺序不一致。
• 原因：图片文件名不是连续数字（如 1.jpg、2.jpg...），FFmpeg 按文件名排序时出现混乱。
• 解决方案：
  1. 确保 AI 推理输出的图片文件名为连续数字（如 1.jpg、2.jpg、3.jpg...）。
  2. 若文件名混乱，可在preprocess_images函数中添加图片重命名逻辑，统一命名为连续数字。

Q4：批量处理时速度太慢？

• 现象：批量处理大量视频 / 图片时，耗时过长。
• 原因：① 编码速度参数preset设置为slow；② 未启用并发处理。
• 解决方案：
  1. 调整batch_optimize_video函数的preset参数为fast（牺牲少量画质，提升编码速度）。
  2. 在批量处理函数中加入多线程（如threading模块），并发处理多个文件（注意控制并发数量，避免资源过载）。

Q5：视频生成后无法播放？

• 现象：视频文件存在，但播放器无法打开或播放卡顿。
• 原因：① 像素格式未设置为yuv420p；② 视频编码不兼容。
• 解决方案：
  1. 确保合成函数中包含-pix_fmt yuv420p参数（兼容所有播放器）。
  2. 检查视频编码是否为libx264（MP4 通用编码），避免使用冷门编码。

七、总结

无论是 AI 图片序列合成视频、单张封面 + 配音生成短视频，还是批量视频优化、多片段拼接，这套函数都能满足需求。你只需将函数复制到你的项目中，修改对应路径和参数，即可快速实现视频生成推理的自动化流转，省去重复编码和调试的时间。

后续可根据实际场景优化函数，如加入多线程并发处理、实时推理日志输出、GPU 加速等功能。如果需要适配特定场景（如实时视频生成、批量生成 100 + 短视频），可在评论区留言，补充对应的优化方案。

收藏本文，下次搭建视频生成推理 Pipeline 时，直接复制复用，高效落地你的 AI 视频项目！