批量添加片头片尾

要解决的问题

给数百到数千个课程视频批量添加统一片头片尾时，常遇到三类问题：一是拼接后播放到拼接点卡住，根源是非单调 PTS/DTS、timebase 不一致或 SPS/PPS 参数集突变；二是编码参数不匹配导致 concat+copy 失败，或音频采样率/声道不一致引发音画不同步；三是跨平台环境配置麻烦——Windows 下找不到合适的 ffmpeg、路径含空格报错，macOS 下易误用 homebrew 版本的 ffmpeg（常出现 x265 库不匹配）。此外，处理后时长异常、片头片尾重复添加、Excel 报告课程名提取错误也是常见坑。

核心能力

• 跨平台 ffmpeg 检测：按 FFMPEG_PATH → imageio_ffmpeg 捆绑版 → 系统 PATH 的优先级查找可用 ffmpeg，自动适配 Windows/macOS/Linux
• 按参数分组标准化：根据分辨率、编码、帧率、音频参数、色彩空间、pix_fmt 分组，每组只标准化一次并缓存，减少重复处理
• 安全拼接策略：优先用 concat demuxer + copy（无重编码，约 10 秒/视频）；失败时用 concat filter + libx264 ultrafast 重编码，避免 libx265 的极慢速度
• 三阶递进修复：针对异常视频，先修复时间戳 + copy（约 5 秒/视频），再同时修复片头片尾和原视频时间戳 + copy（约 8 秒/视频），最后用重编码兜底
• 自动质检与报告：检查处理后视频时长，生成异常列表 CSV；用 openpyxl 生成含课程统计和视频明细的 Excel 报告

关键流程

1. 环境检查：确认 ffmpeg 路径（优先 imageio_ffmpeg）和目录结构，Windows 下临时目录用 %TEMP%\batch_intro_outro
2. 视频分析：扫描原始视频的分辨率、编码、帧率、音频参数、色彩空间、Profile/Level，指导标准化方向
3. 标准化处理：用 scripts/standardize.py 分两步：先统一分辨率/帧率/编码/音频，再标准化时间戳（-fflags +genpts+igndts、剥离 SEI、统一 timebase）
4. 批量拼接：用 scripts/batch_process.py 生成 concat_list.txt，执行时加 -map_metadata -1、-video_track_timescale 90000 等参数防卡顿
5. 质检修复：scripts/check_durations.py 用「实际时长 >= 原时长 + 5s」的规则判断异常，scripts/fix_abnormal.py 按 A→B→C 策略修复
6. 生成报告：scripts/gen_report.py 按「课程名-高等学历继续教育」提取课程名，按最后一个括号提取主讲老师，生成 Excel

适用边界与注意点

• 4K 视频避免重编码，优先用策略 A/B（修复时间戳 + copy）
• 脚本需根据实际路径调整少量变量（如 INTRO_FILE、OUTRO_FILE、BASE_DIR），核心逻辑已封装
• imageio_ffmpeg 不提供 ffprobe，获取时长用 ffmpeg -i file 2>&1 | grep Duration
• 处理前需检查目标文件是否已存在，避免重复添加片头片尾
• Windows 长路径（>260 字符）需在注册表启用 LongPathsEnabled
• 所有路径用 pathlib.Path 处理，避免 Windows 路径含空格或特殊字符导致报错