Before playing TTS, request audio focus

common/src/main/kotlin/io/homeassistant/companion/android/common/util/tts/TextToSpeechClient.kt

@@ -5,14 +5,21 @@ import android.media.AudioAttributes
 import android.media.AudioManager
 import android.widget.Toast
 import androidx.core.content.getSystemService
+import androidx.media.AudioAttributesCompat
+import androidx.media.AudioFocusRequestCompat
+import androidx.media.AudioManagerCompat
 import io.homeassistant.companion.android.common.R
 import io.homeassistant.companion.android.common.notifications.NotificationData
 import java.util.UUID
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.cancelChildren
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeoutOrNull
 import timber.log.Timber
 
 /**
@@ -30,6 +37,38 @@ class TextToSpeechClient(private val applicationContext: Context, private val te
     private val mainScope: CoroutineScope = CoroutineScope(Dispatchers.Main + mainJob)
 
     private var isPlaying = false
+    private var playbackJob: Job? = null
+    private val hasFocus = MutableStateFlow(false)
+    private var isTransientLoss = false
+    private var currentUtterance: Utterance? = null
+    private var focusRequest: AudioFocusRequestCompat? = null
+
+    private val focusListener = AudioManager.OnAudioFocusChangeListener { focusChange ->
+        mainScope.launch {
+            when (focusChange) {
+                AudioManager.AUDIOFOCUS_GAIN -> {
+                    Timber.d("Audio focus gained")
+                    hasFocus.value = true
+                    if (utteranceQueue.isNotEmpty() && !isPlaying) {
+                        startPlayback()
+                    }
+                }
+                AudioManager.AUDIOFOCUS_LOSS -> {
+                    Timber.d("Audio focus lost permanently")
+                    hasFocus.value = false
+                    stopTTS()
+                }
+                AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
+                    Timber.d("Audio focus lost temporarily")
+                    hasFocus.value = false
+                    isTransientLoss = true
+                    playbackJob?.cancel()
+                    playbackJob = null
+                    textToSpeechEngine.release()
+                }
+            }
+        }
+    }
 
     /**
      * Queues a text message to be played back if [data] with a [TextToSpeechData.TTS_TEXT] key is provided.
@@ -57,7 +96,7 @@ class TextToSpeechClient(private val applicationContext: Context, private val te
                 ),
             )
             if (!isPlaying) {
-                play()
+                startPlayback()
             }
         }
     }
@@ -67,39 +106,186 @@ class TextToSpeechClient(private val applicationContext: Context, private val te
      */
     fun stopTTS() {
         Timber.d("stopped TTS")
+        playbackJob?.cancel()
+        playbackJob = null
         mainJob.cancelChildren()
         utteranceQueue.clear()
         textToSpeechEngine.release()
+        abandonAudioFocus()
+        hasFocus.value = false
         isPlaying = false
     }
 
+    private fun startPlayback() {
+        if (isPlaying) return
+        isPlaying = true
+        playbackJob = mainScope.launch {
+            try {
+                play()
+            } finally {
+                isPlaying = false
+            }
+        }
+    }
+
+    private fun requestAudioFocus(): Boolean {
+        return try {
+            val audioManager = applicationContext.getSystemService<AudioManager>() ?: return false
+
+            val audioAttributes = utteranceQueue.firstOrNull()?.audioAttributes
+            val compatAttributes = if (audioAttributes != null) AudioAttributesCompat.wrap(audioAttributes) else null
+            val usage = if (audioAttributes !=
+                null
+            ) {
+                compatAttributes?.usage ?: AudioAttributesCompat.USAGE_MEDIA
+            } else {
+                AudioAttributesCompat.USAGE_MEDIA
+            }
+            val contentType = if (audioAttributes !=
+                null
+            ) {
+                compatAttributes?.contentType ?: AudioAttributesCompat.CONTENT_TYPE_SPEECH
+            } else {
+                AudioAttributesCompat.CONTENT_TYPE_SPEECH
+            }
+
+            val audioAttributesCompat = AudioAttributesCompat.Builder()
+                .setUsage(usage)
+                .setContentType(contentType)
+                .build()
+
+            val request = AudioFocusRequestCompat.Builder(AudioManagerCompat.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK)
+                .setAudioAttributes(audioAttributesCompat)
+                .setOnAudioFocusChangeListener(focusListener)
+                .build()
+
+            focusRequest = request
+
+            val result = AudioManagerCompat.requestAudioFocus(audioManager, request)
+            if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
+                hasFocus.value = true
+                true
+            } else {
+                hasFocus.value = false
+                false
+            }
+        } catch (e: Throwable) {
+            Timber.w(e, "Failed to request audio focus")
+            hasFocus.value = false
+            false
+        }
+    }
+
+    private fun abandonAudioFocus() {
+        val audioManager = applicationContext.getSystemService<AudioManager>() ?: return
+        try {
+            val request = focusRequest
+            if (request != null) {
+                AudioManagerCompat.abandonAudioFocusRequest(audioManager, request)
+            }
+        } catch (e: Exception) {
+            Timber.w(e, "Failed to abandon audio focus")
+        }
+        focusRequest = null
+    }
+
     /**
      * Plays each queued [Utterance] in sequence until [utteranceQueue] is empty.
      * There can be further additions to the queue while a message is playing which will be picked up in the running playback loop.
      */
     private suspend fun play() {
-        isPlaying = true
+        isTransientLoss = false
+        val focusGranted = requestAudioFocus()
+
+        if (!focusGranted && !hasFocus.value) {
+            Timber.e("Audio focus request denied")
+            handleError(applicationContext.getString(R.string.tts_error_focus_denied))
+            utteranceQueue.clear()
+            abandonAudioFocus()
+            return
+        }
+
+        if (!hasFocus.value) {
+            Timber.d("Audio focus not granted yet, waiting...")
+            val regained = withTimeoutOrNull(FOCUS_TIMEOUT_MS) {
+                hasFocus.first { it }
+                true
+            } ?: false
+
+            if (!regained) {
+                Timber.e("Timed out waiting for initial audio focus")
+                handleError(applicationContext.getString(R.string.tts_error_focus_denied))
+                utteranceQueue.clear()
+                abandonAudioFocus()
+                return
+            }
+        }
+
         textToSpeechEngine.initialize().onFailure { throwable ->
             Timber.e(
                 throwable,
                 "Failed to initialize engine.",
             )
             handleError(applicationContext.getString(R.string.tts_error_init))
             utteranceQueue.clear()
+            abandonAudioFocus()
         }.onSuccess {
-            while (utteranceQueue.isNotEmpty()) {
-                utteranceQueue.removeFirst().let { utterance ->
+            try {
+                // Over bluetooth connections, the first syllable or even word can be cut off.
+                // Adding an initial empty utterance seems to fix this.
+                // Testing shows this is more effective than utilizing the
+                // textToSpeech.playSilentUtterance method.
+                if (utteranceQueue.isNotEmpty()) {
+                    utteranceQueue.addFirst(
+                        Utterance(
+                            id = UUID.randomUUID().toString(),
+                            text = " ",
+                            streamVolumeAdjustment = utteranceQueue.first().streamVolumeAdjustment,
+                            audioAttributes = utteranceQueue.first().audioAttributes,
+                        ),
+                    )
+                }
+                while (utteranceQueue.isNotEmpty()) {
+                    if (!hasFocus.value) {
+                        Timber.d("Audio focus lost before playing utterance, waiting...")
+                        val regained = withTimeoutOrNull(FOCUS_TIMEOUT_MS) {
+                            hasFocus.first { it }
+                            true
+                        } ?: false
+
+                        if (!regained) {
+                            Timber.e("Timed out waiting to regain audio focus")
+                            handleError(applicationContext.getString(R.string.tts_error_focus_denied))
+                            utteranceQueue.clear()
+                            abandonAudioFocus()
+                            return@onSuccess
+                        }
+                    }
+
+                    val utterance = utteranceQueue.removeFirst()
+                    currentUtterance = utterance
                     textToSpeechEngine.play(utterance).onFailure { throwable ->
                         Timber.e(throwable, "Failed to play utterance '${utterance.id}'")
                         handleError(
                             applicationContext.getString(R.string.tts_error_utterance, utterance.text),
                         )
                     }
+                    currentUtterance = null
+                }
+            } catch (e: CancellationException) {
+                if (isTransientLoss) {
+                    currentUtterance?.let {
+                        utteranceQueue.addFirst(it)
+                    }
+                }
+                throw e
+            } finally {
+                textToSpeechEngine.release()
+                if (utteranceQueue.isEmpty()) {
+                    abandonAudioFocus()
                 }
             }
-            textToSpeechEngine.release()
         }
-        isPlaying = false
     }
 
     private fun handleError(msg: String) {
@@ -113,6 +299,8 @@ class TextToSpeechClient(private val applicationContext: Context, private val te
     }
 
     private companion object {
+        private const val FOCUS_TIMEOUT_MS = 10000L
+
         private fun getStreamVolumeAdjustment(context: Context, data: Map<String, String>): StreamVolumeAdjustment {
             val audioManager = context.getSystemService<AudioManager>()
             return if (
@@ -136,7 +324,10 @@ class TextToSpeechClient(private val applicationContext: Context, private val te
                     .setUsage(AudioAttributes.USAGE_ALARM)
                     .build()
             } else {
-                AudioAttributes.Builder().build()
+                AudioAttributes.Builder()
+                    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                    .setUsage(AudioAttributes.USAGE_MEDIA)
+                    .build()
             }
         }
     }

common/src/main/res/values/strings.xml

@@ -958,6 +958,7 @@
     <string name="trust_server_summary">Allow this server to enable and manage sensors and send notification commands</string>
     <string name="tts_error_utterance">Unable to process notification \"%1$s\" as text to speech.</string>
     <string name="tts_error_init">Failed to initialize a text to speech engine.</string>
+    <string name="tts_error_focus_denied">Could not obtain audio focus for text to speech.</string>
     <string name="tts_no_text">Please set the text for text to speech to process</string>
     <string name="unknown_address">Unknown address</string>
     <string name="update_shortcut">Update shortcut data</string>