Merge pull request #280786 from garchiro7/closed-captions-ui-native

Add closed captions support into UI library

Author: PMEds28

articles/communication-services/concepts/ui-library/includes/mobile-ui-closed-captions.png

@@ -22,6 +22,8 @@ You can use the call composite in Communication Services to create these use cas
 | [Teams interoperability](../../teams-interop.md)                     | Join the call lobby                                             |
 |                                                                                                 | Display a transcription and recording alert banner               |
 |                                                                                                 | Admit/Reject lobby participants                                 |
+| Closed Captions                                                                                 | Teams interoperability                                      |
+|                                                                                                 | Group call, Rooms call, and 1:1 call                                       |
 | Participant gallery                                                                   | Show remote participants on a grid              |
 |                                                                                                 | Make video preview available throughout a call for a local user |
 |                                                                                                 | Make default avatars available when video is off            |
@@ -69,6 +71,17 @@ The distinction between each role lies in the capabilities they possess during a
 > [!NOTE]
 > The Rooms API serves the purpose of creating rooms, managing users, and adjusting the lifetime of rooms. It is important to note that the Rooms API is a back-end service that is separate from the UI Library.
 
+### Closed captions
+
+Closed captions enable a wide range of scenarios, including interoperability with Teams, Azure Communication Services Group calls, Rooms calls, and one-on-one calls. This feature ensures that users can follow along with conversations in various calling environments, **enhancing accessibility** and user experience. However, it's important to note that users need to manually select the language for captions using the UI Library out of the box, as the system doesn't automatically detect the spoken language.
+
+:::image type="content" source="mobile-ui-closed-captions.png" alt-text="Screenshot that shows the experience of closed captions integration in the UI Library.":::
+
+> [!NOTE]
+>Closed Captions will not be billed at the beginning of its Public Preview. This is for a limited time only, usage of Captions will likely be billed starting from June.
+
+If you're looking more detailed information about closed captions, feel free to visit [the documentation](../../voice-video-calling/closed-captions.md) to review explanations and usage guidelines. Additionally, if you want to jump directly into the configuration of closed captions directly within the UI Library, you can follow our [tutorial](../../../how-tos/ui-library-sdk/closed-captions.md) for easy setup.
+
 ### View shared content
 
 Through the UI Library for mobile native platforms, call participants can view shared content when other participants share their screens during a Teams call. A remote participant can use stretch and pinch gestures to zoom in or out on the shared content in the call.

articles/communication-services/concepts/ui-library/includes/mobile-ui-use-cases.md

@@ -46,3 +46,4 @@ Microsoft indicates to you via the Azure Communication Services API that recordi
 
 - Get started with a [Closed Captions Quickstart](../../quickstarts/voice-video-calling/get-started-with-closed-captions.md)
 - Learn more about using closed captions in [Teams interop](../interop/enable-closed-captions.md) scenarios.
+- Learn more about the [UI Library](../ui-library/ui-library-overview.md).

articles/communication-services/concepts/voice-video-calling/closed-captions.md

@@ -43,3 +43,4 @@ For more information, see the following articles:
 - Learn about [Voice](./manage-calls.md) and [Video calling](./manage-video.md).
 - Learn about [Teams interoperability](./teams-interoperability.md).
 - Learn more about Microsoft Teams [live translated captions](https://support.microsoft.com//office/use-live-captions-in-a-teams-meeting-4be2d304-f675-4b57-8347-cbd000a21260).
+- Learn more about the [UI Library](../../concepts//ui-library/ui-library-overview.md).

articles/communication-services/how-tos/calling-sdk/closed-captions-teams-interop-how-to.md

@@ -0,0 +1,112 @@
+---
+title: Enable scenarios using closed captions and the UI Library
+titleSuffix: An Azure Communication Services how-to guide
+description: Enable scenarios using closed captions and Azure Communication Services UI Library.
+author: garchiro7
+ms.author: jorgegarc
+ms.service: azure-communication-services
+ms.subservice: calling
+ms.topic: how-to 
+ms.date: 07/01/2024
+ms.custom: references_regions
+zone_pivot_groups: acs-plat-ios-android
+
+#Customer intent: As a developer, I want setup closed captions into a call using the UI Library.
+---
+
+# Closed captions
+
+Closed captions play a critical role in video voice calling apps, providing numerous benefits that enhance the accessibility, usability, and overall user experience of these platforms.
+
+In this article, you learn how to enable closed captions scenarios using the UI Library. There's two main scenarios to enable closed captions: Azure Communication Services video and voice calls and Interop calls.
+
+## Azure Communication Service based captions
+
+Supported for calls involving Azure Communication Service users only. Currently, Azure Communication Service captions **do not support language translation**.
+
+## Teams Interop closed captions
+
+Supported during calls with one or more Teams users.
+
+### Translation support
+
+Unlike Azure Communication Service closed captions, Teams Interop closed captions support translation. Users can opt to have closed captions translated into a different language through the captions settings.
+
+## How to use captions
+
+Captions are seamlessly integrated within the `CallingUILibrary`.
+
+1. **Activate captions**:
+   - During a connected call, navigate to the control bar and click the **more button**.
+   - In the menu pop-up, toggle to turn on captions.
+
+2. **Adjust spoken language**:
+   - If a different language is being used in the meeting, users can change the spoken language via the UI. This change applies to all users in the call.
+
+3. **Set caption language** (for Teams Interop Closed Captions):
+   - By default, live captions are displayed in the meeting or event spoken language. Live translated captions allow users to see captions translated into the language they’re most comfortable with.
+   - Change the caption language by clicking on the **Captions language** button after captions start, if translation to a different language is desired.
+
+:::image type="content" source="./includes/closed-captions/mobile-ui-closed-captions.png" alt-text="Screenshot that shows the experience of closed captions integration in the UI Library.":::
+
+> [!NOTE]
+> Live translated captions in meetings are only available as part of [**Teams Premium**](https://learn.microsoft.com/MicrosoftTeams/teams-add-on-licensing/licensing-enhance-teams#meetings), an add-on license that provides additional features to make Teams meetings more personalized, intelligent, and secure. To get access to Teams Premium, contact your IT admin. More details you can find it [here](../calling-sdk/closed-captions-teams-interop-how-to.md).
+
+## Supported languages
+
+Azure Communication Services supports various spoken languages for captions. The next table contains the list of supported language codes that you can use with the `setSpokenLanguage` method to set the desired language for captions.
+
+| Language              | ACS Spoken Code | Teams Spoken Code | Teams Captions Code |
+|-----------------------|-----------------|-------------------|--------------------|
+| Arabic                | ar-ae, ar-sa    | ar-ae, ar-sa      | ar                 |
+| Danish                | da-dk           | da-dk             | da                 |
+| German                | de-de           | de-de             | de                 |
+| English               | en-au, en-ca, en-gb, en-in, en-nz, en-us | en-au, en-ca, en-gb, en-in, en-nz, en-us | en            |
+| Spanish               | es-es, es-mx    | es-es, es-mx      | es                 |
+| Finnish               | fi-fi           | fi-fi             | fi                 |
+| French                | fr-ca, fr-fr    | fr-ca, fr-fr      | fr, fr-ca          |
+| Hindi                 | hi-in           | hi-in             | hi                 |
+| Italian               | it-it           | it-it             | it                 |
+| Japanese              | ja-jp           | ja-jp             | ja                 |
+| Korean                | ko-kr           | ko-kr             | ko                 |
+| Norwegian             | nb-no           | nb-no             | nb                 |
+| Dutch                 | nl-be, nl-nl    | nl-be, nl-nl      | nl                 |
+| Polish                | pl-pl           | pl-pl             | pl                 |
+| Portuguese            | pt-br           | pt-br, pt-pt      | pt, pt-pt          |
+| Russian               | ru-ru           | ru-ru             | ru                 |
+| Swedish               | sv-se           | sv-se             | sv                 |
+| Chinese               | zh-cn, zh-hk    | zh-cn, zh-hk      | zh-Hans, zh-Hant   |
+| Czech                 | —               | cs-cz             | cs                 |
+| Slovak                | —               | sk-sk             | sk                 |
+| Turkish               | —               | tr-tr             | tr                 |
+| Vietnamese            | —               | vi-vn             | vi                 |
+| Thai                  | —               | th-th             | th                 |
+| Hebrew                | —               | he-il             | he                 |
+| Welsh                 | —               | cy-gb             | cy                 |
+| Ukrainian             | —               | uk-ua             | uk                 |
+| Greek                 | —               | el-gr             | el                 |
+| Hungarian             | —               | hu-hu             | hu                 |
+| Romanian              | —               | ro-ro             | ro                 |
+
+Ensure the spoken language selected matches the language used in the call to accurately generate captions.
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+- A deployed Communication Services resource. [Create a Communication Services resource](../../quickstarts/create-communication-resource.md).
+- A user access token to enable the call client. [Get a user access token](../../quickstarts/access-tokens.md).
+- Optional: Completion of the [quickstart for getting started with the UI Library composites](../../quickstarts/ui-library/get-started-composites.md).
+
+## Set up the feature
+
+::: zone pivot="platform-android"
+[!INCLUDE [Enable closed captions in the Android UI Library](./includes/closed-captions/android.md)]
+::: zone-end
+
+::: zone pivot="platform-ios"
+[!INCLUDE [Enable closed captions in the iOS UI Library](./includes/closed-captions/ios.md)]
+::: zone-end
+
+## Next steps
+
+- [Learn more about the UI Library](../../concepts/ui-library/ui-library-overview.md)

articles/communication-services/how-tos/ui-library-sdk/closed-captions.md

@@ -0,0 +1,36 @@
+---
+description: description: Enable scenarios using closed captions and the UI Library in Android
+author: garchiro7
+
+ms.author: jorgegarc
+ms.date: 07/01/2024
+ms.topic: include
+ms.service: azure-communication-services
+---
+
+### Enable closed captions
+
+The method `setCaptionsOn` is configured to start captions by default.
+
+#### [Kotlin](#tab/kotlin)
+
+```kotlin
+val captionsOptions = CallCompositeCaptionsOptions()
+captionsOptions.setCaptionsOn(true)
+captionsOptions.setSpokenLanguage("en-US")
+
+val localOptions = CallCompositeLocalOptions()
+localOptions.setCaptionsOptions(captionsOptions)
+
+```
+
+#### [Java](#tab/java)
+
+```java
+CallCompositeCaptionsOptions captionsOptions = new CallCompositeCaptionsOptions();
+captionsOptions.setCaptionsOn(true);
+captionsOptions.setSpokenLanguage("en-us");
+
+CallCompositeLocalOptions localOptions = new CallCompositeLocalOptions();
+localOptions.setCaptionsOptions(captionsOptions);
+```

articles/communication-services/how-tos/ui-library-sdk/includes/closed-captions/android.md

@@ -0,0 +1,32 @@
+---
+description: Enable scenarios using closed captions and the UI Library in iOS
+author: garchiro7
+
+ms.author: jorgegarc
+ms.date: 07/01/2024
+ms.topic: include
+ms.service: azure-communication-services
+---
+
+### Enable closed captions
+
+The method `captionsOn` is configured to start captions by default.
+
+```swift
+let captionsOptions = CaptionsOptions(
+    captionsOn: true, 
+    spokenLanguage: "en-US"
+)
+
+let localOptions = LocalOptions(
+    participantViewData: participantViewData,
+    setupScreenViewData: setupScreenViewData,
+    cameraOn: false,
+    microphoneOn: false,
+    skipSetupScreen: false,
+    audioVideoMode: .audioAndVideo,
+    captionsOptions: captionsOptions
+)
+
+```
+

articles/communication-services/how-tos/ui-library-sdk/includes/closed-captions/ios.md

@@ -430,6 +430,8 @@ items:
         items: 
         - name: Configure default orientation
           href: how-tos/ui-library-sdk/orientation.md
+        - name: Configure closed captions
+          href: how-tos/ui-library-sdk/closed-captions.md
         - name: Configure theming
           href: how-tos/ui-library-sdk/theming.md
         - name: Disable end call confirmation