UVC4UnityAndroid
Plugin project and samples to access UVC devices on Unity Android.
Copyright (c) 2014-2024 saki t_saki@serenegiant.com
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
All files in the folder are under this Apache License, Version 2.0.
Files under UVC4UnityAndroid/Assets/UVC4UnityAndroidPlugin/Samples/
may have different license. Please read well README.md
in those folders.
Features:
- Supports UVC 1.0/1.1 and 1.5 devices (Most of UVC devices are UVC1.1).
- Supports
armeabi-v7a
, arm64-v8a
, x86
and x86_64
architectures.
arm64-v8a
, x86
and x86_64
require IL2CPP.
- Supports H.264, MJPEG and YUV and automatically decode video images into Texture of Unity. Please see sample scenes in Samples folder.
You can get H.264 stream from Ricoh THETA S(1920x1080@H.264,30fps, dual fisheye video images) and THETA V(3840x1920@H.264,30fps, equirectangular video images), THETA Z1(3840x1920@H.264,30fps, equirectangular video images), Logitech C920, C922, C930e, C1000er etc.
- Supports multiple UVC devices at the same time(Although frame rate, number of UVC devices and video size will be limited by bandwidth and power supply of USB.)
- Supports both isochronous and bulk transfer.
Some Android devices that use China made SoC something like MediaTek, Allwinner etc. may have critical issues on there isochronous transfer.
- Supports USB2 and USB3(experimental).
Unfortunately USB3 on many devices still have issues, especially when using isochronous transfer.
- Support changing video size.
- Experimentally support UAC(USB Audio Class) to get audio stream from UAC/UVC device(s) and playback on Unity app.
- This feature is enabled only
UVC2DScene
now (but you can enable any scenes).
- This feature strongly depends on each UAC/UVC device and may not work well (Unfortunately there are many buggy/wrong UAC devices... ).
- Playback on Unity app will have long latency/delay from video images. As current invastigation, this will be come from audio system on Unity and no idea to improve now.
- Experimentally support controlling UVC device, Ex. controlling contrast, brightness, shutter condition etc.
If you want to control, you need to get
CameraInfo
using UVCManager.GetAttachedDevices
and access via GetCtrls
, GetValue
, SetValue
functions. (There are no UI samples.)
Limitations:
- Apk with target API level 28 and more will not work well on Android 10 devices because of issues on Android 10 itself (Many devices of Android 10 and later were already solved this issues but you may come across this issues).
Please see details about this on Issue Tracker of Google and My Blog.
- This project is still in progress and some features are not available now.
- You can get video images only from UVC devices, some devices like EasyCap are not UVC device and can't get from them. Internal cameras on Android devices also are not supported.
- Backend libraries support UBS3, but USB3 on Android devices are still unstable and it may not work well. In that case please connect your UVC devices over USB2.
- This plugin can work on only real Android devices, can't work on editor of Unity and on
Unity Remote
- User may need to touch app screen after giving USB permission on some Android devices by limitation os Android OS itself.
- Streaming with H.264 needs at Android4.3 and later devices (required API>=16 but API>=26 will be better for performance, API<21 devices may not work well.)
- Android system never send attach event for THETA V and THETA Z1(becauseof issues on Android system itself), as a result app can never start automatically. Please launch app by manually.
- Be sure to confirm THETA V and Z1 is in
live streaming
mode. THETA V and Z1 will report USB Image Class
when they are in camera mode
or video mode
and app will detecte it. But this USB Image Class
is not av UVC(USB Video Class)
and have no video control interface and video control interface and can't get video images from it.
- Currently only supports OpenGL|ES as a Graphic API. Vulkan is not supported now. If you can't see video images, please confirm settings of Graphic API on player settings.
Dependancies:
- This plugin uses
System.Text.Json
(and related packages) from Microsoft to parse JSON. You can install the package using NuGet
(You can use NuGetForUnity)
If you need to use other package like Json.NET
to parse json, you can use it with some modification.
How to use:
- Create new project / open existing project by Unity.
- Install
System.Text.Json
if you don't yet.
- Install 'NuGet'(Ex. NuGetForUnity).
- Select
Manage NuGet Packages
from NuGet
menu.
- Search
System.Text.Json
from search box.
- Select
System.Text.Json
and install it.
- Import release package of
UVC4UnityAndroid
Unfortunately if you have troble importing package, please try to export UVC4UnityAndroid
package by your self.
- Confirm Graphic API setting on player settings, only OpenGL|ES is supported.
- Open one of sample scene from
UVC4UnityAndroid/Samples/Scenes
folder.
- Build and run apk on your real Android device.
- Connect UVC device(s) with Android Device. Some UVC devices / some Android devices may need powered USB hub between UVC device and Android device.
Note:
- The plugin project is for Unity 2022.3.10f1 now and may need modification on other Unity version.
- This plugin setup
AndroidManifest.xml
to be able to keep permanent permission for UVC device(s).
If you don't want this behavior, please remove following steps. The user need to give permission everytime they connect UVC device(s).
- Export your project as project of Android Studio from
Build Settings
window.
- Open the exported project with Android Studio.
- Open
AndroidManifest.xml
under {project root}/src/main
- Add
<activity android:name="com.serenegiant.uvcplugin.UsbPermissionActivity" tools:node="remove"/>
in Application
section.
- Build apk with Android Studio.
Release Note:
- r0.1.0 on 24 Dec. 2019
- r0.2.0 on 3 July. 2022
- r0.2.1 on 10 July. 2022
- r0.2.2 on 3 September. 2022
- Improve isses of shaders of OpenGL|ES
- r0.3.0 on 14 March, 2024
- Migrate Unity 2022.3.10f1(LTS)
- Experimentally add support UAC
- Experimentally add support UVC controls
- Update dependancies.