update readme and modify enabled property for EnhancedModeOptions

Author: amber-yujueWang

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/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/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
      * {

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

@@ -52,13 +52,35 @@ public BinaryData getContent() {
     }
 
     /**
-     * Get the filename property: The filename of the file.
+     * Get the filename property: The filename of the file. If not explicitly set, a filename will be auto-generated
+     * from the contentType.
      *
-     * @return the filename value.
+     * @return the filename value, or an auto-generated filename if not set.
      */
     @Generated
     public String getFilename() {
-        return this.filename;
+        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";
     }
 
     /**

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

@@ -171,4 +171,16 @@ public static EnhancedModeOptions fromJson(JsonReader jsonReader) throws IOExcep
             return deserializedEnhancedModeOptions;
         });
     }
+
+    /**
+     * Set the enabled property: Enable enhanced mode for transcription. Must be set to true to use enhanced mode
+     * features.
+     *
+     * @param enabled the enabled value to set.
+     * @return the EnhancedModeOptions object itself.
+     */
+    public EnhancedModeOptions setEnabled(Boolean enabled) {
+        this.enabled = enabled;
+        return this;
+    }
 }

sdk/cognitiveservices/azure-ai-speech-transcription/src/samples/java/com/azure/ai/speech/transcription/EnhancedModeSample.java

@@ -117,12 +117,12 @@ private static TranscriptionResult transcribeWithFullEnhancedMode(
         String filename
     ) throws Exception {
         // Create audio file details
-        AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData))
-            .setFilename(filename);
+        AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData));
 
         // Configure comprehensive LLM-enhanced mode settings
         // Always include lexical format prompt for best results
         EnhancedModeOptions enhancedMode = new EnhancedModeOptions()
+            .setEnabled(true)
             .setTask("transcribe")
             .setPrompts(Arrays.asList(
                 "Output must be in lexical format."

sdk/cognitiveservices/azure-ai-speech-transcription/src/samples/java/com/azure/ai/speech/transcription/README.md

@@ -10,9 +10,9 @@ To run these samples, you need:
 2. **Azure AI Speech Service Resource**: Create one in the [Azure Portal](https://portal.azure.com)
 3. **Authentication**: Choose one of the following authentication methods:
 
-   ### Option 1: Azure AD Authentication (Recommended for Production)
-   
-   Set the endpoint and configure Azure AD credentials:
+### Option 1: Entra ID Authentication (Recommended for Production)
+
+   Set the endpoint and configure Entra ID credentials:
 
    ```bash
    set SPEECH_ENDPOINT=https://your-resource-name.cognitiveservices.azure.com/
@@ -32,7 +32,7 @@ To run these samples, you need:
        --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<speech-resource-name>
    ```
 
-   **Required dependency** for Azure AD authentication:
+   **Required dependency** for Entra ID authentication:
 
    ```xml
    <dependency>
@@ -64,7 +64,7 @@ To run these samples, you need:
        --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<speech-resource-name>
    ```
 
-   **Required dependency** for Azure AD authentication:
+   **Required dependency** for Entra ID authentication:
 
    ```xml
    <dependency>
@@ -80,10 +80,10 @@ To run these samples, you need:
 
 All samples in this directory support **both authentication methods**:
 
-- **Azure AD (TokenCredential)**: Uses `DefaultAzureCredential` from azure-identity
+- **Entra ID (TokenCredential)**: Uses `DefaultAzureCredential` from azure-identity
 - **API Key (KeyCredential)**: Uses the `SPEECH_API_KEY` environment variable
 
-The samples will automatically detect which authentication method to use based on the environment variables you've set. If `SPEECH_API_KEY` is set, it will use API Key authentication; otherwise, it will attempt Azure AD authentication.
+The samples will automatically detect which authentication method to use based on the environment variables you've set. If `SPEECH_API_KEY` is set, it will use API Key authentication; otherwise, it will attempt Entra ID authentication.
 
 ## Available Samples