@voltkit-rtc/react-native 0.0.0-stage → 0.1.1

package/android/src/main/java/com/voltkit/rtc/reactnative/AudioRouter.kt

@@ -0,0 +1,487 @@
+package com.voltkit.rtc.reactnative
+
+import android.annotation.SuppressLint
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.media.AudioAttributes
+import android.media.AudioDeviceCallback
+import android.media.AudioDeviceInfo
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.os.Looper
+import android.util.Log
+import java.util.concurrent.CopyOnWriteArraySet
+
+/**
+ * The device's audio for calls: the audio mode, audio focus and where sound plays, shared by every client in the
+ * process because `AudioManager` is process-wide. Each connected client that manages audio holds it; the last to let
+ * go puts the device back as it found it. The routing rules are those of Twilio's AudioSwitch, which LiveKit and
+ * flutter_webrtc use: a selected device while it is connected, else a Bluetooth headset, else a wired or USB headset,
+ * else the loudspeaker or the earpiece as preferred. Everything runs on its own thread. No Bluetooth permission is
+ * needed (communication devices and SCO are AudioManager's).
+ *
+ * A line-by-line port of the Android SDK's AudioRouter (android-sdk/voltkit-rtc/src/main/kotlin/com/voltkit/rtc/
+ * AudioRouter.kt), React Native's differences being only these:
+ * - a holder is a token (one per JavaScript client, `audioAcquire`), and listening is separate: the module listens once;
+ * - answers come back through callbacks (the module's promises), not coroutines;
+ * - audio focus changes are told to the listeners, so a phone call can be reported as taking the microphone;
+ * - the speaker preference given at acquire may be null, keeping the one `setSpeakerphoneOn` set before any client.
+ */
+internal class AudioRouter private constructor(context: Context, private val mode: AudioMode) {
+    interface Listener {
+        fun onDevicesChanged(change: DevicesChanged)
+        fun onOutputChanged(device: MediaDevice?)
+        fun onFocusChanged(focus: String)
+    }
+
+    private class Saved(val mode: Int, val speakerphone: Boolean, val micMute: Boolean)
+
+    private val app = context.applicationContext
+    private val am = app.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+    private val thread = HandlerThread("VoltKitAudio").apply { start() }
+    private val handler = Handler(thread.looper)
+    private val listeners = CopyOnWriteArraySet<Listener>()
+
+    // Touched only on the router thread.
+    private val holders = HashSet<Any>()
+    private var saved: Saved? = null
+    private var focusRequest: AudioFocusRequest? = null
+    private val choice = OutputChoice()
+    private val sco = ScoLink()
+    private var watching = false
+    private var scanned = false
+    private val infos = HashMap<String, AudioDeviceInfo>()
+
+    /** Every audio device now; refreshed as they come and go while held. */
+    @Volatile
+    var devices: List<MediaDevice> = emptyList()
+        private set
+
+    /** Where call audio plays now, when the SDK routes it. */
+    @Volatile
+    var output: MediaDevice? = null
+        private set
+
+    val isRouting: Boolean get() = mode == AudioMode.communication
+
+    fun addListener(listener: Listener) {
+        listeners.add(listener)
+    }
+
+    fun removeListener(listener: Listener) {
+        listeners.remove(listener)
+    }
+
+    // --- the clients' side ------------------------------------------------------------------------
+
+    /**
+     * A client connected and manages audio: hold the call audio set up while it is. [speakerphone] sets the preference
+     * (null keeps it). [done] runs on the router thread once the audio is set up, with where it plays.
+     */
+    fun acquire(holder: Any, speakerphone: Boolean?, done: (MediaDevice?) -> Unit = {}) = post {
+        if (holders.add(holder)) {
+            if (speakerphone != null) choice.speakerPreferred = speakerphone
+            if (holders.size == 1) activate() else refresh(route = true)
+        }
+        done(output)
+    }
+
+    /** That client left; the last one out restores the device's audio. */
+    fun release(holder: Any) = post {
+        if (!holders.remove(holder)) return@post
+        if (holders.isEmpty()) deactivate()
+    }
+
+    /** Loudspeaker (true) or earpiece (false) when no headset is connected; a headset still wins. */
+    fun setSpeakerphoneOn(on: Boolean) = post {
+        choice.preferSpeaker(on)
+        if (holders.isNotEmpty()) refresh(route = true)
+    }
+
+    /** Play call audio on [deviceId] while it stays connected. False when there is no such output. */
+    fun selectOutput(deviceId: String, done: (Result<Boolean>) -> Unit) = call(done) {
+        if (devices.isEmpty() || devices.none { it.deviceId == deviceId }) refresh(route = false)
+        if (devices.none { it.kind == DeviceKind.audiooutput && it.deviceId == deviceId }) return@call false
+        choice.pick(deviceId)
+        if (holders.isNotEmpty()) refresh(route = true)
+        true
+    }
+
+    /** The microphone to record from; null when there is no such input. */
+    fun inputInfo(deviceId: String, done: (Result<AudioDeviceInfo?>) -> Unit) = call(done) {
+        if (devices.none { it.deviceId == deviceId }) refresh(route = false)
+        infos[deviceId]?.takeIf { devices.any { d -> d.kind == DeviceKind.audioinput && d.deviceId == deviceId } }
+    }
+
+    /** The audio devices now (scanned on demand when nobody holds the router). */
+    fun list(done: (Result<List<MediaDevice>>) -> Unit) = call(done) {
+        if (holders.isEmpty() || devices.isEmpty()) refresh(route = false)
+        devices
+    }
+
+    // --- activation -------------------------------------------------------------------------------
+
+    private fun activate() {
+        saved = Saved(am.mode, isSpeakerphoneOnCompat(), am.isMicrophoneMute)
+        requestFocus()
+        if (mode == AudioMode.communication) {
+            try {
+                am.mode = AudioManager.MODE_IN_COMMUNICATION
+            } catch (t: Throwable) {
+                Log.w(TAG, "could not set the call audio mode: ${t.message}")
+            }
+        }
+        // Another app may have left the microphone muted for the whole device.
+        if (am.isMicrophoneMute) am.isMicrophoneMute = false
+        watch(true)
+        refresh(route = true)
+    }
+
+    private fun deactivate() {
+        watch(false)
+        stopSco()
+        if (mode == AudioMode.communication && Build.VERSION.SDK_INT >= 31) {
+            runCatching { am.clearCommunicationDevice() }
+        }
+        saved?.let { s ->
+            runCatching { am.mode = s.mode }
+            if (Build.VERSION.SDK_INT < 31) setSpeakerphoneCompat(s.speakerphone)
+            runCatching { am.isMicrophoneMute = s.micMute }
+        }
+        saved = null
+        abandonFocus()
+        choice.reset()
+        setOutput(null)
+    }
+
+    private fun requestFocus() {
+        val usage = if (mode == AudioMode.communication) AudioAttributes.USAGE_VOICE_COMMUNICATION else AudioAttributes.USAGE_MEDIA
+        val content = if (mode == AudioMode.communication) AudioAttributes.CONTENT_TYPE_SPEECH else AudioAttributes.CONTENT_TYPE_MUSIC
+        try {
+            if (Build.VERSION.SDK_INT >= 26) {
+                val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+                    .setAudioAttributes(AudioAttributes.Builder().setUsage(usage).setContentType(content).build())
+                    .setAcceptsDelayedFocusGain(false)
+                    .setOnAudioFocusChangeListener(focusListener, handler)
+                    .build()
+                focusRequest = request
+                am.requestAudioFocus(request)
+            } else {
+                @Suppress("DEPRECATION")
+                am.requestAudioFocus(
+                    focusListener,
+                    if (mode == AudioMode.communication) AudioManager.STREAM_VOICE_CALL else AudioManager.STREAM_MUSIC,
+                    AudioManager.AUDIOFOCUS_GAIN,
+                )
+            }
+        } catch (t: Throwable) {
+            Log.w(TAG, "audio focus request failed: ${t.message}")
+        }
+    }
+
+    private fun abandonFocus() {
+        try {
+            if (Build.VERSION.SDK_INT >= 26) {
+                focusRequest?.let { am.abandonAudioFocusRequest(it) }
+            } else {
+                @Suppress("DEPRECATION")
+                am.abandonAudioFocus(focusListener)
+            }
+        } catch (_: Throwable) {
+        }
+        focusRequest = null
+    }
+
+    // A call keeps its audio when a notification or another app's sound takes focus: nothing to change here. The
+    // listeners hear it, so a phone call taking the microphone can be reported.
+    private val focusListener = AudioManager.OnAudioFocusChangeListener { change ->
+        Log.d(TAG, "audio focus changed: $change")
+        val focus = focusName(change) ?: return@OnAudioFocusChangeListener
+        listeners.forEach { runCatching { it.onFocusChanged(focus) } }
+    }
+
+    // --- watching devices -------------------------------------------------------------------------
+
+    private val deviceCallback = object : AudioDeviceCallback() {
+        override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>) {
+            choice.devicesAdded()
+            refresh(route = holders.isNotEmpty())
+        }
+
+        override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>) = refresh(route = holders.isNotEmpty())
+    }
+
+    private val commDeviceListener: Any? =
+        if (Build.VERSION.SDK_INT >= 31) {
+            AudioManager.OnCommunicationDeviceChangedListener { info ->
+                handler.post { if (holders.isNotEmpty()) setOutput(info?.let { outputOf(it) }) }
+            }
+        } else {
+            null
+        }
+
+    private val scoReceiver = object : BroadcastReceiver() {
+        override fun onReceive(context: Context, intent: Intent) {
+            // The broadcast is sticky: registering replays the last call's state
+            // (usually DISCONNECTED), which says nothing about the link just asked for.
+            if (isInitialStickyBroadcast) return
+            val state = intent.getIntExtra(AudioManager.EXTRA_SCO_AUDIO_STATE, AudioManager.SCO_AUDIO_STATE_ERROR)
+            if (sco.failed(state)) scoFailed()
+        }
+    }
+
+    /** The headset refused the call link: route elsewhere until devices change. */
+    private fun scoFailed() {
+        choice.refusedBy(output?.deviceId)
+        Log.w(TAG, "the Bluetooth headset did not open its call audio; routing elsewhere")
+        stopSco()
+        refresh(route = holders.isNotEmpty())
+    }
+
+    @SuppressLint("UnspecifiedRegisterReceiverFlag")
+    private fun watch(on: Boolean) {
+        if (on == watching) return
+        watching = on
+        try {
+            if (on) {
+                am.registerAudioDeviceCallback(deviceCallback, handler)
+                // Only call audio has a communication device. In media mode sound follows the system's media
+                // routing, and the call's device (often the earpiece) is not where it plays (SR-3).
+                if (Build.VERSION.SDK_INT >= 31 && mode == AudioMode.communication) {
+                    am.addOnCommunicationDeviceChangedListener(
+                        { r -> handler.post(r) },
+                        commDeviceListener as AudioManager.OnCommunicationDeviceChangedListener,
+                    )
+                } else if (Build.VERSION.SDK_INT < 31 && mode == AudioMode.communication) {
+                    app.registerReceiver(scoReceiver, IntentFilter(AudioManager.ACTION_SCO_AUDIO_STATE_UPDATED), null, handler)
+                }
+            } else {
+                am.unregisterAudioDeviceCallback(deviceCallback)
+                if (Build.VERSION.SDK_INT >= 31 && mode == AudioMode.communication) {
+                    am.removeOnCommunicationDeviceChangedListener(commDeviceListener as AudioManager.OnCommunicationDeviceChangedListener)
+                } else if (Build.VERSION.SDK_INT < 31 && mode == AudioMode.communication) {
+                    runCatching { app.unregisterReceiver(scoReceiver) }
+                }
+            }
+        } catch (t: Throwable) {
+            Log.w(TAG, "audio device watch ${if (on) "start" else "stop"} failed: ${t.message}")
+        }
+    }
+
+    // --- the device list and routing ---------------------------------------------------------------
+
+    private fun refresh(route: Boolean) {
+        val before = devices
+        val now = scan()
+        devices = now
+        // The first scan is the starting list, not a change.
+        val first = !scanned
+        scanned = true
+        if (!first && before != now) {
+            val change = DevicesChanged.between(before, now)
+            if (change.added.isNotEmpty() || change.removed.isNotEmpty()) listeners.forEach { runCatching { it.onDevicesChanged(change) } }
+        }
+        val outputs = now.filter { it.kind == DeviceKind.audiooutput }
+        choice.outputsNow(outputs)
+        if (route && holders.isNotEmpty()) applyRoute(choice.choose(outputs))
+    }
+
+    private fun scan(): List<MediaDevice> {
+        infos.clear()
+        val outs: List<AudioDeviceInfo> = try {
+            if (Build.VERSION.SDK_INT >= 31 && mode == AudioMode.communication) {
+                am.availableCommunicationDevices
+            } else {
+                am.getDevices(AudioManager.GET_DEVICES_OUTPUTS).toList()
+            }
+        } catch (_: Throwable) {
+            emptyList()
+        }
+        val ins: List<AudioDeviceInfo> = try {
+            am.getDevices(AudioManager.GET_DEVICES_INPUTS).toList()
+        } catch (_: Throwable) {
+            emptyList()
+        }
+        val outputs = LinkedHashMap<String, MediaDevice>()
+        for (info in outs) {
+            val d = outputOf(info) ?: continue
+            if (d.deviceId !in outputs) {
+                outputs[d.deviceId] = d
+                infos[d.deviceId] = info
+            }
+        }
+        // Before Android 12 the earpiece cannot be chosen over a wired headset: it is not offered then.
+        if (Build.VERSION.SDK_INT < 31 && outputs.values.any { it.type == AudioDeviceType.wiredHeadset }) outputs.remove(EARPIECE)
+        val inputs = LinkedHashMap<String, MediaDevice>()
+        for (info in ins) {
+            val d = inputOf(info) ?: continue
+            if (d.deviceId !in inputs) {
+                inputs[d.deviceId] = d
+                infos[d.deviceId] = info
+            }
+        }
+        val order = listOf(AudioDeviceType.bluetooth, AudioDeviceType.wiredHeadset, AudioDeviceType.usb, AudioDeviceType.earpiece, AudioDeviceType.speaker)
+        return outputs.values.sortedBy { order.indexOf(it.type).let { i -> if (i < 0) order.size else i } } + inputs.values
+    }
+
+    private fun outputOf(info: AudioDeviceInfo): MediaDevice? {
+        val name = info.productName?.toString()?.trim().orEmpty()
+        return when (info.type) {
+            AudioDeviceInfo.TYPE_BUILTIN_SPEAKER -> MediaDevice(SPEAKER, DeviceKind.audiooutput, "Speaker", AudioDeviceType.speaker)
+            AudioDeviceInfo.TYPE_BUILTIN_EARPIECE ->
+                if (mode == AudioMode.communication) MediaDevice(EARPIECE, DeviceKind.audiooutput, "Phone", AudioDeviceType.earpiece) else null
+            AudioDeviceInfo.TYPE_WIRED_HEADSET, AudioDeviceInfo.TYPE_WIRED_HEADPHONES ->
+                MediaDevice("wired", DeviceKind.audiooutput, "Wired headset", AudioDeviceType.wiredHeadset, groupId = "wired")
+            AudioDeviceInfo.TYPE_USB_HEADSET, AudioDeviceInfo.TYPE_USB_DEVICE ->
+                MediaDevice("usb:${info.id}", DeviceKind.audiooutput, name.ifEmpty { "USB audio" }, AudioDeviceType.usb, groupId = "usb:$name")
+            AudioDeviceInfo.TYPE_BLUETOOTH_SCO ->
+                if (mode == AudioMode.communication) bluetooth(info, name) else null
+            // In media mode a Bluetooth headset plays in its high-quality (A2DP) profile.
+            AudioDeviceInfo.TYPE_BLUETOOTH_A2DP ->
+                if (mode == AudioMode.media) bluetooth(info, name) else null
+            else -> when {
+                Build.VERSION.SDK_INT >= 31 && (info.type == AudioDeviceInfo.TYPE_BLE_HEADSET || info.type == AudioDeviceInfo.TYPE_BLE_SPEAKER) -> bluetooth(info, name)
+                Build.VERSION.SDK_INT >= 28 && info.type == AudioDeviceInfo.TYPE_HEARING_AID -> bluetooth(info, name.ifEmpty { "Hearing aid" })
+                else -> null
+            }
+        }
+    }
+
+    private fun bluetooth(info: AudioDeviceInfo, name: String) =
+        MediaDevice("bluetooth:${info.id}", DeviceKind.audiooutput, name.ifEmpty { "Bluetooth" }, AudioDeviceType.bluetooth, groupId = "bluetooth:$name")
+
+    private fun inputOf(info: AudioDeviceInfo): MediaDevice? {
+        val name = info.productName?.toString()?.trim().orEmpty()
+        return when (info.type) {
+            AudioDeviceInfo.TYPE_BUILTIN_MIC -> MediaDevice(MIC, DeviceKind.audioinput, "Phone microphone", AudioDeviceType.builtinMic)
+            AudioDeviceInfo.TYPE_WIRED_HEADSET ->
+                MediaDevice("wired-mic", DeviceKind.audioinput, "Headset microphone", AudioDeviceType.wiredHeadset, groupId = "wired")
+            AudioDeviceInfo.TYPE_USB_HEADSET, AudioDeviceInfo.TYPE_USB_DEVICE ->
+                MediaDevice("usb-mic:${info.id}", DeviceKind.audioinput, name.ifEmpty { "USB microphone" }, AudioDeviceType.usb, groupId = "usb:$name")
+            AudioDeviceInfo.TYPE_BLUETOOTH_SCO ->
+                MediaDevice("bluetooth-mic:${info.id}", DeviceKind.audioinput, name.ifEmpty { "Bluetooth" }, AudioDeviceType.bluetooth, groupId = "bluetooth:$name")
+            else -> if (Build.VERSION.SDK_INT >= 31 && info.type == AudioDeviceInfo.TYPE_BLE_HEADSET) {
+                MediaDevice("bluetooth-mic:${info.id}", DeviceKind.audioinput, name.ifEmpty { "Bluetooth" }, AudioDeviceType.bluetooth, groupId = "bluetooth:$name")
+            } else {
+                null
+            }
+        }
+    }
+
+    private fun applyRoute(target: MediaDevice?) {
+        if (target == null) return
+        if (mode != AudioMode.communication) {
+            // Media playback follows the system's own routing.
+            setOutput(target)
+            return
+        }
+        try {
+            if (Build.VERSION.SDK_INT >= 31) {
+                val info = infos[target.deviceId] ?: return
+                if (am.communicationDevice?.id != info.id && !am.setCommunicationDevice(info)) {
+                    Log.w(TAG, "could not route call audio to ${target.label}")
+                    return
+                }
+            } else {
+                when (target.type) {
+                    AudioDeviceType.bluetooth -> {
+                        setSpeakerphoneCompat(false)
+                        startSco()
+                    }
+                    AudioDeviceType.speaker -> {
+                        stopSco()
+                        setSpeakerphoneCompat(true)
+                    }
+                    else -> {
+                        stopSco()
+                        setSpeakerphoneCompat(false)
+                    }
+                }
+            }
+        } catch (t: Throwable) {
+            Log.w(TAG, "routing call audio to ${target.label} failed: ${t.message}")
+            return
+        }
+        setOutput(target)
+    }
+
+    @Suppress("DEPRECATION")
+    private fun startSco() {
+        if (sco.wanted) return
+        val start = sco.start()
+        runCatching {
+            am.startBluetoothSco()
+            am.isBluetoothScoOn = true
+        }.onFailure { Log.w(TAG, "Bluetooth call audio could not start: ${it.message}") }
+        // A refusal can say only DISCONNECTED, which ScoLink takes for the link stopped before: silence is a refusal too.
+        handler.postDelayed({ if (sco.silent(start)) scoFailed() }, ScoLink.START_TIMEOUT_MILLIS)
+    }
+
+    @Suppress("DEPRECATION")
+    private fun stopSco() {
+        if (!sco.wanted) return
+        sco.stop()
+        runCatching {
+            am.isBluetoothScoOn = false
+            am.stopBluetoothSco()
+        }
+    }
+
+    @Suppress("DEPRECATION")
+    private fun isSpeakerphoneOnCompat(): Boolean = runCatching { am.isSpeakerphoneOn }.getOrDefault(false)
+
+    @Suppress("DEPRECATION")
+    private fun setSpeakerphoneCompat(on: Boolean) {
+        runCatching { if (am.isSpeakerphoneOn != on) am.isSpeakerphoneOn = on }
+    }
+
+    private fun setOutput(device: MediaDevice?) {
+        if (output == device) return
+        output = device
+        listeners.forEach { runCatching { it.onOutputChanged(device) } }
+    }
+
+    // --- threading --------------------------------------------------------------------------------
+
+    private fun post(block: () -> Unit) {
+        if (Looper.myLooper() == thread.looper) block() else handler.post(block)
+    }
+
+    /** Run [block] on the router thread and hand its result (or what it threw) to [done], on that thread. */
+    private fun <T> call(done: (Result<T>) -> Unit, block: () -> T) {
+        val run = Runnable { done(runCatching(block)) }
+        if (Looper.myLooper() == thread.looper) run.run() else handler.post(run)
+    }
+
+    companion object {
+        private const val TAG = "VoltKitRtc"
+        const val SPEAKER = "speaker"
+        const val EARPIECE = "earpiece"
+        const val MIC = "mic"
+
+        @Volatile
+        private var shared: AudioRouter? = null
+
+        /** The process's router. Its audio mode is the process's ([RtcConfig.audioMode]): the first caller's wins. */
+        fun get(context: Context, mode: AudioMode): AudioRouter =
+            shared ?: synchronized(this) { shared ?: AudioRouter(context.applicationContext, mode).also { shared = it } }
+
+        /** The router, if one was made. */
+        fun existing(): AudioRouter? = shared
+
+        /** AudioManager.AUDIOFOCUS_* by the names JavaScript receives. */
+        fun focusName(change: Int): String? = when (change) {
+            AudioManager.AUDIOFOCUS_GAIN, AudioManager.AUDIOFOCUS_GAIN_TRANSIENT,
+            AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE, AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK -> "gain"
+            AudioManager.AUDIOFOCUS_LOSS -> "loss"
+            AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> "lossTransient"
+            AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> "lossTransientCanDuck"
+            else -> null
+        }
+    }
+}

package/android/src/main/java/com/voltkit/rtc/reactnative/CallServiceTypes.kt

@@ -0,0 +1,120 @@
+package com.voltkit.rtc.reactnative
+
+import android.Manifest
+import android.content.pm.ServiceInfo
+
+/**
+ * Which foreground service types the call service runs with (plan §5.4, PLAN_UPDATES 5): a pure function of what the
+ * app's manifest declares, what is granted, what the call publishes and the audio mode, so every Android version's
+ * rules are tested off a device (CallServiceTypesTest). Android's rules
+ * (developer.android.com/develop/background-work/services/fgs/service-types):
+ * - API 28+: FOREGROUND_SERVICE, for any foreground service.
+ * - API 29: the types exist, but microphone and camera only come in API 30.
+ * - API 30+: a service started while the app is visible keeps the microphone (camera) in the background only with the
+ *   microphone (camera) type.
+ * - API 34+: each type needs its FOREGROUND_SERVICE_<TYPE> permission; microphone needs RECORD_AUDIO granted, camera
+ *   CAMERA; mediaProjection the user's consent to a share; and a service must name at least one type.
+ *
+ * The choice: microphone when RECORD_AUDIO is granted, otherwise mediaPlayback (a listener); a listen-only app (media
+ * mode) plays media unless it publishes the microphone. Camera only when the app keeps the camera in the background
+ * (pauseCamera false) and publishes it. mediaProjection only while a share is live. The types only ever widen while
+ * the app is visible: the JavaScript side starts and updates the service then.
+ */
+internal object CallServiceTypes {
+    const val MEDIA_PLAYBACK = ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
+    const val MEDIA_PROJECTION = ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
+    const val CAMERA = ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA
+    const val MICROPHONE = ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
+
+    data class Input(
+        val sdkInt: Int,
+        /** The service's android:foregroundServiceType (0 below API 29, or when it declares none). */
+        val declaredTypes: Int,
+        /** The permissions granted now: runtime ones the user allowed, and normal ones the manifest declares. */
+        val granted: Set<String>,
+        val audioMode: AudioMode,
+        val micPublished: Boolean,
+        val cameraPublished: Boolean,
+        /** The provider's background.pauseCamera: the camera stops in the background, so no camera type. */
+        val pauseCamera: Boolean,
+        /** A screen share is live. */
+        val sharing: Boolean,
+    )
+
+    data class Decision(
+        /** For startForeground: 0 below API 29, where there are no types. */
+        val types: Int,
+        val canStart: Boolean,
+        /** Why it cannot start; null when it can. */
+        val reason: String?,
+    )
+
+    fun decide(input: Input): Decision {
+        val granted = input.granted
+        val sdk = input.sdkInt
+        if (sdk >= 28 && Manifest.permission.FOREGROUND_SERVICE !in granted) {
+            return Decision(0, false, "the app's manifest does not declare android.permission.FOREGROUND_SERVICE")
+        }
+        if (sdk < 29) return Decision(0, true, null)
+
+        fun declared(type: Int) = input.declaredTypes and type == type
+        fun permitted(permission: String) = sdk < 34 || permission in granted
+
+        val mic = sdk >= 30 && declared(MICROPHONE) && Manifest.permission.RECORD_AUDIO in granted &&
+            permitted(Manifest.permission.FOREGROUND_SERVICE_MICROPHONE)
+        val playback = declared(MEDIA_PLAYBACK) && permitted(Manifest.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK)
+        val camera = sdk >= 30 && !input.pauseCamera && input.cameraPublished && declared(CAMERA) &&
+            Manifest.permission.CAMERA in granted && permitted(Manifest.permission.FOREGROUND_SERVICE_CAMERA)
+        val projection = input.sharing && declared(MEDIA_PROJECTION) &&
+            permitted(Manifest.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION)
+
+        val audio = when (input.audioMode) {
+            AudioMode.communication -> if (mic) MICROPHONE else if (playback) MEDIA_PLAYBACK else 0
+            AudioMode.media -> if (mic && input.micPublished) MICROPHONE else if (playback) MEDIA_PLAYBACK else if (mic) MICROPHONE else 0
+        }
+        val types = audio or (if (camera) CAMERA else 0) or (if (projection) MEDIA_PROJECTION else 0)
+        // From Android 14 a foreground service must name a type; below, none keeps the process and its network.
+        if (types == 0 && sdk >= 34) return Decision(0, false, missing(input))
+        return Decision(types, true, null)
+    }
+
+    /** What keeps the service from running on Android 14 and later, in the words of the manifest. */
+    private fun missing(input: Input): String {
+        val granted = input.granted
+        val wantsMic = input.declaredTypes and MICROPHONE != 0
+        val wantsPlayback = input.declaredTypes and MEDIA_PLAYBACK != 0
+        if (!wantsMic && !wantsPlayback) {
+            return "VoltkitCallService's android:foregroundServiceType declares neither microphone nor mediaPlayback"
+        }
+        val needs = ArrayList<String>()
+        if (wantsMic) {
+            if (Manifest.permission.RECORD_AUDIO !in granted) needs += "android.permission.RECORD_AUDIO granted"
+            if (Manifest.permission.FOREGROUND_SERVICE_MICROPHONE !in granted) needs += "android.permission.FOREGROUND_SERVICE_MICROPHONE declared"
+        }
+        if (wantsPlayback && Manifest.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK !in granted) {
+            needs += "android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK declared"
+        }
+        return "the call service can run as neither microphone nor mediaPlayback; it needs " + needs.joinToString(" or ")
+    }
+
+    /** Every ServiceInfo.FOREGROUND_SERVICE_TYPE_* by the name the manifest gives it, lowest bit first. */
+    private val NAMES = listOf(
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC to "dataSync",
+        MEDIA_PLAYBACK to "mediaPlayback",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL to "phoneCall",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION to "location",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE to "connectedDevice",
+        MEDIA_PROJECTION to "mediaProjection",
+        CAMERA to "camera",
+        MICROPHONE to "microphone",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_HEALTH to "health",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING to "remoteMessaging",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED to "systemExempted",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_SHORT_SERVICE to "shortService",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING to "mediaProcessing",
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_SPECIAL_USE to "specialUse",
+    )
+
+    /** The manifest's names for the types in [mask]. */
+    fun names(mask: Int): List<String> = NAMES.filter { (type, _) -> mask and type == type && type != 0 }.map { it.second }
+}