Files
mpv-joc/fork/docs/android.md
T
TheM14 e5954169b2 Sign Android APKs with a fixed repository keystore
The Android workflow generated a new throwaway keystore on every run, so
every APK had a different signature and Android refused to install it over
the previous build.

Load the release keystore from ANDROID_KEYSTORE_BASE64, validate it with
keytool, and sign assembleRelease with the PKCS12 store type plus
ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS and ANDROID_KEY_PASSWORD.
Fail the build when any secret is missing instead of falling back to a
random key, and remove the temporary keystore afterwards.

Document the one-time keystore and secret setup, and ignore *.jks and
*.keystore so private keys cannot be committed.

The first fixed-signature APK needs one uninstall because the installed APK
was signed by the old throwaway key; later builds install as updates.
2026-11-13 18:21:41 +08:00

117 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Android:把 ad_joc 编进 libmpv.so 的可行性调研
结论:**可行**,arm64-v8a 是主路径。没有架构性障碍;工作量集中在把 `joc_core` 用 NDK 编出来、
和把它随 APK 一起分发。
## 现成的构建体系
`mpv-android/mpv-android` 的 `buildscripts/` 就是为这件事准备的:
- NDK(clang)交叉编译 ffmpeg、libass、libplacebo、luajit、mpv,目标 `android`,API 23;
- mpv 用 meson + 生成的 crossfile:
```sh
meson setup build --cross-file "$prefix/crossfile.txt" --default-library shared \
-Dlibmpv=true -Dcplayer=false -D{lua,libcurl}=enabled
ninja -C build && DESTDIR="$prefix" ninja -C build install
```
- 产物是 `prefix/<arch>/lib/libmpv.so`,架构可选 `armv7l / arm64 / x86 / x86_64`;
- 脚本只支持 Linux/macOS,GitHub Actions 的 ubuntu runner 正好合适。整个 ffmpeg+mpv 构建
约 30–60 分钟,可以缓存。
## 我们的补丁落在哪里
和 Windows 一样,只是多一个共享库:
1. 在 mpv 源码树里跑 `tools/apply_edits.py`(纯 Python,与平台无关);
2. 用 NDK 的 CMake toolchain 编 `joc_core` → `libjoc_core.so`;
3. meson 加 `-Djoc-core-dir=<prefix>/lib`;
4. 运行时 `libjoc_core.so` 必须和 `libmpv.so` 一起进 APK 的 `jniLibs/<abi>/`,
这样 `libmpv.so` 的 `DT_NEEDED` 才能解析。
## joc_core 的可移植性(源码层面)
- CMake 已有 `aarch64` 分支和 `src/simd/kernels_intrin_neon.cpp`,`cpu_probe` 用
`getauxval(AT_HWCAP)` 探测;`JOC_SIMD=auto|scalar|neon` 可强制。
- 平台相关代码都有 POSIX 分支(`fs_utf8.cpp`、`io/process.cpp` 里的 `#if defined(_WIN32) ... #else`)。
- 依赖只有 `Threads::Threads`,没有 HDF5 之类的外部库。
- 导出宏 `JOC_API` 在非 Windows 走 visibility,和 Android 默认的 `-fvisibility=hidden` 兼容。
## 需要处理的点
| 点 | 说明 |
|---|---|
| armv7l | `JOC_ARCH` 只认 x86_64/x86_32/aarch64,armv7 会退回标量内核:能播,慢。首选 arm64 |
| `std::filesystem` | NDK 的 libc++ 在 API 23 支持;core 里用到的地方(SOFA 缓存、task、io)需要实际编一遍确认 |
| HRTF 路径 | Android 上 `exe_dir()` 为空,必须由 app 传 `--ad-joc-hrtf=/data/user/0/<pkg>/files/binaural.personalized_headphone` |
| 缓存目录 | `mp_find_user_file(global, "cache", ...)` 在 Android 上可能拿不到 → 代码已自动退回内存缓存 |
| 许可 | LGPL:动态链接 libmpv.so + libjoc_core.so 合规;发布需附对应源码/补丁 |
| 未验证 | NDK 编 joc_core 的真实报错、NEON 内核在手机上的数值正确性、实时性能 |
## 建议的落地顺序
1. CI 先只做 **arm64 的 joc_core 交叉编译**,产出 `libjoc_core.so`。这一步最快暴露平台问题。
2. 再跑 mpv-android 的 buildscripts + 我们的 patch,产出 arm64 的 `libmpv.so`。
3. CI 把 `libmpv.so`、`libjoc_core.so`、`libc++_shared.so` 放进 app 的
`jniLibs/arm64-v8a/`,再 `./gradlew assembleRelease` 打出可安装的 APK;在 mpv 的
配置文件里加 `--ad=joc --ad-joc-hrtf=...`,用 `adb logcat -s mpv` 验证开始渲染。
4. 对拍:手机上把输出写成 WAV(`--ao=pcm`),拉回 PC 与 `joc_cli` 比较,确认 NEON 路径正确。
## CI 产物
`build-android.yml` 的 arm64 任务现在产出两类工件:
- `mpv-ad-joc-android-arm64-v8a`:`libmpv.so`、`libjoc_core.so`、`libc++_shared.so`,
给已经自己编好的 mpv 用;
- `mpv-joc-android-apk`:一个 `app-allstorage-universal-release.apk`,由 `assembleRelease`
打包并签名,直接可装。包里的 `libplayer.so` 由 `ndk-build` 现编(`app/src/main/jni`),
`libmpv.so` 和 ffmpeg 的 `libav*` / `libsw*` 一起放进 `libs/arm64-v8a/`;`ndk.properties`
让 AGP 用 NDK 的 strip 处理这些库。mpv-android 本身会出 `default` / `allstorage`
× `arm64-v8a` / `universal` 四个包,CI 只保留 allstorage 的 universal 版:权限最全,
ABI 拆包也不会让工件变多。
APK 使用仓库 secret 里的固定 release keystore 签名。只要包名不变、签名相同,新 APK 就能
直接覆盖安装,不需要先卸载。签名密钥丢失后无法再覆盖安装,必须卸载旧版,所以 keystore
和密码要单独备份。
### 固定签名的一次性设置
在本机生成 release keystore(`keytool` 来自 JDK;建议 PKCS12):
```powershell
keytool -genkeypair -v -storetype PKCS12 `
-keystore "$env:USERPROFILE\mpv-joc-release.jks" `
-alias mpv-joc -keyalg RSA -keysize 4096 -validity 10000
```
把 keystore 转成单行 Base64 并复制:
```powershell
[Convert]::ToBase64String(
[IO.File]::ReadAllBytes("$env:USERPROFILE\mpv-joc-release.jks")
) | Set-Clipboard
```
在 GitHub 仓库的 **Settings → Secrets and variables → Actions** 添加四个 secret:
| Secret | 内容 |
|---|---|
| `ANDROID_KEYSTORE_BASE64` | 上面复制的 Base64 字符串 |
| `ANDROID_KEYSTORE_PASSWORD` | keystore 密码 |
| `ANDROID_KEY_ALIAS` | `mpv-joc` |
| `ANDROID_KEY_PASSWORD` | key 密码;PKCS12 通常与 keystore 密码相同 |
`build-android.yml` 在构建时把 Base64 解码到 `$RUNNER_TEMP`,用
`-Pandroid.injected.signing.*` 交给 Gradle,构建结束后删除临时 keystore。secret
缺失时任务会直接失败,不会退回临时 key。
APK 里仍是原版 mpv-android 界面,`--ad=joc`、`--ad-joc-hrtf=` 等参数要在应用能读到的
`mpv.conf` 里给出,HRTF 文件也要放在应用可访问的目录。
## 参考
- mpv-android 构建脚本:https://github.com/mpv-android/mpv-android/tree/master/buildscripts
- 交叉编译用的 crossfile 由 `buildall.sh` 生成(`system = 'android'`,`cpu_family` 按架构)
- 现成 libmpv Android 发行版可作对照:https://github.com/jarnedemeulemeester/libmpv-android