faceswap 视频处理库 lib.video 详解：从视频校验、按帧索引随机读取到音视频混流的完整实现

本篇技术文章围绕 faceswap 仓库中 docs/full/lib/video.rst 所对应的 API 文档主体——视频工具模块 lib/video.py 展开。该模块是 faceswap 全流水线中所有视频输入的"第一入口"与所有视频输出的"最后出口"，涵盖视频格式校验、帧数统计、帧元信息解析、基于关键帧定位的任意帧索引读取，以及以源视频为参考的音视频混流编码。读完本文后，你可以理解 faceswap 如何在不对视频做预拆帧（不生成临时图片文件夹）的情况下直接处理视频文件，并知道如何在该库之上构建自定义的帧读取与视频合成逻辑。

一、模块定位与整体结构

lib/video.py 的模块 docstring 为一句话：Utilities for working with videos。从源码结构看，整个模块仅依赖少数几个核心库：av（PyAV，FFmpeg 的 Python 绑定）、ffmpeg（ffmpeg-python，用于定位 ffmpeg 可执行文件）、numpy 与 tqdm（进度条），并在 lib/video.py#L14-L23 处导入、通过 lib/logger.py 与 lib/utils.py 中的 convert_to_secs、FaceswapError、get_module_objects 完成日志与错误体系对接。

该模块对外暴露的公共 API 共 5 个（这也是 docs/full/lib/video.rst 中 automodapi 指令 :include-all-objects: 自动收录的对象）：

对象	类型	职责	源码位置
VIDEO_EXTENSIONS	常量列表	受支持的视频扩展名白名单	lib/video.py#L35-L37
check_for_video()	函数	判断输入路径是视频文件还是文件夹	lib/video.py#L40-L64
count_frames()	函数	统计视频帧数（快速/精确两种模式）	lib/video.py#L93-L166
VideoInfo	类	收集并缓存视频的时长、帧数、PTS 与关键帧信息	lib/video.py#L169-L357
VideoReader	类	包装 PyAV 的迭代器，支持按帧索引随机读取	lib/video.py#L360-L550
VideoMux	类	将已处理帧编码回视频，并以源视频为参考混入音频	lib/video.py#L553-L824

模块末尾通过 get_module_objects(__name__)（lib/video.py#L827）将上述对象注册进 faceswap 的统一模块对象表，这是各 tools 插件通过字符串名称动态引用这些对象的机制。

二、视频扩展名白名单与输入校验

faceswap 的几乎所有入口（对齐、转换、预览）都需要先区分"用户给的是视频还是图片文件夹"。这一职责由 check_for_video() 承担：

VIDEO_EXTENSIONS = [".avi", ".flv", ".mkv", ".mov", ".mp4", ".mpeg", ".mpg", ".webm", ".wmv",
                    ".ts", ".vob"]

check_for_video(input_location) 的判定逻辑（lib/video.py#L40-L64）分三种分支：

1. 输入不是字符串，或者 os.path.isdir() 判定为目录 → 返回 False（走图片文件夹流程）；
2. 文件扩展名（小写化后）命中 VIDEO_EXTENSIONS → 返回 True；
3. 是文件但扩展名非法 → 直接抛出 FaceswapError，错误信息形如 The input file 'xxx' is not a valid video。

与之配合的 validate_video_file(file_path)（lib/video.py#L67-L89）进一步做了两件事：先 os.path.expanduser + os.path.abspath 展开为绝对路径，再校验文件真实存在且扩展名合法，最终返回展开后的规范路径。VideoInfo 与 VideoReader 的构造函数第一行都先调用它，因此任何非法路径会在打开容器之前就被拦截并给出明确报错。

三、count_frames：为什么帧数统计要提供两种模式

count_frames(filename, fast=False)（lib/video.py#L93-L166）的 docstring 里有一句关键论断："There is no guaranteed accurate way to get a count of video frames without iterating through a video and decoding every frame."（不逐帧解码就没有保证准确的帧数统计方式。）

它的实现方式值得细看，因为这是一个很有代表性的"通过子进程 + 解析 stderr 输出"的 FFMPEG 用法：

1. 构造命令行：[ffmpeg -i <filename> -map 0:v:0 ...]，只映射第一条视频流；
2. 若 fast=True，追加 -c copy（不重编码、不解码，速度极快但计数可能不精确）；
3. 以 -f null - 输出到空设备，用 subprocess.Popen 启动并逐行读取合并后的输出；
4. 从输出中解析两类信息：Duration: 行取得总时长（用于 tqdm 进度条的 total），frame= 行提取当前已处理帧数，并在每次秒级变化时刷新进度条（tqdm(desc="Analyzing Video", ...)）；
5. 进程结束后返回最后一次解析到的 frames 值。

注意该函数直接使用 ffmpeg.FFMPEG_PATH（来自 ffmpeg-python），因此运行前提是本机能找到 ffmpeg 可执行文件。源码中 # TODO look for instances of this and see if we can roll it into VideoInfo（lib/video.py#L92）表明作者计划将该逻辑并入 VideoInfo，目前 VideoInfo.count 在 fast_count=True 时正是内部调用 count_frames(self._video_file, fast=True)（lib/video.py#L231-L233）。

docstring 中给出的调用示例：

>>> filename = "/path/to/video.mp4"
>>> frame_count = count_frames(filename)

四、VideoInfo：时长、PTS 与关键帧的元信息层

VideoInfo（lib/video.py#L169-L357）是纯元信息层，不逐帧解码出像素，只回答"这个视频有多长、多少帧、关键帧在哪、每帧的时间戳是多少"。其构造函数签名：

VideoInfo(video_file,
          fast_count: bool = True,
          stream_index: int = 0,
          pts: list[int] | None = None,
          keyframes: list[int] | None = None)

各参数含义（摘自 docstring 并经源码印证）：

• video_file：视频文件完整路径，先经 validate_video_file 校验；
• fast_count：True 时用快速（可能不精确）方式统计帧数；False 时通过完整解析 PTS 得到精确帧数。若显式传入了 pts，则帧数直接取 len(pts)，不再触发任何扫描；
• stream_index：选取容器中的第几条视频流，默认第 0 条；
• pts / keyframes：允许调用方把已知的外置 PTS 数组和关键帧索引数组直接注入（转换为 np.int64 数组），避免重复解析——这在 faceswap 的 alignments 元数据场景中用于缓存复用。

其核心属性与实现要点：

1. duration（秒）：构造时由 _get_duration() 计算（lib/video.py#L285-L317）。优先取 stream.duration * stream.time_base（流级时长），失败再退化到 container.duration / 1_000_000（容器级时长）；两者都缺失时抛出 FaceswapError: ... Missing duration metadata。流获取还通过 _get_stream() 强制设置 stream.thread_type = "AUTO"（lib/video.py#L260-L283），即让 FFmpeg 自动选择帧级/场级解码线程，这是保证解析速度的一个细节。
2. count（帧数）：惰性计算。优先级为——已缓存 → 已提供 pts 则 len(pts) → fast_count=True 走 count_frames(fast=True) → 否则 len(self.pts)（精确值）。
3. pts / keyframes（np.int64 数组）：首次访问时触发 _get_pts_and_keyframes()（lib/video.py#L319-L357）。该方法用 container.decode(stream) 逐帧迭代：收集每帧的 frame.pts，若 frame.key_frame 为真则记录当前帧下标为关键帧；遇到 av.error.InvalidDataError 只告警并跳过该帧而不是中断；同时按秒级推进 tqdm 进度条。第一帧的 PTS 被记为 offset，用于把绝对 PTS 换算成相对秒数。
4. keyframes_count：缓存了关键帧数组长度，属性访问 O(1)。

从源码结构看，VideoInfo 的全部设计目标都是"少解码、可复用"：能查元数据就不解码，能注入外部数组就不重复扫描。

五、VideoReader：按帧索引随机读取视频帧的核心机制

VideoReader（lib/video.py#L360-L550）是整个模块中最具技术含量的类。它解决的问题是：转换、预览等流程并不总是按顺序读帧（例如按 frame range 处理、断点续跑、随机抽查），需要 reader.get(index) 式的随机访问，而视频容器（尤其含 P 帧的编码流）天然不支持任意位置 seek。

5.1 构造与迭代语义

构造函数参数与 VideoInfo 一致（video_file、fast_count、stream_index、pts、keyframes），内部先构建 VideoInfo 实例，再用 av.open(path, "r") 打开容器，取出第 stream_index 条视频流并设置 thread_type = "AUTO"，最后创建解码器迭代器（lib/video.py#L395-L398）。它实现了 __iter__/__next__/__len__：

• len(reader) 等价于 info.count，因此 fast_count=True 时长度只是近似值；
• __next__（lib/video.py#L436-L459）对解码器做了容错：遇到 InvalidDataError 记录告警并跳过该帧继续取下一帧；解码耗尽（StopIteration）时先调用 close() 释放 AV Container，再向上抛出 StopIteration，保证资源一定被关闭。

5.2 随机读取的关键：关键帧定位 + 顺序快进

get(index) 的完整流程（lib/video.py#L524-L550）：

target_pts = int(self._info.pts[index])     # 1. 目标帧的 PTS
self._jump_to_keyframe(index, target_pts)   # 2. 跳到目标前的某个关键帧（或不动）
frame = next(self)                          # 3. 开始顺序解码
while frame.pts < target_pts:               # 4. 快进直到 pts 达到目标
    frame = next(self)
return frame

其中 _jump_to_keyframe()（lib/video.py#L482-L522）分三种情况决策，体现了对"何时该 seek"的精细判断：

1. 目标就是当前帧（index == self._current_index）：不 seek，直接解码下一帧即可；
2. 向前回退（index < self._current_index）：调用 container.seek(target_pts, backward=True, any_frame=False, stream=...) 回退定位，然后重建解码器迭代器，并把 _current_index 置为目标帧之前最近的关键帧（由 _get_previous_keyframe() 用 np.searchsorted 在关键帧数组上二分查找得到）；
3. 向前推进：先用 np.searchsorted(..., side="right") 找当前位置之后的下一个关键帧；若该关键帧已经在目标帧之后，说明只需顺序快进而无需 seek；否则同样 seek 到目标前的关键帧并重建解码器。

注释中特别说明了一个工程细节：If we are seeking we always replace our iterator with a new one due to possible internal pyAV logic getting scrambled——seek 之后 PyAV 内部迭代器状态可能不一致，所以一律重建。any_frame=False 保证 seek 落在关键帧上，backward=True 允许落在略早的位置，二者配合让"从最近关键帧开始顺序解码"这一模式成立。

这套机制的代价是：随机跳到远处帧时，需要解码"目标帧到上一个关键帧之间"的所有帧。这是视频编码（I/P/B 帧结构）的固有约束，faceswap 通过缓存关键帧索引数组把 seek 目标选到最优点，将冗余解码量压到最小。

5.2 在 ImagesLoader 中的实际接线

VideoReader 最主要的使用方是 lib/image.py 中的 ImagesLoader（lib/image.py#L876-L894）：构造函数中先用 check_for_video(self.location) 判定输入类型，若是视频则创建 VideoReader(self.location, fast_count=fast_count, pts=pts, keyframes=keyframes)，否则 _reader 为 None。也就是说 faceswap 的对齐、转换、mask 等流程通过 ImagesLoader 统一抽象后，"视频文件"和"图片文件夹"对外呈现完全相同的 load() 迭代接口——这是 lib.video 模块真正服务业务的方式。

六、VideoMux：把处理好的帧编码回带音轨的视频

VideoMux（lib/video.py#L553-L824）解决输出侧问题：faceswap 转换得到的是逐帧 BGR uint8 numpy 数组，需要把它们写回一个与原视频帧率一致、且带上原始音轨的成品视频。构造签名：

VideoMux(source_video: str,          # 参考视频：提供音频与 FPS
          destination_video: str,    # 输出路径
          codec: "libx264" | "libx265",
          codec_parameters: dict[str, str],
          mux_audio: bool = True)

初始化时同时打开两个容器："src" 以只读打开、"dst" 以写入打开（lib/video.py#L583-L586），然后执行两件事：

6.1 源视频分析：FPS 与音频包生成器

_analyze_source()（lib/video.py#L604-L636）从 src.streams.video[0].average_rate 取出源帧率（Fraction 类型，后续全程使用分数避免浮点误差）；若 mux_audio=True 则找到第一条音频流，构造一个惰性生成器 (p for p in src.demux(audio) if p.dts is not None) 并预取第一个音频包。若源视频没有音频流，打印警告并自动把 mux_audio 降级为 False，不报错。

输出流设置（_set_output_streams()，lib/video.py#L638-L661）：视频流用 dst.add_stream(codec, rate=fps, options=codec_parameters) 创建，像素格式固定为 yuv420p（兼容播放器的常用格式）；音频流用 add_stream_from_template(src_audio) 从源流模板克隆，即音频编码参数与原视频完全一致。

6.2 首帧定尺寸与 16 对齐的缩放滤镜

encode(image) 是对外唯一入口，传入 None 表示流结束（flush）。首帧到达时触发 _initialize_video()（lib/video.py#L694-L714）：把输入宽高向上取整到 16 的倍数（注释说明原因是 macro-blocking，x264/x265 的宏块结构要求），再调用 _add_rescale_filter() 构建 PyAV 滤镜图（lib/video.py#L663-L692）：

buffer(输入尺寸) -> scale(W:H:force_original_aspect_ratio=1) -> pad(W:H:(ow-iw)/2:(oh-ih)/2) -> buffersink

即先按原宽高比缩放，再居中填充到目标画布，保证输出分辨率与 16 对齐后的尺寸严格一致。若输入尺寸恰好等于输出尺寸则不建滤镜图。

6.3 逐帧编码与音视频按时间戳交织

_encode_frame()（lib/video.py#L716-L742）将 numpy 数组转为 av.VideoFrame.from_ndarray(image, format="bgr24")，赋予 pts = frame_index、time_base = Fraction(1, fps)，必要时先经滤镜图重采样，再送入 vid.encode(frame) 得到编码包，压入 deque 队列。

真正的交织发生在 _mux()（lib/video.py#L787-L802）：每次弹出待写视频包时，调用 _get_audio_packet(video_timestamp)，把时间戳小于当前视频包 PTS 的所有音频包先写出、再写视频包。_timestamp() 统一换算为 float(packet.pts * packet.time_base)。这个"以视频包为节拍、按时间戳补发音频包"的策略，使得即使音频与视频的包长度、采样率各异，最终容器中的时间线也是交错对齐的。收尾时 encode(None) 会调用 vid.encode() 无参 flush 出编码器内部缓存的尾包，写完后关闭两个容器。

七、项目内的真实调用链：faceswap 转换器的视频输出

VideoMux 的直接调用方是转换器的 FFmpeg 写入插件 plugins/convert/writer/ffmpeg.py。其 Writer 类（plugins/convert/writer/ffmpeg.py#L41-L51）在初始化时即调用 _get_muxer(source_video) 构建 VideoMux（plugins/convert/writer/ffmpeg.py#L135-L147），编码参数由 _get_codec_parameters()（plugins/convert/writer/ffmpeg.py#L90-L113）从插件默认配置 cfg（plugins/convert/writer/ffmpeg_defaults.py）中读取并组装：

• 基础参数：crf（压缩质量）、preset（编码速度档）；
• tune：仅当取值落在该 codec 的合法列表内才加入，合法值为 libx264: film / animation / grain / stillimage / fastdecode / zerolatency；libx265: grain / fastdecode / zerolatency（见 _valid_tunes，plugins/convert/writer/ffmpeg.py#L53-L58）；
• profile 与 level：仅对 libx264 且配置非 auto 时生效。

音频混流由 _should_mux_audio() 决定（plugins/convert/writer/ffmpeg.py#L115-L133）：配置了 skip_mux 时跳过；设置了部分帧范围（frame ranges）时自动禁用音频混流并给出提示——因为片段输出的时间轴不完整，用户需要手动补音轨。此外输出文件名规则为 <源文件名>_converted.<扩展名>，重名时追加 _1、_2 递增（_get_output_filename，plugins/convert/writer/ffmpeg.py#L60-L88）。

模块中其他调用方还包括：tools/alignments/media.py#L18（对齐工具中 count_frames 统计视频帧、VIDEO_EXTENSIONS 参与输入判断）、tools/preview/preview.py#L26（预览工具用 check_for_video 区分视频/文件夹输入）。可见 lib.video 的 5 个公共对象恰好分别覆盖了"输入判定—帧数统计—元信息—随机读帧—编码输出"的完整闭环。

八、使用要点与工程细节小结

1. fast_count 的取舍：VideoInfo/VideoReader 默认 fast_count=True，用 -c copy 空转统计帧数，速度快但"accuracy is not guaranteed"（docstring 原话）。需要精确帧数时传 fast_count=False（代价是完整解码一遍），或更优地注入已缓存的 pts/keyframes 数组直接跳过扫描。
2. 时间基准一律用分数：VideoMux 内部 fps 是 Fraction，帧 time_base 为 Fraction(1, fps)，避免了 1/25 之类的浮点漂移，这对长视频音画同步很重要。
3. 健壮性设计：读帧路径上 InvalidDataError 全部"告警 + 跳帧"处理（VideoReader.__next__ 与 VideoInfo._get_pts_and_keyframes）；seek 后重建解码器；源视频无音轨时自动降级为无声输出；duration 元数据缺失时显式抛错而非返回垃圾值。
4. 运行环境前提：count_frames 依赖系统中可被 ffmpeg-python 定位的 ffmpeg 可执行文件（ffmpeg.FFMPEG_PATH）；解码/编码性能依赖 PyAV 所链接的 FFmpeg 库，thread_type = "AUTO" 已在读流与写流两侧默认启用自动线程。
5. API 文档入口：本模块的自动 API 参考页即 docs/full/lib/video.rst，其中 automodapi 指令会自动为上述全部对象生成文档条目；阅读源码时以 lib/video.py 为准。

从源码结构看，lib.video 模块是 faceswap 从"基于临时帧文件夹处理视频"演进到"直接对视频容器操作"这一架构的关键基座：ImagesLoader 让上游流程对视频/文件夹无感，VideoReader 提供了带关键帧优化的随机访问，VideoMux 则保证成品视频保留源视频的帧率与音轨。理解这三个类，基本就掌握了 faceswap 视频流水线中除人脸检测与模型推理之外的全部 IO 原理。