Merge pull request #4908 from rhurey/staging

Speech SDK 1.44 doc updates

Author: v-ccolin

articles/ai-services/speech-service/embedded-speech.md

@@ -27,7 +27,7 @@ Embedded speech is included with the Speech SDK (version 1.24.1 and higher) for
 
 # [Android](#tab/android-target)
 
-Requires Android 7.0 (API level 24) or higher on Arm64 (`arm64-v8a`) or Arm32 (`armeabi-v7a`) hardware.
+Requires Android 8.0 (API level 26) or higher on Arm64 (`arm64-v8a`) or Arm32 (`armeabi-v7a`) hardware.
 
 Embedded TTS with neural voices is only supported on Arm64.
 

articles/ai-services/speech-service/how-to-configure-azure-ad-auth.md

@@ -121,7 +121,7 @@ For programming languages where a Microsoft identity platform client library isn
 
 ## Get the Speech resource ID
 
-You need your Speech resource ID to make SDK calls using Microsoft Entra authentication.
+You need your Speech resource ID to make SDK calls using Microsoft Entra authentication in scenarios that don't yet support Entra ID directly.
 
 # [Azure portal](#tab/portal)
 
@@ -184,7 +184,7 @@ For ```SpeechRecognizer```, ```SourceLanguageRecognizer```, ```ConversationTrans
 TokenCredential browserCredential = new InteractiveBrowserCredential();
 
 // Define the custom domain endpoint for your Speech resource.
-var endpoint = "wss://{your custom name}.cognitiveservices.azure.com/stt/speech/universal/v2";
+var endpoint = "https://{your custom name}.cognitiveservices.azure.com/";
 
 // Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
 var speechConfig = SpeechConfig.FromEndpoint(new Uri(endpoint), browserCredential);
@@ -198,7 +198,7 @@ For ```TranslationRecognizer``` object, use an appropriate instance of [TokenCre
 TokenCredential browserCredential = new InteractiveBrowserCredential();
 
 // Define the custom domain endpoint for your Speech resource
-var endpoint = "wss://{your custom name}.cognitiveservices.azure.com/stt/speech/universal/v2";
+var endpoint = "https://{your custom name}.cognitiveservices.azure.com/";
 
 // Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
 var speechConfig = SpeechTranslationConfig.FromEndpoint(new Uri(endpoint), browserCredential);
@@ -233,38 +233,7 @@ std::string region = "Your Speech Region";
 auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
 auto speechConfig = SpeechConfig::FromAuthorizationToken(authorizationToken, region);
 ```
-::: zone-end
-
-::: zone pivot="programming-language-java"
-### SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber
-
-For ```SpeechRecognizer```, ```SpeechSynthesizer```, ```IntentRecognizer```, ```ConversationTranscriber``` objects, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a ```SpeechConfig``` object.
-
-```Java
-String resourceId = "Your Resource ID";
-String region = "Your Region";
-
-// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
-String authorizationToken = "aad#" + resourceId + "#" + token;
-SpeechConfig speechConfig = SpeechConfig.fromAuthorizationToken(authorizationToken, region);
-```
-::: zone-end
-
-::: zone pivot="programming-language-python"
-### SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber
-
-For ```SpeechRecognizer```, ```SpeechSynthesizer```, ```IntentRecognizer```, ```ConversationTranscriber``` objects, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a ```SpeechConfig``` object.
-
-```Python
-resourceId = "Your Resource ID"
-region = "Your Region"
-# You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
-authorizationToken = "aad#" + resourceId + "#" + aadToken.token
-speechConfig = SpeechConfig(auth_token=authorizationToken, region=region)
-```
-::: zone-end
 
-::: zone pivot="programming-language-cpp"
 ### TranslationRecognizer
 
 For the ```TranslationRecognizer```, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a ```SpeechTranslationConfig``` object.
@@ -278,35 +247,91 @@ std::string region = "Your Speech Region";
 auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
 auto speechConfig = SpeechTranslationConfig::FromAuthorizationToken(authorizationToken, region);
 ```
+
 ::: zone-end
 
 ::: zone pivot="programming-language-java"
+### SpeechRecognizer, ConversationTranscriber
+
+For ```SpeechRecognizer```, ```ConversationTranscriber``` objects, use an appropriate instance of [TokenCredential](/dotnet/api/azure.core.tokencredential) for authentication, along with the endpoint that includes your [custom domain](/azure/ai-services/speech-service/speech-services-private-link?tabs=portal#create-a-custom-domain-name), to create a ```SpeechConfig``` object.
+
+```Java
+TokenCredential browserCredential = new InteractiveBrowserCredentialBuilder().build();
+
+// Define the custom domain endpoint for your Speech resource.
+String endpoint = "https://{your custom name}.cognitiveservices.azure.com/";
+
+// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
+SpeechConfig speechConfig = SpeechConfig.fromEndpoint(new java.net.URI(endpoint), browserCredential);
+```
+
 ### TranslationRecognizer
 
-For the ```TranslationRecognizer```, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a ```SpeechTranslationConfig``` object.
+For ```TranslationRecognizer``` object, use an appropriate instance of [TokenCredential](/dotnet/api/azure.core.tokencredential) for authentication, along with the endpoint that includes your [custom domain](/azure/ai-services/speech-service/speech-services-private-link?tabs=portal#create-a-custom-domain-name), to create a ```SpeechTranslationConfig``` object.
+
+```Java
+TokenCredential browserCredential = new InteractiveBrowserCredentialBuilder().build();
+
+// Define the custom domain endpoint for your Speech resource
+String endpoint = "https://{your custom name}.cognitiveservices.azure.com/";
+
+// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
+SpeechConfig speechConfig = SpeechTranslationConfig.fromEndpoint(new java.net.URI(endpoint), browserCredential);
+```
+
+### SpeechSynthesizer, IntentRecognizer
+
+For ```SpeechSynthesizer```, ```IntentRecognizer``` objects, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a ```SpeechConfig``` object.
 
 ```Java
 String resourceId = "Your Resource ID";
 String region = "Your Region";
 
 // You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
 String authorizationToken = "aad#" + resourceId + "#" + token;
-SpeechTranslationConfig translationConfig = SpeechTranslationConfig.fromAuthorizationToken(authorizationToken, region);
+SpeechConfig speechConfig = SpeechConfig.fromAuthorizationToken(authorizationToken, region);
 ```
 ::: zone-end
 
 ::: zone pivot="programming-language-python"
+### SpeechRecognizer, ConversationTranscriber
+
+For ```SpeechRecognizer```, ```ConversationTranscriber``` objects, use an appropriate instance of [TokenCredential](/dotnet/api/azure.core.tokencredential) for authentication, along with the endpoint that includes your [custom domain](/azure/ai-services/speech-service/speech-services-private-link?tabs=portal#create-a-custom-domain-name), to create a ```SpeechConfig``` object.
+
+```Python
+browserCredential = InteractiveBrowserCredential()
+
+// Define the custom domain endpoint for your Speech resource.
+custom_endpoint = "https://{your custom name}.cognitiveservices.azure.com/"
+
+// Create the SpeechConfig object using the custom domain endpoint and TokenCredential.
+speechConfig = SpeechConfig(token_credential=credential, endpoint=custom_endpoint)
+```
+
 ### TranslationRecognizer
 
-For the ```TranslationRecognizer```, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a ```SpeechTranslationConfig``` object.
+For ```TranslationRecognizer``` object, use an appropriate instance of [TokenCredential](/dotnet/api/azure.core.tokencredential) for authentication, along with the endpoint that includes your [custom domain](/azure/ai-services/speech-service/speech-services-private-link?tabs=portal#create-a-custom-domain-name), to create a ```SpeechTranslationConfig``` object.
+
+```Python
+browserCredential = InteractiveBrowserCredential()
+
+// Define the custom domain endpoint for your Speech resource
+custom_endpoint = "https://{your custom name}.cognitiveservices.azure.com/"
+
+// Create the SpeechTranslationConfig object using the custom domain endpoint and TokenCredential.
+speechTranslationConfig = SpeechTranslationConfig(token_credential=credential, endpoint=custom_endpoint)
+```
+
+### SpeechSynthesizer, IntentRecognizer
+
+For ```SpeechSynthesizer```, ```IntentRecognizer``` objects, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a ```SpeechConfig``` object.
 
 ```Python
 resourceId = "Your Resource ID"
 region = "Your Region"
-
 # You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
 authorizationToken = "aad#" + resourceId + "#" + aadToken.token
-translationConfig = SpeechTranslationConfig(auth_token=authorizationToken, region=region)
+speechConfig = SpeechConfig(auth_token=authorizationToken, region=region)
 ```
 ::: zone-end
 

articles/ai-services/speech-service/includes/common/azure-prerequisites-resourcekey-endpoint.md

@@ -0,0 +1,12 @@
+---
+author: eric-urban
+ms.service: azure-ai-speech
+ms.date: 9/9/2024
+ms.topic: include
+ms.author: eur
+---
+
+> [!div class="checklist"]
+> - An Azure subscription. You can [create one for free](https://azure.microsoft.com/free/cognitive-services).
+> - [Create an AI Services resource for Speech](https://portal.azure.com/#create/Microsoft.CognitiveServicesAIServices) in the Azure portal.
+> - Get the Speech resource key and endpoint. After your Speech resource is deployed, select **Go to resource** to view and manage keys.

articles/ai-services/speech-service/includes/common/environment-variables-resourcekey-endpoint.md

@@ -0,0 +1,71 @@
+---
+author: eric-urban
+ms.service: azure-ai-speech
+ms.topic: include
+ms.date: 8/11/2024
+ms.author: eur
+---
+
+You need to authenticate your application to access Azure AI services. This article shows you how to use environment variables to store your credentials. You can then access the environment variables from your code to authenticate your application. For production, use a more secure way to store and access your credentials.
+
+[!INCLUDE [Azure key vault](~/reusable-content/ce-skilling/azure/includes/ai-services/security/microsoft-entra-id-akv-expanded.md)]
+
+To set the environment variables for your Speech resource key and endpoint, open a console window, and follow the instructions for your operating system and development environment.
+
+- To set the `SPEECH_KEY` environment variable, replace *your-key* with one of the keys for your resource.
+- To set the `ENDPOINT` environment variable, replace *your-endpoint* with one of the endpoints for your resource.
+
+#### [Windows](#tab/windows)
+
+```console
+setx SPEECH_KEY your-key
+setx ENDPOINT your-endpoint
+```
+
+> [!NOTE]
+> If you only need to access the environment variables in the current console, you can set the environment variable with `set` instead of `setx`.
+
+After you add the environment variables, you might need to restart any programs that need to read the environment variables, including the console window. For example, if you're using Visual Studio as your editor, restart Visual Studio before you run the example.
+
+#### [Linux](#tab/linux)
+
+##### Bash
+
+Edit your *.bashrc* file, and add the environment variables:
+
+```bash
+export SPEECH_KEY=your-key
+export ENDPOINT=your-endpoint
+```
+
+After you add the environment variables, run `source ~/.bashrc` from your console window to make the changes effective.
+
+#### [macOS](#tab/macos)
+
+##### Bash
+
+Edit your *.bash_profile* file, and add the environment variables:
+
+```bash
+export SPEECH_KEY=your-key
+export ENDPOINT=your-endpoint
+```
+
+After you add the environment variables, run `source ~/.bash_profile` from your console window to make the changes effective.
+
+##### Xcode
+
+For iOS and macOS development, you set the environment variables in Xcode. For example, follow these steps to set the environment variable in Xcode 13.4.1.
+
+1. Select **Product** > **Scheme** > **Edit scheme**.
+1. Select **Arguments** on the **Run** (Debug Run) page.
+1. Under **Environment Variables** select the plus (+) sign to add a new environment variable.
+1. Enter `SPEECH_KEY` for the **Name** and enter your Speech resource key for the **Value**.
+
+To set the environment variable for your Speech resource endpoint, follow the same steps. Set `ENDPOINT` to the endpoint of your resource. For example, `https://YourServiceRegion.api.cognitive.microsoft.com`.
+
+
+
+For more configuration options, see [the Xcode documentation](https://help.apple.com/xcode/#/dev745c5c974).
+
+---

articles/ai-services/speech-service/includes/quickstarts/platform/java-android.md

@@ -36,7 +36,7 @@ Create a new project in Android Studio and add the Speech SDK for Java as a libr
 1. Enter *samples.speech.cognitiveservices.microsoft.com* in the **Package name** text box.
 1. Select a project directory in the **Save location** selection box.
 1. Select **Java** in the **Language** selection box.
-1. Select **API 23: Android 6.0 (Marshmallow)** in the **Minimum API level** selection box.
+1. Select **API 26: Android 8.0 (Oreo)** in the **Minimum API level** selection box.
 1. Select **Finish**.
 
 Android Studio takes some time to prepare your new project. For your first time using Android Studio, it might take a few minutes to set preferences, accept licenses, and complete the wizard.

articles/ai-services/speech-service/includes/quickstarts/speech-to-text-basics/cpp.md

@@ -12,15 +12,15 @@ ms.author: eur
 
 ## Prerequisites
 
-[!INCLUDE [Prerequisites](../../common/azure-prerequisites.md)]
+[!INCLUDE [Prerequisites](../../common/azure-prerequisites-resourcekey-endpoint.md)]
 
 ## Set up the environment
 
 The Speech SDK is available as a [NuGet package](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech) and implements .NET Standard 2.0. You install the Speech SDK later in this guide. For other requirements, see [Install the Speech SDK](../../../quickstarts/setup-platform.md?pivots=programming-language-cpp).
 
 ### Set environment variables
 
-[!INCLUDE [Environment variables](../../common/environment-variables.md)]
+[!INCLUDE [Environment variables](../../common/environment-variables-resourcekey-endpoint.md)]
 
 ## Recognize speech from a microphone
 
@@ -51,16 +51,16 @@ Follow these steps to create a console application and install the Speech SDK.
     
    int main()
    {
-       // This example requires environment variables named "SPEECH_KEY" and "SPEECH_REGION"
+       // This example requires environment variables named "SPEECH_KEY" and "ENDPOINT"
        auto speechKey = GetEnvironmentVariable("SPEECH_KEY");
-       auto speechRegion = GetEnvironmentVariable("SPEECH_REGION");
+       auto endpoint = GetEnvironmentVariable("ENDPOINT");
         
-       if ((size(speechKey) == 0) || (size(speechRegion) == 0)) {
-           std::cout << "Please set both SPEECH_KEY and SPEECH_REGION environment variables." << std::endl;
+       if ((size(speechKey) == 0) || (size(endpoint) == 0)) {
+           std::cout << "Please set both SPEECH_KEY and ENDPOINT environment variables." << std::endl;
            return -1;
        }
     
-       auto speechConfig = SpeechConfig::FromSubscription(speechKey, speechRegion);
+       auto speechConfig = SpeechConfig::FromEndpoint(speechKey, endpoint);
     
        speechConfig->SetSpeechRecognitionLanguage("en-US");
     
@@ -87,7 +87,7 @@ Follow these steps to create a console application and install the Speech SDK.
            {
                std::cout << "CANCELED: ErrorCode=" << (int)cancellation->ErrorCode << std::endl;
                std::cout << "CANCELED: ErrorDetails=" << cancellation->ErrorDetails << std::endl;
-               std::cout << "CANCELED: Did you set the speech resource key and region values?" << std::endl;
+               std::cout << "CANCELED: Did you set the speech resource key and endpoint values?" << std::endl;
            }
        }
    }
@@ -113,10 +113,10 @@ Follow these steps to create a console application and install the Speech SDK.
 
 1. To change the speech recognition language, replace `en-US` with another [supported language](~/articles/ai-services/speech-service/language-support.md). For example, use `es-ES` for Spanish (Spain). If you don't specify a language, the default is `en-US`. For details about how to identify one of multiple languages that might be spoken, see [Language identification](~/articles/ai-services/speech-service/language-identification.md).
 
-1. [Build and run](/cpp/build/vscpp-step-2-build) your new console application to start speech recognition from a microphone.
+1. To start speech recognition from a microphone, [Build and run](/cpp/build/vscpp-step-2-build) your new console application.
 
    > [!IMPORTANT]
-   > Make sure that you set the `SPEECH_KEY` and `SPEECH_REGION` [environment variables](#set-environment-variables). If you don't set these variables, the sample fails with an error message.
+   > Make sure that you set the `SPEECH_KEY` and `ENDPOINT` [environment variables](#set-environment-variables). If you don't set these variables, the sample fails with an error message.
 
 1. Speak into your microphone when prompted. What you speak should appear as text: