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 个

用于桌面环境下的应用操作

配件实物参考

../../../_images/image_I4yObTVxzor64IxmFQEcMQi9ndh.webp

快速上手

环境要求

  • 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 包名进行调整。

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 编码器插件。

检查摄像头和插件

查看系统是否发现摄像头：

ls /dev/video*

检查预览所需插件：

gst-inspect-1.0 v4l2src
gst-inspect-1.0 appsink
gst-inspect-1.0 jpegdec
gst-inspect-1.0 videoconvert

检查录像编码器：

gst-inspect-1.0 mpph264enc
gst-inspect-1.0 x264enc
gst-inspect-1.0 openh264enc
gst-inspect-1.0 avenc_h264

只要至少有一个 H.264 编码器检查成功，应用就可以尝试启动录像功能。

设置摄像头访问权限

如果应用提示没有摄像头访问权限，先查看当前用户所属用户组：

groups

将当前用户加入 video 用户组后重新登录：

sudo usermod -aG video "$USER"

也可以临时检查设备权限：

ls -l /dev/video*

编译项目

进入项目目录执行：

cd camj/camapp_latest
qmake camapp.pro
make -j"$(nproc)"

如果系统同时安装了多个 Qt 版本，请使用目标 Qt 版本对应的 qmake。

启动应用

./camapp

启动后，应用会自动扫描摄像头并尝试选择最佳采集模式。默认优先选择 MJPEG，并综合考虑帧率和分辨率。

应用使用方法

主界面

主界面主要包含以下区域：

  1. 顶部采集状态

  2. 实时预览区域

  3. 摄像头信息

  4. 工作状态

  5. 拍照/录像按钮

  6. LIVE/REC 状态指示

  7. 摄像头选择与 Rescan

  8. Toast 操作提示

../../../_images/image_N9PhbpZvfoOHQMxbf3ccd6gunkf.webp

拍照

  1. 连接并确认摄像头已经显示实时画面。

  2. 点击拍照按钮。

  3. 等待界面提示照片保存成功。

  4. 在默认照片目录中查看 JPG 文件。

MJPEG 模式下，应用优先保存采集到的原始 JPEG 数据；YUYV 模式下，应用将当前预览帧保存为 JPG。

照片默认保存到：

~/Pictures/Camera/

文件名格式如下：

IMG_yyyyMMdd_HHmmss_zzz.jpg

实际路径由系统的 QStandardPaths 决定。如果系统没有返回标准图片，应用会回退到用户主目录下的 Pictures 目录。

../../../_images/image_B7W7bw6LzoOGrDxDBrBcZQbZnIe.webp ../../../_images/image_GELmbb79Wow1qFxJkE5c6rhwnPb.webp

录像

  1. 确认系统中至少存在一个可用的 H.264 编码器。

  2. 点击录像按钮开始录制，界面状态切换为 REC。

  3. 录制过程中可以观察录像时长。

  4. 再次点击录像按钮停止录制。

  5. 在默认视频目录中查看 MP4 文件。

录像过程中会禁用摄像头切换，停止录像后才可以重新选择设备。

视频默认保存到：

~/Videos/Camera/

文件名格式如下：

VID_yyyyMMdd_HHmmss.mp4

实际路径由系统的 QStandardPaths 决定。如果系统没有返回标准视频目录，应用会回退到用户主目录下的 Videos 目录。

录屏 2026-10-12 03-46-29

切换摄像头

连接多个摄像头后，应用底部的摄像头下拉框会显示可用设备：

  1. 停止当前录像（如正在录像）。

  2. 打开摄像头下拉框。

  3. 选择目标摄像头。

  4. 应用会停止旧管线，重新检测新设备的能力，并启动新的预览管线。

../../../_images/image_MefPbISRnomCPsxBTPQc0hZqnvf.webp

重新扫描摄像头

插拔摄像头或更换 USB 设备后，可以点击 Rescan/重新扫描按钮：

  1. 点击重新扫描。

  2. 应用重新枚举 /dev/v4l/by-id/*video-index0 和 /dev/video*。

  3. 选择可用摄像头并恢复预览。

录像编码器配置

应用默认按以下顺序自动选择第一个可用编码器：

mpph264enc → x264enc → openh264enc → avenc_h264

可以通过 CAMAPP_VIDEO_ENCODER 指定编码器：

CAMAPP_VIDEO_ENCODER=x264enc ./camapp

支持的值为：

mpph264enc
x264enc
openh264enc
avenc_h264

如果指定的编码器不存在，应用会提示安装对应 GStreamer 插件或取消该环境变量。硬件平台建议优先使用平台提供的硬件编码器，以降低 CPU 占用。

应用演示

../../../_images/image_OEwJbtSkXoH7AQxelD7cpMYwn5e.webp
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. 是否有足够的磁盘空间写入视频目录。

可以先取消环境变量，恢复自动选择：

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 版本、摄像头型号、完整错误提示以及相关命令输出。如在使用过程中遇到问题，欢迎在 移远官方论坛 提交技术咨询，我们的技术支持团队将及时为您解答。