Update audio guidance for AA compatibility

Author: kmadsen

CHANGELOG.md

@@ -4,6 +4,7 @@ Mapbox welcomes participation and contributions from everyone.
 
 ## Unreleased
 #### Features
+- Moved `MapboxAudioGuidance` and `MapboxAudioGuidanceState` into public api. [#6336](https://github.com/mapbox/mapbox-navigation-android/pull/6336)
 #### Bug fixes and improvements
 
 ## Mapbox Navigation SDK 2.8.0-rc.1 - 15 September, 2022

libnavui-androidauto/src/main/java/com/mapbox/androidauto/MapboxCarApp.kt

@@ -1,19 +1,16 @@
 package com.mapbox.androidauto
 
-import android.app.Application
 import com.mapbox.androidauto.navigation.location.CarAppLocation
 import com.mapbox.androidauto.navigation.location.impl.CarAppLocationImpl
 import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
 import com.mapbox.navigation.core.lifecycle.MapboxNavigationApp
-import com.mapbox.navigation.ui.app.internal.SharedApp
-import com.mapbox.navigation.ui.voice.internal.MapboxAudioGuidance
+import com.mapbox.navigation.ui.voice.api.MapboxAudioGuidance
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 
 /**
  * The entry point for your Mapbox Android Auto app.
  */
-@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
 object MapboxCarApp {
 
     private val carAppStateFlow = MutableStateFlow<CarAppState>(FreeDriveState)
@@ -43,12 +40,15 @@ object MapboxCarApp {
     }
 
     /**
-     * Setup android auto from your [Application.onCreate]
-     *
-     * @param application used to detect when activities are foregrounded
+     * Setup android auto with defaults
      */
-    fun setup(application: Application) {
-        SharedApp.setup(application)
-        MapboxNavigationApp.registerObserver(CarAppLocationImpl())
+    @OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
+    fun setup() {
+        if (MapboxNavigationApp.getObservers(MapboxAudioGuidance::class).isEmpty()) {
+            MapboxNavigationApp.registerObserver(MapboxAudioGuidance())
+        }
+        if (MapboxNavigationApp.getObservers(CarAppLocation::class).isEmpty()) {
+            MapboxNavigationApp.registerObserver(CarAppLocationImpl())
+        }
     }
 }

libnavui-androidauto/src/main/java/com/mapbox/androidauto/navigation/audioguidance/AppAudioGuidanceUi.kt

@@ -8,7 +8,7 @@ import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.lifecycleScope
 import androidx.lifecycle.repeatOnLifecycle
 import com.mapbox.androidauto.MapboxCarApp
-import com.mapbox.navigation.ui.voice.internal.MapboxAudioGuidance
+import com.mapbox.navigation.ui.voice.api.MapboxAudioGuidanceState
 import com.mapbox.navigation.ui.voice.view.MapboxSoundButton
 import kotlinx.coroutines.flow.collect
 import kotlinx.coroutines.launch
@@ -40,7 +40,7 @@ fun Fragment.attachAudioGuidance(
  */
 fun Lifecycle.muteAudioGuidance() {
     addObserver(object : DefaultLifecycleObserver {
-        lateinit var initialState: MapboxAudioGuidance.State
+        lateinit var initialState: MapboxAudioGuidanceState
         override fun onResume(owner: LifecycleOwner) {
             with(MapboxCarApp.carAppAudioGuidanceService()) {
                 initialState = stateFlow().value

libnavui-app/src/main/java/com/mapbox/navigation/ui/app/internal/SharedApp.kt

@@ -18,8 +18,7 @@ import com.mapbox.navigation.ui.app.internal.controller.TripSessionStarterStateC
 import com.mapbox.navigation.ui.maps.internal.ui.RouteAlternativeComponent
 import com.mapbox.navigation.ui.maps.internal.ui.RouteAlternativeContract
 import com.mapbox.navigation.ui.utils.internal.datastore.NavigationDataStoreOwner
-import com.mapbox.navigation.ui.voice.internal.MapboxAudioGuidance
-import com.mapbox.navigation.ui.voice.internal.impl.MapboxAudioGuidanceImpl
+import com.mapbox.navigation.ui.voice.api.MapboxAudioGuidance
 import java.util.concurrent.atomic.AtomicBoolean
 
 @OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
@@ -56,7 +55,6 @@ object SharedApp {
     @JvmOverloads
     fun setup(
         context: Context,
-        audioGuidance: MapboxAudioGuidance? = null,
         routeAlternativeContract: RouteAlternativeContract? = null
     ) {
         if (isSetup) return
@@ -69,7 +67,9 @@ object SharedApp {
             }
         )
         MapboxNavigationApp.lifecycleOwner.attachCreated(*navigationObservers)
-        MapboxNavigationApp.registerObserver(audioGuidance ?: defaultAudioGuidance(context))
+        if (MapboxNavigationApp.getObservers(MapboxAudioGuidance::class).isEmpty()) {
+            MapboxNavigationApp.registerObserver(MapboxAudioGuidance())
+        }
     }
 
     fun tripSessionTransaction(updateSession: () -> Unit) {
@@ -80,12 +80,4 @@ object SharedApp {
         updateSession()
         ignoreTripSessionUpdates.set(false)
     }
-
-    private fun defaultAudioGuidance(context: Context): MapboxAudioGuidance {
-        return MapboxAudioGuidanceImpl.create(context).also {
-            it.dataStoreOwner = NavigationDataStoreOwner(context, DEFAULT_DATA_STORE_NAME)
-        }
-    }
-
-    private const val DEFAULT_DATA_STORE_NAME = "mapbox_navigation_preferences"
 }

libnavui-app/src/main/java/com/mapbox/navigation/ui/app/internal/controller/AudioGuidanceStateController.kt

@@ -8,7 +8,7 @@ import com.mapbox.navigation.ui.app.internal.State
 import com.mapbox.navigation.ui.app.internal.Store
 import com.mapbox.navigation.ui.app.internal.audioguidance.AudioAction
 import com.mapbox.navigation.ui.app.internal.audioguidance.AudioGuidanceState
-import com.mapbox.navigation.ui.voice.internal.MapboxAudioGuidance
+import com.mapbox.navigation.ui.voice.api.MapboxAudioGuidance
 
 /**
  * This class is responsible for playing voice instructions. Use the [AudioAction] to turning the

libnavui-voice/api/current.txt

@@ -21,6 +21,27 @@ package com.mapbox.navigation.ui.voice.api {
     method public operator void invoke(boolean result);
   }
 
+  public final class MapboxAudioGuidance implements com.mapbox.navigation.core.lifecycle.MapboxNavigationObserver {
+    ctor public MapboxAudioGuidance();
+    method public void mute();
+    method public void onAttached(com.mapbox.navigation.core.MapboxNavigation mapboxNavigation);
+    method public void onDetached(com.mapbox.navigation.core.MapboxNavigation mapboxNavigation);
+    method public kotlinx.coroutines.flow.StateFlow<com.mapbox.navigation.ui.voice.api.MapboxAudioGuidanceState> stateFlow();
+    method public void toggle();
+    method public void unmute();
+  }
+
+  public final class MapboxAudioGuidanceState {
+    method public com.mapbox.navigation.ui.voice.model.SpeechAnnouncement? getSpeechAnnouncement();
+    method public com.mapbox.api.directions.v5.models.VoiceInstructions? getVoiceInstructions();
+    method public boolean isMuted();
+    method public boolean isPlayable();
+    property public final boolean isMuted;
+    property public final boolean isPlayable;
+    property public final com.mapbox.navigation.ui.voice.model.SpeechAnnouncement? speechAnnouncement;
+    property public final com.mapbox.api.directions.v5.models.VoiceInstructions? voiceInstructions;
+  }
+
   public final class MapboxSpeechApi {
     ctor public MapboxSpeechApi(android.content.Context context, String accessToken, String language, com.mapbox.navigation.ui.voice.options.MapboxSpeechApiOptions options = MapboxSpeechApiOptions.<init>().build());
     ctor public MapboxSpeechApi(android.content.Context context, String accessToken, String language);

…internal/impl/MapboxAudioGuidanceImpl.kt …tion/ui/voice/api/MapboxAudioGuidance.ktlibnavui-voice/src/main/java/com/mapbox/navigation/ui/voice/internal/impl/MapboxAudioGuidanceImpl.kt renamed to libnavui-voice/src/main/java/com/mapbox/navigation/ui/voice/api/MapboxAudioGuidance.kt libnavui-voice/src/main/java/com/mapbox/navigation/ui/voice/internal/impl/MapboxAudioGuidanceImpl.kt renamed to libnavui-voice/src/main/java/com/mapbox/navigation/ui/voice/api/MapboxAudioGuidance.kt

@@ -1,16 +1,14 @@
-package com.mapbox.navigation.ui.voice.internal.impl
+package com.mapbox.navigation.ui.voice.api
 
-import android.content.Context
-import com.mapbox.api.directions.v5.models.VoiceInstructions
-import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
+import androidx.annotation.VisibleForTesting
 import com.mapbox.navigation.core.MapboxNavigation
+import com.mapbox.navigation.core.lifecycle.MapboxNavigationApp
+import com.mapbox.navigation.core.lifecycle.MapboxNavigationObserver
 import com.mapbox.navigation.ui.utils.internal.configuration.NavigationConfigOwner
 import com.mapbox.navigation.ui.utils.internal.datastore.NavigationDataStoreOwner
 import com.mapbox.navigation.ui.utils.internal.datastore.booleanDataStoreKey
-import com.mapbox.navigation.ui.voice.internal.MapboxAudioGuidance
-import com.mapbox.navigation.ui.voice.internal.MapboxAudioGuidanceServices
 import com.mapbox.navigation.ui.voice.internal.MapboxAudioGuidanceVoice
-import com.mapbox.navigation.ui.voice.model.SpeechAnnouncement
+import com.mapbox.navigation.ui.voice.internal.impl.MapboxAudioGuidanceServices
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
@@ -35,30 +33,41 @@ import kotlinx.coroutines.launch
 /**
  * Implementation of [MapboxAudioGuidance]. See interface for details.
  */
-@ExperimentalPreviewMapboxNavigationAPI
-class MapboxAudioGuidanceImpl(
+class MapboxAudioGuidance
+@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
+internal constructor(
     private val audioGuidanceServices: MapboxAudioGuidanceServices,
-    private val configOwner: NavigationConfigOwner,
-    dispatcher: CoroutineDispatcher = Dispatchers.Main,
-) : MapboxAudioGuidance {
+    dispatcher: CoroutineDispatcher,
+) : MapboxNavigationObserver {
 
-    var dataStoreOwner: NavigationDataStoreOwner? = null
+    constructor() : this(MapboxAudioGuidanceServices(), Dispatchers.Main)
 
+    private var dataStoreOwner: NavigationDataStoreOwner? = null
+    private var configOwner: NavigationConfigOwner? = null
     private var mutedStateFlow = MutableStateFlow(false)
     private val internalStateFlow = MutableStateFlow(MapboxAudioGuidanceState())
     private val scope = CoroutineScope(SupervisorJob() + dispatcher)
     private val mapboxVoiceInstructions = audioGuidanceServices.mapboxVoiceInstructions()
 
     private var job: Job? = null
 
+    /**
+     * @see [MapboxNavigationApp]
+     */
     override fun onAttached(mapboxNavigation: MapboxNavigation) {
+        val context = mapboxNavigation.navigationOptions.applicationContext
+        dataStoreOwner = audioGuidanceServices.dataStoreOwner(context, DEFAULT_DATA_STORE_NAME)
+        configOwner = audioGuidanceServices.configOwner(context)
         mapboxVoiceInstructions.registerObservers(mapboxNavigation)
         job = scope.launch {
             restoreMutedState()
             audioGuidanceFlow(mapboxNavigation).collect()
         }
     }
 
+    /**
+     * @see [MapboxNavigationApp]
+     */
     override fun onDetached(mapboxNavigation: MapboxNavigation) {
         mapboxVoiceInstructions.unregisterObservers(mapboxNavigation)
         job?.cancel()
@@ -73,12 +82,12 @@ class MapboxAudioGuidanceImpl(
      *
      * You can also control audio guidance by calling [mute], [unmute] or [toggle]
      */
-    override fun stateFlow(): StateFlow<MapboxAudioGuidance.State> = internalStateFlow
+    fun stateFlow(): StateFlow<MapboxAudioGuidanceState> = internalStateFlow
 
     /**
      * Explicit call to mute the audio guidance state.
      */
-    override fun mute() {
+    fun mute() {
         scope.launch {
             setMutedState(true)
         }
@@ -87,7 +96,7 @@ class MapboxAudioGuidanceImpl(
     /**
      * Explicit call to unmute the audio guidance state.
      */
-    override fun unmute() {
+    fun unmute() {
         scope.launch {
             setMutedState(false)
         }
@@ -96,7 +105,7 @@ class MapboxAudioGuidanceImpl(
     /**
      * Toggle the muted state. E.g., if audio is muted, make it unmuted.
      */
-    override fun toggle() {
+    fun toggle() {
         scope.launch {
             if (mutedStateFlow.value) {
                 unmute()
@@ -112,10 +121,10 @@ class MapboxAudioGuidanceImpl(
     @OptIn(ExperimentalCoroutinesApi::class)
     private fun audioGuidanceFlow(
         mapboxNavigation: MapboxNavigation
-    ): Flow<MapboxAudioGuidance.State> {
+    ): Flow<MapboxAudioGuidanceState> {
         return combine(
             mapboxVoiceInstructions.voiceLanguage(),
-            configOwner.language(),
+            configOwner!!.language(),
         ) { voiceLanguage, deviceLanguage -> voiceLanguage ?: deviceLanguage }
             .distinctUntilChanged()
             .flatMapLatest { language ->
@@ -134,7 +143,7 @@ class MapboxAudioGuidanceImpl(
     /**
      * This flow will monitor navigation state to determine if audio is available.
      */
-    private fun silentFlow(): Flow<MapboxAudioGuidance.State> {
+    private fun silentFlow(): Flow<MapboxAudioGuidanceState> {
         return mapboxVoiceInstructions.voiceInstructions()
             .map { state ->
                 internalStateFlow.updateAndGet {
@@ -153,7 +162,7 @@ class MapboxAudioGuidanceImpl(
     @OptIn(FlowPreview::class)
     private fun speechFlow(
         audioGuidance: MapboxAudioGuidanceVoice
-    ): Flow<MapboxAudioGuidance.State> {
+    ): Flow<MapboxAudioGuidanceState> {
         return mapboxVoiceInstructions.voiceInstructions()
             .flatMapConcat { voice ->
                 internalStateFlow.update {
@@ -166,7 +175,14 @@ class MapboxAudioGuidanceImpl(
                 audioGuidance.speak(voice.voiceInstructions)
             }
             .map { speechAnnouncement ->
-                internalStateFlow.updateAndGet { it.copy(speechAnnouncement = speechAnnouncement) }
+                internalStateFlow.updateAndGet {
+                    MapboxAudioGuidanceState(
+                        isPlayable = it.isPlayable,
+                        isMuted = it.isMuted,
+                        voiceInstructions = it.voiceInstructions,
+                        speechAnnouncement = speechAnnouncement
+                    )
+                }
             }
     }
 
@@ -181,22 +197,9 @@ class MapboxAudioGuidanceImpl(
         dataStoreOwner?.write(STORE_AUDIO_GUIDANCE_MUTED, muted)
     }
 
-    companion object {
-        val STORE_AUDIO_GUIDANCE_MUTED =
+    private companion object {
+        private val STORE_AUDIO_GUIDANCE_MUTED =
             booleanDataStoreKey("audio_guidance_muted", false)
-
-        fun create(context: Context): MapboxAudioGuidanceImpl {
-            return MapboxAudioGuidanceImpl(
-                MapboxAudioGuidanceServicesImpl(),
-                NavigationConfigOwner(context)
-            )
-        }
+        private const val DEFAULT_DATA_STORE_NAME = "mapbox_navigation_preferences"
     }
 }
-
-private data class MapboxAudioGuidanceState(
-    override val isPlayable: Boolean = false,
-    override val isMuted: Boolean = false,
-    override val voiceInstructions: VoiceInstructions? = null,
-    override val speechAnnouncement: SpeechAnnouncement? = null,
-) : MapboxAudioGuidance.State

libnavui-voice/src/main/java/com/mapbox/navigation/ui/voice/api/MapboxAudioGuidanceState.kt

@@ -0,0 +1,74 @@
+package com.mapbox.navigation.ui.voice.api
+
+import com.mapbox.api.directions.v5.models.VoiceInstructions
+import com.mapbox.navigation.ui.voice.model.SpeechAnnouncement
+
+/**
+ * Represents the state of [MapboxAudioGuidance].
+ */
+class MapboxAudioGuidanceState internal constructor(
+    /**
+     * When the trip session has started, and there is an active route.
+     */
+    val isPlayable: Boolean = false,
+
+    /**
+     * Controlled by the [MapboxAudioGuidance] service. When [MapboxAudioGuidance.mute] is called
+     * this will be changed to true.
+     */
+    val isMuted: Boolean = false,
+
+    /**
+     * Once a voice instruction becomes available this will not be null.
+     * When the state [isPlayable] and this is null, it means there are no voice instructions
+     * on the route at this time.
+     */
+    val voiceInstructions: VoiceInstructions? = null,
+
+    /**
+     * After a [voiceInstructions] has been announced, this value will be emitted.
+     * This will always be null when [isMuted] is true.
+     */
+    val speechAnnouncement: SpeechAnnouncement? = null,
+) {
+
+    /**
+     * Regenerate whenever a change is made
+     */
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (javaClass != other?.javaClass) return false
+
+        other as MapboxAudioGuidanceState
+
+        if (isPlayable != other.isPlayable) return false
+        if (isMuted != other.isMuted) return false
+        if (voiceInstructions != other.voiceInstructions) return false
+        if (speechAnnouncement != other.speechAnnouncement) return false
+
+        return true
+    }
+
+    /**
+     * Regenerate whenever a change is made
+     */
+    override fun hashCode(): Int {
+        var result = isPlayable.hashCode()
+        result = 31 * result + isMuted.hashCode()
+        result = 31 * result + (voiceInstructions?.hashCode() ?: 0)
+        result = 31 * result + (speechAnnouncement?.hashCode() ?: 0)
+        return result
+    }
+
+    /**
+     * Regenerate whenever a change is made
+     */
+    override fun toString(): String {
+        return "MapboxAudioGuidanceState(" +
+            "isPlayable=$isPlayable, " +
+            "isMuted=$isMuted, " +
+            "voiceInstructions=$voiceInstructions, " +
+            "speechAnnouncement=$speechAnnouncement" +
+            ")"
+    }
+}