简介面向Android底层开发与USB外设接入方向的C/C项目资源对应Android-UVC-Camera应用用于通过OTG连接UVC摄像头并实现视频流采集。项目基于Android Studio构建适配Micro USB与Type-C接口并集成LibUsb以改善标准USB设备驱动的性能可作为中高级开发者研究Android USB Host、Camera驱动与视频流的参考实现。压缩包共1447个文件大小约9.67MB包含大量c/h/cc/cpp源码、java工程文件、xml配置、so动态库及mk/gn构建脚本另有png/jpg示意图与md说明文档目录结构完整便于按模块阅读。资源已有448人学习内容虽标注仍在开发中但足以展示USB摄像头接入的系统框架、OTG兼容性处理与LibUsb整合思路适合用于源码剖析、驱动调试或移植到其他嵌入式平台。1. Android-UVC-Camera为什么外接USB摄像头在Android上是个生死局把一支标准的USB摄像头插到Android设备上并且流畅出图这个需求在工业巡检、医疗内窥、视频会议一体机、直播推流盒子上反复出现。很多团队第一次接这个需求时都以为“插上去系统自己就能识别”结果发现 Camera2 API 面对UVC设备基本是瞎的——系统相机框架压根不把USB摄像头当摄像头看待。Android-UVC-Camera 这条技术路线本质上就是绕过系统相机框架直接通过 USB Host 通道和摄像头对话把 UVC 协议的数据流接进来。这条路不是没有坑但确实是目前安卓设备外接USB摄像头最主流的方案。这篇笔记会从协议层讲起落到权限、枚举、预览、拍照、录像的完整实现再把供电、格式、带宽、掉帧这几个最常见的问题逐条拆开。适合做Android底层开发、工业平板应用、或者想给安卓盒子外挂USB视觉能力的工程师新手能按步骤跑通熟手也能在参数层面找到值得调的地方。2. UVC协议与Android USB Host先搞清楚摄像头数据从哪条路进来2.1 为什么UVC摄像头能“免驱”UVCUSB Video Class是USB规范里的视频设备类协议摄像头厂商只要按这个协议实现描述符和传输逻辑主机端就不需要装厂商驱动。Android 3.1 开始支持 USB Host 模式所以在系统层面UVC 摄像头插上 OTG 线之后USB 枚举是可以完成的UsbDevice里能看到这个设备。问题在于Android 上层的相机架构只认自身定义的 Camera HAL 设备UVC 摄像头不在这个列表里所以 Camera2 API 拿不到它。数据链路实际上是这样的摄像头把 YUYV 或 MJPEG 格式的视频流通过 USB Bulk 端点发出来主机端通过UsbDeviceConnection的bulkTransfer或者基于 libuvc 的 Android 封装去读这些数据包再解码成 Image 帧最后交给TextureView或SurfaceView渲染。整条链路里没有系统相机 HAL 什么事所以你拥有完全的控制权但也要自己处理格式协商、带宽分配和帧同步。2.2 两条技术路线的选型系统相机框架还是直接走UVC常见做法是直接在应用层用两套方案对比选型我通常会先画一张表给项目组看对比项Camera2 系统框架UsbManager UVC 直接接管设备识别不识别外接UVC摄像头通过USB枚举通用识别格式支持只支持 HAL 定义的格式摄像头描述符里的格式都可控帧率控制由 HAL 策略决定自己协商 bandwidth 和 framerate多设备支持基本不支持按 VID/PID/序列号区分多个设备稳定性风险系统级黑盒应用层可调试可重连开发成本低但做不了中等需要理解UVC描述符结论很清楚如果只是用设备自带的摄像头走 Camera2如果要外接 USB 摄像头尤其是工业场景里需要指定分辨率、帧率、固定曝光直接走 UsbManager 加 UVC 开源封装是唯一稳妥的路。有的团队最初想通过“虚拟摄像头”方案把UVC设备映射成系统Camera这在个别系统定制项目里能成但ROM级的改动维护成本太高兼容性也差实际落地时很少选。2.3 前置条件清单硬件和系统环境动手写代码之前先确认三件事否则后面全是玄学问题。第一设备必须支持 USB Host。手机和平板基本都支持但部分低端电视盒子把 OTG 引脚砍了插了没反应。可以用adb shell dumpsys usb看有没有枚举日志或者直接检查系统里有没有android.hardware.usb.host这个 feature。第二供电要够。UVC 摄像头工作电流通常在 150mA 到 500mA 之间部分带补光灯、云台电机的摄像头会到 1A 以上。手机 OTG 口在无外部供电时输出电流有限插上后摄像头灯亮但不出流多半是供电不足。常见做法是用带供电的 OTG HUB或者选低功耗的 UVC 模组。第三系统版本。Android 5.0 以上对 USB Host 的支持才比较完整Android 11 之后还多了包可见性限制需要在 Manifest 里声明查询 USB 设备的权限。这几点确认完再进入代码实现。3. Android接入UVC摄像头从权限声明到预览上屏的完整实现3.1 权限声明与设备发现机制先在你的AndroidManifest.xml里加上 USB Host 相关的声明。我一般会把摄像头对应的usb-device过滤也写上这样插上设备时系统可以直接拉起应用不用每次手动打开。uses-feature android:nameandroid.hardware.usb.host android:requiredtrue / uses-permission android:nameandroid.permission.USB_PERMISSION / activity android:name.MainActivity intent-filter action android:nameandroid.hardware.usb.action.USB_DEVICE_ATTACHED / /intent-filter meta-data android:nameandroid.hardware.usb.action.USB_DEVICE_ATTACHED android:resourcexml/device_filter / /activitydevice_filter.xml里按 USB Vendor ID 和 Product ID 做过滤格式如下resources usb-device vendor-id0x1234 product-id0x5678 / /resources这段配置的含义是系统检测到 USB 设备插入时先比对 VID/PID匹配上就直接拉起应用。注意USB_PERMISSION这个权限实际上不是危险权限但很多项目因为忘了加它导致requestPermission的时候回调静默失败。vendor-id和product-id可以从摄像头的说明书拿到或者先用adb shell lsusb部分固件支持查更通用的办法是插上设备后看系统日志里的 USB 枚举信息。3.2 枚举设备并申请USB权限在 Activity 里拿到UsbManager枚举设备然后向用户弹出授权对话框。这一步是很多新手首次翻车的地方插上设备后getDeviceList有数据但打开连接时openDevice抛异常原因就是没申请权限。class MainActivity : AppCompatActivity() { private lateinit var usbManager: UsbManager private var uvcDevice: UsbDevice? null private val permissionRequestCode 1001 private val usbPermissionReceiver object : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { val action intent.action if (action com.example.USB_PERMISSION) { synchronized(this) { if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { // 授权成功可以打开设备 openUvcCamera(uvcDevice!!) } else { // 用户拒绝授权摄像头无法使用 } } } } } private fun findAndRequestPermission() { usbManager getSystemService(Context.USB_SERVICE) as UsbManager val deviceList usbManager.deviceList uvcDevice deviceList.values.firstOrNull { device - device.deviceClass UsbConstants.USB_CLASS_VENDOR_SPEC || device.interfaceCount 0 } uvcDevice?.let { device - if (usbManager.hasPermission(device)) { openUvcCamera(device) } else { val permissionIntent PendingIntent.getBroadcast( this, permissionRequestCode, Intent(com.example.USB_PERMISSION), PendingIntent.FLAG_IMMUTABLE ) usbManager.requestPermission(device, permissionIntent) } } } }在onCreate里注册广播接收器onDestroy里注销。这段代码里最关键的是hasPermission的检查如果之前授权过就不需要再弹窗PendingIntent的FLAG_IMMUTABLE在 Android 12 以上是必须的不加在高版本会直接崩。设备筛选的deviceClass判断实际上不同 UVC 设备实现有差异有的把 class 放在接口层面而不是设备层面所以更稳妥的做法是遍历device.interfaceList找接口类型为 Video 的项或者直接用后面讲到的 UVC 库封装去打开。3.3 使用开源UVC库打开设备并建立预览权限拿到之后就可以用 libuvc 的 Android 封装来打开设备了。这里我用一个化简后的、基于该封装的调用流程来写核心逻辑和真实项目一致。class UvcPreviewFragment : Fragment() { private lateinit var textureView: TextureView private var uvcCamera: UVCCamera? null private var uvcTexture: SurfaceTexture? null private fun startPreview(device: UsbDevice) { val usbManager requireContext().getSystemService(Context.USB_SERVICE) as UsbManager uvcCamera UVCCamera() uvcCamera?.open(usbManager, device) uvcCamera?.setPreviewSize(1280, 720, UVCCamera.FRAME_FORMAT_MJPEG) uvcTexture textureView.surfaceTexture uvcCamera?.setPreviewTexture(uvcTexture) uvcCamera?.startPreview() } }逻辑说明open()负责建立 USB 连接、读取设备的 VideoStreaming 描述符setPreviewSize的三个参数分别是宽、高、像素格式这里用 MJPEG 格式是因为绝大多数 UVC 摄像头对 MJPEG 的编码支持最稳定带宽占用也小于 YUYV。setPreviewTexture把 SurfaceTexture 和摄像头输出绑定最后startPreview()启动数据流。这里的UVCCamera类是开源 UVC Android 库提供的封装如果你不想用这个封装直接用UsbDeviceConnection做claimInterface之后自己解析 ISO/Bulk 端点工程量会大很多。所以除非有特殊需求否则不要重复造轮子。3.4 拍照与录像的实现要点预览跑通之后拍照和录像是另一个高频需求。UVC 库通常提供captureStillImage方法但它和预览流共用一个视频流接口有的摄像头在切换静态图像时会有短暂卡顿。还有一种常见做法是直接截取预览帧。private fun captureFrame(): Bitmap { // 从当前 TextureView 上获取位图 val bitmap textureView.bitmap // 注意如果 TextureView 尺寸和预览尺寸不一致这里要做裁剪 return bitmap ?: throw IllegalStateException(预览尚未就绪) }这段代码看起来简单但实际用在工业检测里要小心textureView.bitmap拿到的只是当前渲染的帧如果摄像头帧率低或者 Surface 被遮挡会拿到黑帧。更可靠的做法是在startPreview时通过setFrameAvailableListener从 SurfaceTexture 里取最新的图像缓冲区然后转成 Bitmap。录像方面我一般建议用 MediaCodec 配合 SurfaceTexture 做硬件编码直接把摄像头纹理投给编码器避免 CPU 转码导致发热掉帧。4. 必须避开的坑从没反应到花屏再到掉帧的排查记录这一章的每一条都是实际项目里踩过的按“现象 → 原因 → 解决”的格式记录。4.1 插上OTG线完全没有反应现象摄像头插到 Android 设备上设备没有任何提示getDeviceList返回空列表灯不亮或者亮了一下就灭。原因最常见的是 OTG 线本身不支持数据传输只支持充电其次是设备 USB Host 模式没启用部分平板需要到系统设置里打开“USB Host”开关还有一种隐蔽情况是摄像头要求 5V/1A 供电而 OTG 输出达不到。解决换一根短线、高质量的 OTG 转接线把摄像头插到带供电的 USB HUB 上再连设备用万用表量 OTG 头供电电压低于 4.8V 基本就是供电不足。排查时用adb shell dumpsys usb看mDevices里有没有新设备如果系统压根没枚举到问题就在硬件链路。4.2 预览画面绿屏或花屏现象权限弹窗正常startPreview()不报错但画面是绿色、紫色条纹或者直接花掉。原因摄像头实际支持的像素格式和代码里设置的不一致。比如摄像头只支持 YUYV 格式你强制用 MJPEG 打开就会得到乱码帧或者分辨率不在摄像头支持列表里自动协商到了一个异常值。解决先打印摄像头支持的格式列表。通常 UVC 库会提供getSupportedSizeList或者类似接口把宽高、格式枚举出来然后选择一个摄像头原生支持的分辨率和格式。我遇到的坑里九成的花屏都是格式配错改成FRAME_FORMAT_YUYV后立竿见影。不要盲目追求高分辨率很多 4K 摄像头在 4K 下帧率只有 5fps画面的撕裂感比 720p 下 30fps 难看得多。4.3 预览帧率低掉到 10fps 以下现象画面能出来但明显不流畅系统 CPU 占用率很高触摸操作也变得卡顿。原因可能是带宽不够。UVC 摄像头在 USB 2.0 下的理论带宽约 480Mbps实际有效传输约 240Mbps。1080p30fps 的 YUYV 格式原生带宽约 1080×1920×2×30 ≈ 125Mbps看起来够但如果同时传音频、多个端点并发或者 OTG 线质量差就会严重掉帧。另一个原因是解码路径走了软解——MJPEG 格式是 JPEG 帧流如果库或者设备没有硬件 JPEG 解码CPU 解码就会吃满核心。解决优先降低到 720p 或者把格式改回 MJPEG 压缩流确认bulkTransfer的 read buffer 大小设置合理一般设成 USB 包大小的整数倍比如 16384 字节用adb shell top看 CPU 占用如果是mediaserver或者应用进程 CPU 拉满就把解码和渲染放到支持硬解的链路上。4.4 摄像头拔掉再插上应用崩溃现象使用过程中用户拔掉 USB 线应用直接闪退或者重插之后startPreview报DeviceNotFound。原因没有监听ACTION_USB_DEVICE_DETACHED广播拔线后 UVC 库还在读 USB 数据连接断开导致 Native 层段错误重插后设备节点变了旧的UsbDevice对象已经失效。解决注册UsbManager.ACTION_USB_DEVICE_DETACHED广播收到后先stopPreview()再close()并且把 SurfaceTexture 释放掉。重连逻辑放到广播里重新走一遍枚举流程。这属于接入 UVC 摄像头必须处理的边界场景没有异常处理稳定性评分直接不及格。4.5 部分设备上权限弹窗不出现现象代码里调了requestPermission但系统没有弹出授权对话框onReceive也没有回调。原因Android 11 开始PendingIntent的FLAG_IMMUTABLE缺失会导致广播无法发送或者 Manifest 里的 USB 设备过滤和实际设备 VID/PID 不匹配系统认为这不是你需要访问的设备。另一个可能性是Activity的onResume之前就调了请求方法此时 UI 还没就绪。解决检查 Manifest 的device_filter是否覆盖目标设备给PendingIntent明确加FLAG_IMMUTABLE把请求动作放到onResume之后再执行。如果项目里同时要在多个页面使用摄像头可以把权限申请封装到一个独立的UvcPermissionManager里避免重复逻辑。5. 性能调优把预览延迟、功耗和帧率拿捏住5.1 优先选择摄像头原生支持的视频参数这是最有用的一条经验。UVC 摄像头内部有一个视频流配置表包含分辨率、帧率、格式的组合。你在代码里setPreviewSize(1920, 1080, MJPEG)但摄像头可能并不支持 1920×108030fps 的 MJPEG于是它回退到一个接近的分辨率帧率却降到 15fps。通用做法是在初始化后读取支持列表然后按“优先级 帧率 分辨率 画质”的依据去选。工业扫码场景需要帧率选 640×48060fps拍照美颜场景需要画质选 1080p30fps。不要直接硬编码。我一般不信任摄像头的默认模式因为同一颗感光芯片做成多种模组后厂家给的默认描述符可能是最差的兼容模式。5.2 尽量避免每一帧都走 Bitmap 拷贝预览、识别、渲染三件事如果都拿Bitmap做中间人内存和耗电会很难看。 常见做法是让摄像头输出的SurfaceTexture直接作为数据源一路给到显示另一路在 GL 环境里注册为外部纹理做图像处理最后如果需要识别把纹理再转成识别库需要的输入。这样能充分利用 GPU 和硬件解码应用 CPU 占用能从 80% 降到 20% 以下。我见过一些项目把每帧先转 Bitmap再做缩放再转 ByteArray 传给算法这种链路在 1080p30fps 下 CPU 几乎跑满。改成共享纹理之后帧率反而从 20fps 提到 28fps设备温度也降了一个档。5.3 建立重连与掉帧监控策略摄像头不像系统自带相机那样稳定USB 链路受供电、接触、电磁干扰影响偶发掉帧是常态。完全不让掉帧不现实但要让系统可感知、可恢复。我习惯在预览回调里维护一个“最近 30 帧”的时间戳列表每来一帧就计算平均帧间隔。如果连续 1 秒没有新帧就主动做一次stopPreview再startPreview同时上报错误。这个策略比等死强得多。USB 摄像头项目上线后最大的投诉通常是“画面卡住之后要重启 App”加了自动重连后这类投诉基本清零。6. 进阶验证用 adb 和日志确认 UVC 链路每个环节都稳了把预览跑通只是开始真正上线前要做一次系统级的验证。我常用的验证方式不是盯着屏幕看画面而是插上设备后用 adb 拉日志和数据来量化确认。先插上摄像头执行adb shell dumpsys usb看mDevices里设备是否枚举成功再执行adb shell ls -l /dev/bus/usb/001/00X确认设备节点存在。接着打开应用在日志里过滤UVC或uvc关键字确认视频流协商时的分辨率、格式、帧率参数。一个健康的链路日志里应该能看到带宽分配成功、start streaming之类的记录没有bandwidth insufficient或device descriptor read error报错。如果要压测稳定性我会写一个小脚本循环执行“拔插 USB 摄像头 100 次”每轮操作后自动检查进程是否存活、预览是否恢复。这里的关键是观察两个指标掉线重连的成功率和重连所需时间。如果重连需要超过 3 秒用户体验就会明显变差这时候优先检查权限广播是否有延迟、UVCCamera.close()是否阻塞了主线程。另一个很实用的验证技巧是看 USB 带宽占用。执行adb shell cat /sys/kernel/debug/usb/devices部分设备需要 root可以看到当前设备的信息传输速率如果接近带宽上限就说明你设置的分辨率和帧率已经到顶了再往上调只会掉帧。配合adb shell top -p pid观察应用 CPU 占用一般 720p30fps 的 MJPEG 解码加预览总 CPU 占用不应超过 30%超过这个值就该检查是否走了软解或者内存抖动。最后说一个我自己的习惯每次交付这类 UVC 接入功能我都会保留一张“不同摄像头的兼容性对照表”记录每一颗摄像头实拍出来的最大稳定分辨率和帧率因为描述符里写的参数并不等于实际稳定运行的参数。这个表以后做新项目时是排坑的第一手资料。希望这套思路对你手头的项目能有帮助少走一段弯路。本文还有配套的精品资源点击获取