NVVL 是 DALI 的一部分！

DALI（Nvidia 数据加载库） 集成了 NVVL 的功能，并且提供了更多特性，因此建议切换到 DALI。 DALI 的源代码也是开源的，可在 GitHub 上获取。 最新的文档可以在这里找到：DALI 开发者指南。 NVVL 项目仍将在 GitHub 上提供，但将不再维护。所有问题和未来的需求请在 DALI 仓库 中提交。

NVVL

NVVL（NVIDIA Video Loader）是一个用于从压缩视频文件中加载随机视频帧序列的库，以方便机器学习训练。它利用 FFmpeg 的库来解析和读取视频文件中的压缩数据包，并借助 NVIDIA GPU 上可用的视频解码硬件来卸载并加速这些数据包的解码过程，从而在 GPU 设备内存中生成可以直接用于训练的张量。NVVL 还可以在加载帧的同时进行数据增强。通过 GPU 专用的纹理映射单元，可以对帧进行缩放、裁剪和水平翻转。输出可以是 RGB 或 YCbCr 色彩空间，归一化到 [0, 1] 或 [0, 255]，并且可以是 float、half 或 uint8 类型的张量。

请注意，虽然我们希望您觉得 NVVL 很有用，但它实际上是 NVIDIA 一小群研究人员在一个研究项目中编写的示例代码。我们会尽力回答问题并修复出现的小 bug，但这并不是 NVIDIA 的正式支持产品，大部分情况下是以“原样”提供的。

与单独的帧图像文件相比，使用压缩视频文件可以显著降低训练过程中对存储和 I/O 系统的要求。将视频数据集以视频文件形式存储，所需的磁盘空间会减少一个数量级，这样不仅可以让更大的数据集同时容纳在系统内存中，还可以存放在本地 SSD 上以便快速访问。在加载时，需要从磁盘读取的数据量也更少。将数据放置在更小、更快的存储设备上，并在加载时减少读取的数据量，可以缓解从磁盘获取数据的瓶颈问题——而随着 GPU 不断提速，这一瓶颈只会越来越严重。在我们的示例项目中使用的数据集里，H.264 压缩的 .mp4 文件比以 .png 格式存储帧要小近 40 倍。

利用 NVIDIA GPU 上的硬件解码器来解码图像，可以显著减轻主机 CPU 的负担。这意味着在训练过程中，不需要分配那么多 CPU 核心来专门负责数据加载。这一点在每颗 CPU 对应大量 GPU 的服务器中尤为重要，例如 NVIDIA DGX-2 服务器，但对于其他平台也同样有益。当我们在 NVIDIA DGX-1 上训练示例项目时，使用 NVVL 时的 CPU 负载仅为使用常规 .png 文件数据加载器时负载的 50% 到 60%。

量化使用 NVVL 性能优势的测量结果详细记录在我们的 超分辨率示例项目 中。

大多数用户会选择使用深度学习框架提供的封装接口，而不是直接使用该库。目前提供了 PyTorch 的封装接口（欢迎为其他框架贡献 PR）。有关如何使用 PyTorch 封装接口的文档，请参阅 PyTorch 封装 README。需要注意的是，在构建 PyTorch 封装之前，无需手动构建或安装 C++ 库——其安装脚本会自动完成这些步骤。

构建与安装

NVVL 依赖于以下内容：

• CUDA 工具包。我们已测试过 8.0 及更高版本，但早期版本也可能适用。使用 CUDA 9.0 或更高版本时，NVVL 的性能会更好¹。
• FFmpeg 的 libavformat、libavcodec、libavfilter 和 libavutil。这些库可以从源码安装，如 示例 Dockerfile 所示，也可以从 Ubuntu 16.04 的软件包 libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev 中获取。其他发行版也应有类似的软件包。

此外，从源码构建还需要 CMake 3.8 或更高版本，某些示例可选地使用 OpenCV 的部分库（如果已安装）。

docker 目录包含可用于构建或使用 NVVL 库的 Dockerfile 示例。示例项目的 docker 目录 中有一个实际构建并安装 NVVL 库的 Dockerfile 示例。

CMake 3.8 及以上版本内置了 CUDA 语言支持，NVVL 的构建系统正是利用这一特性。由于 CMake 3.8 较新，尚未广泛集成到主流 Linux 发行版中，可能需要安装新版本的 CMake。最简单的方法是通过 PyPI 安装：

pip install cmake

或者，如果无法使用 pip，也可以从二进制分发包中安装到 /usr/local：

wget https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.sh
/bin/sh cmake-3.10.2-Linux-x86_64.sh --prefix=/usr/local

更多选项请参见 https://cmake.org/download/。

NVVL 的构建和安装遵循典型的 CMake 模式：

mkdir build && cd build
cmake ..
make -j
sudo make install

这将会把 libnvvl.so 和开发头文件安装到 /usr/local 下的相应子目录中。可以通过 cmake .. -DOPTION=Value 向 CMake 传递以下选项：

• CUDA_ARCH - 用于生成设备代码的 CUDA 架构名称，用分号分隔。有效选项包括 Kepler、Maxwell、Pascal 和 Volta。也可以指定具体的架构名称，如 sm_61。默认值为 Maxwell;Pascal;Volta。
• CMAKE_CUDA_FLAGS - 传递给 nvcc 的编译参数字符串。例如，可以通过 -cudart shared 或 -cudart static 来选择链接静态或共享运行时库。还可以通过此选项对代码生成进行更精细的控制，具体请参考 nvcc 文档。默认值为 -cudart shared。
• WITH_OPENCV - 设置为 1 以构建包含可选 OpenCV 功能的示例。
• CMAKE_INSTALL_PREFIX - 安装目录。默认值为 /usr/local。
• CMAKE_BUILD_TYPE - 构建类型，可以是 Debug 或 Release。

更多选项请参阅 CMake 文档。

doc/examples 目录下的示例可以通过 examples 目标进行构建：

make examples

最后，如果已安装 Doxygen，可以通过 doc 目标构建 API 文档：

make doc

这将会在 doc/html 目录下生成 HTML 文件。

准备数据

NVVL 支持 FFmpeg 能够解析的任何容器格式中的 H.264 和 HEVC（H.265）视频编解码器。视频编解码器在数据流中仅将某些帧（称为关键帧或 I 帧）存储为完整图像。其他所有帧都需要借助时间上在其之前或之后的其他帧的数据才能被解码。为了能够解码一串连续的帧，必须从该序列之前的关键帧开始解码，并一直持续到该序列之后的下一个关键帧。在顺序播放视频时，这通常不是问题；然而，当随机解码视频中分散的小段帧序列时，如果关键帧之间的间隔较大，则会导致读取和解码大量实际上并不会用到的帧。

因此，为了在随机读取视频文件中的短序列时获得良好的性能，有必要以较频繁的关键帧间隔对视频进行编码。我们发现，将关键帧间隔设置为你计划读取的序列长度，可以在文件大小和加载性能之间取得较好的平衡。此外，NVVL 的查找逻辑不支持 HEVC 流中的开放 GOP 结构。使用 ffmpeg 时，要将关键帧间隔设置为 X：

• 对于 libx264，使用 -g X
• 对于 libx265，使用 -x265-params "keyint=X:no-open-gop=1"

视频的像素格式还必须是 yuv420p，才能被硬件解码器支持。这可以通过向 ffmpeg 传递 -pix_fmt yuv420p 来实现。此外，你还应该通过在输入之后、输出之前向 ffmpeg 传递 -map v:0，来移除视频文件中多余的音频或视频流。

例如，要转码为 H.264：

ffmpeg -i original.mp4 -map v:0 -c:v libx264 -crf 18 -pix_fmt yuv420p -g 5 -profile:v high prepared.mp4

基本用法

本节介绍基础 C/C++ 库的用法。有关 PyTorch 封装库的使用，请参阅 pytorch 目录下的 README。

该库同时提供了 C++ 和 C 接口。有关如何使用该库的简要示例代码，请参阅 doc/examples 中的示例。extract_frames.cpp 展示了 C++ 接口，而 extract_frames_c.c 则展示了 C 接口。通过运行 make doc 构建的 API 文档是该 API 的权威参考。

基本流程是创建一个 VideoLoader 对象，告知它要读取哪些帧序列，然后为其提供设备内存中的缓冲区，用于存放解码后的序列。在 C++ 中，创建视频加载器非常简单：

auto loader = NVVL::VideoLoader{device_id};

随后，你可以通过调用 read_sequence 来指定要读取的序列：

loader.read_sequence(filename, frame_num, sequence_length);

要接收解码器输出的帧，你需要创建一个 PictureSequence 对象，以指定你希望如何以及在哪里接收这些解码后的帧。首先，创建一个 PictureSequence，并指定要从解码器接收的帧数。请注意，此处指定的帧数不必与传递给 read_sequence 的序列长度相同；你可以读取一大段帧序列，并将其拆分为多个张量接收，或者读取多个较小的序列，然后将它们拼接成一个单一的张量接收。

auto seq = PictureSequence{sequence_count};

接下来，你需要在序列中创建“层”，以指定帧的存放目标。每层可以是不同的类型，具有不同的处理方式，并包含来自接收序列的不同帧。首先，创建所需类型的 PictureSequence::Layer：

auto pixels = PictureSequence::Layer<float>{};

然后，填写数据指针和其他详细信息。有关所有可用选项的描述，请参阅 PictureSequence.h 中的文档。

float* data = nullptr;
size_t pitch = 0;
cudaMallocPitch(&data, &pitch,
                crop_width * sizeof(float),
                crop_height * sequence_count * 3);
pixels.data = data;
pixels.desc.count = sequence_count;
pixels.desc.channels = 3;
pixels.desc.width = crop_width;
pixels.desc.height = crop_height;
pixels.desc.scale_width = scale_width;
pixels.desc.scale_height = scale_height;
pixels.desc.horiz_flip = false;
pixels.desc.normalized = true;
pixels.desc.color_space = ColorSpace_RGB;
pixels.desc.stride.x = 1;
pixels.desc.stride.y = pitch / sizeof(float);
pixels.desc.stride.c = pixels.desc.stride.y * crop_height;
pixels.desc.stride.n = pixels.desc.stride.c * 3;

请注意，这里我们设置了步幅，使得维度顺序为 “nchw”。通过适当设置步幅，也可以选择 “nhwc” 或其他任意维度顺序。另外，需要注意的是，层描述中的步幅是指元素的数量，而非字节数。

现在，我们将这一层添加到我们的 PictureSequence 中，并将其发送给加载器：

seq.set_layer("pixels", pixels);
loader.receive_frames(seq);

调用 receive_frames 是异步操作。如果需要同步读取，可以使用 receive_frames_sync。当我们准备好使用这些帧时，可以在我们用于计算的 CUDA 流中插入一个等待事件：

seq.wait(stream);

这会在流 stream 中插入一个等待事件，导致在该流上启动的后续内核都会等待数据准备就绪。

C 接口遵循非常相似的模式，具体示例请参阅 doc/examples/extract_frames_c.c。

参考文献

如果你在工作中觉得本库很有用，请在你的出版物中使用以下 BibTeX 条目引用本库：

@misc{nvvl,
  author = {Jared Casper and Jon Barker and Bryan Catanzaro},
  title = {NVVL: NVIDIA Video Loader},
  year = {2018},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/NVIDIA/nvvl}}
}

注释

[1] 具体来说，使用版本 384 及更高版本的 NVIDIA 内核模块（随 CUDA 9.0+ 提供）时，由 NVVL 启动的 CUDA 内核将在独立的流上异步执行。而在更早的内核模块中，所有 CUDA 内核都会在默认流上启动。↩

NVVL 快速上手指南

重要提示：NVVL 项目已停止维护，其功能已完整集成至 NVIDIA DALI 库中。官方强烈建议新用户直接迁移至 DALI。本指南仅适用于需要直接使用旧版 NVVL 源码的特定场景。

NVVL (NVIDIA Video Loader) 是一个利用 NVIDIA GPU 硬件解码器加速视频加载的库，专为机器学习训练设计。它能直接从压缩视频文件（如 MP4）中读取随机帧序列，显著降低存储占用和 CPU 负载。

环境准备

系统要求

• 操作系统：Linux (推荐 Ubuntu 16.04+)
• GPU：支持硬件解码的 NVIDIA GPU (Kepler, Maxwell, Pascal, Volta 架构及以上)
• CUDA Toolkit：版本 8.0+ (推荐 9.0+ 以获得更佳性能)

前置依赖

安装 FFmpeg 开发库和构建工具。

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev cmake build-essential

安装 CMake (若源中版本低于 3.8):

pip install cmake
# 或者手动安装二进制包
# wget https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.sh
# /bin/sh cmake-3.10.2-Linux-x86_64.sh --prefix=/usr/local

安装步骤

从源码编译并安装 NVVL：

# 克隆仓库 (假设已下载或 git clone)
# cd nvvl

mkdir build && cd build
cmake .. -DCUDA_ARCH="Maxwell;Pascal;Volta"
make -j
sudo make install

可选配置参数：

• CUDA_ARCH: 指定生成的 CUDA 架构代码 (默认: Maxwell;Pascal;Volta)
• WITH_OPENCV: 设为 1 以构建包含 OpenCV 功能的示例
• CMAKE_BUILD_TYPE: 设为 Debug 或 Release

数据准备 (关键)

为了在随机读取短序列时获得最佳性能，视频必须编码为频繁的关键帧 (Keyframes)，且像素格式必须为 yuv420p。

使用 FFmpeg 转码示例 (设置关键帧间隔为 5)：

H.264 编码:

ffmpeg -i original.mp4 -map v:0 -c:v libx264 -crf 18 -pix_fmt yuv420p -g 5 -profile:v high prepared.mp4

HEVC (H.265) 编码:

ffmpeg -i original.mp4 -map v:0 -c:v libx265 -crf 18 -pix_fmt yuv420p -x265-params "keyint=5:no-open-gop=1" prepared.mp4

基本使用

大多数用户建议使用 PyTorch 封装器（见 /pytorch/README.md）。以下是直接使用 C++ 接口的核心流程：

1. 创建 VideoLoader。
2. 调用 read_sequence 指定要读取的文件和帧范围。
3. 创建 PictureSequence 并配置输出层（Layer），包括显存指针、尺寸、缩放、归一化等。
4. 调用 receive_frames 异步获取数据。

C++ 代码示例:

#include <nvvl/video_loader.h>
#include <nvvl/picture_sequence.h>
#include <cuda_runtime.h>

// 1. 初始化加载器 (device_id 为 GPU ID)
auto loader = NVVL::VideoLoader{0};

// 2. 请求读取序列 (文件路径，起始帧号，序列长度)
loader.read_sequence("prepared.mp4", 10, 5);

// 3. 配置接收缓冲区
int sequence_count = 5;
int crop_width = 224;
int crop_height = 224;

auto seq = PictureSequence{sequence_count};
auto pixels = PictureSequence::Layer<float>{};

// 分配显存
float* data = nullptr;
size_t pitch = 0;
cudaMallocPitch(&data, &pitch,
                crop_width * sizeof(float),
                crop_height * sequence_count * 3);

// 配置 Layer 描述
pixels.data = data;
pixels.desc.count = sequence_count;
pixels.desc.channels = 3;
pixels.desc.width = crop_width;
pixels.desc.height = crop_height;
pixels.desc.scale_width = crop_width;   // 如需缩放可修改此处
pixels.desc.scale_height = crop_height;
pixels.desc.horiz_flip = false;         // 是否水平翻转
pixels.desc.normalized = true;          // 归一化到 [0, 1]
pixels.desc.color_space = ColorSpace_RGB;

// 设置步长 (Stride)，此处示例为 NCHW 格式
pixels.desc.stride.x = 1;
pixels.desc.stride.y = pitch / sizeof(float);
pixels.desc.stride.c = pixels.desc.stride.y * crop_height;
pixels.desc.stride.n = pixels.desc.stride.c * 3;

// 将 Layer 添加到序列
seq.set_layer("pixels", pixels);

// 4. 异步接收帧数据
loader.receive_frames(seq);

// 5. 同步等待 (在 CUDA stream 中插入事件，确保数据就绪后再进行计算)
cudaStream_t stream; // 假设已创建流
seq.wait(stream);

// ... 后续进行模型训练推理 ...

注：完整的 C 和 C++ 示例代码请参考源码目录 doc/examples/ 下的 extract_frames.cpp 和 extract_frames_c.c。