编码与格式 / 系统课时

综合项目:视频处理流水线

综合项目:视频处理流水线

本课把常见的 FFmpeg 操作组合成一条可重复执行的流水线:先探测输入媒体,再生成两种 MP4 规格、标准化音频、提取封面并输出 HLS,最终得到结构清晰、便于交付的构建目录。

学习目标

  • 设计媒体探测、转码、音频、封面和 HLS 的执行顺序
  • 使用 Python 调用 FFmpeg,形成可重复运行的处理脚本
  • 根据产物目录和基础检查结果判断流水线是否成功

流水线设计

流水线应先用 ffprobe 固化输入信息,再执行彼此独立的产物任务。探测结果既能用于判断是否存在音频流,也能留作后续质量验证的基线;任何一步失败时,脚本立即停止,避免把残缺文件继续交付。

视频处理流水线数据流

这里采用“探测一次、按产物分别执行”的结构。它比一条超长命令更容易定位失败步骤,也方便后续只重跑封面、HLS 或某一种清晰度。

实现完整流水线

运行环境需要 Python 3.10+、ffmpeg 与 ffprobe,并确保三者已经加入系统命令路径。以下脚本接收输入文件和构建目录两个参数;输入没有音频流时,会跳过独立音频文件,并为视频产物使用 -an。

python
from __future__ import annotations

import json
import shutil
import subprocess
import sys
from pathlib import Path

def run(command: list[str]) -> None:
    # 所有子命令统一采用失败即停止,避免继续生成残缺产物。
    result = subprocess.run(command, text=True)
    if result.returncode != 0:
        raise SystemExit(result.returncode)

def encode_mp4(source: Path, target: Path, height: int, crf: int, has_audio: bool) -> None:
    command = [
        'ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',
        '-i', str(source),
        '-map', '0:v:0',
        '-vf', f'scale=-2:{height}:flags=lanczos',
        '-c:v', 'libx264', '-preset', 'medium', '-crf', str(crf),
        '-pix_fmt', 'yuv420p', '-movflags', '+faststart'
    ]
    if has_audio:
        command += [
            '-map', '0:a:0', '-c:a', 'aac', '-b:a', '128k',
            '-af', 'loudnorm=I=-16:LRA=11:TP=-1.5'
        ]
    else:
        command += ['-an']
    command.append(str(target))
    run(command)

def main() -> None:
    if len(sys.argv) not in (2, 3):
        raise SystemExit('用法: python3 pipeline.py <输入视频> [构建目录]')

    source = Path(sys.argv[1])
    root = Path(sys.argv[2]) if len(sys.argv) == 3 else Path('build')
    output = root / 'output'
    hls = output / 'hls'

    for program in ('ffmpeg', 'ffprobe'):
        if shutil.which(program) is None:
            raise SystemExit(f'未找到命令: {program}')
    if not source.is_file():
        raise SystemExit(f'输入文件不存在: {source}')

    hls.mkdir(parents=True, exist_ok=True)

    # 先保存原始探测信息,后续验证可直接使用同一份基线。
    probe_result = subprocess.run(
        ['ffprobe', '-v', 'error', '-show_format', '-show_streams', '-of', 'json', str(source)],
        check=True, capture_output=True, text=True
    )
    probe_data = json.loads(probe_result.stdout)
    (root / 'probe.json').write_text(
        json.dumps(probe_data, ensure_ascii=False, indent=2),
        encoding='utf-8'
    )
    has_video = any(stream.get('codec_type') == 'video' for stream in probe_data.get('streams', []))
    has_audio = any(stream.get('codec_type') == 'audio' for stream in probe_data.get('streams', []))
    if not has_video:
        raise SystemExit('输入文件缺少视频流')

    # 两种 MP4 规格独立生成,便于单独重试或替换参数。
    encode_mp4(source, output / 'video-1080p.mp4', 1080, 22, has_audio)
    encode_mp4(source, output / 'video-720p.mp4', 720, 23, has_audio)

    # 只有输入存在音频流时,才生成独立的响度标准化音频。
    if has_audio:
        run([
            'ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',
            '-i', str(source), '-map', '0:a:0', '-vn',
            '-c:a', 'aac', '-b:a', '128k',
            '-af', 'loudnorm=I=-16:LRA=11:TP=-1.5',
            str(output / 'audio-normalized.m4a')
        ])

    run([
        'ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',
        '-ss', '00:00:01', '-i', str(source),
        '-frames:v', '1', '-q:v', '2', str(output / 'cover.jpg')
    ])

    # HLS 使用固定分片命名,便于完整性检查和整体替换。
    hls_command = [
        'ffmpeg', '-hide_banner', '-loglevel', 'error', '-y',
        '-i', str(source), '-map', '0:v:0',
        '-vf', 'scale=-2:720:flags=lanczos',
        '-c:v', 'libx264', '-preset', 'medium', '-crf', '23',
        '-pix_fmt', 'yuv420p'
    ]
    if has_audio:
        hls_command += [
            '-map', '0:a:0', '-c:a', 'aac', '-b:a', '128k',
            '-af', 'loudnorm=I=-16:LRA=11:TP=-1.5'
        ]
    else:
        hls_command += ['-an']
    hls_command += [
        '-f', 'hls', '-hls_time', '6', '-hls_playlist_type', 'vod',
        '-hls_segment_filename', str(hls / 'segment_%03d.ts'),
        str(hls / 'index.m3u8')
    ]
    run(hls_command)

    for path in sorted(item for item in root.rglob('*') if item.is_file()):
        print(path.as_posix())

if __name__ == '__main__':
    main()

预期结果

text
build/probe.json
build/output/audio-normalized.m4a
build/output/cover.jpg
build/output/hls/index.m3u8
build/output/hls/segment_000.ts
build/output/hls/segment_<ID>.ts
build/output/video-1080p.mp4
build/output/video-720p.mp4

执行方式为 python3 pipeline.py input.mp4 build。当输入没有音频时,不会生成 audio-normalized.m4a;分片数量和 <ID> 会随视频时长变化。

运行、验收与边界

先确认脚本返回码为 0,再检查 probe.json 是否可读、两个 MP4 是否能正常播放、封面是否来自有效画面,以及 index.m3u8 引用的所有 TS 文件是否存在。目录存在不代表产物一定有效,因此不能只以“文件已生成”作为验收结论。

转码规格应与业务场景一致。示例固定输出 H.264、AAC 和 yuv420p,适合常见网页与移动端播放;若输入分辨率低于目标高度,当前脚本会放大画面,生产环境通常应增加“只缩小、不放大”的尺寸规则。

  • 超短视频可能在 1 秒位置提取不到封面,可改为按总时长比例选择时间点。
  • 需要多码率自适应播放时,应分别生成多个 HLS 变体,并增加主播放列表。
  • 大批量任务应把每个产物步骤记录为独立状态,失败后只重试未完成步骤,而不是无条件全部重跑。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

综合项目:视频处理流水线

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通