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

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

@@ -0,0 +1,287 @@
+package com.voltkit.rtc.reactnative
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.ComponentName
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.Handler
+import android.os.IBinder
+import android.os.Looper
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.ServiceCompat
+import java.util.concurrent.CopyOnWriteArraySet
+
+/**
+ * The call service (plan §5.4): a plain foreground service that keeps a call's process, network and microphone alive
+ * while the app is in the background or the screen is off. Without one Android destroys the app's sockets about 6 s
+ * after it leaves the foreground or the screen goes off (Phase 0 finding 3), and Android 17 blocks background audio
+ * for apps with neither a visible activity nor a foreground service. JavaScript keeps working on native timers; this
+ * is not a Headless JS task.
+ *
+ * It is not in the library's manifest, so an app that never runs background calls takes on no Play declaration. The
+ * app declares it (the Expo plugin's callService option, or the manifest block in the docs):
+ *
+ *     <service android:name="com.voltkit.rtc.reactnative.VoltkitCallService" android:exported="false"
+ *              android:foregroundServiceType="microphone|mediaPlayback" />
+ *
+ * It is started with startService while the app is visible and promoted to the foreground at once: a refusal can then
+ * be reported, where a startForegroundService that never reaches startForeground crashes the app. Its types come from
+ * [CallServiceTypes], and are only ever widened while the app is visible. The notification opens the app and has a
+ * Leave action; swiping the app away ends the call (JavaScript closes the client with code 1000 on `taskRemoved`).
+ */
+class VoltkitCallService : Service() {
+    private val main = Handler(Looper.getMainLooper())
+    private var foreground = false
+    private var startedAt = 0L
+
+    /** Into the foreground with [Request]'s notification and these types; the JVM tests stand in for it (no notifications there). */
+    internal var promote: (Request, Int) -> Unit = { next, types ->
+        ServiceCompat.startForeground(this, NOTIFICATION_ID, notification(next), types)
+    }
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        when (intent?.action) {
+            ACTION_LEAVE -> {
+                // JavaScript leaves the call and stops the service; with no JavaScript listening, end it here.
+                if (listeners.isEmpty()) stopNow() else tell(EVENT_LEAVE, runningTypes, "")
+            }
+            else -> {
+                val next = takePending()
+                when {
+                    next != null -> runWith(next.request, next.done)
+                    // Started by something else (a stale intent): stay as it is, or go if it never got going.
+                    !foreground -> stopSelf(startId)
+                }
+            }
+        }
+        return START_NOT_STICKY
+    }
+
+    /** Show [next] and run with its types; [done] hears the types it runs with, or why it could not. On the main thread. */
+    internal fun runWith(next: Request, done: (Result<Int>) -> Unit) {
+        val first = !foreground
+        if (first) startedAt = System.currentTimeMillis()
+        var types = next.types
+        var error: Throwable? = null
+        while (true) {
+            try {
+                promote(next, types)
+                error = null
+                break
+            } catch (t: Throwable) {
+                error = t
+                // The share's consent can be gone (Android 14): keep the call, without the screen-share type.
+                if (types and CallServiceTypes.MEDIA_PROJECTION != 0) {
+                    Log.w(TAG, "the call service could not take the mediaProjection type (${t.message}); going on without it")
+                    types = types and CallServiceTypes.MEDIA_PROJECTION.inv()
+                    if (types != 0 || Build.VERSION.SDK_INT < 34) continue
+                }
+                break
+            }
+        }
+        val failure = error
+        if (failure != null) {
+            val message = "Android refused the call service: ${failure.javaClass.simpleName}: ${failure.message}"
+            Log.e(TAG, message)
+            if (first) {
+                // Never reached the foreground: started with startService, so stopping is safe.
+                stopSelf()
+            }
+            tell(EVENT_FAILED, if (first) 0 else runningTypes, message)
+            done(Result.failure(IllegalStateException(message, failure)))
+            return
+        }
+        foreground = true
+        running = this
+        runningTypes = types
+        tell(if (first) EVENT_STARTED else EVENT_UPDATED, types, "")
+        done(Result.success(types))
+    }
+
+    /**
+     * Out of the foreground and gone. It stops being the call's service now, not at onDestroy, which Android calls
+     * later: until then the status would still say running, and a start would ride this dying instance (onDestroy then
+     * taking the new call's service down). A start from here on goes through startService and gets a fresh instance.
+     */
+    internal fun stopNow() {
+        if (foreground) runCatching { ServiceCompat.stopForeground(this, ServiceCompat.STOP_FOREGROUND_REMOVE) }
+        foreground = false
+        if (running === this) {
+            running = null
+            runningTypes = 0
+            tell(EVENT_STOPPED, 0, "")
+        }
+        stopSelf()
+    }
+
+    override fun onTaskRemoved(rootIntent: Intent?) {
+        // The user swiped the app away: JavaScript ends the call (close code 1000) and stops the service. If it does
+        // not (its runtime is gone), the service goes on its own after a few seconds.
+        tell(EVENT_TASK_REMOVED, runningTypes, "")
+        main.postDelayed({ if (running === this) stopNow() }, TASK_REMOVED_GRACE_MILLIS)
+        super.onTaskRemoved(rootIntent)
+    }
+
+    override fun onDestroy() {
+        main.removeCallbacksAndMessages(null)
+        // stopNow already let go of it, unless it was stopped some other way (a stopService elsewhere in the app).
+        val was = running === this
+        if (was) {
+            running = null
+            runningTypes = 0
+        }
+        foreground = false
+        if (was) tell(EVENT_STOPPED, 0, "")
+        super.onDestroy()
+    }
+
+    private fun notification(next: Request): android.app.Notification {
+        val manager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        if (Build.VERSION.SDK_INT >= 26 && manager.getNotificationChannel(CHANNEL_ID) == null) {
+            manager.createNotificationChannel(
+                NotificationChannel(CHANNEL_ID, CHANNEL_NAME, NotificationManager.IMPORTANCE_LOW).apply {
+                    setShowBadge(false)
+                    enableVibration(false)
+                    setSound(null, null)
+                },
+            )
+        }
+        val immutable = PendingIntent.FLAG_IMMUTABLE
+        val open = packageManager.getLaunchIntentForPackage(packageName)?.let { launch ->
+            launch.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED)
+            PendingIntent.getActivity(this, 0, launch, PendingIntent.FLAG_UPDATE_CURRENT or immutable)
+        }
+        val leave = PendingIntent.getService(
+            this,
+            1,
+            Intent(this, VoltkitCallService::class.java).setAction(ACTION_LEAVE),
+            PendingIntent.FLAG_UPDATE_CURRENT or immutable,
+        )
+        return NotificationCompat.Builder(this, CHANNEL_ID)
+            .setContentTitle(next.title)
+            .setContentText(next.text)
+            .setSmallIcon(smallIcon())
+            .setOngoing(true)
+            .setOnlyAlertOnce(true)
+            .setCategory(NotificationCompat.CATEGORY_CALL)
+            .setPriority(NotificationCompat.PRIORITY_LOW)
+            .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
+            .setWhen(startedAt)
+            .setUsesChronometer(true)
+            .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
+            .apply { if (open != null) setContentIntent(open) }
+            .addAction(0, next.leaveLabel, leave)
+            .build()
+    }
+
+    /**
+     * The app's own icon for calls if it ships one, else its general notification icon, else the SDK's white handset.
+     * Never the launcher icon: Android draws a small icon from its alpha channel only, so a launcher icon shows as a
+     * solid square, and an adaptive one can crash Android 8.0 ("Bad notification posted ... Couldn't create icon").
+     */
+    private fun smallIcon(): Int {
+        for (name in ICON_NAMES) {
+            @Suppress("DiscouragedApi")
+            val id = resources.getIdentifier(name, "drawable", packageName)
+            if (id != 0) return id
+        }
+        return R.drawable.voltkit_rtc_default_call_icon
+    }
+
+    /** What the notification shows and the types the service runs with. */
+    internal data class Request(val title: String, val text: String, val leaveLabel: String, val types: Int)
+
+    private class Pending(val request: Request, val done: (Result<Int>) -> Unit)
+
+    /** Told on the main thread: started, updated, stopped, leave, taskRemoved, failed. */
+    internal fun interface Listener {
+        fun onCallServiceEvent(type: String, types: Int, message: String)
+    }
+
+    internal companion object {
+        private const val TAG = "VoltKitRtc"
+        private const val NOTIFICATION_ID = 0x564b_5254 // "VKRT"
+        private const val CHANNEL_ID = "voltkit_rtc_call"
+        private const val CHANNEL_NAME = "Calls"
+        private const val ACTION_START = "com.voltkit.rtc.reactnative.action.START_CALL"
+        private const val ACTION_LEAVE = "com.voltkit.rtc.reactnative.action.LEAVE_CALL"
+        private const val TASK_REMOVED_GRACE_MILLIS = 5_000L
+        // The app's drawables, by name: res/raw/voltkit_rtc_keep.xml keeps them through resource shrinking.
+        private val ICON_NAMES = listOf("voltkit_call_notification_icon", "notification_icon", "ic_notification")
+
+        const val EVENT_STARTED = "started"
+        const val EVENT_UPDATED = "updated"
+        const val EVENT_STOPPED = "stopped"
+        const val EVENT_LEAVE = "leave"
+        const val EVENT_TASK_REMOVED = "taskRemoved"
+        const val EVENT_FAILED = "failed"
+
+        val listeners = CopyOnWriteArraySet<Listener>()
+
+        /** The service while it runs in the foreground (main thread). */
+        @Volatile
+        var running: VoltkitCallService? = null
+            private set
+
+        /** The types it runs with now; 0 when stopped. */
+        @Volatile
+        var runningTypes: Int = 0
+            private set
+
+        private var pending: Pending? = null
+
+        private fun takePending(): Pending? = synchronized(this) { pending.also { pending = null } }
+
+        private fun tell(type: String, types: Int, message: String) {
+            listeners.forEach { runCatching { it.onCallServiceEvent(type, types, message) } }
+        }
+
+        /** The types the app's manifest declares for the service, or null when it does not declare the service. */
+        fun declaredTypes(context: Context): Int? = try {
+            @Suppress("DEPRECATION")
+            val info = context.packageManager.getServiceInfo(ComponentName(context, VoltkitCallService::class.java), 0)
+            if (Build.VERSION.SDK_INT >= 29) info.foregroundServiceType else 0
+        } catch (_: PackageManager.NameNotFoundException) {
+            null
+        }
+
+        /** Start it (main thread): [done] hears the types it runs with, or why it could not start. */
+        fun start(context: Context, request: Request, done: (Result<Int>) -> Unit) {
+            running?.let { return it.runWith(request, done) }
+            val previous = synchronized(this) { pending.also { pending = Pending(request, done) } }
+            previous?.done?.invoke(Result.failure(IllegalStateException("replaced by a newer start")))
+            val started = try {
+                context.startService(Intent(context, VoltkitCallService::class.java).setAction(ACTION_START))
+            } catch (t: Throwable) {
+                // IllegalStateException: the app is in the background (Android 8+).
+                takePending()
+                return done(Result.failure(IllegalStateException("Android refused to start the call service: ${t.message}", t)))
+            }
+            if (started == null) {
+                takePending()
+                done(Result.failure(IllegalStateException("the app's manifest does not declare VoltkitCallService")))
+            }
+        }
+
+        /** New text or types for the running service (main thread); nothing when it is not running. */
+        fun update(request: Request, done: (Result<Int>) -> Unit) {
+            val service = running ?: return done(Result.success(0))
+            service.runWith(request, done)
+        }
+
+        /** Stop it, and any start still on its way (main thread). */
+        fun stop(context: Context) {
+            takePending()?.done?.invoke(Result.failure(IllegalStateException("stopped before it started")))
+            running?.stopNow()
+            runCatching { context.stopService(Intent(context, VoltkitCallService::class.java)) }
+        }
+    }
+}

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

@@ -0,0 +1,215 @@
+package com.voltkit.rtc.reactnative
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.content.Context
+import android.content.pm.PackageManager
+import android.database.Cursor
+import android.media.AudioAttributes
+import android.media.AudioDeviceInfo
+import android.net.Uri
+import android.util.Log
+import com.oney.WebRTCModule.WebRTCModuleOptions
+import org.webrtc.audio.JavaAudioDeviceModule
+import java.lang.reflect.Field
+import java.lang.reflect.Method
+import java.util.concurrent.CopyOnWriteArraySet
+
+/**
+ * Runs once when the app's process starts, before Application.onCreate and long before react-native-webrtc's
+ * WebRTCModule exists (plan §5.3): it reads the meta-data ([RtcConfig]), gives react-native-webrtc the audio device
+ * module for the audio mode (WebRTCModuleOptions.audioDeviceModule), and turns on react-native-webrtc's screen-share
+ * service when the app declares screen sharing. So apps edit neither MainApplication nor MainActivity. Phase 0 S7
+ * proved a module made here is the one react-native-webrtc plays and records with.
+ *
+ * It must not touch ProcessLifecycleOwner while being created: providers run before androidx.startup's
+ * InitializationProvider, which starts the process lifecycle (Phase 0 S8). [AppVisibility.install] posts its
+ * registration to the main looper, which runs after every provider and Application.onCreate.
+ *
+ * An app that sets WebRTCModuleOptions.audioDeviceModule itself in MainApplication.onCreate replaces this module
+ * (MainApplication runs after providers): the audio mode and echo cancellation are then the app's, and the constant
+ * audioDeviceModule is false. selectAudioInput keeps working when the app's module is a JavaAudioDeviceModule; with any
+ * other module, or none, it answers false.
+ */
+class VoltkitRtcInitProvider : ContentProvider() {
+    override fun onCreate(): Boolean {
+        val context = context?.applicationContext ?: return true
+        try {
+            install(context)
+        } catch (t: Throwable) {
+            // Never stop the app from starting: react-native-webrtc then makes its own audio device module.
+            Log.e(TAG, "VoltKit RTC could not set up react-native-webrtc's audio: ${t.message}", t)
+        }
+        AppVisibility.install()
+        return true
+    }
+
+    private fun install(context: Context) {
+        val config = configOf(context)
+        config.problems.forEach { Log.w(TAG, "manifest meta-data: $it") }
+        val options = WebRTCModuleOptions.getInstance()
+        if (config.screenShare) options.enableMediaProjectionService = true
+        if (options.audioDeviceModule != null) {
+            Log.i(TAG, "react-native-webrtc already has an audio device module; keeping it")
+            return
+        }
+        val adm = createAudioDeviceModule(context, config)
+        options.audioDeviceModule = adm
+        audioDeviceModule = adm
+    }
+
+    override fun query(uri: Uri, projection: Array<out String>?, selection: String?, selectionArgs: Array<out String>?, sortOrder: String?): Cursor? = null
+
+    override fun getType(uri: Uri): String? = null
+
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<out String>?): Int = 0
+
+    override fun update(uri: Uri, values: ContentValues?, selection: String?, selectionArgs: Array<out String>?): Int = 0
+
+    internal companion object {
+        private const val TAG = "VoltKitRtc"
+
+        @Volatile
+        private var config: RtcConfig? = null
+
+        /**
+         * The module this provider gave react-native-webrtc; null when it did not run or found one already set. The app
+         * can still replace it in MainApplication: WebRTC uses it only while it is WebRTCModuleOptions.audioDeviceModule.
+         */
+        @Volatile
+        var audioDeviceModule: JavaAudioDeviceModule? = null
+            private set
+
+        /** Microphone failures the audio device module reports, for every client to report (mic-interrupted). */
+        val microphoneErrors = CopyOnWriteArraySet<(String) -> Unit>()
+
+        /** The process's settings from the manifest, read once (by the provider, or by the module when it did not run). */
+        fun configOf(context: Context): RtcConfig = config ?: synchronized(this) {
+            config ?: readConfig(context).also { config = it }
+        }
+
+        private fun readConfig(context: Context): RtcConfig {
+            val meta = try {
+                @Suppress("DEPRECATION")
+                context.packageManager.getApplicationInfo(context.packageName, PackageManager.GET_META_DATA).metaData
+            } catch (t: Throwable) {
+                Log.w(TAG, "could not read the app's meta-data: ${t.message}")
+                null
+            }
+            @Suppress("DEPRECATION")
+            return RtcConfig.from { key -> meta?.get(key) }
+        }
+
+        /**
+         * react-native-webrtc's audio device module for [config]: call audio (USAGE_VOICE_COMMUNICATION) or media
+         * playback (USAGE_MEDIA), the handset's echo canceller and noise suppressor where it has them, as the Android
+         * SDK's VoltKitRtc.create. The native module behind it is made only when WebRTC starts.
+         */
+        private fun createAudioDeviceModule(context: Context, config: RtcConfig): JavaAudioDeviceModule {
+            val playback = if (config.audioMode == AudioMode.communication) {
+                AudioAttributes.Builder()
+                    .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
+                    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                    .build()
+            } else {
+                AudioAttributes.Builder()
+                    .setUsage(AudioAttributes.USAGE_MEDIA)
+                    .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
+                    .build()
+            }
+            fun micError(message: String) {
+                Log.e(TAG, message)
+                microphoneErrors.forEach { runCatching { it(message) } }
+            }
+            return JavaAudioDeviceModule.builder(context)
+                .setAudioAttributes(playback)
+                .setUseHardwareAcousticEchoCanceler(
+                    config.hardwareEchoCancellation && JavaAudioDeviceModule.isBuiltInAcousticEchoCancelerSupported(),
+                )
+                .setUseHardwareNoiseSuppressor(
+                    config.hardwareEchoCancellation && JavaAudioDeviceModule.isBuiltInNoiseSuppressorSupported(),
+                )
+                .setEnableVolumeLogger(false)
+                .setAudioRecordErrorCallback(object : JavaAudioDeviceModule.AudioRecordErrorCallback {
+                    override fun onWebRtcAudioRecordInitError(errorMessage: String) =
+                        micError("microphone init failed: $errorMessage")
+
+                    override fun onWebRtcAudioRecordStartError(
+                        errorCode: JavaAudioDeviceModule.AudioRecordStartErrorCode,
+                        errorMessage: String,
+                    ) = micError("microphone start failed ($errorCode): $errorMessage")
+
+                    override fun onWebRtcAudioRecordError(errorMessage: String) = micError("microphone error: $errorMessage")
+                })
+                .setAudioTrackErrorCallback(object : JavaAudioDeviceModule.AudioTrackErrorCallback {
+                    override fun onWebRtcAudioTrackInitError(errorMessage: String) {
+                        Log.e(TAG, "audio playback init failed: $errorMessage")
+                    }
+
+                    override fun onWebRtcAudioTrackStartError(
+                        errorCode: JavaAudioDeviceModule.AudioTrackStartErrorCode,
+                        errorMessage: String,
+                    ) {
+                        Log.e(TAG, "audio playback start failed ($errorCode): $errorMessage")
+                    }
+
+                    override fun onWebRtcAudioTrackError(errorMessage: String) {
+                        Log.e(TAG, "audio playback error: $errorMessage")
+                    }
+                })
+                .createAudioDeviceModule()
+        }
+    }
+}
+
+/**
+ * The microphone react-native-webrtc's audio device module records from (`selectAudioInput`).
+ *
+ * Going back to the default (null) cannot go through JavaAudioDeviceModule.setPreferredInputDevice in jitsi's WebRTC
+ * 155: it logs `preferredInputDevice.getId()` first, so null throws a NullPointerException (found on the API 37
+ * emulator, 2026-10-25). Its WebRtcAudioRecord.setPreferredDevice takes null, and is reached through the module's
+ * `audioInput` field (react-native-webrtc's rules keep org.webrtc's names; consumer-rules.pro keeps these two too).
+ */
+internal object PreferredInput {
+    private const val TAG = "VoltKitRtc"
+
+    /** Record from [info]; false when the module refused it. */
+    fun choose(adm: JavaAudioDeviceModule, info: AudioDeviceInfo): Boolean = try {
+        adm.setPreferredInputDevice(info)
+        true
+    } catch (t: Throwable) {
+        Log.w(TAG, "could not choose the microphone ${info.id}: ${t.message}")
+        false
+    }
+
+    /** Back to the system's choice of microphone (a headset's when one is connected). */
+    fun clear(adm: JavaAudioDeviceModule): Boolean {
+        try {
+            adm.setPreferredInputDevice(null)
+            return true
+        } catch (_: NullPointerException) {
+            // jitsi's WebRTC 155: see above.
+        } catch (t: Throwable) {
+            Log.w(TAG, "could not go back to the default microphone: ${t.message}")
+            return false
+        }
+        return try {
+            val recorder = recorderField().get(adm) ?: return false
+            setterOf(recorder.javaClass).invoke(recorder, null as AudioDeviceInfo?)
+            true
+        } catch (t: Throwable) {
+            Log.w(TAG, "could not go back to the default microphone: ${t.message}")
+            false
+        }
+    }
+
+    /** JavaAudioDeviceModule's recorder. */
+    fun recorderField(): Field =
+        JavaAudioDeviceModule::class.java.getDeclaredField("audioInput").apply { isAccessible = true }
+
+    /** The recorder's setPreferredDevice(AudioDeviceInfo), which takes null. */
+    fun setterOf(recorder: Class<*>): Method =
+        recorder.getDeclaredMethod("setPreferredDevice", AudioDeviceInfo::class.java).apply { isAccessible = true }
+}