编码与格式 / 系统课时

验证输出与交付质量

验证输出与交付质量

本课建立一套可执行的交付验证流程:先检查文件与媒体流,再核对编码、分辨率和时长,随后执行完整解码扫描、HLS 分片检查与哈希计算,最后补充真实设备播放测试。

学习目标

  • 按固定顺序检查容器、媒体流、参数、时长与文件完整性
  • 编写脚本自动验证 MP4 和 HLS 交付产物
  • 形成可复用的人工兼容性检查与交付清单

验证顺序

质量验证应从“能否读取”开始,再逐步检查“是否符合规格”和“能否完整播放”。若容器或媒体流已经损坏,继续做分辨率、码率等检查没有意义;发现失败项时应停止交付,并回到对应生产步骤修复。

视频交付质量验证流程

自动检查适合发现结构化问题,人工播放则负责发现黑屏、花屏、音画不同步、首帧等待过长等体验问题,两者不能互相替代。

自动化质量检查

运行环境需要 Python 3.10+、ffmpeg 与 ffprobe。下面的脚本验证源文件、720p MP4 和 HLS 播放列表。示例规格为 H.264、AAC、1280×720,允许源文件与输出文件最多相差 1 秒;它还会调用 FFmpeg 完整解码 MP4 与 HLS,并为 MP4 计算 SHA-256。

python
from __future__ import annotations

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

EXPECTED_VIDEO_CODEC = 'h264'
EXPECTED_AUDIO_CODEC = 'aac'
EXPECTED_WIDTH = 1280
EXPECTED_HEIGHT = 720
MAX_DURATION_DRIFT_SECONDS = 1.0

def probe(path: Path) -> dict:
    # 只提取交付判断需要的字段,减少报告噪声。
    result = subprocess.run(
        [
            'ffprobe', '-v', 'error',
            '-show_entries', 'format=duration',
            '-show_entries', 'stream=codec_type,codec_name,width,height,pix_fmt',
            '-of', 'json', str(path)
        ],
        capture_output=True, text=True
    )
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip() or f'ffprobe 无法解析 {path}')
    return json.loads(result.stdout)

def first_stream(metadata: dict, codec_type: str) -> dict | None:
    return next(
        (stream for stream in metadata.get('streams', []) if stream.get('codec_type') == codec_type),
        None
    )

def duration_seconds(metadata: dict) -> float:
    return float(metadata.get('format', {}).get('duration', 0.0))

def decode_scan(path: Path) -> str | None:
    # 完整解码能发现仅靠容器元数据无法识别的数据损坏。
    result = subprocess.run(
        ['ffmpeg', '-v', 'error', '-i', str(path), '-f', 'null', '-'],
        capture_output=True, text=True
    )
    return None if result.returncode == 0 else result.stderr.strip()

def sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open('rb') as file:
        for block in iter(lambda: file.read(1024 * 1024), b''):
            digest.update(block)
    return digest.hexdigest()

def hls_segments(playlist: Path) -> tuple[list[Path], list[str]]:
    # 播放列表中的非注释行在本项目中都是相对路径 TS 分片。
    references = [
        line.strip()
        for line in playlist.read_text(encoding='utf-8').splitlines()
        if line.strip() and not line.startswith('#')
    ]
    segments = [playlist.parent / reference for reference in references]
    missing = [path.name for path in segments if not path.is_file() or path.stat().st_size == 0]
    return segments, missing

def main() -> None:
    if len(sys.argv) != 4:
        raise SystemExit('用法: python3 verify_delivery.py <源文件> <输出MP4> <HLS播放列表>')

    for program in ('ffmpeg', 'ffprobe'):
        if shutil.which(program) is None:
            raise SystemExit(f'未找到命令: {program}')

    source = Path(sys.argv[1])
    output = Path(sys.argv[2])
    playlist = Path(sys.argv[3])
    errors: list[str] = []

    missing_files = [
        str(path) for path in (source, output, playlist)
        if not path.is_file() or path.stat().st_size == 0
    ]
    if missing_files:
        errors.append(f'文件不存在或为空: {missing_files}')
        print(json.dumps({'status': 'FAIL', 'errors': errors}, ensure_ascii=False, indent=2))
        raise SystemExit(1)

    try:
        source_meta = probe(source)
        output_meta = probe(output)
    except RuntimeError as error:
        errors.append(str(error))
        print(json.dumps({'status': 'FAIL', 'errors': errors}, ensure_ascii=False, indent=2))
        raise SystemExit(1)
    source_duration = duration_seconds(source_meta)
    output_duration = duration_seconds(output_meta)
    video = first_stream(output_meta, 'video')
    source_audio = first_stream(source_meta, 'audio')
    output_audio = first_stream(output_meta, 'audio')

    if video is None:
        errors.append('输出文件缺少视频流')
    else:
        if video.get('codec_name') != EXPECTED_VIDEO_CODEC:
            errors.append(f'视频编码应为 {EXPECTED_VIDEO_CODEC}')
        if (video.get('width'), video.get('height')) != (EXPECTED_WIDTH, EXPECTED_HEIGHT):
            errors.append(f'分辨率应为 {EXPECTED_WIDTH}x{EXPECTED_HEIGHT}')
        if video.get('pix_fmt') != 'yuv420p':
            errors.append('像素格式应为 yuv420p')

    if source_audio and output_audio is None:
        errors.append('源文件包含音频,但输出文件缺少音频流')
    if output_audio and output_audio.get('codec_name') != EXPECTED_AUDIO_CODEC:
        errors.append(f'音频编码应为 {EXPECTED_AUDIO_CODEC}')
    if abs(source_duration - output_duration) > MAX_DURATION_DRIFT_SECONDS:
        errors.append('输出时长偏差超过允许阈值')

    mp4_decode_error = decode_scan(output)
    hls_decode_error = decode_scan(playlist)
    if mp4_decode_error:
        errors.append(f'MP4 解码失败: {mp4_decode_error}')
    if hls_decode_error:
        errors.append(f'HLS 解码失败: {hls_decode_error}')

    segments, missing_segments = hls_segments(playlist)
    if not segments:
        errors.append('HLS 播放列表没有媒体分片')
    if missing_segments:
        errors.append(f'HLS 分片缺失或为空: {missing_segments}')

    # 报告同时用于人工审阅和持续集成的返回码判断。
    report = {
        'status': 'PASS' if not errors else 'FAIL',
        'sourceDurationSeconds': round(source_duration, 3),
        'outputDurationSeconds': round(output_duration, 3),
        'videoCodec': video.get('codec_name') if video else None,
        'resolution': '{}x{}'.format(video.get('width'), video.get('height')) if video else None,
        'audioCodec': output_audio.get('codec_name') if output_audio else None,
        'hlsSegmentCount': len(segments),
        'sha256': sha256(output),
        'errors': errors
    }
    print(json.dumps(report, ensure_ascii=False, indent=2))
    raise SystemExit(0 if not errors else 1)

if __name__ == '__main__':
    main()

预期输出

json
{
  "status": "PASS",
  "sourceDurationSeconds": "<SOURCE_DURATION>",
  "outputDurationSeconds": "<OUTPUT_DURATION>",
  "videoCodec": "h264",
  "resolution": "1280x720",
  "audioCodec": "aac",
  "hlsSegmentCount": "<COUNT>",
  "sha256": "<SHA256>",
  "errors": []
}

使用 python3 verify_delivery.py input.mp4 build/output/video-720p.mp4 build/output/hls/index.m3u8 运行。时长、分片数量和哈希值属于动态数据,实际结果会不同;脚本返回码为 0 才表示自动检查通过。

人工检查与交付清单

检查项 操作方式 通过标准
起播与拖动 从头播放并随机拖动到中段、尾段 无黑屏、卡死或异常回退
音画同步 观察对白、击掌或明显节奏点 口型与声音无可感知偏移
多端兼容 至少覆盖桌面浏览器和一台真实移动设备 MP4 与 HLS 均能正常播放
网络波动 在限速或弱网环境播放 HLS 能继续加载,失败时有明确重试行为
画面与声音 检查首帧、亮度、声道和响度 无花屏、静音、爆音或单声道异常

人工检查应记录设备、系统、播放器、网络条件和结论。只写“已播放正常”无法在问题复现时提供有效证据。

交付包至少应包含最终媒体文件、HLS 播放列表与全部分片、封面、probe.json、自动验证报告、SHA-256 值和规格说明。文件名、目录结构与版本号应固定,避免接收方依赖临时命名。

交付前还要确认没有零字节文件、临时文件、旧版本分片或未引用资源。重新生成 HLS 后必须整体替换目录,不能只覆盖播放列表,否则可能混入上一版本的 TS 文件。

参数不符应回到转码配置修复;时长异常应检查截取参数、时间戳和音频滤镜;完整解码失败通常说明文件截断、分片缺失或编码数据损坏;只有特定终端失败时,则优先检查该终端支持的编码、封装、像素格式和网络策略。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

验证输出与交付质量

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

登录哪都通