# yuvc
**Repository Path**: yos/yuvc
## Basic Information
- **Project Name**: yuvc
- **Description**: 可以调用 单usb摄像头，多usb摄像头，可以获取每一帧数据bitmap（做人脸识别），可以切换分辨率，调节亮度对比，可以拍照录制视频，可以推流。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-18
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# UVC 摄像头（YUVC）
Android 平台上的 **USB UVC 摄像头** 解决方案：底层基于 [serenegiant/libuvc](https://github.com/saki4510t/UVCCamera)（libuvc + libusb），上层由 **`yuvc` 库** 封装多路预览、取流、录制与人脸识别常用的 Bitmap 回调。
| 模块 | 说明 |
|------|------|
| **`:yuvc`** | Android Library，对外 API 为 `com.yujing.uvc.YUVC` |
| **`:app`** | 示例应用：多路预览、录制、新功能测试页 |
库模块详细 API 见 **[yuvc/README.md](yuvc/README.md)**。
---
```
//引用
implementation 'com.kotlinx:yuvc:1.1.1'
```
## 效果
|  |  |
| -- | -- |
|  |  |
---
## 环境要求
- Android Studio，Gradle 8.x
- `compileSdk` / `targetSdk` 34，`minSdk` 21
- NDK（模块内含 JNI，构建时会执行 `ndk-build`）
- 真机 + **OTG** 支持的 UVC 摄像头（模拟器一般无法测 USB）
---
## 快速集成
### 1. 引入模块
在 `settings.gradle` 中：
```gradle
include ':yuvc'
```
在 App 的 `build.gradle` 中：
```gradle
dependencies {
implementation project(':yuvc')
}
```
若使用发布好的 AAR/JAR，将 `yuvc/libs` 下依赖一并打入（见 `yuvc/build.gradle` 的 `fileTree`）。
### 2. 权限（App 的 AndroidManifest.xml）
```xml
```
Android 6+ 存储权限、Android 13+ 媒体权限请按业务自行申请；USB 权限由系统在插入设备时弹窗授予。
### 3. 布局预览控件
```xml
```
### 4. 最小代码（Kotlin）
```kotlin
class MainActivity : AppCompatActivity() {
private lateinit var yuvc: YUVC
private var cameraKey: CameraKey? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
yuvc = YUVC(this)
if (yuvc.usbDevice.isNotEmpty()) {
val dev = yuvc.usbDevice[0] ?: return
cameraKey = CameraKey.from(dev)
yuvc.add(cameraKey!!, findViewById(R.id.camera_view), null, null, null)
yuvc.autoRestart()
}
}
// 单路停止 / 重启（可选按钮绑定）
fun onStopCamera() {
cameraKey?.let { yuvc.onStop(it) } // 标记 stoppedByUser，不误报
}
fun onRestartCamera() {
cameraKey?.let { yuvc.reStart(it) } // 清除标记，立即重建
}
override fun onStart() {
super.onStart()
yuvc.onStart()
}
override fun onStop() {
yuvc.onStop() // Activity 级：关闭全部 + unregister USB
super.onStop()
}
override fun onDestroy() {
yuvc.onDestroy()
super.onDestroy()
}
}
```
### 5. 最小代码（Java）
```java
private YUVC yuvc;
private CameraKey cameraKey;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
yuvc = new YUVC(this);
if (!yuvc.getUsbDevice().isEmpty()) {
UsbDevice dev = yuvc.getUsbDevice().get(0);
cameraKey = CameraKey.from(dev);
yuvc.add(cameraKey, textureView, null, null, null);
yuvc.autoRestart();
}
}
// 单路停止 / 重启（可选按钮绑定）
void onStopCamera() {
if (cameraKey != null) yuvc.onStop(cameraKey);
}
void onRestartCamera() {
if (cameraKey != null) yuvc.reStart(cameraKey);
}
// onStart / onStop / onDestroy 中同样调用 yuvc.onStart() / yuvc.onStop() / yuvc.onDestroy()
```
---
## 示例应用（`:app`）
安装 Debug APK 后：
| 入口 | 说明 |
|------|------|
| **启动** | 多路自动识别预览（`MainActivityAutoOne`） |
| **新功能测试** | 菜单进入 Test01/02/03，覆盖连接回调、镜像、纯取流等 |
---
## 工程结构
```
YUVC/
├── app/ # 示例 App
├── yuvc/ # 库模块（见 yuvc/README.md）
│ ├── src/main/java/com/yujing/uvc/ # YUVC API（Kotlin）
│ ├── src/main/java/com/serenegiant/ # UVC 底层
│ └── src/main/jni/ # native
├── README.md # 本文件
└── settings.gradle
```
---
## 打包
```bash
# 库 AAR / JAR（见 yuvc/build.gradle 中 makeJar 任务）
gradlew :yuvc:assembleRelease
# 示例 APK
gradlew :app:assembleDebug
```
---
## 注意事项（必读）
1. **生命周期**：`onStart` / `onStop` / `onDestroy` 必须与 Activity 同步；`onStop` 会注销 USB 监视器，返回页面后需再 `onStart()`。
2. **单路停止与重启**：`onStop(key)` 会标记 `stoppedByUser = true`，10 秒启动检测会跳过该摄像头，不会误报"启动失败"；调用 `reStart(key)` 后标记自动清除。
3. **多路同 PID 摄像头**：必须使用 `CameraKey(vendorId, productId)`，不能只用 `productId`。
4. **帧回调线程**：`YUVCListener`、`BitmapListener` 在后台协程执行，更新 UI 请 `runOnUiThread`。
5. **Bitmap 回调**：每帧转 Bitmap CPU 开销大，人脸识别等场景可设 `YUVCConfig.useRenderScriptForBitmap = true`。
6. **双路摄像头**：默认不录外置麦克风（`recordAudioEnabled = false`），避免编码压力过大。
7. **OTG 与供电**：部分设备需外接供电 USB Hub，否则易掉线或无法枚举。
8. **录制分段**：弹窗中时间分段默认 5 分钟，可在 Spinner 中选择 1-60 分钟。
---
## 作者
yujing — 3373217@qq.com
---
## 许可证
`yuvc` 模块内 serenegiant 相关代码遵循 Apache License 2.0（见各文件头）。其余以仓库为准。