Virtual Camera Proxy (vcam)

A high-performance, zero-latency Linux V4L2 virtual camera proxy tool designed for seamless hotkey switching between live webcam feed and pre-recorded looping video.

功能特性 • 架构原理 • 快速开始 • 热键说明 • 代码规范 • 进阶文档

---

🚀 功能特性

• ⚡ 无缝帧级切换（~33ms）：基于 V4L2 内核 Loopback 管道，会议软件（腾讯会议、Zoom、Teams、钉钉）全程无需重选设备、0黑屏、0卡顿。
• 🎯 现场自适应录制：支持开会时现场按键实时抓取 10~20 秒当前光线、穿着与背景表情，录完自动进入循环假人模式，杜绝光线/着装穿帮。
• 🏎️ 高性能与超低开销：
  • 内存环形帧队列（RAM Ring Buffer）回放，0 磁盘 I/O 抖动。
  • 内置定点数优化的 BGR24 -> YUYV422 像素转换内核，单帧耗时 < 0.3ms。
  • CPU 占用率 $< 2%$，内存占用 $< 80\text{MB}$。
• 🛡️ 纯天然设备隔离：独占物理摄像头节点，避免第三方软件旁路读取。
• 💎 遵循 Google C++ 代码规范：采用现代 C++17、RAII 资源管理、严格的编译告警检查（-Wall -Wextra -Wpedantic）。

---

📐 架构原理

[ 会议软件: 腾讯会议 / Zoom / Teams / 钉钉 / 微信 ]
                     |
                     | (只连接虚拟节点，全程不重连、不换设备)
                     v
             /dev/video10 (VirtualCam)
                     ^
                     | (推流 YUYV422 @ 30FPS)
        +-------------------------+
        |   virtual_cam_proxy     |
        +-------------------------+
           |                   ^
           | (直通复制)         | (内存帧循环)
           v                   |
  [ 模式 1: LIVE 真人 ]       +-------------------------+
  读取物理摄像头 /dev/video0                            |
           |                                            |
           +---> [ 模式 2: RECORDING 录制 10s 现场 ] ----+

---

🛠️ 快速开始

1. 安装依赖与配置内核模块

git clone https://github.com/lilucpp/GhostCam.git
cd GhostCam

# 运行自动化环境检查与 v4l2loopback 模块加载
./scripts/setup_v4l2.sh

2. 编译构建

./scripts/build.sh

3. 启动代理服务

./build/virtual_cam_proxy

自定义参数运行：

./build/virtual_cam_proxy -i 0 -o /dev/video10 -d 15 -w 1280 -h 720 -f 30

4. 会议软件设置

1. 打开腾讯会议 / Zoom / 钉钉；
2. 进入【设置】->【视频】，摄像头选择 VirtualCam（不要选择物理摄像头）；
3. 保持该设置，会议全程由本代理工具接管。

---

⌨️ 热键说明

热键	模式	行为描述
R	录制现场 (RECORDING)	现场抓取 $N$ 秒当前光线与着装画面，录制完毕自动切入循环播放
L	假人循环 (LOOP)	立即进入预录制内存循环播放模式（假装在线）
S	真人直通 (LIVE)	瞬间秒切回物理摄像头实时画面（被提问发言时切回真人）
Q / ESC	退出	安全释放 V4L2 句柄与内存资源退出

---

📁 代码规范与工程结构

本项目严格遵循 Google C++ Style Guide 与现代 CMake 最佳实践：

virtual-cam-proxy/
├── CMakeLists.txt              # 现代 CMake 构建配置
├── LICENSE                     # MIT 开源许可证
├── README.md                   # 项目主页与说明
├── .clang-format               # Google 官方 C++ 格式化规则
├── .gitignore
├── include/
│   └── vcam/
│       ├── color_converter.h   # BGR 转 YUYV422 像素转换接口
│       ├── input_handler.h     # 终端非阻塞按键监听封装
│       ├── proxy_engine.h      # 核心状态机调度引擎
│       └── v4l2_sink.h         # V4L2 裸设备写入 RAII 封装
├── src/
│   ├── color_converter.cc
│   ├── input_handler.cc
│   ├── main.cc                 # 程序入口与命令行解析
│   ├── proxy_engine.cc
│   └── v4l2_sink.cc
├── scripts/
│   ├── build.sh                # 一键构建脚本
│   └── setup_v4l2.sh           # 模块加载与依赖检测脚本
└── docs/
    ├── troubleshooting_guide.md                  # V4L2 故障诊断排查指南
    └── video_stream_formats_and_diagnostics.md  # 视频流格式全景与抓包实战

---

📚 进阶文档

• 📖 V4L2 虚拟摄像头故障排查与诊断指南 (docs/troubleshooting_guide.md)
  • 包含排查 SOP 流程图、v4l2-ctl、fuser、strace、ffplay 诊断工具箱；
  • 覆盖 EINVAL 格式锁定、黑屏、EBUSY 独占锁等 5 大典型故障的根因与一键自愈方案。
• 📖 音视频流格式全景与 Linux 视频设备诊断指南 (docs/video_stream_formats_and_diagnostics.md)
  • 深入剖析 YUYV、I420、NV12、MJPEG 格式差异与选型；
  • 腾讯会议、微信、钉钉等软件的底层采集协商机制与抓包方法。

---

📄 开源许可证

本项目基于 MIT License 开源。