ccap 命令行工具

基于 CameraCapture (ccap) 库的强大命令行界面工具。

概述

ccap 命令行工具提供了全面的相机操作命令行界面,包括设备枚举、帧捕获、格式转换和可选的实时预览。它专为自动化、脚本编程和快速测试相机功能而设计。

功能特性

设备发现: 列出所有可用相机及其详细功能
帧捕获: 以各种分辨率和像素格式捕获帧
格式支持: RGB、BGR、RGBA、BGRA、YUV (NV12、I420、YUYV、UYVY)
YUV 操作: 直接 YUV 捕获和 YUV 转图像转换
实时预览: 基于 OpenGL 的预览窗口(需 GLFW 支持)
自动化友好: 专为脚本和 CI/CD 流水线设计
跨平台: Windows、macOS、Linux

构建 CLI 工具

基本构建

cmake -B build -DCCAP_BUILD_CLI=ON
cmake --build build

启用预览支持构建 (GLFW)

cmake -B build -DCCAP_BUILD_CLI=ON -DCCAP_CLI_WITH_GLFW=ON
cmake --build build

启用图片格式支持构建 (JPG/PNG)

cmake -B build -DCCAP_BUILD_CLI=ON -DCCAP_CLI_WITH_STB_IMAGE=ON
cmake --build build

默认情况下，CCAP_CLI_WITH_STB_IMAGE 是启用的，除了 BMP 外还提供 JPG 和 PNG 格式支持。如果要禁用此功能而仅使用 BMP：

cmake -B build -DCCAP_BUILD_CLI=ON -DCCAP_CLI_WITH_STB_IMAGE=OFF
cmake --build build

优化的 Release 构建

对于生产环境使用，建议使用 Release 模式构建以获得最佳性能和最小体积：

cmake -B build -DCMAKE_BUILD_TYPE=Release -DCCAP_BUILD_CLI=ON
cmake --build build

Release 构建自动启用的优化：

链接时优化 (LTO/IPO) 以获得更好的性能 (+20%) 和更小的体积
符号表剥离以实现最小二进制体积 (减少约 25%)
编译器优化 (-O3)

预期二进制文件大小：

Debug: ~6MB (包含调试符号)
Release: ~1.8MB (优化并剥离符号)
MinSizeRel: ~1.5MB (体积优化，性能略有权衡)

可执行文件将位于 build/ 目录(或 build/Debug、build/Release,取决于您的构建配置)。

静态运行时链接

Windows (MSVC)：CLI 工具使用静态运行时链接（/MT 标志）来消除对 VCRUNTIME DLL 的依赖，允许单文件分发而无需用户安装 Visual C++ 运行库。

Windows 后端覆盖：在 Windows 上，CLI 现在也支持 --camera-backend auto|msmf|dshow，以及 --auto、--msmf、--dshow 这几个别名。参数生效后，CLI 会输出当前选中的后端覆盖日志。如果你更希望使用进程级覆盖，也可以在启动前设置 CCAP_WINDOWS_BACKEND=auto|msmf|dshow。

Linux：当可用时尝试静态链接 libstdc++ 和 libgcc。如果不可用（例如 Fedora 未安装 libstdc++-static 包），则回退到动态链接。二进制文件仍然依赖 glibc，可能无法在旧 glibc 版本的系统上运行。

命令行参考

通用选项

选项	描述
`-h, --help`	显示帮助信息并退出
`-v, --version`	显示版本信息
`--verbose`	启用详细日志输出
`--json`	对已支持的命令输出结构化 JSON
`--schema-version VERSION`	设置 JSON 输出中的 schema_version 字段（默认：`1.0`）

Windows 相机后端选项

这些选项仅在 Windows 上支持。

选项	描述
`--camera-backend auto\|msmf\|dshow`	显式选择 Windows 相机后端
`--auto`	`--camera-backend auto` 的别名
`--msmf`	`--camera-backend msmf` 的别名
`--dshow`	`--camera-backend dshow` 的别名

设备枚举

选项	描述
`-l, --list-devices`	列出所有可用的相机设备
`-i, --device-info [INDEX]`	显示指定索引设备的详细功能如果省略 INDEX,则显示所有设备的信息

捕获选项

选项	默认值	描述
`-d, --device INDEX\|NAME`	`0`	通过索引或名称选择相机设备
`-w, --width WIDTH`	`1280`	设置捕获宽度(像素)
`-H, --height HEIGHT`	`720`	设置捕获高度(像素)
`-f, --fps FPS`	`30.0`	设置帧率（支持浮点数，例如 29.97）相机模式：设置相机的捕获帧率视频模式：计算播放速度（例如视频是 15fps，--fps 30 → 2.0倍速）注意：不能与 `--speed` 同时使用
`-c, --count COUNT`	`1`	要捕获的帧数
`-t, --timeout MS`	`5000`	捕获超时时间(毫秒)
`-o, --output DIR`	-	捕获图像的输出目录
`--format FORMAT`	-	输出像素格式(参见支持的格式)
`--internal-format FORMAT`	-	相机的内部像素格式
`--save-yuv`	-	将帧保存为原始 YUV 数据而不转换为图像
`--image-format FORMAT`	`jpg`	图像输出格式：`jpg`、`png`、`bmp`（jpg/png 需要 `CCAP_CLI_WITH_STB_IMAGE=ON`）
`--jpeg-quality QUALITY`	`90`	JPEG 质量 (1-100，仅用于 JPG 格式)

预览选项

这些选项仅在启用 GLFW 支持(CCAP_CLI_WITH_GLFW=ON)构建时可用。

选项	描述
`-p, --preview`	启用实时预览窗口
`--preview-only`	仅显示预览,不保存帧到磁盘

视频播放选项

选项	描述
`-i, --input FILE`	输入视频文件路径
`--loop[=N]`	循环播放视频。省略 N 表示无限循环，指定 N 表示精确循环次数
`--speed SPEED`	播放速度倍数 `0.0` = 无帧率控制（以最快速度处理） `1.0` = 正常速度（匹配视频原始帧率） `>1.0` = 加速播放（例如 2.0 = 2倍速） `<1.0` = 减速播放（例如 0.5 = 半速）默认值：捕获模式下为 `0.0`，预览模式下为 `1.0` 注意：不能与 `-f/--fps` 同时使用

注意： --loop 和 -c 选项互斥。使用 -c 限制捕获帧数，或使用 --loop 循环播放视频，但不能同时使用两者。

格式转换

选项	描述
`--convert INPUT`	将 YUV 文件转换为 BMP 图像
`--yuv-format FORMAT`	指定 YUV 输入格式(参见YUV 格式)
`--yuv-width WIDTH`	YUV 输入文件的宽度
`--yuv-height HEIGHT`	YUV 输入文件的高度
`--convert-output FILE`	转换后图像的输出文件路径

支持的格式

RGB/BGR 格式

rgb24 - 24位 RGB (每通道 8 位)
bgr24 - 24位 BGR (每通道 8 位)
rgba32 - 32位 RGBA (每通道 8 位 + alpha)
bgra32 - 32位 BGRA (每通道 8 位 + alpha)

YUV 格式

nv12 - YUV 4:2:0 半平面 (UV 交错)
nv12f - YUV 4:2:0 半平面 (全范围)
i420 - YUV 4:2:0 平面 (独立的 U 和 V 平面)
i420f - YUV 4:2:0 平面 (全范围)
yuyv - YUV 4:2:2 打包 (YUYV 顺序)
yuyvf - YUV 4:2:2 打包 (YUYV 顺序,全范围)
uyvy - YUV 4:2:2 打包 (UYVY 顺序)
uyvyf - YUV 4:2:2 打包 (UYVY 顺序,全范围)

使用示例

设备发现

列出所有可用相机:

ccap --list-devices

显示第一个相机的详细信息:

ccap --device-info 0

显示所有相机的信息:

ccap --device-info

以 JSON 形式列出设备，便于脚本或 Agent 消费:

ccap --list-devices --json

以 JSON 形式查看单个设备的能力信息:

ccap --device-info 0 --json

以 JSON 形式输出视频元数据:

ccap -i /path/to/video.mp4 --json

当前 JSON 输出先覆盖设备枚举、设备信息和视频元数据。返回体采用稳定的顶层结构，包含 schema_version、command 与 success；成功时返回 data，错误时返回 exit_code 和 error。

基本帧捕获

从默认相机捕获单帧（默认保存为 JPG）:

ccap -d 0 -o ./captures

以 1080p 分辨率捕获 10 帧:

ccap -d 0 -w 1920 -H 1080 -c 10 -o ./captures

使用特定相机名称捕获:

ccap -d "HD Pro Webcam C920" -c 5 -o ./captures

图片格式选项

捕获帧为 JPEG 格式（默认，需要 CCAP_CLI_WITH_STB_IMAGE=ON）:

ccap -d 0 -c 5 -o ./captures --image-format jpg

捕获帧为 PNG 格式:

ccap -d 0 -c 5 -o ./captures --image-format png

捕获帧为 BMP 格式（始终可用）:

ccap -d 0 -c 5 -o ./captures --image-format bmp

使用自定义 JPEG 质量捕获:

ccap -d 0 -c 5 -o ./captures --image-format jpg --jpeg-quality 95

特定格式捕获

以 BGR24 格式捕获帧:

ccap -d 0 --format bgr24 -c 5 -o ./captures

使用特定的内部相机格式捕获(以提高性能):

ccap -d 0 --internal-format nv12 --format bgr24 -c 5 -o ./captures

YUV 操作

将帧保存为原始 YUV 数据:

ccap -d 0 --format nv12 --save-yuv -c 5 -o ./yuv_captures

将 YUV 文件转换为 BMP 图像:

ccap --convert input.yuv \
     --yuv-format nv12 \
     --yuv-width 1920 \
     --yuv-height 1080 \
     --convert-output output.bmp

将 YUV 文件转换为 JPEG（需要 CCAP_CLI_WITH_STB_IMAGE=ON）:

ccap --convert input.yuv \
     --yuv-format nv12 \
     --yuv-width 1920 \
     --yuv-height 1080 \
     --convert-output output.jpg \
     --image-format jpg \
     --jpeg-quality 90

将 YUV 文件转换为 PNG:

ccap --convert input.yuv \
     --yuv-format nv12 \
     --yuv-width 1920 \
     --yuv-height 1080 \
     --convert-output output.png \
     --image-format png

预览模式

实时预览相机画面(需要 GLFW):

ccap -d 0 --preview

仅预览,不保存帧:

ccap -d 0 --preview-only

在捕获帧的同时预览:

ccap -d 0 -w 1920 -H 1080 -c 10 -o ./captures --preview

视频播放

从视频文件提取 30 帧:

ccap -i /path/to/video.mp4 -c 30 -o ./frames

无限循环播放视频:

ccap -i /path/to/video.mp4 --preview --loop

循环播放视频 5 次:

ccap -i /path/to/video.mp4 --preview --loop=5

以 2 倍速预览视频:

ccap -i /path/to/video.mp4 --preview --speed 2.0

以最快速度提取帧（无帧率控制）:

ccap -i /path/to/video.mp4 -c 100 -o ./frames --speed 0.0

以半速预览视频（慢动作）:

ccap -i /path/to/video.mp4 --preview --speed 0.5

使用 --fps 控制播放（自动计算速度）：

# 视频是 30fps，以 60fps 播放（2倍速）
ccap -i /path/to/video.mp4 --preview --fps 60

# 视频是 30fps，以 15fps 播放（0.5倍速）
ccap -i /path/to/video.mp4 --preview --fps 15

高级用法

使用自定义超时和高帧率捕获:

ccap -d 0 -w 1920 -H 1080 -f 60 -c 100 -t 10000 -o ./captures

启用详细日志用于调试:

ccap --verbose -d 0 -c 5 -o ./captures

输出文件

图像文件 (BMP)

在 RGB/BGR 格式捕获或将 YUV 转换为图像时,文件保存为:

<output_dir>/capture_<时间戳>_<分辨率>_<帧索引>.bmp

示例: captures/capture_20231224_153045_1920x1080_0.bmp

YUV 文件

使用 --save-yuv 时,原始 YUV 数据保存为:

<output_dir>/capture_<时间戳>_<分辨率>_<帧索引>.<格式>.yuv

示例: yuv_captures/capture_20231224_153045_1920x1080_0.NV12.yuv

这些文件包含原始平面或打包 YUV 数据,没有任何容器格式。

错误处理

CLI 工具返回以下退出代码:

退出代码	含义
`0`	成功
`1`	无效参数或用法错误
`2`	未找到相机设备
`3`	相机打开/启动失败
`4`	帧捕获失败
`5`	文件 I/O 错误

集成示例

Bash 脚本

#!/bin/bash
# 从所有可用相机捕获帧

# 列出设备
ccap --list-devices

# 从每个相机捕获
for i in 0 1 2; do
    mkdir -p "camera_${i}_captures"
    ccap -d "$i" -w 1920 -H 1080 -c 5 -o "camera_${i}_captures" || true
done

Python 集成

import subprocess
import json

# 运行 ccap 并捕获输出
result = subprocess.run(
    ['ccap', '--list-devices'],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    print("找到的设备:")
    print(result.stdout)
    
    # 捕获帧
    subprocess.run([
        'ccap', '-d', '0', 
        '-w', '1920', '-H', '1080',
        '-c', '10', 
        '-o', './captures'
    ])

Makefile 集成

.PHONY: capture test-camera

capture:
	mkdir -p captures
	ccap -d 0 -w 1920 -H 1080 -c 5 -o ./captures

test-camera:
	ccap --list-devices
	ccap --device-info 0

性能提示

使用内部格式: 指定 --internal-format 以匹配相机的原生格式,以获得更好的性能
直接 YUV 捕获: 当需要 YUV 数据时使用 --save-yuv,避免不必要的转换
更大的超时: 对于高分辨率捕获或慢速相机,增加 --timeout
硬件加速: 库会在可用时自动使用硬件加速(AVX2、NEON、Apple Accelerate)

故障排除

未找到设备

ccap --list-devices
# 返回: No camera devices found

解决方案:

确保相机已连接并被操作系统识别
在 Linux 上,检查是否有 /dev/video* 设备的权限
尝试使用 --verbose 运行以获取更多详细信息

权限被拒绝(Linux)

# 将用户添加到 video 组
sudo usermod -a -G video $USER
# 然后注销并重新登录

捕获超时

ccap -d 0 -c 1 -o ./captures
# 错误: Frame capture timeout