diff --git a/Voiceover-Tutorial.md b/Voiceover-Tutorial.md new file mode 100644 index 00000000..c121fca7 --- /dev/null +++ b/Voiceover-Tutorial.md @@ -0,0 +1,96 @@ +## 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 **(Email: web-server-admins@oppia.org)**. +- Admins must enable voiceover regeneration functionality via the **Admin Misc** tab. Reach out to the admin to verify. **(Email: sean@seanlip.org)** +- The desired **language-accent pair** must be supported by Oppia. Confirm with the voiceover admins. **(Email: voiceovers-leads@oppia.org)** + +### 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 after the above steps** + +4. Set **Supports Autogeneration** to "Yes" **only if**: + - The language-accent is supported by Azure Text-to-Speech service. + - You are aware that this will incur costs. + +> ⚠️ 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.

- Visit the Azure portal and verify that the API keys are not expired.
- 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.

- Upgrade the subscription from the free plan to a standard plan to increase the quota. | +| **RuntimeError** | Indicates an unexpected runtime error.

- Check the error message and search online for common solutions.
- If no specific action is needed, try regenerating the voiceovers after 10–15 minutes.
- Take appropriate actions based on the error message.
- 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.

- Check the error message and look for solutions online.
- Verify that the language-accent code used for speech synthesis is still supported by Azure TTS. (See reference [here](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=stt)).
- If no action is needed, retry after 10–15 minutes.
- Take appropriate actions based on the error message.
- If the issue continues, contact Azure Support or raise a question with the Azure team. | +| **ServiceUnavailable** | Indicates that the Speech service is currently unavailable.

- 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 (voiceovers-leads@oppia.org), 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.| Contact admin (sean@seanlip.org), for enabling Cloud based text-to-speech service from Admin tab.| +|**Adding / regenerating voiceovers buttons are disabled:** There is no content available for voiceover in the selected language.| Add translations for the given content either from contributor dashboard or from translation tab of the exploration editor page itself.| + + +## Getting Help + +If you encounter issues or need assistance with voiceovers, please contact: + +📧 **voiceover-tech-support@oppia.org**