编码与格式 / 系统课时
验证输出与交付质量
验证输出与交付质量
本课建立一套可执行的交付验证流程:先检查文件与媒体流,再核对编码、分辨率和时长,随后执行完整解码扫描、HLS 分片检查与哈希计算,最后补充真实设备播放测试。
学习目标
- 按固定顺序检查容器、媒体流、参数、时长与文件完整性
- 编写脚本自动验证 MP4 和 HLS 交付产物
- 形成可复用的人工兼容性检查与交付清单
验证顺序
质量验证应从“能否读取”开始,再逐步检查“是否符合规格”和“能否完整播放”。若容器或媒体流已经损坏,继续做分辨率、码率等检查没有意义;发现失败项时应停止交付,并回到对应生产步骤修复。

自动检查适合发现结构化问题,人工播放则负责发现黑屏、花屏、音画不同步、首帧等待过长等体验问题,两者不能互相替代。
自动化质量检查
运行环境需要 Python 3.10+、ffmpeg 与 ffprobe。下面的脚本验证源文件、720p MP4 和 HLS 播放列表。示例规格为 H.264、AAC、1280×720,允许源文件与输出文件最多相差 1 秒;它还会调用 FFmpeg 完整解码 MP4 与 HLS,并为 MP4 计算 SHA-256。
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()预期输出
{
"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 文件。
参数不符应回到转码配置修复;时长异常应检查截取参数、时间戳和音频滤镜;完整解码失败通常说明文件截断、分片缺失或编码数据损坏;只有特定终端失败时,则优先检查该终端支持的编码、封装、像素格式和网络策略。