add docs to say that MapboxVoiceInstructionsPlayer should be initialized in onCreate

Author: dzinad

examples/src/main/java/com/mapbox/navigation/examples/core/MapboxVoiceActivity.kt

@@ -103,17 +103,13 @@ class MapboxVoiceActivity : AppCompatActivity(), OnMapLongClickListener {
     /**
      * The [MapboxVoiceInstructionsPlayer] consumes the voice instructions data
      * and plays them using the appropriate TTS player.
+     * NOTE: do not use lazy initialization for this class since it takes some time to initialize
+     * the system services required for on-device speech synthesis. With lazy initialization
+     * there is a high risk that said services will not be available when the first instruction
+     * has to be played. [MapboxVoiceInstructionsPlayer] should be instantiated in
+     * `Activity#onCreate`.
      */
-    private val voiceInstructionsPlayer: MapboxVoiceInstructionsPlayer by lazy {
-        val options = VoiceInstructionsPlayerOptions.Builder()
-            .abandonFocusDelay(PLAYER_ABANDON_FOCUS_DELAY)
-            .build()
-        MapboxVoiceInstructionsPlayer(
-            this,
-            Locale.US.toLanguageTag(),
-            options
-        )
-    }
+    private lateinit var voiceInstructionsPlayer: MapboxVoiceInstructionsPlayer
 
     private val routeLineResources: RouteLineResources by lazy {
         RouteLineResources.Builder().build()
@@ -378,6 +374,13 @@ class MapboxVoiceActivity : AppCompatActivity(), OnMapLongClickListener {
             setLocationProvider(navigationLocationProvider)
             enabled = true
         }
+        voiceInstructionsPlayer = MapboxVoiceInstructionsPlayer(
+            this,
+            Locale.US.toLanguageTag(),
+            VoiceInstructionsPlayerOptions.Builder()
+                .abandonFocusDelay(PLAYER_ABANDON_FOCUS_DELAY)
+                .build()
+        )
         init()
     }
 

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

@@ -18,6 +18,12 @@ import kotlin.concurrent.schedule
 /**
  * Hybrid implementation of [MapboxVoiceInstructionsPlayer] combining [VoiceInstructionsTextPlayer] and
  * [VoiceInstructionsFilePlayer] speech players.
+ * NOTE: do not use lazy initialization for this class since it takes some time to initialize
+ * the system services required for on-device speech synthesis. With lazy initialization
+ * there is a high risk that said services will not be available when the first instruction
+ * has to be played. [MapboxVoiceInstructionsPlayer] should be instantiated in
+ * `Activity#onCreate`.
+ *
  * @param context Context
  * @param language [Locale] language (in a format acceptable by [Locale])
  * @param options [VoiceInstructionsPlayerOptions] (optional)