Merge pull request #267878 from garchiro7/main

JamesJBarnett · web-flow · commit b05ad3af0342 · 2024-03-15T09:19:13.000-07:00
Add music mode documentation.
diff --git a/articles/communication-services/concepts/voice-video-calling/calling-sdk-features.md b/articles/communication-services/concepts/voice-video-calling/calling-sdk-features.md
@@ -97,6 +97,8 @@ The following list presents the set of features that are currently available in
 |                   | Render remote video stream                                                                                          | ✔️   | ✔️       | ✔️              | ✔️                 |
 | Video Effects     | [Background Blur](../../quickstarts/voice-video-calling/get-started-video-effects.md)          | ✔️   | ✔️       | ✔️              | ✔️                 |
 |                   | Custom background image                                                                                             | ✔️   | ❌       | ❌              | ❌                 |
+| Audio Effects     | [Music Mode](./music-mode.md)          | ❌   | ✔️       | ✔️              | ✔️                 |
+|      | [Audio filters](../../how-tos/calling-sdk/manage-audio-filters.md)          | ❌   | ✔️       | ✔️              | ✔️                 |
 
 
 <sup>1</sup> The capability to Mute Others is currently in public preview.
diff --git a/articles/communication-services/concepts/voice-video-calling/music-mode.md b/articles/communication-services/concepts/voice-video-calling/music-mode.md
@@ -0,0 +1,39 @@
+---
+title: Music Mode on Native Calling SDK
+titleSuffix: An Azure Communication Services Calling concept doc
+description: Use Azure Communication Services Calling to review Music Mode.
+author: garchiro7
+ms.author: jorgegarc
+ms.service: azure-communication-services
+ms.subservice: calling
+ms.topic: how-to 
+ms.date: 03/01/2024
+ms.custom: template-how-to
+---
+
+# Music Mode
+
+[!INCLUDE [Public Preview Disclaimer](../../includes/public-preview-include-document.md)]
+
+The **music mode** enhances the audio quality for music playback and performance within virtual environments, ensuring clarity and depth in sound reproduction; currently supports a 32-kHz sampling rate at 128 kbps when network bandwidth allows; when network bandwidth is insufficient, the bitrate can be reduced to as low as 48 kbps.
+
+This feature is designed to elevate the audio quality for calls, ensuring the audio is crispy and offering a richer and more immersive audio experience. Also, it reduces audio compression to maintain the original sound, making it ideal for applications ranging from live musical performances and remote music education or music sessions.
+
+Once music mode is enabled, you should consider:
+
+- Input and output audio devices that allow high bitrate and sampling rate (two channels, 32 kHz or higher)
+- Enable Control Noise suppression
+
+We recommend using high-quality external loudspeakers, professional microphones, or headsets instead of Bluetooth devices to optimize the music mode.
+
+**Note:** music mode only works in 1:1 calls on native platforms and group calls. Currently, music mode doesn't work in 1:1 calls between native and web. By default, music mode is disabled.
+
+The Calling native SDK provides an additional set of audio filters that bring a richer experience during the call:
+
+- Analog Automatic gain control
+- Digital Automatic gain control
+- Echo cancellation. *You can only toggle echo cancellation only if music mode is enabled*
+- Noise suppression. *The currently available modes are `Off`, `Auto`, `Low`, and `High`*
+
+## Next steps
+- [Learn how to setup audio filters](../../how-tos/calling-sdk/manage-audio-filters.md)
diff --git a/articles/communication-services/how-tos/calling-sdk/includes/manage-audio-filters/manage-audio-filters-android.md b/articles/communication-services/how-tos/calling-sdk/includes/manage-audio-filters/manage-audio-filters-android.md
@@ -7,17 +7,18 @@ ms.author: zehangzheng
 ---
 [!INCLUDE [Install SDK](../install-sdk/install-sdk-android.md)]
 
-The audio filter feature allows different audio preprocessing options to be applied to outgoing audio. There are two types of audio filters: OutgoingAudioFilters and LiveOutgoingAudioFilters, with OutgoingAudioFilters changing settings before the call starts and LiveOutgoingAudioFilters changing settings while a call is in progress. 
+The audio filter feature allows different audio preprocessing options to be applied to outgoing audio. There are two types of audio filters: `OutgoingAudioFilters` and `LiveOutgoingAudioFilters`, with `OutgoingAudioFilters` changing settings before the call starts and `LiveOutgoingAudioFilters` changing settings while a call is in progress.
 
-You first need import the Calling SDK and the associated classes:
+You first need to import the Calling SDK and the associated classes:
 
 ```csharp
 import com.azure.android.communication.calling.OutgoingAudioOptions;
 import com.azure.android.communication.calling.OutgoingAudioFilters;
 import com.azure.android.communication.calling.LiveOutgoingAudioFilters;
 ```
 
-## OutgoingAudioFilters
+## Before call starts
+
 `OutgoingAudioFilters` can be applied when a call starts. 
 
 Begin by creating a `OutgoingAudioFilters` and passing it into OutgoingAudioOptions as shown in the following code:
@@ -33,7 +34,8 @@ filters.setAcousticEchoCancellationEnabled(true);
 outgoingAudioOptions.setAudioFilters(filters);
 ```
 
-## LiveOutgoingAudioFilters
+## During the call
+
 `LiveOutgoingAudioFilters` can be applied after a call has started. You can retrieve this object from the call object once the call has started. To change the setting in `LiveOutgoingAudioFilters`, set the members inside the class to a valid value and they're applied.
 
 Only a subset of the filters available from `OutgoingAudioFilters` are available during an active call: music mode, echo cancellation, and noise suppression mode.
@@ -44,23 +46,3 @@ filters.setMusicModeEnabled(false);
 filters.setAcousticEchoCancellationEnabled(false);
 filters.setNoiseSuppressionMode(NoiseSuppressionMode.HIGH);
 ```
-
-## Available Filters
-
-Currently, there are five different filters available to control.
-
-### Analog Automatic gain control
-Analog automatic gain control is a filter available before a call. By default, this filter is enabled.
-
-### Digital Automatic gain control
-Digital automatic gain control is a filter available before a call. By default, this filter is enabled.
-
-### Music Mode
-Music mode is a filter available before and during a call. Learn more about music mode [here](https://support.microsoft.com/office/use-high-fidelity-music-mode-to-play-music-in-microsoft-teams-c1550582-2f76-4b31-9f72-e98c7167a18e). Note that music mode only works in 1:1 calls on native platforms and group calls. Currently, music mode doesn't work in 1:1 calls between native and web. By default, music mode is disabled.
-
-
-### Echo cancellation
-Echo cancellation is a filter available before and during a call. You can only toggle echo cancellation only if music mode is enabled. By default, this filter is enabled. 
-
-### Noise suppression
-Noise suppression is a filter available before and during a call. The currently available modes are `Off`, `Auto`, `Low`, and `High`. By default, this feature is set to `High` mode. 
diff --git a/articles/communication-services/how-tos/calling-sdk/includes/manage-audio-filters/manage-audio-filters-ios.md b/articles/communication-services/how-tos/calling-sdk/includes/manage-audio-filters/manage-audio-filters-ios.md
@@ -7,15 +7,16 @@ ms.author: zehangzheng
 ---
 [!INCLUDE [Install SDK](../install-sdk/install-sdk-ios.md)]
 
-The audio filter feature allows different audio preprocessing options to be applied to outgoing audio. There are two types of audio filters: OutgoingAudioFilters and LiveOutgoingAudioFilters, with OutgoingAudioFilters changing settings before the call starts and LiveOutgoingAudioFilters changing settings while a call is in progress. 
+The audio filter feature allows different audio preprocessing options to be applied to outgoing audio. There are two types of audio filters: `OutgoingAudioFilters` and `LiveOutgoingAudioFilters`, with `OutgoingAudioFilters` changing settings before the call starts and `LiveOutgoingAudioFilters` changing settings while a call is in progress.
 
-You first need import the Calling SDK:
+You first need to import the Calling SDK:
 
 ```swift
 import AzureCommunicationCalling
 ```
 
-## OutgoingAudioFilters
+## Before call starts
+
 `OutgoingAudioFilters` can be applied when a call starts. 
 
 Begin by creating a `OutgoingAudioFilters` and passing it into OutgoingAudioOptions as shown in the following code:
@@ -31,7 +32,8 @@ filters.acousticEchoCancellationEnabled = true
 outgoingAudioOptions.audioFilters = filters
 ```
 
-## LiveOutgoingAudioFilters
+## During the call
+
 `LiveOutgoingAudioFilters` can be applied after a call has started. You can retrieve this object from the call object once the call has started. To change the setting in `LiveOutgoingAudioFilters`, set the members inside the class to a valid value and they're applied.
 
 Only a subset of the filters available from `OutgoingAudioFilters` are available during an active call: music mode, echo cancellation, and noise suppression mode.
@@ -42,23 +44,3 @@ filters.musicModeEnabled = true
 filters.acousticEchoCancellationEnabled = true
 filters.NoiseSuppressionMode = NoiseSuppressionMode.high
 ```
-
-## Available Filters
-
-Currently, there are five different filters available to control.
-
-### Analog Automatic gain control
-Analog automatic gain control is a filter available before a call. By default, this filter is enabled.
-
-### Digital Automatic gain control
-Digital automatic gain control is a filter available before a call. By default, this filter is enabled.
-
-### Music Mode
-Music mode is a filter available before and during a call. Learn more about music mode [here](https://support.microsoft.com/office/use-high-fidelity-music-mode-to-play-music-in-microsoft-teams-c1550582-2f76-4b31-9f72-e98c7167a18e). Note that music mode only works in 1:1 calls on native platforms and group calls. Currently, music mode doesn't work in 1:1 calls between native and web. By default, music mode is disabled.
-
-
-### Echo cancellation
-Echo cancellation is a filter available before and during a call. You can only toggle echo cancellation only if music mode is enabled. By default, this filter is enabled. 
-
-### Noise suppression
-Noise suppression is a filter available before and during a call. The currently available modes are `Off`, `Auto`, `Low`, and `High`. By default, this feature is set to `High` mode. 
diff --git a/articles/communication-services/how-tos/calling-sdk/includes/manage-audio-filters/manage-audio-filters-windows.md b/articles/communication-services/how-tos/calling-sdk/includes/manage-audio-filters/manage-audio-filters-windows.md
@@ -7,17 +7,18 @@ ms.author: t-leejiyoon
 ---
 [!INCLUDE [Install SDK](../install-sdk/install-sdk-windows.md)]
 
-The audio filter feature allows different audio preprocessing options to be applied to outgoing audio. There are two types of audio filters: OutgoingAudioFilters and LiveOutgoingAudioFilters, with OutgoingAudioFilters changing settings before the call starts and LiveOutgoingAudioFilters changing settings while a call is in progress. 
+The audio filter feature allows different audio preprocessing options to be applied to outgoing audio. There are two types of audio filters: `OutgoingAudioFilters` and `LiveOutgoingAudioFilters`, with `OutgoingAudioFilters` changing settings before the call starts and `LiveOutgoingAudioFilters` changing settings while a call is in progress.
 
-You first need import the Calling SDK:
+You first need to import the Calling SDK:
 
 ```csharp
 using Azure.Communication;
 using Azure.Communication.Calling.WindowsClient;
 ```
 
-## OutgoingAudioFilters
-`OutgoingAudioFilters` can be applied when a call starts. 
+## Before call starts
+
+`OutgoingAudioFilters` can be applied when a call starts.
 
 Begin by creating a `OutgoingAudioFilters` and passing it into OutgoingAudioOptions as shown in the following code:
 
@@ -34,7 +35,8 @@ var filters = new OutgoingAudioFilters()
 outgoingAudioOptions.Filters = filters;
 ```
 
-## LiveOutgoingAudioFilters
+## During the call
+
 `LiveOutgoingAudioFilters` can be applied after a call has started. You can retrieve this object from the call object once the call has started. To change the setting in `LiveOutgoingAudioFilters`, set the members inside the class to a valid value and they're applied.
 
 Only a subset of the filters available from `OutgoingAudioFilters` are available during an active call: music mode, echo cancellation, and noise suppression mode.
@@ -45,23 +47,3 @@ filter.MusicModeEnabled = true;
 filter.AcousticEchoCancellationEnabled = true;
 filter.NoiseSuppressionMode = NoiseSuppressionMode.Auto;
 ```
-
-## Available Filters
-
-Currently, there are five different filters available to control.
-
-### Analog Automatic gain control
-Analog automatic gain control is a filter available before a call. By default, this filter is enabled.
-
-### Digital Automatic gain control
-Digital automatic gain control is a filter available before a call. By default, this filter is enabled.
-
-### Music Mode
-Music mode is a filter available before and during a call. Learn more about music mode [here](https://support.microsoft.com/office/use-high-fidelity-music-mode-to-play-music-in-microsoft-teams-c1550582-2f76-4b31-9f72-e98c7167a18e). Note that music mode only works in 1:1 calls on native platforms and group calls. Currently, music mode doesn't work in 1:1 calls between native and web. By default, music mode is disabled.
-
-
-### Echo cancellation
-Echo cancellation is a filter available before and during a call. You can only toggle echo cancellation only if music mode is enabled. By default, this filter is enabled. 
-
-### Noise suppression
-Noise suppression is a filter available before and during a call. The currently available modes are `Off`, `Auto`, `Low`, and `High`. By default, this feature is set to `High` mode. 
diff --git a/articles/communication-services/how-tos/calling-sdk/manage-audio-filters.md b/articles/communication-services/how-tos/calling-sdk/manage-audio-filters.md
@@ -1,7 +1,7 @@
 ---
-title: Outgoing Audio Filters
+title: Manage the audio filters on Calling Native SDKs
 titleSuffix: An Azure Communication Services how-to guide
-description: Use Azure Communication Services SDKs to set outgoing audio filters.
+description: Use Azure Communication Services Calling SDKs to set the audio filters.
 author: t-leejiyoon
 ms.author: zehangzheng
 ms.service: azure-communication-services
@@ -16,12 +16,34 @@ zone_pivot_groups: acs-plat-ios-android-windows
 
 [!INCLUDE [Public Preview Disclaimer](../../includes/public-preview-include-document.md)]
 
-Learn how to manage audio processing features with the Azure Communication Services SDKS. We'll learn how to apply different audio features before and during calls using audio filters.
+Learn how to manage audio processing features with the Azure Communication Services SDKS. You learn how to apply different audio features before and during calls using audio filters. 
+
+Currently, there are five different filters available to control.
+
+## Analog Automatic gain control
+
+Analog automatic gain control is a filter available before a call. By default, this filter is enabled.
+
+## Digital Automatic gain control
+
+Digital automatic gain control is a filter available before a call. By default, this filter is enabled.
+
+## Music Mode
+
+Music mode is a filter available before and during a call. Learn more about music mode [here](../../concepts/voice-video-calling/music-mode.md). Note that music mode only works in 1:1 calls on native platforms and group calls. Currently, music mode doesn't work in 1:1 calls between native and web. By default, music mode is disabled.
+
+## Echo cancellation
+
+Echo cancellation is a filter available before and during a call. You can only toggle echo cancellation only if music mode is enabled. By default, this filter is enabled.
+
+## Noise suppression
+
+Noise suppression is a filter available before and during a call. The currently available modes are `Off`, `Auto`, `Low`, and `High`. By default, this feature is set to `High` mode.
 
 ## 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).
+- 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 calling client. For more information, see [Create and manage access tokens](../../quickstarts/identity/access-tokens.md).
 - Optional: Complete the quickstart to [add voice calling to your application](../../quickstarts/voice-video-calling/getting-started-with-calling.md)
 
@@ -38,6 +60,7 @@ Learn how to manage audio processing features with the Azure Communication Servi
 ::: zone-end
 
 ## Next steps
+
 - [Learn how to manage calls](./manage-calls.md)
 - [Learn how to record calls](./record-calls.md)
 - [Learn how to transcribe calls](./call-transcription.md)
diff --git a/articles/communication-services/toc.yml b/articles/communication-services/toc.yml
@@ -725,6 +725,10 @@ items:
     - name: Video constraints
       href: concepts/voice-video-calling/video-constraints.md
       displayName: diagnostics, diagnose, feedback, quality, reliability, users, call, quick, satisfaction, improve, issues
+    - name: Music mode
+      href: concepts/voice-video-calling/music-mode.md
+      displayName: music mode, audio filters, calling
+    
     - name: Simulcast
       href: concepts/voice-video-calling/simulcast.md
       displayName: diagnostics, diagnose, feedback, quality, reliability, users, call, quick, satisfaction, improve, issues
