Merge branch 'wangamber/transcription' of https://github.com/amber-yujueWang/azure-sdk-for-java into wangamber/transcription

Author: amber-yujueWang

.vscode/cspell.json

@@ -223,17 +223,13 @@
     "autodetection",
     "awps",
     "azconfig",
-    "azuread",
     "azsdk",
     "azsynapse",
     "azurecr",
     "azurestackhci",
     "backoff",
     "boringssl",
-    "BYOS",
     "BYOD",
-    "dexec",
-    "diarization",
     "Dgpg",
     "Dskip",
     "mvnw",

eng/common/pipelines/templates/jobs/prepare-pipelines.yml

@@ -82,7 +82,7 @@ jobs:
         $generateUnifiedWeekly = 'false'
 
         $testServiceConnections = '"Azure" "azure-sdk-tests" "azure-sdk-tests-preview" "azure-sdk-tests-public" "Azure SDK Test Resources - LiveTestSecrets"'
-        $internalServiceConnections = '"Azure" "Azure SDK Artifacts" "Azure SDK Engineering System" "opensource-api-connection" "AzureSDKEngKeyVault Secrets" "Azure SDK PME Managed Identity"'
+        $internalServiceConnections = '"Azure" "Azure SDK Artifacts" "Azure SDK Engineering System" "opensource-api-connection" "AzureSDKEngKeyVault Secrets" "Azure SDK PME Managed Identity" "APIView prod deployment"'
 
         # Map the language to the appropriate variable groups
         switch ($lang)

sdk/agrifood/azure-verticals-agrifood-farming/README.md

@@ -103,8 +103,9 @@ Farm hierarchy is a collection of below entities.
 
 ```java readme-sample-createFarmHierarchy
 // Create Party
-JSONObject object = new JSONObject().appendField("name", "party1");
-BinaryData party = BinaryData.fromObject(object);
+Map<String, String> partyData = new HashMap<>();
+partyData.put("name", "party1");
+BinaryData party = BinaryData.fromObject(partyData);
 partiesClient.createOrUpdateWithResponse("contoso-party", party, null).block();
 
 // Get Party

sdk/cognitiveservices/azure-ai-speech-transcription/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Release History
 
-## 1.0.0-beta.1 (2025-11-14)
+## 1.0.0-beta.1 (2025-12-12)
 
 ### Features Added
 

sdk/cognitiveservices/azure-ai-speech-transcription/README.md

@@ -1,6 +1,6 @@
 # Azure AI Speech Transcription client library for Java
 
-The Azure AI Speech Transcription client library provides a simple and efficient way to convert audio to text using Azure Cognitive Services. This library enables you to transcribe audio files with features like speaker diarization, profanity filtering, and phrase hints for improved accuracy.
+The Azure AI Speech Transcription client library provides a simple and efficient way to convert audio to text using Azure Cognitive Services. This library enables you to transcribe audio with features like speaker diarization, profanity filtering, and phrase hints for improved accuracy.
 
 ## Documentation
 
@@ -30,9 +30,9 @@ Various documentation is available to help you get started:
 ```
 [//]: # ({x-version-update-end})
 
-#### Optional: For Azure AD Authentication
+#### Optional: For Entra ID Authentication
 
-If you plan to use Azure AD authentication (recommended for production), also add the `azure-identity` dependency:
+If you plan to use Entra ID authentication (recommended for production), also add the `azure-identity` dependency:
 
 ```xml
 <dependency>
@@ -65,11 +65,9 @@ TranscriptionClient client = new TranscriptionClientBuilder()
     .buildClient();
 ```
 
-#### Option 2: Azure AD OAuth2 Authentication (Recommended for Production)
+#### Option 2: Entra ID OAuth2 Authentication (Recommended for Production)
 
-For production scenarios, it's recommended to use Azure Active Directory (Azure AD) authentication with managed identities or service principals. This provides better security and easier credential management.
-
-The OAuth2 scope for Azure Cognitive Services is: `https://cognitiveservices.azure.com/.default`
+For production scenarios, it's recommended to use Entra ID authentication with managed identities or service principals. This provides better security and easier credential management.
 
 ```java
 import com.azure.identity.DefaultAzureCredential;
@@ -84,28 +82,28 @@ TranscriptionClient client = new TranscriptionClientBuilder()
     .buildClient();
 ```
 
-**Note:** To use Azure AD authentication, you need to:
+**Note:** To use Entra ID authentication, you need to:
 1. Add the `azure-identity` dependency to your project
 2. Assign the appropriate role (e.g., "Cognitive Services User") to your managed identity or service principal
-3. Ensure your Cognitive Services resource has Azure AD authentication enabled
+3. Ensure your Cognitive Services resource has Entra ID authentication enabled
 
-For more information on Azure AD authentication, see:
+For more information on Entra ID authentication, see:
 - [Authenticate with Azure Identity](https://learn.microsoft.com/azure/developer/java/sdk/identity)
 - [Azure Cognitive Services authentication](https://learn.microsoft.com/azure/ai-services/authentication)
 
 ## Key concepts
 
 ### TranscriptionClient
 
-The `TranscriptionClient` is the primary interface for interacting with the Speech Transcription service. It provides methods to transcribe audio files to text.
+The `TranscriptionClient` is the primary interface for interacting with the Speech Transcription service. It provides methods to transcribe audio to text.
 
 ### TranscriptionAsyncClient
 
 The `TranscriptionAsyncClient` provides asynchronous methods for transcribing audio, allowing non-blocking operations that return reactive types.
 
 ### Audio Formats
 
-The service supports various audio formats including WAV, MP3, OGG, and more. Audio files must be:
+The service supports various audio formats including WAV, MP3, OGG, and more. Audio must be:
 
 - Shorter than 2 hours in duration
 - Smaller than 250 MB in size
@@ -135,8 +133,7 @@ try {
     byte[] audioData = Files.readAllBytes(Paths.get("path/to/audio.wav"));
 
     // Create audio file details
-    AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData))
-        .setFilename("audio.wav");
+    AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData));
 
     // Create transcription options
     TranscriptionOptions options = new TranscriptionOptions(audioFileDetails);
@@ -176,45 +173,14 @@ result.getCombinedPhrases().forEach(phrase -> {
 });
 ```
 
-### Transcribe using AudioFileDetails constructor
-
-You can also create `TranscriptionOptions` directly with `AudioFileDetails`:
-
-```java readme-sample-transcribeWithAudioFileDetails
-TranscriptionClient client = new TranscriptionClientBuilder()
-    .endpoint("https://<your-resource-name>.cognitiveservices.azure.com/")
-    .credential(new KeyCredential("<your-api-key>"))
-    .buildClient();
-
-// Read audio file
-byte[] audioData = Files.readAllBytes(Paths.get("path/to/audio.wav"));
-
-// Create audio file details
-AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData))
-    .setFilename("audio.wav")
-    .setContentType("audio/wav");
-
-// Create transcription options with AudioFileDetails
-TranscriptionOptions options = new TranscriptionOptions(audioFileDetails);
-
-// Transcribe audio
-TranscriptionResult result = client.transcribe(options);
-
-// Process results
-result.getCombinedPhrases().forEach(phrase -> {
-    System.out.println(phrase.getText());
-});
-```
-
 ### Transcribe with multi-language support
 
 The service can automatically detect and transcribe multiple languages within the same audio file.
 
 ```java com.azure.ai.speech.transcription.transcriptionoptions.multilanguage
 byte[] audioData = Files.readAllBytes(Paths.get("path/to/audio.wav"));
 
-AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData))
-    .setFilename("audio.wav");
+AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData));
 
 // Configure transcription WITHOUT specifying locales
 // This allows the service to auto-detect and transcribe multiple languages
@@ -235,10 +201,10 @@ Enhanced mode provides advanced features to improve transcription accuracy with
 ```java com.azure.ai.speech.transcription.transcriptionoptions.enhancedmode
 byte[] audioData = Files.readAllBytes(Paths.get("path/to/audio.wav"));
 
-AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData))
-    .setFilename("audio.wav");
+AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData));
 
 EnhancedModeOptions enhancedMode = new EnhancedModeOptions()
+    .setEnabled(true)
     .setTask("transcribe")
     .setPrompts(java.util.Arrays.asList("Output must be in lexical format."));
 
@@ -257,8 +223,7 @@ You can use a phrase list to improve recognition accuracy for specific terms.
 ```java com.azure.ai.speech.transcription.transcriptionoptions.phraselist
 byte[] audioData = Files.readAllBytes(Paths.get("path/to/audio.wav"));
 
-AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData))
-    .setFilename("audio.wav");
+AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData));
 
 PhraseListOptions phraseListOptions = new PhraseListOptions()
     .setPhrases(java.util.Arrays.asList("Azure", "Cognitive Services"))
@@ -299,7 +264,7 @@ You can enable logging to debug issues with the client library. The Azure client
 
 #### Authentication errors
 
-- Verify that your API key is correct and has not expired
+- Verify that your API key is correct
 - Ensure your endpoint URL matches your Azure resource region
 
 #### Audio format errors

sdk/cognitiveservices/azure-ai-speech-transcription/assets.json

@@ -1 +1 @@
-{"AssetsRepo":"Azure/azure-sdk-assets","AssetsRepoPrefixPath":"java","TagPrefix":"java/cognitiveservices/azure-ai-speech-transcription","Tag": "java/cognitiveservices/azure-ai-speech-transcription_5be01e978d"}
+{"AssetsRepo":"Azure/azure-sdk-assets","AssetsRepoPrefixPath":"java","TagPrefix":"java/cognitiveservices/azure-ai-speech-transcription","Tag": "java/cognitiveservices/azure-ai-speech-transcription_3b50d0dce8"}

sdk/cognitiveservices/azure-ai-speech-transcription/cspell.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "azuread",
+    "BYOD",
+    "BYOS",
+    "dexec",
+    "diarization",
+    "doméstica",
+    "empleada",
+    "habitación",
+    "misrecognized",
+    "Mundo"
+  ]
+}

sdk/cognitiveservices/azure-ai-speech-transcription/customization/src/main/java/SpeechTranscriptionCustomization.java

@@ -59,6 +59,14 @@ public void customize(LibraryCustomization customization, Logger logger) {
             logger.info("Customizing TranscriptionDiarizationOptions.toJson()");
             customizeDiarizationOptionsToJson(models);
 
+            // Customize EnhancedModeOptions to add setter for enabled property
+            logger.info("Customizing EnhancedModeOptions to add setEnabled() method");
+            customizeEnhancedModeOptions(models);
+
+            // Customize AudioFileDetails.getFilename() to auto-generate filename from contentType if not set
+            logger.info("Customizing AudioFileDetails.getFilename() to auto-generate filename");
+            customizeAudioFileDetailsGetFilename(models);
+
             // Add AudioFileDetails field and constructors to TranscriptionOptions, make setAudioUrl private, remove no-arg constructor
             logger
                 .info("Customizing TranscriptionOptions to add AudioFileDetails support and remove no-arg constructor");
@@ -111,6 +119,58 @@ private void customizeDiarizationOptionsToJson(PackageCustomization packageCusto
         });
     }
 
+    /**
+     * Customize AudioFileDetails.getFilename() to auto-generate a filename from contentType if not explicitly set.
+     * This allows developers to omit setFilename() and have the SDK automatically provide a sensible default.
+     *
+     * @param packageCustomization the package customization
+     */
+    private void customizeAudioFileDetailsGetFilename(PackageCustomization packageCustomization) {
+        packageCustomization.getClass("AudioFileDetails").customizeAst(ast -> {
+            ast.getClassByName("AudioFileDetails").ifPresent(clazz -> {
+                clazz.getMethodsByName("getFilename").forEach(method -> {
+                    method.setBody(parseBlock(
+                        "{ if (this.filename != null && !this.filename.isEmpty()) { return this.filename; } "
+                        + "if (\"audio/wav\".equalsIgnoreCase(this.contentType)) { return \"audio.wav\"; } "
+                        + "if (\"audio/mpeg\".equalsIgnoreCase(this.contentType) || \"audio/mp3\".equalsIgnoreCase(this.contentType)) { return \"audio.mp3\"; } "
+                        + "if (\"audio/ogg\".equalsIgnoreCase(this.contentType)) { return \"audio.ogg\"; } "
+                        + "if (\"audio/flac\".equalsIgnoreCase(this.contentType)) { return \"audio.flac\"; } "
+                        + "if (\"audio/webm\".equalsIgnoreCase(this.contentType)) { return \"audio.webm\"; } "
+                        + "if (\"audio/opus\".equalsIgnoreCase(this.contentType)) { return \"audio.opus\"; } "
+                        + "return \"audio\"; }"));
+                    method.setJavadocComment(
+                        new Javadoc(parseText("Get the filename property: The filename of the file. "
+                            + "If not explicitly set, a filename will be auto-generated from the contentType."))
+                            .addBlockTag("return", "the filename value, or an auto-generated filename if not set."));
+                });
+            });
+        });
+    }
+
+    /**
+     * Customize the EnhancedModeOptions to add a setter for the enabled property.
+     * The enabled property must be explicitly set by users to enable enhanced mode features.
+     *
+     * @param packageCustomization the package customization
+     */
+    private void customizeEnhancedModeOptions(PackageCustomization packageCustomization) {
+        packageCustomization.getClass("EnhancedModeOptions").customizeAst(ast -> {
+            ast.getClassByName("EnhancedModeOptions").ifPresent(clazz -> {
+                // Add setEnabled method following the fluent pattern
+                com.github.javaparser.ast.body.MethodDeclaration setEnabledMethod
+                    = clazz.addMethod("setEnabled", Modifier.Keyword.PUBLIC);
+                setEnabledMethod.addParameter("Boolean", "enabled");
+                setEnabledMethod.setType("EnhancedModeOptions");
+                setEnabledMethod.setBody(parseBlock("{ this.enabled = enabled; return this; }"));
+                setEnabledMethod.setJavadocComment(
+                    new Javadoc(parseText(
+                        "Set the enabled property: Enable enhanced mode for transcription. Must be set to true to use enhanced mode features."))
+                            .addBlockTag("param", "enabled the enabled value to set.")
+                            .addBlockTag("return", "the EnhancedModeOptions object itself."));
+            });
+        });
+    }
+
     /**
      * Customize TranscriptionOptions to:
      * 1. Add AudioFileDetails field (final)

sdk/cognitiveservices/azure-ai-speech-transcription/src/main/java/com/azure/ai/speech/transcription/TranscriptionAsyncClient.java

@@ -48,7 +48,7 @@ public final class TranscriptionAsyncClient {
     /**
      * Transcribes the provided audio stream.
      * <p><strong>Response Body Schema</strong></p>
-     *
+     * 
      * <pre>
      * {@code
      * {

sdk/cognitiveservices/azure-ai-speech-transcription/src/main/java/com/azure/ai/speech/transcription/TranscriptionClient.java

@@ -46,7 +46,7 @@ public final class TranscriptionClient {
     /**
      * Transcribes the provided audio stream.
      * <p><strong>Response Body Schema</strong></p>
-     *
+     * 
      * <pre>
      * {@code
      * {