支持的模型

动作识别

• S3D (Kinetics 400)
• R(2+1)d RGB (IG-65M, Kinetics 400)
• I3D-Net RGB + Flow (Kinetics 400)

声音识别

• VGGish (AudioSet)

光流

• RAFT (FlyingChairs, FlyingThings3D, Sintel, KITTI)

帧级特征

• TIMM 中的所有模型，例如 ViT、ConvNeXt、EVA、Swin、DINO (ImageNet、LAION 等)
• CLIP
• ResNet-18,34,50,101,152 (ImageNet)

快速开始

或者在本地使用 conda 运行：

# 克隆仓库并切换到工作目录
git clone https://github.com/v-iashin/video_features.git
cd video_features

# 安装环境
conda env create -f conda_env.yml

# 激活环境
conda activate video_features

# 为示例视频提取 r(2+1)d 特征
# （默认打印；使用 on_extraction=save_numpy 或 save_h5 或 save_pickle 可以保存到磁盘）
python main.py \
    feature_type=r21d \
    device="cuda:0" \
    video_paths="[./sample/v_ZNVhz7ctTq0.mp4, ./sample/v_GGSY1Qvo990.mp4]"

# 如果你有多块 GPU，只需在另一个终端用另一块 GPU 运行此命令
# device 也可以是 "cpu"

如果你更习惯使用 Docker，我们提供了一个预装了所有模型环境的 Docker 镜像。 请查看 Docker 支持 文档页面。

多 GPU 和多节点设置

借助 video_features，可以轻松地在多块 GPU 之间并行化特征提取。 只需在另一个终端用另一块 GPU（甚至同一块 GPU）运行脚本，并指向相同的输出文件夹和输入视频路径即可。 脚本会检查特征是否已存在，如果存在则跳过。它还会尝试加载特征文件，以确认文件未损坏（即无法打开）。 这种方法允许你在之前的脚本因某种原因失败时继续进行特征提取。

如果你可以访问具有共享磁盘空间的 GPU 集群，可以通过创建多个单 GPU 任务来扩展提取规模，每个任务使用相同的命令即可。

由于每次运行脚本时输入文件列表都会被随机打乱，因此无需担心不同工作者会处理同一段视频。 在极少数发生冲突的情况下，脚本会重新写入之前已提取的特征。

输入

输入是视频文件的路径。 路径可以以视频路径列表的形式传递，也可以以每行一个路径的文本文件形式传递。

输出

输出由 on_extraction 参数定义；默认情况下，它会将特征打印到命令行。 可能的输出值包括 ['print', 'save_numpy', 'save_pickle', 'save_h5']。

• save_numpy / save_pickle：将特征保存到 output_path 文件夹中，文件名与输入视频文件相同，但扩展名为 .npy 或 .pkl。
• save_h5：将特征保存到 output_path 下的单个 HDF5 文件中（例如 video_features_cuda0.h5），以视频路径作为键（//\\ 替换为 _）。结构：file.h5 / video_key (group) / feature_name (rgb, flow, fps 等)。使用 utils.py/inspect_h5() 可以查看内容。

应用于

• SpecVQGAN 分支 specvqgan
• BMT 分支 bmt
• MDVC 分支 mdvc

如果你发现这个仓库对你的项目或论文有所帮助，请告知我。

致谢

• @Kamino666：添加了 CLIP 模型以及 Windows 和 CPU 的支持（还有许多其他有用的功能）。
• @ohjho：增加了对 37 层 R(2+1)d 模型的支持。
• @borijang：解决了文件名相关的问题，增强了 I3D 检查点的加载功能，并改进了代码风格。
• @bjuncek：协助处理 timm 模型并进行了线下讨论。
• @VivekNarula7：添加了对 .h5 输出格式的支持。

引用

如果你的研究中使用了该项目，请考虑引用：

@misc{videofeatures2020,
  title = {Video Features},
  author = {Vladimir Iashin 和其他贡献者},
  year = {2020},
  howpublished = {\url{https://github.com/v-iashin/video_features}},
}

video_features 快速上手指南

video_features 是一个强大的开源工具，支持从视频片段中提取多种模态的特征，包括视觉外观（Visual Appearance）、光流（Optical Flow）和音频（Audio）。它集成了 S3D、I3D、RAFT、CLIP 等多种主流模型。

环境准备

• 操作系统：Linux 或 Windows（需安装 WSL 或原生支持）
• 硬件要求：
  • 推荐使用 NVIDIA GPU（需安装 CUDA 驱动）以加速提取过程。
  • 也支持 CPU 模式运行。
• 前置依赖：
  • Conda (推荐用于环境管理)
  • Git

提示：国内用户若下载 Conda 包速度较慢，可配置清华或中科大镜像源：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/

安装步骤

1. 克隆仓库

   git clone https://github.com/v-iashin/video_features.git
   cd video_features
   

2. 创建并激活 Conda 环境 使用项目提供的配置文件一键安装所有依赖：

   conda env create -f conda_env.yml
   conda activate video_features
   

3. 替代方案：Docker 如果您更习惯使用 Docker，可以直接拉取预装好所有模型的镜像（详见官方文档 Docker 部分），无需本地配置环境。

基本使用

以下示例演示如何提取样本视频的 R(2+1)d 视觉特征。默认情况下，特征会打印到终端；若要保存文件，需指定 on_extraction 参数。

命令行运行示例

python main.py \
    feature_type=r21d \
    device="cuda:0" \
    video_paths="[./sample/v_ZNVhz7ctTq0.mp4, ./sample/v_GGSY1Qvo990.mp4]" \
    on_extraction=save_numpy

参数说明

• feature_type: 指定模型类型。支持 r21d, i3d, s3d, raft, vggish, clip, timm (如 vit_base_patch16_224) 等。
• device: 指定运行设备，如 "cuda:0" 或 "cpu"。
• video_paths: 输入视频路径列表，或用文本文件（每行一个路径）代替。
• on_extraction: 输出方式。
  • print: 打印到屏幕（默认）。
  • save_numpy: 保存为 .npy 文件。
  • save_pickle: 保存为 .pkl 文件。
  • save_h5: 保存为单个 .h5 文件（适合多视频批量处理）。

多显卡并行加速

该工具天然支持多卡并行。只需在不同的终端窗口中运行相同的命令，但指定不同的 device（例如 cuda:1, cuda:2），并指向相同的输出文件夹。脚本会自动检测已提取的文件并跳过，断点续传无需额外配置。