OpenBeam

OpenBeam 是一个 Android 工具，用来把手机上的应用启动到外接显示器，并把手机屏幕当作触控板、键盘和导航控制器使用。项目基于 Kotlin、Jetpack Compose、Gradle 和 Shizuku。

功能

• 检测 USB-C 显示器、转接器或其他 Android 外接显示设备。
• 搜索并选择手机上可启动的应用。
• 将选中的应用启动到外接显示器。
• 在手机上控制外接显示器里的应用：移动指针、点击、长按、拖动、滚动、输入文本、返回、主页和最近任务。
• 支持外接屏光标叠加显示，并可在控制时熄黑手机本机屏幕。
• 使用 Shizuku 执行需要更高权限的输入注入和外接显示启动操作。

项目状态

项目仍处于早期阶段，目标是探索 Android 设备在外接显示器上的异步投屏和触控控制体验。不同 Android 厂商对外接显示、隐藏 API 和输入注入的兼容性可能不同。

环境要求

• Android Studio：建议使用当前稳定版。
• JDK：17。Android Studio 自带的 JBR/JDK 17 一般可以直接使用。
• Android SDK：需要安装项目使用的 compileSdk，当前为 Android API 36 / 36.1。如果 Gradle Sync 提示缺少 SDK，按提示在 SDK Manager 中安装。
• Android 设备：Android 11 或更高版本，项目 minSdk 为 30。
• Shizuku：运行应用时需要安装并启动 Shizuku。
• 外接显示设备：USB-C 显示器、扩展坞、采集卡或支持 Android 外接显示的转接方案。

项目已经提交 Gradle Wrapper，不需要单独安装 Gradle。

从零编译 Debug APK

1. 获取源码

git clone https://github.com/your-name/OpenBeam.git
cd OpenBeam

如果你是直接下载 ZIP，解压后进入项目根目录，也就是包含 settings.gradle.kts 和 gradlew.bat 的目录。

2. 安装 Android Studio 和 SDK

1. 安装 Android Studio。
2. 打开 Android Studio 的 SDK Manager。
3. 安装 Android SDK Platform 36 / 36.1，以及 Android SDK Build-Tools。
4. 确认 JDK 版本是 17。

可以在终端检查：

java -version

输出里应该能看到 17。

3. 编译 APK

Windows PowerShell：

.\gradlew.bat assembleDebug

macOS / Linux：

chmod +x ./gradlew
./gradlew assembleDebug

第一次编译会下载 Android Gradle Plugin、Kotlin、AndroidX Compose、Shizuku 等依赖。项目已经配置了阿里云 Maven 镜像和官方仓库；如果下载失败，先检查网络、代理和 Android Studio 的 Gradle 设置。

4. 找到 APK

编译成功后，Debug APK 位于：

app/build/outputs/apk/debug/app-debug.apk

5. 安装到手机

如果已经配置 ADB：

adb install -r app/build/outputs/apk/debug/app-debug.apk

也可以把 APK 传到手机上，通过系统文件管理器安装。Debug APK 适合本地测试，不建议作为正式发布包。

编译签名 Release APK

Release APK 需要本地签名文件。签名文件和密码不应该提交到 GitHub，本项目已经在 .gitignore 中排除了 signing/、keystore.properties、*.jks、*.keystore 等文件。

1. 生成签名文件

Windows PowerShell：

New-Item -ItemType Directory -Force signing
keytool -genkeypair -v -keystore signing/openbeam-release.jks -alias openbeam -keyalg RSA -keysize 2048 -validity 10000

macOS / Linux：

mkdir -p signing
keytool -genkeypair -v -keystore signing/openbeam-release.jks -alias openbeam -keyalg RSA -keysize 2048 -validity 10000

keytool 来自 JDK。如果命令找不到，先确认 Android Studio/JDK 的 bin 目录是否在 PATH 中。

2. 创建本地签名配置

用 keystore.properties.example 作为模板，在项目根目录创建本地的 keystore.properties：

storeFile=signing/openbeam-release.jks
storePassword=你的-keystore-密码
keyAlias=openbeam
keyPassword=你的-key-密码

不要把真实密码写进 keystore.properties.example，也不要提交 keystore.properties。

3. 编译 Release APK

Windows PowerShell：

.\gradlew.bat assembleRelease

macOS / Linux：

./gradlew assembleRelease

编译成功后，Release APK 位于：

app/build/outputs/apk/release/app-release.apk

运行准备

1. 在手机上安装并启动 Shizuku。
2. 按 Shizuku 的提示通过无线调试、ADB 或 Root 启动 Shizuku 服务。
3. 连接外接显示器或 USB-C 显示转接器。
4. 打开 OpenBeam，授予 Shizuku 权限。
5. 选择外接显示器和要启动的应用。
6. 点击 Launch，然后进入 Touchpad 页面控制外接屏上的应用。

如果外接光标无法显示，应用会尝试通过 Shizuku 授予悬浮窗权限。不同系统 ROM 可能仍需要在系统设置中手动允许悬浮窗。

常用 Gradle 命令

Windows 使用 .\gradlew.bat，macOS / Linux 使用 ./gradlew。

./gradlew assembleDebug      # 编译 Debug APK
./gradlew assembleRelease    # 编译 Release APK
./gradlew test               # 运行单元测试
./gradlew clean              # 清理构建产物

常见问题

Gradle 提示缺少 SDK

打开 Android Studio 的 SDK Manager，安装提示中的 Android SDK Platform 和 Build-Tools，然后重新执行编译命令。

JAVA_HOME 或 Java 版本不对

确认终端使用的是 JDK 17。Android Studio 自带 JDK 的路径可以在 Settings > Build, Execution, Deployment > Build Tools > Gradle 中查看。

依赖下载失败

项目已配置阿里云 Maven 镜像、Google Maven、Maven Central 和 Gradle Plugin Portal。若仍失败，检查代理、DNS、公司网络限制或重新打开 Android Studio 触发 Gradle Sync。

手机上没有可选外接显示器

确认手机和系统 ROM 支持外接显示输出，并且显示器或转接器已经连接成功。有些设备只支持镜像显示，或者限制应用启动到第二显示器。

Shizuku 一直未就绪

先打开 Shizuku 应用，确认服务正在运行，再回到 OpenBeam 点击授权或绑定按钮。重启手机后通常需要重新启动 Shizuku。

贡献

欢迎提交 Issue 和 Pull Request。提交代码前建议先运行：

./gradlew test
./gradlew assembleDebug

如果改动涉及外接显示、输入注入或 Shizuku 行为，请在 PR 中说明测试设备、Android 版本、Shizuku 启动方式和外接显示方案。

开源协议

本项目采用 GNU General Public License v3.0 or later，SPDX 标识为 GPL-3.0-or-later。

GPLv3 是强 copyleft 协议：如果你分发基于本项目源码的修改版、衍生项目或 APK，需要按 GPLv3 或兼容方式提供对应源代码，并保留版权和许可证声明。仅在本地私下修改和使用，通常不触发分发源码的义务。

完整条款见 LICENSE。如果你需要对商业分发、闭源集成或合规边界做正式判断，请咨询专业法律意见。