# USB摄像头 ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- 本项目以 Quectel Pi M2 作为相机应用的主要运行平台，支持实时预览、拍照、录像、多摄像头选择、摄像头重新扫描和错误提示，适用于基于 Quectel Pi M2 的桌面相机、开发板相机终端、边缘视觉设备和产品功能演示。 ## **开发配件清单** 说明：以下为推荐开发配件，实际使用时可根据目标平台和展示场景灵活调整。 | **配件名称** | **

数量
** | **规格或要求** | | --- | --- | --- | | Quectel Pi M2智能主控板 |

1 块
| Quectel Pi M2智能主控板 | | USB UVC 摄像头 |

1 个或多个
| 能被 Quectel Pi M2智能主控板 识别为 V4L2 设备，建议支持 MJPEG、30 FPS 或更高帧率 | | USB 数据线 |

1 根或多根
| 用于连接摄像头和Quectel Pi M2智能主控板；多摄像头场景需确认 USB 带宽和供电能力 | | 显示器 |

1 台
| 用于运行桌面应用和查看实时预览 | | 键盘、鼠标 |

各 1 个
| 用于桌面环境下的应用操作 | ### **配件实物参考** ```{image} images/image_I4yObTVxzor64IxmFQEcMQi9ndh.webp :width: 1160px :height: 688px :align: center ``` ## **快速上手** ### **环境要求** - Quectel Pi M2 智能主控板，运行 Linux 桌面环境。 - 具备相同软件条件的 Linux 主机可用于开发和兼容性验证，但项目主要面向 Quectel Pi M2 部署。 - Qt 5.15 或兼容版本。 - 支持 C++11 的 C++ 编译器。 - `qmake`、`make` 和 `pkg-config`。 - GStreamer 1.0 运行时和开发包。 - 一个或多个可访问的 V4L2 摄像头。 - 录像功能至少需要一个可用的 H.264 编码器插件。 ### **安装基础依赖** 本项目以 Quectel Pi M2 智能主控板作为主要验证平台。请先确保主控板已经正常启动 Linux 桌面环境，并接入显示器、键盘和鼠标，再按照以下步骤安装依赖。除 Quectel Pi M2 外，具备相同 Qt、GStreamer 和 V4L2 软件条件的 Linux 主机也可用于兼容性验证。 不同 Linux 发行版的软件包名称可能不同，以下命令以 Debian/Ubuntu 系统为参考。请根据目标系统的 Qt 版本和 GStreamer 包名进行调整。 ```bash sudo apt update sudo apt install -y \ build-essential \ qt5-qmake qtbase5-dev qtdeclarative5-dev \ pkg-config \ libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev \ gstreamer1.0-tools \ gstreamer1.0-plugins-base \ gstreamer1.0-plugins-good \ gstreamer1.0-plugins-bad \ gstreamer1.0-plugins-ugly \ gstreamer1.0-libav ``` 说明：部分系统可能需要额外安装 Qt Quick Controls 2 相关运行包。若使用硬件 H.264 编码器，还需要安装目标平台对应的 GStreamer 编码器插件。 ### **检查摄像头和插件** 查看系统是否发现摄像头： ```bash ls /dev/video* ``` 检查预览所需插件： ```bash gst-inspect-1.0 v4l2src gst-inspect-1.0 appsink gst-inspect-1.0 jpegdec gst-inspect-1.0 videoconvert ``` 检查录像编码器： ```bash gst-inspect-1.0 mpph264enc gst-inspect-1.0 x264enc gst-inspect-1.0 openh264enc gst-inspect-1.0 avenc_h264 ``` 只要至少有一个 H.264 编码器检查成功，应用就可以尝试启动录像功能。 ### **设置摄像头访问权限** 如果应用提示没有摄像头访问权限，先查看当前用户所属用户组： ```bash groups ``` 将当前用户加入 `video` 用户组后重新登录： ```bash sudo usermod -aG video "$USER" ``` 也可以临时检查设备权限： ```bash ls -l /dev/video* ``` ### **编译项目** 进入项目目录执行： ```bash cd camj/camapp_latest qmake camapp.pro make -j"$(nproc)" ``` 如果系统同时安装了多个 Qt 版本，请使用目标 Qt 版本对应的 `qmake`。 ### **启动应用** ```bash ./camapp ``` 启动后，应用会自动扫描摄像头并尝试选择最佳采集模式。默认优先选择 MJPEG，并综合考虑帧率和分辨率。 ## **应用使用方法** ### **主界面** 主界面主要包含以下区域： 1. 顶部采集状态 2. 实时预览区域 3. 摄像头信息 4. 工作状态 5. 拍照/录像按钮 6. LIVE/REC 状态指示 7. 摄像头选择与 Rescan 8. Toast 操作提示 ```{image} images/image_N9PhbpZvfoOHQMxbf3ccd6gunkf.webp :width: 1284px :height: 854px :align: center ``` ### **拍照** 1. 连接并确认摄像头已经显示实时画面。 2. 点击拍照按钮。 3. 等待界面提示照片保存成功。 4. 在默认照片目录中查看 JPG 文件。 MJPEG 模式下，应用优先保存采集到的原始 JPEG 数据；YUYV 模式下，应用将当前预览帧保存为 JPG。 照片默认保存到： ```plaintext ~/Pictures/Camera/ ``` 文件名格式如下： ```plaintext IMG_yyyyMMdd_HHmmss_zzz.jpg ``` 实际路径由系统的 `QStandardPaths` 决定。如果系统没有返回标准图片，应用会回退到用户主目录下的 `Pictures` 目录。 ```{image} images/image_B7W7bw6LzoOGrDxDBrBcZQbZnIe.webp :width: 1286px :height: 849px :align: center ``` ```{image} images/image_GELmbb79Wow1qFxJkE5c6rhwnPb.webp :width: 1817px :height: 740px :align: center ``` ### **录像** 1. 确认系统中至少存在一个可用的 H.264 编码器。 2. 点击录像按钮开始录制，界面状态切换为 REC。 3. 录制过程中可以观察录像时长。 4. 再次点击录像按钮停止录制。 5. 在默认视频目录中查看 MP4 文件。 录像过程中会禁用摄像头切换，停止录像后才可以重新选择设备。 视频默认保存到： ```plaintext ~/Videos/Camera/ ``` 文件名格式如下： ```plaintext VID_yyyyMMdd_HHmmss.mp4 ``` 实际路径由系统的 `QStandardPaths` 决定。如果系统没有返回标准视频目录，应用会回退到用户主目录下的 `Videos` 目录。
录屏 2026-10-12 03-46-29
### **切换摄像头** 连接多个摄像头后，应用底部的摄像头下拉框会显示可用设备： 1. 停止当前录像（如正在录像）。 2. 打开摄像头下拉框。 3. 选择目标摄像头。 4. 应用会停止旧管线，重新检测新设备的能力，并启动新的预览管线。 ```{image} images/image_MefPbISRnomCPsxBTPQc0hZqnvf.webp :width: 1286px :height: 849px :align: center ``` ### **重新扫描摄像头** 插拔摄像头或更换 USB 设备后，可以点击 Rescan/重新扫描按钮： 1. 点击重新扫描。 2. 应用重新枚举 `/dev/v4l/by-id/*video-index0` 和 `/dev/video*`。 3. 选择可用摄像头并恢复预览。 ## **录像编码器配置** 应用默认按以下顺序自动选择第一个可用编码器： ```plaintext mpph264enc → x264enc → openh264enc → avenc_h264 ``` 可以通过 `CAMAPP_VIDEO_ENCODER` 指定编码器： ```bash CAMAPP_VIDEO_ENCODER=x264enc ./camapp ``` 支持的值为： ```plaintext mpph264enc x264enc openh264enc avenc_h264 ``` 如果指定的编码器不存在，应用会提示安装对应 GStreamer 插件或取消该环境变量。硬件平台建议优先使用平台提供的硬件编码器，以降低 CPU 占用。 ## **应用演示** ```{image} images/image_OEwJbtSkXoH7AQxelD7cpMYwn5e.webp :width: 1284px :height: 854px :align: center ```
10月13日
## **常见问题排查** ### **启动后没有摄像头画面** 1. 检查摄像头是否连接并执行 `ls /dev/video*`。 2. 确认当前用户有访问视频设备的权限。 3. 确认摄像头支持 MJPEG 或 YUYV。 4. 检查 `v4l2src`、`appsink`、`jpegdec` 和 `videoconvert` 是否安装。 5. 关闭可能占用摄像头的其他应用后重新启动 Camera Studio。 ### **应用提示没有权限** 确认当前用户已经加入 `video` 用户组，并重新登录系统。也可以使用 `ls -l /dev/video*` 检查设备节点权限。 ### **应用提示缺少 GStreamer 插件** 根据界面提示安装缺少的 element。实时预览通常需要 `v4l2src`、`appsink`、`jpegdec` 和 `videoconvert`；录像还需要 `appsrc`、H.264 编码器、`h264parse` 和 `mp4mux`。 ### **录像启动失败** 依次检查： 1. 是否至少安装了一个 H.264 编码器。 2. 编码器是否支持当前平台和输入格式。 3. 是否指定了不存在的 `CAMAPP_VIDEO_ENCODER`。 4. 是否有足够的磁盘空间写入视频目录。 可以先取消环境变量，恢复自动选择： ```bash unset CAMAPP_VIDEO_ENCODER ./camapp ``` ### **多个摄像头无法同时稳定使用** 检查 USB 集线器供电、USB 带宽和摄像头分辨率。可以减少同时连接的摄像头数量，或使用带独立供电的 USB 集线器。 ### **编译时找不到 Qt 或 GStreamer** 确认 `qmake --version`、`make --version`、`pkg-config --version` 和 `gst-inspect-1.0 --version` 均可执行。若系统存在多个 Qt 版本，请使用对应版本的 `qmake` 重新生成工程文件。 ## **技术支持与贡献** 如在使用或二次开发过程中遇到问题，建议在项目 Issue 中提供以下信息：Linux 发行版和版本、Qt 版本、GStreamer 版本、摄像头型号、完整错误提示以及相关命令输出。如在使用过程中遇到问题，欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。