Android Development

The Android client lives in android/; its Rust boundary is crates/pstr-android. It targets Android 12 (API 31) and newer on arm64-v8a phones/tablets and x86_64 emulators. Compose owns navigation and screens, while UniFFI exposes the existing catalog, share, streaming, watch-state, and offline logic. Keep reusable behavior in the Rust crates rather than reimplementing it in Kotlin.

Android TV

The same build installs on Android TV: it is listed in the TV launcher (LEANBACK_LAUNCHER, with the banner scripts/render-tv-banner.sh renders) and requires neither a touch screen nor leanback. Every screen is Compose clickables, which the D-pad already moves between. The player takes a remote's keys while its controls are down: left and right seek ten seconds, the middle button brings the controls up, and play/pause works as on a keyboard. There is no TV-specific layout yet, and none of it has been run on a TV. Signing in to an account, so that shares arrive through sync, is the way to set one up without typing a share link on a remote.

Toolchain

Install JDK 17, Android SDK Platform/Build Tools 36, NDK 30.0.16248370, Rust 1.96, Gradle 8.13, and the native helpers:

rustup target add aarch64-linux-android x86_64-linux-android
cargo install cargo-ndk --version 4.1.2 --locked

Set ANDROID_HOME (or ANDROID_SDK_ROOT); cargo-ndk discovers the NDK below that SDK. The workspace-provided uniffi-bindgen binary keeps binding generation on the same UniFFI version as the bridge. Use bash scripts/build-android.sh debug for an installable debug APK, bash scripts/build-android.sh check for Android lint/unit tests, and bash scripts/build-android.sh release for release APK/AAB output. Gradle first generates UniFFI Kotlin into android/app/build/generated/source/uniffi, then builds both Rust ABIs into android/app/build/generated/jniLibs. Generated files belong under build/ and must not be committed.

versionName always comes from [workspace.package].version in Cargo.toml, so a tagged build cannot drift from the desktop release. The default versionCode is major * 1,000,000 + minor * 1,000 + patch (0.1.1 becomes 1001). Set ANDROID_VERSION_CODE only when Play requires a higher monotonic code; Gradle rejects non-integers, zero, and values above Android's limit. The Android workflow tests both the default derivation and the override path.

Local Run and Verification

Start an API 31+ emulator or attach a device, then run:

bash scripts/build-android.sh debug
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

Before submitting Android work, run the Rust workspace gate from the repository root, then:

bash scripts/build-android.sh check          # ktlint, Android lint, host and screenshot tests
bash scripts/android-acceptance.sh --release # the on-device matrix, minified APK

check needs no device. Run the matrix with --release where you can: it installs the signed minified APK and runs instrumentation against it, which is the only path that exercises R8 — the step that has broken this app five distinct ways that a debug build cannot reproduce. Without the ANDROID_RELEASE_* variables below, drop --release and the debug APK is used instead. The matrix — phone and tablet layouts, rotation, process recreation, playback and background controls, download cancellation/resume, and an offline launch with networking disabled — is scripts/android-acceptance.sh; --list prints every case and what it needs, and PSTR_ACCEPTANCE_ONLY=name runs one. Five cases need a real share, given as PSTR_ACCEPTANCE_SHARE_URL and PSTR_ACCEPTANCE_SHARE_PASSWORD; they reach the device as instrumentation arguments and are stored nowhere. Without them those cases report skip. There is no Picture-in-Picture: it was removed after a PiP window that never sized its video right proved less use than background audio and the lock-screen transport. docs/TESTING.md has the layer-by-layer detail, including why lint runs against a baseline.

Requires JDK 17. build-android.sh locates it, because a newer JVM does not fail with a version message — the Kotlin compiler throws IllegalArgumentException: 26.0.2 from an IntelliJ version parser.

Release Signing

Release signing is optional locally and never stored in the repository. Set all four variables before bash scripts/build-android.sh signed:

ANDROID_RELEASE_STORE_FILE
ANDROID_RELEASE_STORE_PASSWORD
ANDROID_RELEASE_KEY_ALIAS
ANDROID_RELEASE_KEY_PASSWORD

GitHub Actions expects the keystore itself as the base64-encoded ANDROID_RELEASE_KEYSTORE_BASE64 secret and the other three values as secrets. Keep the keystore and passwords in a durable external secret manager; losing the key prevents users from upgrading an installed APK.

A v* tag runs release.yml, which calls android.yml with signed_release: true and publishes the signed APK as proton-stream-<version>-android.apk next to the desktop artifacts, together with the mpv-android-source-<rev>.tar.gz corresponding source for the bundled libmpv. The AAB is kept as the android-bundle workflow artifact only; nothing uploads it to Play. A manual android.yml run with signed_release builds the same signed files without publishing them.

Licensing and Native Playback

The Android application is GPL-3.0-or-later; the shared Rust crates remain MIT. See android/LICENSE.md and android/THIRD_PARTY_NOTICES.md. Before distributing a binary with bundled libmpv, pin its exact source revision/build configuration, package the notices, and retain the corresponding source plus build scripts required by the GPL. The current playback service scaffold is not a substitute for the final bundled libmpv integration.

bash scripts/build-libmpv-android.sh pins and stages libmpv for both supported ABIs, plus a source archive and revision record, under android/app/build/generated/mpv. Gradle runs that task before native builds, packages the staged libraries, and compiles pstr_mpv, the JNI/EGL adapter. It feeds libmpv through the Rust stream C ABI; decrypted bytes remain in native memory. PlaybackService owns the mpv core for background audio and media controls, while the activity supplies the current Surface. Do not publish an Android binary until this exact pipeline is verified on real arm64 hardware and an x86_64 emulator.