perf(android): low-latency decode overhaul — vendor keys, async loop, system tuning

Close the latency gap on the Android client with per-SoC decoder tuning, an
event-driven decode loop, and full system integration.

- Decoder selection: rank MediaCodecList decoders in Kotlin (hardware/vendor
  preferred, software avoided, FEATURE_LowLatency probed) and create the chosen
  one by name. Per-SoC low-latency keys gated on the codec-name prefix: Qualcomm
  picture-order + low-latency, Exynos (also Google Tensor), Amlogic, HiSilicon;
  MediaTek vdec-lowlatency set unconditionally. operating-rate = MAX (Qualcomm)
  vs priority = 0 (else) are mutually exclusive. NVIDIA/Rockchip/Realtek have no
  vendor key — covered by ranking + the standard low-latency key.

- Async decode loop: AMediaCodec async-notify replaces the poll loop, presenting a
  decoded frame the instant it is ready instead of waiting out a poll interval.
  Behind USE_ASYNC_DECODE with the synchronous loop kept for A/B during bring-up.

- System integration: Wi-Fi FULL_LOW_LATENCY lock and HDMI ALLM
  (setPreferMinimalPostProcessing) for the stream's lifetime; game_mode_config.xml
  opting out of OEM downscaling / FPS overrides.

- Pipeline: boost the data-plane pump + audio thread priorities, AAudio usage=Game,
  DSCP marking on by default on Android, ADPF setPreferPowerEfficiency(false),
  and setFrameRateWithChangeStrategy(ALWAYS) to force the HDMI mode switch on TV.

- lowLatencyMode master toggle (default on) as the escape hatch; the stats HUD now
  shows the resolved decoder name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/android/app/src/main/AndroidManifest.xml

@@ -43,6 +43,14 @@
         android:supportsRtl="true"
         android:theme="@style/Theme.PunktfunkAndroid">
 
+        <!-- Game Mode config (Android 13+): declare we support Performance mode and opt OUT of the
+             OEM interventions that would fight the negotiated stream — resolution downscaling and
+             FPS overrides. A game-streaming client renders exactly the host's mode; a platform
+             downscale/FPS-cap corrupts that. Ignored below API 33. -->
+        <meta-data
+            android:name="android.game_mode_config"
+            android:resource="@xml/game_mode_config" />
+
         <activity
             android:name=".MainActivity"
             android:exported="true"

clients/android/app/src/main/kotlin/io/unom/punktfunk/Settings.kt

@@ -54,6 +54,14 @@ data class Settings(
      * client's `libraryEnabled`.
      */
     val libraryEnabled: Boolean = true,
+    /**
+     * Aggressive decoder latency tuning — the master escape hatch. On (default): the decoder runs
+     * the full low-latency profile (per-SoC vendor keys + max-clock operating-rate on Qualcomm).
+     * Off: a conservative profile (the standard `low-latency` key only), for a device that thermally
+     * throttles or misbehaves under the aggressive clocks. Decoder ranking, the Wi-Fi low-latency
+     * lock and HDMI game-mode signalling stay on regardless — they're harmless.
+     */
+    val lowLatencyMode: Boolean = true,
 )
 
 /** [Settings.touchMode] values; persisted by name. */
@@ -82,6 +90,7 @@ class SettingsStore(context: Context) {
             ?: if (prefs.getBoolean(K_TRACKPAD, true)) TouchMode.TRACKPAD else TouchMode.POINTER,
         gamepadUiEnabled = prefs.getBoolean(K_GAMEPAD_UI, true),
         libraryEnabled = prefs.getBoolean(K_LIBRARY, true),
+        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
     )
 
     fun save(s: Settings) {
@@ -100,6 +109,7 @@ class SettingsStore(context: Context) {
             .putString(K_TOUCH_MODE, s.touchMode.name)
             .putBoolean(K_GAMEPAD_UI, s.gamepadUiEnabled)
             .putBoolean(K_LIBRARY, s.libraryEnabled)
+            .putBoolean(K_LOW_LATENCY, s.lowLatencyMode)
             .apply()
     }
 
@@ -118,6 +128,7 @@ class SettingsStore(context: Context) {
         const val K_TOUCH_MODE = "touch_mode"
         const val K_GAMEPAD_UI = "gamepad_ui_enabled"
         const val K_LIBRARY = "library_enabled"
+        const val K_LOW_LATENCY = "low_latency_mode"
 
         /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
         const val K_TRACKPAD = "trackpad_mode"

clients/android/app/src/main/kotlin/io/unom/punktfunk/SettingsScreen.kt

@@ -324,6 +324,14 @@ private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: an
             options = COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl },
             selected = s.compositor,
         ) { c -> update(s.copy(compositor = c)) }
+
+        ToggleRow(
+            title = "Low-latency mode",
+            subtitle = "Run the decoder at max clocks for the lowest latency. Turn off only if a " +
+                "device overheats or glitches during long sessions.",
+            checked = s.lowLatencyMode,
+            onCheckedChange = { on -> update(s.copy(lowLatencyMode = on)) },
+        )
     }
 }
 

clients/android/app/src/main/kotlin/io/unom/punktfunk/StatsOverlay.kt

@@ -27,7 +27,7 @@ import kotlin.math.roundToInt
  * older layouts just omit those lines.
  */
 @Composable
-internal fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
+internal fun StatsOverlay(s: DoubleArray, decoderLabel: String = "", modifier: Modifier = Modifier) {
     if (s.size < 10) return
     val w = s[6].toInt()
     val h = s[7].toInt()
@@ -46,6 +46,14 @@ internal fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
             fontFamily = FontFamily.Monospace,
             fontSize = 12.sp,
         )
+        if (decoderLabel.isNotEmpty()) {
+            Text(
+                decoderLabel,
+                color = Color(0xFFB0D0FF),
+                fontFamily = FontFamily.Monospace,
+                fontSize = 12.sp,
+            )
+        }
         videoFeedLine(s)?.let { feed ->
             Text(
                 feed,

clients/android/app/src/main/kotlin/io/unom/punktfunk/StreamScreen.kt

@@ -1,8 +1,11 @@
 package io.unom.punktfunk
 
 import android.Manifest
+import android.content.Context
 import android.content.pm.ActivityInfo
 import android.content.pm.PackageManager
+import android.net.wifi.WifiManager
+import android.os.Build
 import android.view.SurfaceHolder
 import android.view.SurfaceView
 import android.view.WindowManager
@@ -30,6 +33,7 @@ import androidx.core.view.WindowInsetsControllerCompat
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.GamepadFeedback
 import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.VideoDecoders
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlinx.coroutines.delay
 
@@ -55,15 +59,23 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
     // comes from Settings.
     val initialSettings = remember { SettingsStore(context).load() }
     var stats by remember { mutableStateOf<DoubleArray?>(null) }
+    var decoderLabel by remember { mutableStateOf("") }
     var showStats by remember { mutableStateOf(initialSettings.statsHudEnabled) }
     // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
     val touchMode = initialSettings.touchMode
+    // Master low-latency toggle, resolved once for the session and passed to the decoder at start.
+    val lowLatencyMode = initialSettings.lowLatencyMode
+    // TV form factor (leanback): the decoder actively switches the HDMI output mode to the stream
+    // refresh; a phone/tablet gets the softer seamless frame-rate hint instead.
+    val isTv = remember { context.packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK) }
     LaunchedEffect(handle, showStats) {
         NativeBridge.nativeSetVideoStatsEnabled(handle, showStats)
         if (showStats) {
             while (true) {
                 delay(1000)
                 stats = NativeBridge.nativeVideoStats(handle)
+                // The decoder is fixed for the session; fetch its label once it's resolved.
+                if (decoderLabel.isEmpty()) decoderLabel = NativeBridge.nativeVideoDecoderLabel(handle)
             }
         } else {
             stats = null // drop the last snapshot so a re-show never flashes stale numbers
@@ -76,8 +88,29 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
     // main thread, so a plain flag is race-free; AtomicBoolean just makes the intent explicit.
     val closed = remember { AtomicBoolean(false) }
 
+    // A Wi-Fi low-latency lock held for the stream's duration: asks the Wi-Fi firmware to drop its
+    // power-save polling (a common source of tens-of-ms jitter). WIFI_MODE_FULL_LOW_LATENCY (API
+    // 29+) is the strongest; older releases fall back to FULL_HIGH_PERF. Needs no extra permission
+    // beyond ACCESS_WIFI_STATE (already declared). Non-reference-counted: one explicit acquire/release.
+    val wifiLock = remember(handle) {
+        val wm = context.applicationContext.getSystemService(Context.WIFI_SERVICE) as? WifiManager
+        val mode = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            WifiManager.WIFI_MODE_FULL_LOW_LATENCY
+        } else {
+            @Suppress("DEPRECATION")
+            WifiManager.WIFI_MODE_FULL_HIGH_PERF
+        }
+        wm?.createWifiLock(mode, "punktfunk:stream")?.apply { setReferenceCounted(false) }
+    }
+
     DisposableEffect(handle) {
         window?.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+        runCatching { wifiLock?.acquire() }
+        // HDMI Auto Low-Latency Mode: ask the display to drop its post-processing (game mode) —
+        // the biggest panel-side latency win on the TV boxes. No-op where ALLM isn't supported. API 30+.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            window?.setPreferMinimalPostProcessing(true)
+        }
         controller?.let {
             it.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
             it.hide(WindowInsetsCompat.Type.systemBars())
@@ -105,6 +138,10 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
             activity?.setConsoleHighRefreshRate(true) // back to the console UI's max refresh
             controller?.show(WindowInsetsCompat.Type.systemBars())
             window?.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                window?.setPreferMinimalPostProcessing(false)
+            }
+            runCatching { if (wifiLock?.isHeld == true) wifiLock.release() }
             // Release the landscape lock so the rest of the app follows the device/system again.
             activity?.requestedOrientation =
                 priorOrientation ?: ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
@@ -125,7 +162,19 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                 SurfaceView(ctx).apply {
                     holder.addCallback(object : SurfaceHolder.Callback {
                         override fun surfaceCreated(holder: SurfaceHolder) {
-                            NativeBridge.nativeStartVideo(handle, holder.surface)
+                            // Rank MediaCodecList decoders for the negotiated MIME (framework-only
+                            // API) and hand the chosen one to Rust, which creates it by name and
+                            // applies the per-SoC vendor low-latency keys.
+                            val mime = NativeBridge.nativeVideoMime(handle)
+                            val choice = VideoDecoders.pickDecoder(mime)
+                            NativeBridge.nativeStartVideo(
+                                handle,
+                                holder.surface,
+                                choice?.name ?: "",
+                                lowLatencyMode,
+                                choice?.lowLatencyFeature ?: false,
+                                isTv,
+                            )
                             NativeBridge.nativeStartAudio(handle)
                             if (micWanted) NativeBridge.nativeStartMic(handle)
                         }
@@ -150,7 +199,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         // Live stats HUD (FPS / throughput / capture→client latency), drawn over the video but
         // BEFORE the transparent gesture layer below, so it shows through and never eats touches.
         if (showStats) {
-            stats?.let { StatsOverlay(it, Modifier.align(Alignment.TopStart).padding(12.dp)) }
+            stats?.let { StatsOverlay(it, decoderLabel, Modifier.align(Alignment.TopStart).padding(12.dp)) }
         }
         // Touch input per the Settings model: trackpad/direct-pointer mouse (the shared gesture
         // vocabulary) or real multi-touch passthrough — see TouchInput.kt.

clients/android/app/src/main/res/xml/game_mode_config.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Game Mode config (Android 13 / API 33+). We support the Performance game mode; and we opt OUT of
+  the two OEM interventions that would corrupt a game-streaming session:
+    - allowGameDownscaling=false: the client renders exactly the host's negotiated resolution; a
+      platform downscale would blur the stream.
+    - allowGameFpsOverride=false: the stream is paced to the host's frame rate; a platform FPS cap
+      would drop frames / add judder.
+  Ignored on releases below API 33.
+-->
+<game-mode-config xmlns:android="http://schemas.android.com/apk/res/android"
+    android:supportsPerformanceGameMode="true"
+    android:allowGameDownscaling="false"
+    android:allowGameFpsOverride="false" />