feat(audio): 添加 AsrConfig支持增强语音转录功能

[qyou]

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

[coderabbitai]

Walkthrough

Added ASR (Automatic Speech Recognition) configuration support to websocket audio transcriptions by introducing new fields to AsrConfig with builder defaults, adding asrConfig to TranscriptionsUpdateEventData, and updating test coverage. Also applied Builder.Default annotations to existing model fields for consistency.

Changes

Cohort / File(s)	Summary
ASR Configuration Model api/src/main/java/com/coze/openapi/client/websocket/event/model/AsrConfig.java	Added three new configuration fields (enableDdc, enableItn, enablePunc) with @Builder.Default annotations (default true). Updated userLanguage field to include @Builder.Default with "common" default value.
Transcriptions Event Data Model api/src/main/java/com/coze/openapi/client/websocket/event/model/TranscriptionsUpdateEventData.java	Added asrConfig field with @JsonProperty("asr_config") annotation. Introduced new constructor accepting InputAudio parameter.
Builder Annotations api/src/main/java/com/coze/openapi/client/audio/rooms/model/RoomConfig.java	Added @Builder.Default annotation to roomMode field to align builder behavior with field initializer.
Test Coverage api/src/test/java/com/coze/openapi/service/service/websocket/audio/transcriptions/WebsocketAudioTranscriptionsClientTest.java	Added testHandleTranscriptionsUpdatedEventWithAsrConfig() to verify asr_config parsing. Added testTranscriptionsUpdateWithoutAsrConfig() for backward compatibility. Extended existing tests to validate asrConfig handling.
Utilities and Examples api/src/test/java/com/coze/openapi/utils/Utils.java, example/src/main/java/example/websocket/audio/transcriptions/WebsocketTranscriptionsExample.java	Added serialVersionUID to HashMap subclass in Utils. Updated example to construct and pass AsrConfig alongside InputAudio; removed unused ByteBuffer field.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10–15 minutes

• Verify AsrConfig default values (enableDdc, enableItn, enablePunc set to true; userLanguage set to "common") align with API requirements
• Confirm TranscriptionsUpdateEventData constructor properly initializes fields and integrates with existing builder pattern
• Review test coverage for both scenarios: with and without asrConfig in events
• Check example code demonstrates correct AsrConfig instantiation and usage

Possibly related PRs

• feat: Support translate_config for audio.rooms.create #118: Introduced the room_mode field in RoomConfig; this PR adds @Builder.Default annotation to the same field for builder consistency.

Suggested labels

feature

Poem

🐰 New ASR configs hop into place,
With Builder.Default setting the pace,
AsrConfig fields now fluently flow,
Through transcriptions where sound-waves go,
A whisper of change, both swift and light! 🎙️

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 describes adding AsrConfig support to enhance speech transcription features, which aligns with the main changes (adding ASR configuration fields, updating TranscriptionsUpdateEventData, and extending tests).
Description check	✅ Passed	The description comprehensively lists all major changes including new AsrConfig fields, userLanguage defaults, RoomConfig updates, TranscriptionsUpdateEventData modifications, test extensions, example updates, and serialVersionUID fixes, all of which match the changeset.

✨ 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 (1)

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

25-35: Consider using primitive boolean instead of Boolean wrapper.

All three enable flags (enableDdc, enableItn, enablePunc) use the Boolean wrapper type with defaults of true. If tri-state logic (true/false/null) is not required, consider using primitive boolean types instead. This would:

• Prevent potential NullPointerException issues
• Make the API contract clearer (always present, never null)
• Align with typical boolean flag patterns

However, if the API specification requires nullable booleans for backward compatibility or future extensibility, the current implementation is fine.

📜 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 (2)

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)

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

api/src/main/java/com/coze/openapi/service/service/CozeAPI.java (1)

• Builder (150-310)

⏰ 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 17 on Windows)
• GitHub Check: test (Java 17 on macOS)
• GitHub Check: test (Java 17 on Ubuntu)
• GitHub Check: test (Java 8 on macOS)
• GitHub Check: test (Java 11 on Windows)

🔇 Additional comments (11)

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

13-14: LGTM!

Adding serialVersionUID to the anonymous HashMap subclass is a good practice to suppress serialization warnings. The value 1L is appropriate for internal test utilities where serialization version control is not critical.

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

23-24: LGTM!

Adding @Builder.Default ensures the builder pattern respects the default value of "" for roomMode. Without this annotation, the builder would set null when the field is not explicitly provided, which would break the intended default behavior.

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

22-23: LGTM!

Adding @Builder.Default with "common" as the default value for userLanguage ensures consistent builder behavior and provides a sensible language-agnostic default.

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

16-17: LGTM!

Adding the optional asrConfig field with @JsonProperty("asr_config") properly extends the event data model to support ASR configuration while maintaining backward compatibility (field can be null).

---

19-21: LGTM!

The convenience constructor provides a simpler API for cases where asrConfig is not needed, supporting backward compatibility. It complements the all-args constructor generated by @AllArgsConstructor without conflict.

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

123-128: LGTM!

The AsrConfig construction properly demonstrates the builder pattern and shows how to override defaults. The enable flags (enableDdc, enableItn, enablePunc) will automatically use their default true values.

---

130-130: LGTM!

The transcriptionsUpdate call correctly demonstrates passing both inputAudio and asrConfig using the all-args constructor generated by Lombok's @AllArgsConstructor.

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

123-128: LGTM!

Adding the null check for asrConfig ensures backward compatibility is tested—verifying that events without asr_config in the JSON payload correctly deserialize with asrConfig as null.

---

130-187: LGTM!

The new test comprehensively validates asrConfig deserialization, covering all fields including the list of hot words, string context, language setting, and boolean enable flags. This provides excellent test coverage for the new functionality.

---

355-360: LGTM!

The test correctly demonstrates using the builder pattern to include asrConfig in the transcriptions update, validating the happy path with ASR configuration.

---

368-383: LGTM!

The new test validates the backward-compatible path where asrConfig is not provided, using the single-argument constructor. This ensures both usage patterns are supported and tested.