feat(audio): 添加 ASR 配置支持以增强语音转录功能

[qyou]

• 在 AsrConfig 类中新增多个配置项，包括 enable_ddc、enable_itn 和 enable_punc，默认值设为 true
• 为 userLanguage 字段设置默认值 "common"
• 在 RoomConfig 中为 roomMode 设置默认空字符串并添加 Builder 默认注解
• 更新 TranscriptionsUpdateEventData 模型以支持 asrConfig 参数
• 扩展 WebSocket 客户端测试用例，验证带和不带 asrConfig 的事件处理逻辑
• 更新示例代码以演示如何传递 ASR 配置进行实时转录
• 修复测试工具类中的序列化版本 UID 缺失问题

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

Walkthrough

This change enhances audio transcription configuration by introducing default values for existing fields and adding three new boolean feature flags (enableDdc, enableItn, enablePunc) to AsrConfig. The TranscriptionsUpdateEventData model is extended with AsrConfig support, and supporting tests and examples are updated to demonstrate the new functionality.

Changes

Cohort / File(s)	Summary
ASR Configuration Enhancements api/src/main/java/com/coze/openapi/client/websocket/event/model/AsrConfig.java, api/src/main/java/com/coze/openapi/client/audio/rooms/model/RoomConfig.java	Added @Builder.Default annotations to establish default values; AsrConfig now includes userLanguage defaulting to "common" and three new boolean fields (enableDdc, enableItn, enablePunc) each defaulting to true. RoomConfig's roomMode now has @Builder.Default annotation.
Event Data Model api/src/main/java/com/coze/openapi/client/websocket/event/model/TranscriptionsUpdateEventData.java	Added asrConfig field with @JsonProperty("asr_config") annotation and introduced new constructor accepting InputAudio parameter.
Test Coverage api/src/test/java/com/coze/openapi/service/service/websocket/audio/transcriptions/WebsocketAudioTranscriptionsClientTest.java	Extended tests to validate AsrConfig handling in transcriptions.updated events, covering both scenarios with and without asr_config present, verifying all field mappings.
Examples & Utilities example/src/main/java/example/websocket/audio/transcriptions/WebsocketTranscriptionsExample.java, api/src/test/java/com/coze/openapi/utils/Utils.java	Example updated to import and construct AsrConfig with hotWords, context, and userLanguage; removed local 10 MB ByteBuffer. Utils.java adds serialVersionUID to anonymous HashMap class.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

• Focus on the constructor signature change in TranscriptionsUpdateEventData and verify backward compatibility strategy (overloading vs. replacement)
• Confirm all new Boolean fields in AsrConfig have proper Lombok annotations and getters/setters
• Validate test coverage properly exercises all new AsrConfig fields and default values
• Ensure example code correctly demonstrates the new constructor and AsrConfig usage pattern

Possibly related PRs

• feat: Support translate_config for audio.rooms.create #118: Modifies RoomConfig class and room_mode field; this PR adds @Builder.Default annotation to the same field.

Suggested labels

feature

Poem

🐰 Whiskers twitching with delight,
New defaults shine so bright!
Three flags hop into the fray—
Enable, enable, hooray, hooray!
Audio dreams come true today! 🎙️

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title in Chinese accurately describes the main change: adding ASR configuration support to enhance speech transcription functionality, which aligns with the multiple file changes implementing AsrConfig.
Description check	✅ Passed	The description comprehensively covers all major changes in the pull request, including new ASR config fields, default values, model updates, test extensions, example code updates, and serialization fixes.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

api/src/main/java/com/coze/openapi/client/websocket/event/model/TranscriptionsUpdateEventData.java (1)

15-21: LGTM with a note on constructor usage.

The new asrConfig field and single-argument constructor provide good backward compatibility. The constructor allows creating TranscriptionsUpdateEventData with only inputAudio when asrConfig is not needed.

Note: Consider whether the builder pattern (already available via @Builder) could replace this convenience constructor to maintain a more consistent API surface.

example/src/main/java/example/websocket/audio/transcriptions/WebsocketTranscriptionsExample.java (1)

123-128: ASR config builder is clear; consider briefly documenting the new boolean flags

The example nicely shows hotWords/context/userLanguage. To better surface the new ASR options, consider a short comment indicating that enableDdc/enableItn/enablePunc default to true and can be customized here if needed, so users discover them from the sample.

For example:

       AsrConfig asrConfig =
           AsrConfig.builder()
               .hotWords(Arrays.asList("Coze", "AI"))
               .context("Real-time transcription")
               .userLanguage("en-US")
+              // enableDdc/enableItn/enablePunc default to true; customize here if needed.
               .build();

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a1dad15 and 0ff5fc9.

📒 Files selected for processing (6)

• api/src/main/java/com/coze/openapi/client/audio/rooms/model/RoomConfig.java (1 hunks)
• api/src/main/java/com/coze/openapi/client/websocket/event/model/AsrConfig.java (1 hunks)
• api/src/main/java/com/coze/openapi/client/websocket/event/model/TranscriptionsUpdateEventData.java (1 hunks)
• api/src/test/java/com/coze/openapi/service/service/websocket/audio/transcriptions/WebsocketAudioTranscriptionsClientTest.java (4 hunks)
• api/src/test/java/com/coze/openapi/utils/Utils.java (1 hunks)
• example/src/main/java/example/websocket/audio/transcriptions/WebsocketTranscriptionsExample.java (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

api/src/test/java/com/coze/openapi/service/service/websocket/audio/transcriptions/WebsocketAudioTranscriptionsClientTest.java (1)

api/src/main/java/com/coze/openapi/client/websocket/event/EventType.java (1)

• EventType (3-94)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: test (Java 8 on macOS)
• GitHub Check: test (Java 17 on Windows)
• GitHub Check: test (Java 11 on Windows)
• GitHub Check: test (Java 17 on Ubuntu)
• GitHub Check: test (Java 11 on Ubuntu)

🔇 Additional comments (9)

api/src/test/java/com/coze/openapi/utils/Utils.java (1)

12-18: LGTM!

Adding serialVersionUID to the anonymous HashMap subclass addresses serialization warnings. This is a good practice even when the class is not intended for serialization.

api/src/main/java/com/coze/openapi/client/audio/rooms/model/RoomConfig.java (1)

22-24: LGTM!

Adding @Builder.Default ensures the builder correctly uses the empty string default value for roomMode instead of leaving it null when not explicitly set.

api/src/test/java/com/coze/openapi/service/service/websocket/audio/transcriptions/WebsocketAudioTranscriptionsClientTest.java (3)

123-128: Good addition for backward compatibility testing.

Explicitly asserting that asrConfig is null when not present in the JSON payload ensures backward compatibility with existing messages.

---

130-187: Comprehensive test coverage for AsrConfig parsing.

The test thoroughly validates all AsrConfig fields including the new boolean flags (enableDdc, enableItn, enablePunc), list handling for hotWords, and string fields.

---

368-383: Good coverage for the new single-argument constructor.

This test validates backward compatibility by ensuring TranscriptionsUpdateEventData can be created with only InputAudio, using the new constructor.

api/src/main/java/com/coze/openapi/client/websocket/event/model/AsrConfig.java (2)

21-23: LGTM!

Setting userLanguage default to "common" via @Builder.Default ensures a sensible fallback when not explicitly configured.

---

25-35: This review comment references code that does not exist in the current AsrConfig.java file.

The file contains only three fields (hotWords, context, userLanguage) and ends at line 23. The Boolean wrapper fields (enableDdc, enableItn, enablePunc) at lines 25-35 mentioned in the review are not present in the codebase, and searches for these fields and their getters return no results.

Likely an incorrect or invalid review comment.

example/src/main/java/example/websocket/audio/transcriptions/WebsocketTranscriptionsExample.java (2)

12-12: AsrConfig import wiring looks correct

Import points to the expected websocket event model package and aligns with the new ASR configuration integration in this example.

---

130-130: Updated TranscriptionsUpdateEventData usage matches the new API

Passing both inputAudio and asrConfig into TranscriptionsUpdateEventData keeps the example aligned with the new model and clearly shows how to attach per-request ASR config.