更新记录

1.0.0（2026-09-29）

• 首次发布：打开/关闭摄像头、预览、拍照、录像、RTMP 推流、设备枚举与切换、分辨率读写、旋转镜像、亮度/对比度百分比及 25 项 UVC 参数通用 get/set/reset

平台兼容性

uni-app(4.72)

uni-app x(4.72)

zy-uvc-plus

基于 UVCAndroid 的 USB 摄像头增强插件，提供打开/关闭摄像头、预览、拍照、录像、RTMP 推流、多设备枚举与切换、分辨率控制、镜像旋转，以及全部 UVC 参数（含百分比）的通用读写能力。

特性

• USB 摄像头即插即用（需设备支持 USB Host/OTG）
• 打开 / 关闭摄像头、开启 / 关闭预览
• 拍照（JPEG，可选时间戳水印）、录像（MP4，可选音频）
• 获取摄像头列表、按设备名/ID/名称/下标切换摄像头
• 获取支持的分辨率 / 当前分辨率 / 动态设置分辨率
• 预览旋转（0/90/180/270）、镜像模式（正常/水平/垂直/水平垂直）
• 亮度、对比度百分比获取与设置（通用百分比接口同时支持其余参数）
• 通用 UVC 参数 get/set：25 个参数（含范围、当前值、百分比、默认值）
• RTMP 推流：把摄像头画面 H.264 + 麦克风 AAC 推流到 rtmp 服务器
• 统一事件回调（同步/异步结果统一走 @onResult，设备状态走 @onDeviceState）

平台支持

最低 Android SDK 版本：21（Android 5.0）

快速开始

引入组件

<zy-uvc-plus
  ref="uvc"
  class="camera"
  @onResult="onResult"
  @onDeviceState="onDeviceState">
</zy-uvc-plus>

打开摄像头并预览

// 自动选择第一个 USB 摄像头，打开后自动开启预览
this.$refs.uvc.openCamera()

// 指定设备名 / 产品名 / 下标，并指定期望分辨率
this.$refs.uvc.openCamera({
  deviceName: '/dev/bus/usb/001/002',
  size: [1280, 720],
  autoPreview: true
})

拍照

this.$refs.uvc.takePicture()
// 结果: { uri, path }，文件保存在 {app-files-dir}/uvcPlus/

this.$refs.uvc.takePicture({ addTimestamp: true, timestampFormat: 'formatted' })
this.$refs.uvc.takePicture({ fileName: 'my.jpg' })

录像

this.$refs.uvc.startRecord({ audio: true, bitRate: 640000, frameRate: 25 })
this.$refs.uvc.stopRecord()
// 结果: { uri, path }，文件保存在 {app-files-dir}/uvcPlus/

参数调节

// 百分比（0-100）
this.$refs.uvc.getBrightnessPercent()
this.$refs.uvc.setBrightnessPercent(80)
this.$refs.uvc.getContrastPercent()
this.$refs.uvc.setContrastPercent(50)

// 通用参数
this.$refs.uvc.getAllParams()
this.$refs.uvc.getParam('whiteBalance')
this.$refs.uvc.setParam('saturation', 64)
this.$refs.uvc.getParamPercent('exposureTime')
this.$refs.uvc.setParamPercent('exposureTime', 30)
this.$refs.uvc.resetParams()

RTMP 推流

// 开始推流（需摄像头已打开且预览中；audio 默认 true，首次会申请录音权限）
this.$refs.uvc.startPush({ url: 'rtmp://server/live/stream', audio: true })

// 仅推视频
this.$refs.uvc.startPush({ url: 'rtmp://server/live/stream', audio: false })

// 自定义码率/帧率/音频参数
this.$refs.uvc.startPush({
  url: 'rtmp://server/live/stream',
  videoBitrate: 2000000,
  fps: 25,
  audioSampleRate: 44100,
  audioChannels: 1,
  audioBitrate: 64000
})

this.$refs.uvc.stopPush()
this.$refs.uvc.isPushing()

推流状态通过 @onDeviceState 下发：onPushStart（已连接）、onPushStop（已停止）、onPushError（连接/编码失败，code 9010011/9010012）、onPushAudioError（音频采集失败，code 9010013，不影响视频推流）。

推流依赖 libs/rtmpservice.aar（内含 librtmp_stream.so），需使用自定义基座；关闭摄像头、拔出设备或页面卸载时会自动停止推流。

分辨率 / 旋转镜像

this.$refs.uvc.getSupportedResolutions()
this.$refs.uvc.getCurrentResolution()
this.$refs.uvc.setResolution({ width: 1920, height: 1080 })

this.$refs.uvc.setRotation(90)
this.$refs.uvc.setMirror(1) // 0正常 1水平 2垂直 3水平垂直
this.$refs.uvc.getPreviewConfig()

API

所有方法均为「事件回调式」：方法调用后通过 @onResult 返回结果，结构为 { type: 方法名, data: { code, msg, data } }，code === 0 表示成功。

事件

@onResult

方法调用与异步操作的统一回调。

onResult(e) {
  const { type, data } = e.detail
  if (data.code !== 0) {
    uni.showToast({ title: data.msg, icon: 'none' })
    return
  }
  switch (type) {
    case 'openCamera': break
    case 'getCameraList': break
    case 'takePicture': break
    case 'startRecord': break
    case 'stopRecord': break
    case 'getAllParams': break
    // ...
  }
}

type 取值：openCamera、closeCamera、startPreview、stopPreview、getCameraList、switchCamera、getSupportedResolutions、getCurrentResolution、setResolution、setRotation、setMirror、getPreviewConfig、isCameraOpen、takePicture、startRecord、stopRecord、getAllParams、getParam、setParam、getParamPercent、setParamPercent、resetParams、getBrightnessPercent、setBrightnessPercent、getContrastPercent、setContrastPercent、startPush、stopPush、isPushing。

@onDeviceState

USB / 摄像头状态变化回调，结构同上。

方法

options 参数

openCamera / switchCamera：

takePicture：addTimestamp（是否加水印）、timestampFormat（raw/formatted）、fileName（自定义文件名）。

startRecord：audio（默认 true）、bitRate（默认 1024*1024*25*0.25 ≈ 6.5Mbps）、frameRate（默认 25）。

支持的 UVC 参数

数值型（19 个）：brightness 亮度、contrast 对比度、saturation 饱和度、hue 色调、sharpness 锐度、gamma Gamma、whiteBalance 白平衡、gain 增益、backlightComp 背光补偿、exposureTime 曝光时间、focus 焦距、zoom 变焦、pan 水平、tilt 垂直、roll 滚转、iris 光圈、powerlineFrequency 电源频率、autoExposureMode 曝光模式、digitalMultiplier 数字增益。

布尔型（6 个）：focusAuto 自动对焦、hueAuto 色调自动、whiteBalanceAuto 白平衡自动、contrastAuto 对比度自动、exposureTimeAuto 曝光自动、privacy 隐私遮蔽。

参数项结构：

{
  name: 'brightness',
  label: '亮度',
  supported: true,
  isBool: false,
  current: 128,
  percent: 50,
  min: 0,
  max: 255,
  def: 128
}

注：setPercent/getPercent 会先刷新对应参数的取值范围（updateXxxLimit），亮度等参数因此可正确换算。

错误码

注意事项

• 组件根节点是一个原生预览 Surface，需设置宽高（如 width: 100%; height: 400px），否则画面不显示。
• openCamera/switchCamera 会先校验 CAMERA、RECORD_AUDIO 运行时权限，未授权时自动弹出系统授权框；被拒绝返回 9010014。
• 组件销毁（NVBeforeUnload/unmounted）时自动停止录像、停止推流并释放摄像头资源。
• 多实例同时使用时建议每页仅放置一个组件实例（内部资源为全局单例）。