中文README | VideoPipe 官网 | VideoPipe 教程(视频教程)

🚀one-yolo，让 YOLO 集成一步到位。所有任务、所有版本、所有运行时环境，一应俱全。🚀

---

简介

VideoPipe 是一个用 C++ 编写的视频分析与结构化框架，依赖极少且易于使用。它采用流水线式架构，每个节点相互独立，可以灵活组合。VideoPipe 可用于构建各类视频分析应用，适用于视频结构化、图像搜索、人脸识别以及交通/安防领域的行为分析（如交通事件检测）等场景。

优势与特性

VideoPipe 类似于 NVIDIA 的 DeepStream 和华为的 mxVision 框架，但使用起来更加简单，移植性也更强。

以下是对比表格：

名称	开源	学习曲线	支持平台	性能	第三方依赖
DeepStream	否	高	仅 NVIDIA	高	多
mxVision	否	高	仅华为	高	多
VideoPipe	是	低	任意平台	中	少

VideoPipe 采用插件化的编程风格，可根据不同需求灵活配置。我们可以通过独立的插件（在框架中称为“Node”类型）来构建各种类型的视频分析应用。用户只需准备好模型并了解其输出解析方式即可。推理部分可使用不同的后端实现，例如 OpenCV::DNN（默认）、TensorRT、PaddleInference、ONNXRuntime，或任何其他您偏好的后端。

演示

https://github.com/sherlockchou86/video_pipe_c/assets/13251045/b1289faa-e2c7-4d38-871e-879ae36f6d50

全屏观看请使用播放器右下角的按钮，更多视频演示

功能

VideoPipe 是一个简化计算机视觉算法模型集成的框架。需要注意的是，它并非像 TensorFlow 或 TensorRT 那样的深度学习框架。VideoPipe 的主要功能如下：

• 流读取：支持主流视频流协议，如 UDP、RTSP、RTMP、文件和应用程序；同时也支持图像读取。
• 视频解码：基于 OpenCV/GStreamer 支持视频和图像解码，并具备硬件加速功能。
• 算法推理：支持多层级的深度学习推理，如目标检测、图像分类、特征提取和图像生成；同时支持传统图像算法的集成。现已支持多模态大语言模型（mLLM）集成（更新于 2025 年 8 月 12 日）
• 目标跟踪：支持目标跟踪，例如 IOU 和 SORT 跟踪算法。
• 行为分析（BA）：基于跟踪结果进行行为分析，例如交通行为检测，如越线、停车和违规行为。
• 业务逻辑：允许集成任何自定义业务逻辑，以紧密贴合具体业务需求。
• 数据代理：支持将结构化数据（JSON、XML 或自定义格式）通过 Kafka、Socket 等方式推送到云端、文件或其他第三方平台。
• 录制：支持特定时间段的视频录制及特定帧的截图，并可保存为文件。
• 屏幕显示（OSD）：支持在帧上叠加结构化数据及业务逻辑处理结果。
• 视频编码：基于 OpenCV/GStreamer 支持视频和图像编码，并具备硬件加速功能。
• 流推送：支持主流视频流协议，如 UDP、RTSP、RTMP、文件和应用程序；同时也支持图像流传输。

快速入门

依赖项

平台

• Ubuntu 18.04 x86_64，配备 NVIDIA RTX/Tesla 显卡
• Ubuntu 18.04 aarch64，NVIDIA Jetson 系列设备，已测试 TX2 型号
• Ubuntu 22.04 x86_64，基于 Windows 10 的 VMware 虚拟机，纯 CPU 环境
• Ubuntu 18.04 x86_64，Cambrian MLU 系列设备，已测试 MLU 370 型号（未提供代码）
• Ubuntu 18.04 aarch64，Rockchip RK35** 系列设备，已测试 RK3588 型号（未提供代码）
• Ubuntu 22.04 aarch64，Ascend 310/910 系列设备，已测试 Atlas 300I-Pro 型号（未提供代码）
• 欢迎您的测试

基础

• C++ 17
• OpenCV >= 4.6
• GStreamer 1.14.5（OpenCV 所需）
• GCC >= 7.5

可选，如果您需要实现自定义推理后端，或使用除 opencv::dnn 之外的其他后端：

• CUDA
• TensorRT
• Paddle Inference
• ONNX Runtime
• mLLM（Ollama/vLLM/OpenAI 兼容 API 服务）
• 您喜欢的任何工具

如何安装 CUDA 和 TensorRT

如何安装 Paddle_Inference

编译与调试

1. 运行 git clone https://github.com/sherlockchou86/VideoPipe.git
2. 运行 cd VideoPipe
3. 运行 mkdir build && cd build
4. 运行 cmake ..
5. 运行 make -j8

编译完成后，所有库文件将存储在 build/libs 目录下，所有示例可执行文件则位于 build/bin 目录。在第4步中，您可以添加一些编译选项：

• -DVP_WITH_CUDA=ON（编译 CUDA 相关功能；默认为 OFF）
• -DVP_WITH_TRT=ON（编译 TensorRT 相关功能及示例；默认为 OFF）
• -DVP_WITH_PADDLE=ON（编译 PaddlePaddle 相关功能及示例；默认为 OFF）
• -DVP_WITH_KAFKA=ON（编译 Kafka 相关功能及示例；默认为 OFF）
• -DVP_WITH_LLM=ON（编译 LLM 相关功能及示例；默认为 OFF）
• -DVP_BUILD_COMPLEX_SAMPLES=ON（编译高级示例；默认为 OFF）

例如，要启用 CUDA 和 TensorRT 模块，可以运行：

cmake -DVP_WITH_CUDA=ON -DVP_WITH_TRT=ON ..

如果您只运行：

cmake ..

则所有代码将在 CPU 上执行。

要运行编译好的示例，首先需要下载模型文件和测试数据：

1. Google Drive - 下载测试文件和模型
2. 百度网盘 - 下载测试文件和模型

将下载的目录（命名为 vp_data）放置在任意位置（例如 /root/abc）。然后，在 vp_data 所在的目录下运行示例。例如，在 /root/abc 中执行以下命令：

[path to VideoPipe]/build/bin/1-1-1_sample

注意：./third_party/ 目录包含独立的项目。其中一些是仅含头文件的库，直接由 VideoPipe 引用；另一些则包含 CPP 文件，可以单独编译或运行。VideoPipe 依赖这些库，并且它们会在 VideoPipe 的构建过程中自动编译。这些库也包含各自的示例；具体使用方法请参考相应子目录中的 README 文件。

使用方法

以下是使用 VideoPipe 构建并运行示例管道的指南。您可以将 VideoPipe 编译为库并进行链接，也可以直接包含源代码并编译整个应用程序。

下面是一个示例代码，演示如何构建管道并运行它。请务必根据实际情况更新代码中的文件路径：

#include "../nodes/vp_file_src_node.h"
#include "../nodes/infers/vp_yunet_face_detector_node.h"
#include "../nodes/infers/vp_sface_feature_encoder_node.h"
#include "../nodes/osd/vp_face_osd_node_v2.h"
#include "../nodes/vp_screen_des_node.h"
#include "../nodes/vp_rtmp_des_node.h"
#include "../utils/analysis_board/vp_analysis_board.h"

/*
* 名称：1-1-N 示例
* 完整代码位于：samples/1-1-N_sample.cpp
* 功能：1 路视频输入，1 项视频分析任务（人脸检测与识别），2 路输出（屏幕显示/RTMP 流）
*/

int main() {
    VP_SET_LOG_INCLUDE_CODE_LOCATION(false);
    VP_SET_LOG_INCLUDE_THREAD_ID(false);
    VP_LOGGER_INIT();

    // 1. 创建节点
    // 视频源节点
    auto file_src_0 = std::make_shared<vp_nodes::vp_file_src_node>("file_src_0", 0, "./test_video/10.mp4", 0.6);
    
    // 2. 模型推理节点
    // 第一层推理：人脸检测
    auto yunet_face_detector_0 = std::make_shared<vp_nodes::vp_yunet_face_detector_node>("yunet_face_detector_0", "./models/face/face_detection_yunet_2022mar.onnx");
    // 第二层推理：人脸识别
    auto sface_face_encoder_0 = std::make_shared<vp_nodes::vp_sface_feature_encoder_node>("sface_face_encoder_0", "./models/face/face_recognition_sface_2021dec.onnx");
    
    // 3. OSD 节点
    // 在帧上绘制结果
    auto osd_0 = std::make_shared<vp_nodes::vp_face_osd_node_v2>("osd_0");
    
    // 屏幕显示节点
    auto screen_des_0 = std::make_shared<vp_nodes::vp_screen_des_node>("screen_des_0", 0);
    // RTMP 流节点
    auto rtmp_des_0 = std::make_shared<vp_nodes::vp_rtmp_des_node>("rtmp_des_0", 0, "rtmp://192.168.77.60/live/10000");

    // 通过连接节点构建管道
    yunet_face_detector_0->attach_to({file_src_0});
    sface_face_encoder_0->attach_to({yunet_face_detector_0});
    osd_0->attach_to({sface_face_encoder_0});

    // 自动拆分管道，分别用于屏幕显示和 RTMP 流传输
    screen_des_0->attach_to({osd_0});
    rtmp_des_0->attach_to({osd_0});

    // 启动管道
    file_src_0->start();

    // 可视化管道
    vp_utils::vp_analysis_board board({file_src_0});
    board.display();
}

注意：运行此代码将显示三个画面：

1. 管道状态：实时更新的管道运行状态。
2. 屏幕输出：GUI 界面显示的结果。
3. RTMP 输出：可在指定 RTMP URL 上观看的流媒体输出。

原型示例

编号	示例	截图
1	face_tracking_sample
2	vehicle_tracking_sample
3	mask_rcnn_sample
4	openpose_sample
5	face_swap_sample
6	mllm_analyse_sample

总共提供了超过 40 个原型示例。点击此处 查看更多。

更多信息

• 示例代码
• 节点表
• VideoPipe 工作原理
• 开发环境参考

微信讨论群

致谢

VideoPipe 快速上手指南

VideoPipe 是一个基于 C++ 编写的视频分析与结构化框架。它采用插件化（Node）设计，依赖极少，可跨平台运行（支持 x86、ARM、各类加速卡），适用于视频结构化、人脸/车辆识别、行为分析及多模态大模型（mLLM）集成等场景。

1. 环境准备

系统要求

VideoPipe 已在以下平台验证通过：

• x86_64: Ubuntu 18.04 / 22.04 (支持 NVIDIA GPU, 纯 CPU, 寒武纪 MLU)
• aarch64: Ubuntu 18.04 / 22.04 (支持 NVIDIA Jetson, Rockchip RK3588, 华为 Ascend)

前置依赖

确保安装以下基础库：

• C++: 标准需支持 C++ 17
• 编译器: GCC >= 7.5
• 核心库:
  • OpenCV >= 4.6
  • GStreamer >= 1.14.5 (OpenCV 依赖)

可选依赖（按需安装）

若需使用特定推理后端或功能，请额外安装：

• GPU 加速: CUDA, TensorRT
• 其他框架: Paddle Inference, ONNX Runtime
• 大模型: mLLM (Ollama/vLLM/OpenAI-compatible API)
• 消息队列: Kafka

提示：CUDA 和 TensorRT 的安装参考 官方文档；Paddle 安装参考 此处。

2. 安装步骤

第一步：克隆代码

git clone https://github.com/sherlockchou86/VideoPipe.git
cd VideoPipe

第二步：编译构建

创建构建目录并执行 cmake。可根据需求添加编译选项（如启用 CUDA、TensorRT 或 LLM 支持）。

基础编译（仅 CPU）：

mkdir build && cd build
cmake ..
make -j8

启用高级功能示例（CUDA + TensorRT）：

mkdir build && cd build
cmake -DVP_WITH_CUDA=ON -DVP_WITH_TRT=ON ..
make -j8

常用编译选项说明：

• -DVP_WITH_CUDA=ON: 启用 CUDA
• -DVP_WITH_TRT=ON: 启用 TensorRT
• -DVP_WITH_PADDLE=ON: 启用 PaddlePaddle
• -DVP_WITH_LLM=ON: 启用大模型相关功能
• -DVP_BUILD_COMPLEX_SAMPLES=ON: 编译高级示例

编译完成后，库文件位于 build/libs，可执行示例位于 build/bin。

第三步：准备测试数据

下载测试视频和模型文件（任选其一）：

• Google Drive: 下载链接
• 百度网盘: 下载链接 (提取码: nf53)

解压后将文件夹重命名为 vp_data，并将其放置在任意目录（例如 /root/vp_data）。后续运行示例时，需在该目录下执行。

3. 基本使用

VideoPipe 通过组合不同的“节点（Node）”来构建处理流水线。以下是一个最简示例，实现读取视频 -> 人脸检测 -> 人脸识别 -> 屏幕显示/推流的功能。

示例代码 (1-1-N_sample)

请确保已根据实际路径调整代码中的模型和视频文件路径。

#include "../nodes/vp_file_src_node.h"
#include "../nodes/infers/vp_yunet_face_detector_node.h"
#include "../nodes/infers/vp_sface_feature_encoder_node.h"
#include "../nodes/osd/vp_face_osd_node_v2.h"
#include "../nodes/vp_screen_des_node.h"
#include "../nodes/vp_rtmp_des_node.h"
#include "../utils/analysis_board/vp_analysis_board.h"

/*
* 功能：1 路视频输入，1 个分析任务（人脸检测 + 识别），2 路输出（屏幕显示 + RTMP 推流）
*/

int main() {
    VP_SET_LOG_INCLUDE_CODE_LOCATION(false);
    VP_SET_LOG_INCLUDE_THREAD_ID(false);
    VP_LOGGER_INIT();

    // 1. 创建节点
    // 视频源节点
    auto file_src_0 = std::make_shared<vp_nodes::vp_file_src_node>("file_src_0", 0, "./test_video/10.mp4", 0.6);
    
    // 2. 模型推理节点
    // 一级推理：人脸检测
    auto yunet_face_detector_0 = std::make_shared<vp_nodes::vp_yunet_face_detector_node>("yunet_face_detector_0", "./models/face/face_detection_yunet_2022mar.onnx");
    // 二级推理：人脸特征提取
    auto sface_face_encoder_0 = std::make_shared<vp_nodes::vp_sface_feature_encoder_node>("sface_face_encoder_0", "./models/face/face_recognition_sface_2021dec.onnx");
    
    // 3. OSD 节点 (在画面上绘制结果)
    auto osd_0 = std::make_shared<vp_nodes::vp_face_osd_node_v2>("osd_0");
    
    // 输出节点
    auto screen_des_0 = std::make_shared<vp_nodes::vp_screen_des_node>("screen_des_0", 0);
    auto rtmp_des_0 = std::make_shared<vp_nodes::vp_rtmp_des_node>("rtmp_des_0", 0, "rtmp://192.168.77.60/live/10000");

    // 4. 构建流水线 (连接节点)
    yunet_face_detector_0->attach_to({file_src_0});
    sface_face_encoder_0->attach_to({yunet_face_detector_0});
    osd_0->attach_to({sface_face_encoder_0});

    // 分流输出：同时显示在屏幕并推送到 RTMP
    screen_des_0->attach_to({osd_0});
    rtmp_des_0->attach_to({osd_0});

    // 5. 启动流水线
    file_src_0->start();

    // 可视化流水线状态
    vp_utils::vp_analysis_board board({file_src_0});
    board.display();
}

运行示例

假设你将 vp_data 放在了 /root/vp_data，且编译后的程序在 /root/VideoPipe/build/bin：

cd /root/vp_data
/root/VideoPipe/build/bin/1-1-N_sample

运行后将看到三个窗口/效果：

1. 流水线状态板：实时显示各节点处理状态。
2. 屏幕输出：带有检测框和识别结果的 видео画面。
3. RTMP 流：可通过播放器访问指定的 RTMP 地址观看。

更多示例（如车辆追踪、姿态估计、大模型分析等）请参考 samples 目录或 示例列表。