SimpleWebCam for Android

这是一个基于 SimpleWebCam 项目改造的 Android USB 摄像头库。

项目通过 JNI 调用底层的 C++ 代码，使用 V4L2 (Video4Linux2) 直接与 USB 摄像头硬件通信，提供了一个健壮且易于集成的 CameraPreview 组件，用于在 Android 应用中显示 USB 摄像头的实时视频流。

✨ 主要功能

• 原生性能: 通过 C++ 和 V4L2 直接访问摄像头，性能高效。
• 生命周期管理: 提供 startPreview() 和 stopPreview() 方法，适配 Android 的 Activity/Fragment 生命周期。
• 新增 API: 优化了 CameraPreview View 组件，新增setPreviewRotated()方法，可以旋转预览180°。
• 灵活配置: 支持动态配置，如设置预览画面旋转、是否自动开始预览等。
• 模块化设计: 核心功能被封装在 uvccamlib 模块中，可以轻松编译成 AAR 库供其他项目使用。

🚀 如何使用

将 CameraPreview 集成到您的 Android 项目中非常简单。

1. 添加到 XML 布局

<!-- res/layout/activity_main.xml -->
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.yuy.uvccamlib.CameraPreview
        android:id="@+id/camera_preview"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_alignParentBottom="true"
        android:gravity="center"
        android:orientation="horizontal">

        <Button
            android:id="@+id/start_button"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:text="Start"/>

        <Button
            android:id="@+id/stop_button"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:text="Stop"/>
    </LinearLayout>

</RelativeLayout>

2. 在 Activity/Fragment 中管理

在对应的 Activity 或 Fragment 中，获取 CameraPreview 实例并管理其生命周期。

import android.os.Bundle;
import android.view.View;
import android.widget.Button;
import androidx.appcompat.app.AppCompatActivity;
import com.yuy.uvccamlib.CameraPreview;

public class MainActivity extends AppCompatActivity {

    private CameraPreview cameraPreview;
    private Button startButton;
    private Button stopButton;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        cameraPreview = findViewById(R.id.camera_preview);
        startButton = findViewById(R.id.start_button);
        stopButton = findViewById(R.id.stop_button);

        // --- 配置 CameraPreview ---
        // 设置预览画面旋转180度（适配某些摄像头）
        cameraPreview.setPreviewRotated(true);
        
        // 设置当 Surface 创建时自动开始预览
        // 如果设为 false，则需要手动调用 startPreview()
        cameraPreview.setAutoStartPreview(true);

        // --- 设置手动控制按钮 ---
        startButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                // 手动开始预览
                cameraPreview.startPreview();
            }
        });

        stopButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                // 手动停止预览
                cameraPreview.stopPreview();
            }
        });
    }

    @Override
    protected void onPause() {
        super.onPause();
        // 关键：在 Activity 进入后台时，必须调用 stopPreview 释放摄像头资源
        if (cameraPreview != null) {
            cameraPreview.stopPreview();
        }
    }

    @Override
    protected void onResume() {
        super.onResume();
        // onResume 时，如果 autoStartPreview 为 true，预览会自动恢复
        // 如果为 false，你可以在这里决定是否手动调用 cameraPreview.startPreview()
    }
}

📚 API 参考

CameraPreview 控件提供的主要公共方法：

• void startPreview(): 启动摄像头预览。该方法是安全的，可以重复调用。它会检查摄像头状态，并在需要时进行初始化。
• void stopPreview(): 停止摄像头预览并释放底层硬件资源。该方法是安全的，可以重复调用。
• void setPreviewRotated(boolean rotated): 设置预览画面是否需要旋转180度。
• void setAutoStartPreview(boolean autoStart): 设置是否在 Surface 创建后自动开始预览。默认为 true。

📦 如何构建 AAR 库

您可以轻松地将 uvccamlib 模块编译成一个 .aar 文件，以便在其他项目中使用。

1. 打开 Android Studio 的 Terminal 窗口。

2. 执行以下 Gradle 命令：

   # Windows
   gradlew.bat :uvccamlib:assembleRelease
   
   # Linux / macOS
   ./gradlew :uvccamlib:assembleRelease

3. 编译成功后，您可以在 uvccamlib/build/outputs/aar/ 目录下找到 uvccamlib-release.aar 文件。

🙏 致谢

本项目基于 neuralassembly/simplewebcam。