Voiceover tutorial for voice artists

Voiceover-Tutorial.md

@@ -0,0 +1,102 @@
+## Contents
+- [Voiceovers in Oppia](#voiceovers-in-oppia)
+- [How to Add Manual Voiceovers to Oppia Lessons](#how-to-add-manual-voiceovers-to-oppia-lessons)
+- [How to Regenerate Automatic Voiceovers](#how-to-regenerate-automatic-voiceovers)
+- [Precedence Between Automatic and Manual Voiceovers](#precedence-between-automatic-and-manual-voiceovers)
+- [Adding a New Language-Accent Pair to Oppia's Voiceover Support](#adding-a-new-language-accent-pair-to-oppias-voiceover-support)
+- [Technical Cheat Sheet – Troubleshooting Voiceover Regeneration](#technical-cheat-sheet--troubleshooting-voiceover-regeneration)
+- [Getting Help](#getting-help)
+
+
+## Voiceovers in Oppia
+
+Oppia's lessons include voiceovers to support auditory learning. We’ve introduced **accent-specific** voiceovers, enabling students to hear lessons in accents familiar to them (e.g., English - United States or English - Nigeria).
+
+
+## How to Add Manual Voiceovers to Oppia Lessons
+
+Follow these steps to add a manual voiceover:
+
+1. Navigate to the **Translation** tab in the Exploration Editor. The exploration must be **curated** (i.e., linked to a published story)
+2. Select the desired **language and accent**.
+   > **Note:** For non-English languages, ensure that the translation for that language exists. You cannot add a voiceover unless the translation is available.
+3. Upload your manual voiceover in the selected language-accent pair.
+4. And then save the draft changes.
+
+
+## How to Regenerate Automatic Voiceovers
+
+Automatic voiceover generation is currently in its early phase, and requires certain conditions to be met:
+
+### Pre-requisites
+
+- The exploration must be **curated** (i.e., linked to a published story).
+- Ensure the feature flags `"automatic_voiceover_regeneration_from_exp"` and `"show_regenerated_voiceovers_to_learners"` are enabled in the **Release Coordinator** page. Contact the release team for confirmation **(TODO: add Email)**.
+- Admins must enable voiceover regeneration functionality via the **Admin Misc** tab. Reach out to the admin team to verify. **(TODO: add email)**
+- The desired **language-accent pair** must be supported by Oppia. Confirm with the voiceover admins. **(TODO: add email)**
+
+### Steps
+
+1. Go to the **Translation** tab in the Exploration Editor.
+2. Select the **language and accent**.
+3. Click **Regenerate Voiceovers** for the selected language-accent.
+
+## Precedence Between Automatic and Manual Voiceovers
+
+When both manual and automatic voiceovers exist for the same content:
+
+- **Manual voiceovers take precedence**.
+- If a manual voiceover is marked as **stale**, the system will use the automatic voiceover instead.
+- If only one type of voiceover is present (manual or automatic), that one will be used.
+
+## Adding a New Language-Accent Pair to Oppia's Voiceover Support
+
+Oppia supports only selected **language-accent pairs** for voiceovers. To onboard a new pair, follow these steps:
+
+### Pre-requisites
+
+1. Update the fields `LANGUAGE_CODE_TO_MATH_SYMBOL_PRONUNCIATIONS` & `LANGUAGE_CODE_TO_SENTENCE_ENDING_PUNCTUATION_MARKS` in the file **[constants.ts](https://github.com/oppia/oppia/blob/develop/assets/constants.ts)** via a pull request.
+
+>  **Note:** If you're adding a new **accent** to a language already supported (e.g., adding "English (India)" when "English (United States)" is already supported), you don't need to update the above mentioned fields.
+
+
+### Steps
+
+1. Visit the **Voiceover Admin Page** (`/voiceover-admin`).
+2. Locate the card titled **“Update language/accent pairs that learners and voice artists can select.”**
+3. Click **“+ Add new language accent support”**, then select the new language-accent.
+
+### Optional: Enable Automatic Voiceover Support
+
+- Set **Supports Autogeneration** to "Yes" **only if**:
+  - The language-accent is supported by Azure Text-to-Speech.
+  - You are aware that this will incur costs.
+
+Once enabled:
+
+- All curated explorations in that language-accent will support autogenerated voiceovers.
+- Voiceovers will be generated for both **new content updates** and **manual regeneration** actions (in the voiceover tab of the exploration editor).
+
+> ⚠️ Language-accents like **Hinglish** and **Nigerian Pidgin** do not support autogeneration due to Azure limitations, and you will not be able to enable the autogeneration flag for them.
+
+
+## Technical Cheat Sheet – Troubleshooting Voiceover Regeneration
+
+| **Error Type**         | **Steps to Fix** |
+|------------------------|------------------|
+| **AuthenticationFailure** | Indicates an authentication error. This occurs if the subscription key or authorization token is invalid, expired, or does not match the region.<br><br>- Visit the Azure portal and verify that the API keys are not expired.<br>- Ensure the API key and region match the values in cloud secrets and the `feconf` file. |
+| **Forbidden** | Indicates that the free subscription used by the request has run out of quota.<br><br>- Upgrade the subscription from the free plan to a standard plan to increase the quota. |
+| **RuntimeError** | Indicates an unexpected runtime error.<br><br>- Check the error message and search online for common solutions.<br>- If no specific action is needed, try regenerating the voiceovers after 10–15 minutes.<br>- Take appropriate actions based on the error message.<br>- If the error persists after retrying, contact Azure Support or raise a question with the Azure team. |
+| **ServiceError** | Indicates an error returned by the Speech service.<br><br> - Check the error message and look for solutions online.<br>- Verify that the language-accent code used for speech synthesis is still supported by Azure TTS. (See reference [here]).<br>- If no action is needed, retry after 10–15 minutes.<br>- Take appropriate actions based on the error message.<br>- If the issue continues, contact Azure Support or raise a question with the Azure team. |
+| **ServiceUnavailable** | Indicates that the Speech service is currently unavailable.<br><br>- Retry after 10–15 minutes. |
+| **Autogeneration button disabled:**  Autogenerated voiceovers are not supported for the selected language accent. Please reach out to the voiceover admin if you would like them to be supported.| Reach out to voiceover admins, they will either add the language accents to Oppia's voiceovers support or give you the rationale why this language accent can't be added.|
+| **Autogeneration button disabled:** Voiceover autogeneration via cloud services is currently disabled. Please contact the admins for more information.| Follow pre-requisite sub-sections in 'How to Regenerate Automatic Voiceovers' section above.|
+|**Adding / regenerating voiceovers buttons are disabled:** There is no content available for voiceover in the selected language.| Add trnaslations for the given content either from contributor dashboard or from translation tab of the exploration editor itself.|
+
+
+
+## Getting Help
+
+If you encounter issues or need assistance with voiceovers, please contact:
+
+📧 **[email protected]**