Decord

Decord 是 Record 的逆过程。它基于硬件加速视频解码器的轻量封装，提供了便捷的视频切片方法，例如：

• FFMPEG/LibAV（已完成）
• Nvidia 编解码器（已完成）
• Intel 编解码器

Decord 的设计旨在解决深度学习中视频随机打乱时的卡顿问题，从而提供类似于随机图像加载器的流畅体验。

此外，Decord 还可以从视频和音频文件中解码音频。用户可以同时对视频和音频进行切片以获得同步的结果，因此它为视频和音频解码提供了一站式的解决方案。

目录

• 基准测试
• 安装
• 使用
• 深度学习框架桥接

初步基准测试

Decord 在处理随机访问模式方面表现出色，而这种模式在神经网络训练中非常常见。

安装

通过 pip 安装

只需运行以下命令：

pip install decord

支持的平台：

• Linux
• Mac OS >= 10.12, python>=3.5
• Windows

请注意，目前 PYPI 上仅提供 CPU 版本。如需启用 GPU 加速，请从源代码编译安装。

从源代码安装

Linux

安装用于构建共享库的系统软件包。对于 Debian/Ubuntu 用户，执行以下操作：

# 官方 PPA 提供的是 ffmpeg 2.8，功能严重不足，我们这里使用 ffmpeg 4.0
sudo add-apt-repository ppa:jonathonf/ffmpeg-4 # 对于 ubuntu20.04，官方 PPA 已经是版本 4.2，可以跳过这一步
sudo apt-get update
sudo apt-get install -y build-essential python3-dev python3-setuptools make cmake
sudo apt-get install -y ffmpeg libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev
# 注意：确保你有 cmake 3.8 或更高版本，如果太旧，可以从 cmake 官网安装

递归克隆仓库（重要）：

git clone --recursive https://github.com/dmlc/decord

在源码根目录下构建共享库：

cd decord
mkdir build && cd build
cmake .. -DUSE_CUDA=0 -DCMAKE_BUILD_TYPE=Release
make

你可以指定 -DUSE_CUDA=ON 或 -DUSE_CUDA=/path/to/cuda 或 -DUSE_CUDA=ON -DCMAKE_CUDA_COMPILER=/path/to/cuda/nvcc 来启用 NVDEC 硬件加速解码：

cmake .. -DUSE_CUDA=ON -DCMAKE_BUILD_TYPE=Release

请注意，如果你遇到 libnvcuvid.so 相关的问题（例如参见 #102），很可能是缺少该库的链接。你可以手动查找它（ldconfig -p | grep libnvcuvid）并将其链接到 CUDA_TOOLKIT_ROOT_DIR\lib64，以便 decord 能够顺利检测并链接正确的库。

要指定自定义的 FFMPEG 库路径，使用 -DFFMPEG_DIR=/path/to/ffmpeg。

安装 Python 绑定：

cd ../python
# 选项 1：将 Python 路径添加到 $PYTHONPATH，你需要单独安装 numpy
pwd=$PWD
echo "PYTHONPATH=$PYTHONPATH:$pwd" >> ~/.bashrc
source ~/.bashrc
# 选项 2：使用 setuptools 安装
python3 setup.py install --user

Mac OS

macOS 上的安装与 Linux 类似。但 macOS 用户需要先安装 clang、GNU Make 和 cmake 等构建工具。

clang 和 GNU Make 等工具包含在 macOS 的 Command Line Tools 中。安装方法如下：

xcode-select --install

要安装其他所需的软件包，如 cmake，建议先安装 Homebrew，这是一个流行的 macOS 包管理器。详细说明可在其官网找到。

安装 Homebrew 后，再安装 cmake 和 ffmpeg：

brew install cmake ffmpeg
# 注意：确保你有 cmake 3.8 或更高版本，如果太旧，可以从 cmake 官网安装

递归克隆仓库（重要）：

git clone --recursive https://github.com/dmlc/decord

然后进入根目录构建共享库：

cd decord
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

安装 Python 绑定：

cd ../python
# 选项 1：将 Python 路径添加到 $PYTHONPATH，你需要单独安装 numpy
pwd=$PWD
echo "PYTHONPATH=$PYTHONPATH:$pwd" >> ~/.bash_profile
source ~/.bash_profile
# 选项 2：使用 setuptools 安装
python3 setup.py install --user
``。

#### Windows

在 Windows 上，你需要 CMake 和 Visual Studio 来进行 C++ 编译。

-   首先，安装 `git`、`cmake`、`ffmpeg` 和 `python`。你可以使用 [Chocolatey](https://chocolatey.org/) 来管理软件包，类似于 Linux/Mac OS。
-   其次，安装 [`Visual Studio 2017 Community`](https://visualstudio.microsoft.com/)，这可能需要一些时间。

当依赖项准备就绪后，打开命令提示符：

```bash
cd your-workspace
git clone --recursive https://github.com/dmlc/decord
cd decord
mkdir build
cd build
cmake -DCMAKE_CXX_FLAGS="/DDECORD_EXPORTS" -DCMAKE_CONFIGURATION_TYPES="Release" -G "Visual Studio 15 2017 Win64" ..
# 打开 `decord.sln` 并构建项目

使用

Decord 提供了最小化的 API 集合，方便快速上手。你也可以查看 Jupyter Notebook 中的示例。

VideoReader

VideoReader 用于直接从视频文件中访问帧。

from decord import VideoReader
from decord import cpu, gpu

vr = VideoReader('examples/flipping_a_pancake.mkv', ctx=cpu(0))
# 文件对象同样适用，可用于内存中的解码
with open('examples/flipping_a_pancake.mkv', 'rb') as f:
  vr = VideoReader(f, ctx=cpu(0))
print('视频帧数:', len(vr))
# 1. 最简单的方式是直接访问帧
for i in range(len(vr)):
    # 视频读取器会以最高效的方式处理寻址和跳过操作
    frame = vr[i]
    print(frame.shape)

# 如果需要一次获取多帧，可以使用 get_batch
# 这是获取大量帧的高效方式
frames = vr.get_batch([1, 3, 5, 7, 9])
print(frames.shape)
# (5, 240, 320, 3)
# 重复的帧索引会被接受并在内部处理，以避免重复解码
frames2 = vr.get_batch([1, 2, 3, 2, 3, 4, 3, 4, 5]).asnumpy()
print(frames2.shape)
# (9, 240, 320, 3)

# 2. 你也可以采用 cv2 风格的读取方式
# 跳过 100 帧
vr.skip_frames(100)
# 寻找开头
vr.seek(0)
batch = vr.next()
print('帧形状:', batch.shape)
print('numpy 帧:', batch.asnumpy())

VideoLoader

VideoLoader 专为使用大量视频文件训练深度学习模型而设计。它提供了智能的视频打乱技术，以实现高效的随机访问性能（我们知道，在视频中进行定位是非常缓慢且冗余的）。这些优化都隐藏在底层的 C++ 代码中，用户无需感知。

from decord import VideoLoader
from decord import cpu, gpu

vl = VideoLoader(['1.mp4', '2.avi', '3.mpeg'], ctx=[cpu(0)], shape=(2, 320, 240, 3), interval=1, skip=5, shuffle=1)
print('总批次数:', len(vl))

for batch in vl:
    print(batch[0].shape)

视频的打乱操作可能比较复杂，因此我们提供了多种模式：

shuffle = -1  # 智能打乱模式，基于视频属性（尚未实现）
shuffle = 0  # 全部按顺序，不进行定位，按照初始文件名顺序
shuffle = 1  # 随机文件名顺序，每个视频内部不进行随机访问，非常高效
shuffle = 2  # 完全随机顺序
shuffle = 3  # 仅在每个视频内随机访问帧

AudioReader

AudioReader 用于直接从视频（如果有音频轨道）和音频文件中读取样本。

from decord import AudioReader
from decord import cpu, gpu

# 可以指定所需的采样率和声道布局
# 声道方面有两个选项：保持原始布局或转换为单声道
ar = AudioReader('example.mp3', ctx=cpu(0), sample_rate=44100, mono=False)
print('音频样本的形状: ', ar.shape())
# 访问音频样本
print('第一个样本: ', ar[0])
print('前五个样本: ', ar[0:5])
print('获取一批样本: ', ar.get_batch([1,3,5]))

AVReader

AVReader 是 AudioReader 和 VideoReader 的封装器，允许您同时对视频和音频进行切片操作。

from decord import AVReader
from decord import cpu, gpu

av = AVReader('example.mov', ctx=cpu(0))
# 同时访问视频帧和对应的音频样本
audio, video = av[0:20]
# audio 中的每个元素都是与视频帧相对应的一批音频样本
print('帧数: ', len(audio))
print('第一帧的音频样本形状: ', audio[0].shape)
print('第一帧的形状: ', video.asnumpy()[0].shape)
# 同样地，也可以获取一批数据
audio2, video2 = av.get_batch([1,3,5])

深度学习框架的桥接：

将 Decord 与流行的深度学习框架连接起来，对于训练和推理非常重要。

• Apache MXNet（已完成）
• PyTorch（已完成）
• TensorFlow（已完成）

使用深度学习框架的桥接非常简单，例如，可以将默认张量输出设置为 mxnet.ndarray：

import decord
vr = decord.VideoReader('examples/flipping_a_pancake.mkv')
print('原生输出: ', type(vr[0]), vr[0].shape)
# 原生输出: <class 'decord.ndarray.NDArray'>, (240, 426, 3)
# 只需设置一次输出类型即可
decord.bridge.set_bridge('mxnet')
print(type(vr[0], vr[0].shape))
# <class 'mxnet.ndarray.ndarray.NDArray'> (240, 426, 3)
# 或者切换到 PyTorch 和 TensorFlow（>=2.2.0）
decord.bridge.set_bridge('torch')
decord.bridge.set_bridge('tensorflow')
# 或者恢复为 Decord 原生格式
decord.bridge.set_bridge('native')

Decord 快速上手指南

Decord 是一个专为深度学习设计的视频处理库，提供基于硬件加速（如 FFMPEG、Nvidia NVDEC）的高效视频随机访问和切片功能。它解决了传统视频读取中随机跳转帧速度慢的问题，特别适合训练需要随机采样帧的神经网络模型。

环境准备

系统要求

• Linux: 推荐 Ubuntu/Debian 系列
• macOS: >= 10.12
• Windows: 需安装 Visual Studio
• Python: >= 3.5

前置依赖

若需从源码编译以启用 GPU 加速或自定义 FFmpeg 版本，请预先安装以下工具：

Ubuntu/Debian:

sudo add-apt-repository ppa:jonathonf/ffmpeg-4
sudo apt-get update
sudo apt-get install -y build-essential python3-dev python3-setuptools make cmake
sudo apt-get install -y ffmpeg libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev
# 确保 cmake 版本 >= 3.8

macOS:

xcode-select --install
brew install cmake ffmpeg

Windows:

• 安装 git, cmake, ffmpeg, python
• 安装 Visual Studio 2017 Community 或更高版本（包含 C++ 编译环境）

安装步骤

方式一：通过 pip 安装（仅 CPU 版本）

最简单的方式，适用于快速体验，但默认不包含 GPU 加速支持。

pip install decord
# 国内用户推荐使用清华源加速
pip install decord -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码编译（支持 GPU 加速）

1. 克隆仓库（注意必须递归克隆子模块）：

git clone --recursive https://github.com/dmlc/decord
cd decord

2. 编译构建：

   Linux (启用 CUDA):

   mkdir build && cd build
   cmake .. -DUSE_CUDA=ON -DCMAKE_BUILD_TYPE=Release
   make
   

   macOS:

   mkdir build && cd build
   cmake .. -DCMAKE_BUILD_TYPE=Release
   make
   

   Windows:

   mkdir build
   cd build
   cmake -DCMAKE_CXX_FLAGS="/DDECORD_EXPORTS" -DCMAKE_CONFIGURATION_TYPES="Release" -G "Visual Studio 15 2017 Win64" ..
   # 随后在生成的 decord.sln 中使用 Visual Studio 进行构建
   

3. 安装 Python 绑定：

cd ../python
python3 setup.py install --user
# 或者配置环境变量
pwd=$PWD
echo "PYTHONPATH=$PYTHONPATH:$pwd" >> ~/.bashrc
source ~/.bashrc

基本使用

Decord 提供了简洁的 API 用于读取视频、音频及音视频同步数据。

1. 读取视频帧 (VideoReader)

支持直接索引访问和批量获取，自动处理高效的寻址和跳转。

from decord import VideoReader, cpu

# 初始化读取器
vr = VideoReader('examples/flipping_a_pancake.mkv', ctx=cpu(0))

# 获取视频总帧数
print('video frames:', len(vr))

# 方式一：直接索引访问单帧
frame = vr[0]
print(frame.shape)

# 方式二：高效批量获取多帧（避免重复解码）
frames = vr.get_batch([1, 3, 5, 7, 9])
print(frames.shape)  # 输出：(5, H, W, 3)

# 方式三：类似 OpenCV 的顺序读取
vr.seek(0)          # 跳转到开头
vr.skip_frames(100) # 跳过 100 帧
batch = vr.next()   # 读取下一帧

2. 深度学习框架桥接

Decord 原生输出为 decord.ndarray，可一键转换为 PyTorch、MXNet 或 TensorFlow 格式。

import decord

vr = VideoReader('examples/flipping_a_pancake.mkv')

# 设置为 PyTorch 后端
decord.bridge.set_bridge('torch')

# 此时获取的帧直接为 torch.Tensor
frame = vr[0]
print(type(frame))  # <class 'torch.Tensor'>

# 支持的后端：'mxnet', 'tensorflow', 'native'

3. 读取音频与音视频同步 (AudioReader & AVReader)

支持单独提取音频，或同时提取同步的音视频数据。

from decord import AudioReader, AVReader, cpu

# 读取音频
ar = AudioReader('example.mp3', ctx=cpu(0), sample_rate=44100)
samples = ar[0:5]

# 同时读取音视频（自动同步）
av = AVReader('example.mov', ctx=cpu(0))
audio_batch, video_batch = av[0:20]

# audio_batch 包含对应每一帧视频的音频采样片段
print('Frame count:', len(audio_batch))
print('Video shape:', video_batch.asnumpy()[0].shape)