feat: enable troubleshooting dialog box for user guidance

Added a dialog box to provide users with troubleshooting guidance during critical operations.
This dialog appears when the user encounters common errors and offers solutions or next steps.

Key changes include:
- Integrated the new troubleshooting dialog into the main user interface.
- Implemented logic to trigger the dialog based on specific error codes.
- Updated the UI to support the dialog's appearance and behavior.
- Refined error-handling flow to ensure that appropriate guidance is displayed.

This feature aims to improve user experience by helping users resolve issues without leaving the app.

AnkiDroid/src/main/java/com/ichi2/anki/TtsVoices.kt

@@ -58,6 +58,17 @@ object TtsVoices {
     /** A job which populates [availableLocaleData] */
     private var buildLocalesJob: Job? = null
 
+    /**
+     * The package name of the default speech synthesis engine.
+     *
+     * @return Package name of the Tts engine that the user has chosen as their default.
+     * 'null' if the system has no engine or if an error occurs
+     *
+     * @see TextToSpeech.getDefaultEngine
+     */
+    var ttsEngine: String? = null
+        private set
+
     /**
      * Returns the list of available locales for use in TTS
      *
@@ -188,6 +199,7 @@ object TtsVoices {
             textToSpeech = TextToSpeech(context) { status ->
                 if (status == TextToSpeech.SUCCESS) {
                     Timber.v("TTS creation success")
+                    ttsEngine = textToSpeech?.defaultEngine
                     continuation.resume(textToSpeech)
                 } else {
                     Timber.e("TTS creation failed. status: %d", status)

AnkiDroid/src/main/java/com/ichi2/anki/cardviewer/CardMediaPlayer.kt

@@ -28,10 +28,12 @@ import com.ichi2.anki.AndroidTtsPlayer
 import com.ichi2.anki.AnkiDroidApp
 import com.ichi2.anki.CollectionHelper.getMediaDirectory
 import com.ichi2.anki.CollectionManager.withCol
+import com.ichi2.anki.R
 import com.ichi2.anki.ReadText
 import com.ichi2.anki.cardviewer.SoundErrorBehavior.CONTINUE_AUDIO
 import com.ichi2.anki.cardviewer.SoundErrorBehavior.RETRY_AUDIO
 import com.ichi2.anki.cardviewer.SoundErrorBehavior.STOP_AUDIO
+import com.ichi2.anki.dialogs.TtsPlaybackErrorDialog
 import com.ichi2.anki.localizedErrorMessage
 import com.ichi2.anki.reviewer.CardSide
 import com.ichi2.anki.snackbar.showSnackbar
@@ -429,7 +431,13 @@ fun AbstractFlashcardViewer.createSoundErrorListener(): SoundErrorListener {
 
         override fun onTtsError(error: TtsPlayer.TtsError, isAutomaticPlayback: Boolean) {
             AbstractFlashcardViewer.mediaErrorHandler.processTtsFailure(error, isAutomaticPlayback) {
-                activity.showSnackbar(error.localizedErrorMessage(activity))
+                when (error) {
+                    is AndroidTtsError.MissingVoiceError ->
+                        TtsPlaybackErrorDialog.ttsPlaybackErrorDialog(activity, supportFragmentManager, error.tag)
+                    is AndroidTtsError.InvalidVoiceError ->
+                        activity.showSnackbar(getString(R.string.voice_not_supported))
+                    else -> activity.showSnackbar(error.localizedErrorMessage(activity))
+                }
             }
         }
 

AnkiDroid/src/main/java/com/ichi2/anki/dialogs/TtsPlaybackErrorDialog.kt

@@ -0,0 +1,63 @@
+/*
+ *  Copyright (c) 2024 RohanRaj123 <rajrohan88293@gmail.com>
+ *
+ *  This program is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU General Public License as published by the Free Software
+ *  Foundation; either version 3 of the License, or (at your option) any later
+ *  version.
+ *
+ *  This program is distributed in the hope that it will be useful, but WITHOUT ANY
+ *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *  PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License along with
+ *  this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.ichi2.anki.dialogs
+
+import android.app.Activity
+import android.content.Intent
+import android.net.Uri
+import androidx.appcompat.app.AlertDialog
+import androidx.fragment.app.FragmentManager
+import com.ichi2.anki.CrashReportService
+import com.ichi2.anki.R
+import com.ichi2.anki.TtsVoices
+import com.ichi2.anki.utils.openUrl
+import com.ichi2.libanki.TTSTag
+import com.ichi2.utils.show
+import timber.log.Timber
+
+object TtsPlaybackErrorDialog {
+
+    fun ttsPlaybackErrorDialog(activity: Activity, fragmentManager: FragmentManager, ttsTag: TTSTag?) {
+        Timber.i("Dialog is shown to guide users correctly to troubleshoot the Tts error: Missing voice error")
+        activity.runOnUiThread {
+            AlertDialog.Builder(activity).show {
+                setTitle(activity.getString(R.string.tts_error_dialog_title))
+                setMessage(activity.getString(R.string.tts_error_dialog_reason_text, TtsVoices.ttsEngine, ttsTag?.lang))
+                setNegativeButton(context.getString(R.string.tts_error_dialog_change_button_text)) { _, _ -> openSettings(activity) }
+                setPositiveButton(activity.getString(R.string.tts_error_dialog_supported_voices_button_text)) { _, _ -> showVoicesDialog(fragmentManager) }
+                setNeutralButton(context.getString(R.string.help)) { _, _ ->
+                    activity.openUrl(Uri.parse(context.getString(R.string.link_faq_tts)))
+                }
+            }
+        }
+    }
+
+    private fun openSettings(activity: Activity) {
+        try {
+            Timber.i("Opening TextToSpeech engine settings to change the engine")
+            activity.startActivity(
+                Intent("com.android.settings.TTS_SETTINGS").apply { flags = Intent.FLAG_ACTIVITY_NEW_TASK }
+            )
+        } catch (e: Exception) {
+            CrashReportService.sendExceptionReport(e, e.localizedMessage)
+        }
+    }
+
+    private fun showVoicesDialog(fragmentManager: FragmentManager) {
+        TtsVoicesDialogFragment().show(fragmentManager, "TTS_VOICES_DIALOG_FRAGMENT")
+    }
+}

AnkiDroid/src/main/res/values/02-strings.xml

@@ -402,4 +402,6 @@ opening the system text to speech settings fails">
     <string name="orphan_note_title">Cannot Delete Card Type</string>
     <string name="orphan_note_message">Deleting this card type will leave some notes without any cards.</string>
 
+    <string name="voice_not_supported">Voice not supported. Try another or install a voice engine.</string>
+
 </resources>

AnkiDroid/src/main/res/values/03-dialogs.xml

@@ -282,4 +282,11 @@ also changes the interval of the card"
 
     <!-- Outdated WebView dialog -->
     <string name="webview_update_message">The system WebView is outdated. Some features won’t work correctly. Please update it.\n\nInstalled version: %1$d\nMinimum required version: %2$d</string>
+
+    <!-- Tts playback error dialog -->
+    <string name="tts_error_dialog_title">Language not supported</string>
+    <string name="tts_error_dialog_reason_text">The text to speech engine <b>%1$s</b> does not support the following language: <b>%2$s</b></string>
+    <string name="tts_error_dialog_change_button_text">Change engine</string>
+    <string name="tts_error_dialog_supported_voices_button_text">Voice options</string>
+
 </resources>