feat: support voice emotions #297
Conversation
|
|
WalkthroughAdds voice-emotion support to the JS SDK: new changelog entries; minor package version bump; optional emotion fields on speech requests; voice metadata advertising supported emotions; websocket OutputAudio extended with emotion_config. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant SDK as coze-js (Speech)
participant API
Client->>SDK: create({ text, voice_id, emotion?, emotion_scale? })
SDK->>API: POST /audio/speech (payload includes emotion fields)
API-->>SDK: Audio response (may include emotion metadata)
SDK-->>Client: Return audio data/stream
sequenceDiagram
participant Client
participant SDK as coze-js (WS)
participant Server
Client->>SDK: Open WS, request audio
Server-->>SDK: OutputAudio { ..., emotion_config? }
SDK-->>Client: Emit OutputAudio with emotion_config
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15 minutes Possibly related PRs
Suggested reviewers
Poem
✨ Finishing Touches
🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
duwenhan2byte
force-pushed
the
feat/voice-emotion
branch
from
da74135 to
645bb66
Compare
duwenhan2byte
force-pushed
the
feat/voice-emotion
branch
from
645bb66 to
e1fa501
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
packages/coze-js/src/resources/websockets/types.ts (1)
521-527: Clarify docs, add bounds, and consider extracting a reusable EmotionConfig typeGood addition. Two suggestions:
- Documentation: add English and specify bounds/default for emotion_scale to align with speech.ts.
- Type reuse: consider a shared EmotionConfig type to avoid divergence across modules.
Apply doc improvements:
- /** 输出语音的情感配置 */ + /** 输出语音的情感配置 | Emotion configuration for the output audio */ emotion_config?: { - /** 情感 */ + /** 情感 | Emotion name (should be one of the voice's supported emotions) */ emotion?: string; - /** 情绪值 */ + /** 情绪值，范围 [1,5]，默认为 4，通常保留一位小数即可 | Emotion intensity in [1,5], default 4 (usually one decimal place is sufficient) */ emotion_scale?: number; };Optional: extract and reuse a shared type to keep REST/WebSocket in sync.
// e.g. in a shared types module (resources/audio/types.ts) export interface EmotionConfig { emotion?: string; emotion_scale?: number; // [1,5], default 4 } // Then here: emotion_config?: EmotionConfig;common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-11.json (1)
1-11: Nit: prefer sentence case in changelog commentsFor consistency with typical changelog styles, consider capitalizing the first letter.
- "comment": "support voice emotions", + "comment": "Support voice emotions",packages/coze-js/src/resources/audio/speech/speech.ts (1)
46-49: Document bounds/default and add English to match file style; optionally validate input
- Add English and specify bounds/default for emotion_scale to align with WebSocket docs and improve DX.
- Optional: clamp or validate emotion_scale in create() to avoid server-side validation errors.
Doc improvements:
- /** 情感，默认为空 */ + /** 情感（可选）| Emotion (optional). Should match one of the voice's supported emotions if provided. */ emotion?: string; - /** 情感强度，[1,5]，默认为4，通常保留一位小数即可 */ + /** 情感强度 | Emotion intensity in [1,5], default 4 (usually one decimal place is sufficient). */ emotion_scale?: number;Optional validation (outside the selected range), e.g. clamp before sending:
// Inside create() const payload = { ...params, sample_rate: params.sample_rate || 24000, ...(typeof params.emotion_scale === 'number' ? { emotion_scale: Math.min(5, Math.max(1, params.emotion_scale)) } : {}), }; const response = await this._client.post<CreateSpeechReq, ArrayBuffer>( apiUrl, payload, false, mergeConfig(options, { responseType: 'arraybuffer' }), );packages/coze-js/src/resources/audio/voices/voices.ts (3)
106-111: Add concise bilingual docs for Interval to improve discoverabilityAdding minimal JSDoc helps SDK users understand the semantics quickly.
-export interface Interval { - min?: number; - max?: number; - default?: number; -} +/** 数值区间（闭区间）| Numeric interval (inclusive) */ +export interface Interval { + /** 最小值 | Minimum value (inclusive) */ + min?: number; + /** 最大值 | Maximum value (inclusive) */ + max?: number; + /** 默认值 | Default value */ + default?: number; +}
112-117: Doc the emotion fields and relate the scale interval to the [1,5] guidanceThis connects voice metadata with request parameters.
-export interface EmotionInfo { - emotion?: string; - display_name?: string; - emotion_scale_interval?: Interval; -} +export interface EmotionInfo { + /** 情感标识 | Emotion identifier (e.g., neutral/happy/sad) */ + emotion?: string; + /** 展示名称 | Human-readable display name */ + display_name?: string; + /** 情感强度区间 | Allowed emotion intensity interval (typically within [1,5]) */ + emotion_scale_interval?: Interval; +}
140-142: Add English to the new Voice.support_emotions field docKeeps the file’s bilingual doc style consistent.
- /** 支持的情感列表 */ + /** Supported emotions of this voice | 支持的情感列表 */ support_emotions?: EmotionInfo[];
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-11.json(1 hunks)packages/coze-js/package.json(3 hunks)packages/coze-js/src/resources/audio/speech/speech.ts(1 hunks)packages/coze-js/src/resources/audio/voices/voices.ts(2 hunks)packages/coze-js/src/resources/websockets/types.ts(1 hunks)
🔇 Additional comments (5)
packages/coze-js/package.json (5)
3-3: Version bump looks goodMinor version bump to 1.3.6 is appropriate for additive, non-breaking API surface (new optional fields).
25-30: Dist-based exports for "." look correctThe CJS/ESM/types entries point to dist and align with main/module/types below.
31-34: Please verify ws-tools types path (duplicated segment may be unintended)The types path contains "ws-tools/ws-tools/index.d.ts". This duplication may be accidental and could break TS type resolution after publish, depending on build output structure. Recommend verifying the actual dist output before release.
If build output places d.ts at dist/types/ws-tools/index.d.ts, apply:
"./ws-tools": { "require": "./dist/cjs/ws-tools/index.js", "import": "./dist/esm/ws-tools/index.mjs", - "types": "./dist/types/ws-tools/ws-tools/index.d.ts" + "types": "./dist/types/ws-tools/index.d.ts" }Action:
- Build locally and inspect the generated types under packages/coze-js/dist/types/ws-tools/.
- Ensure the exports.types path matches the actual layout.
45-55: Align typesVersions with actual d.ts output layoutThe typesVersions mapping for "ws-tools" mirrors the same duplicated path. Please verify generated paths and update if necessary to avoid TS resolution issues.
If the real output is dist/types/ws-tools/index.d.ts:
"typesVersions": { "*": { ".": [ "dist/types/index.d.ts" ], "ws-tools": [ - "dist/types/ws-tools/ws-tools/index.d.ts" + "dist/types/ws-tools/index.d.ts" ] } },
112-116: cozePublishConfig.types for ws-tools likely needs the same path correctionKeep internal publish config consistent with package.exports/typesVersions.
"./ws-tools": { "require": "./dist/cjs/ws-tools/index.js", "import": "./dist/esm/ws-tools/index.mjs", - "types": "./dist/types/ws-tools/ws-tools/index.d.ts" + "types": "./dist/types/ws-tools/index.d.ts" }
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-15.json (1)
5-6: Tighten up the changelog comment for clarity.Use imperative, concise phrasing and reference the surface area touched to make release notes more informative.
Apply this diff to refine the comment:
- "comment": "support voice emotions", + "comment": "Support voice emotions across speech and voice APIs.",
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-11.json(1 hunks)common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-14.json(1 hunks)common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-15.json(1 hunks)packages/coze-js/package.json(2 hunks)packages/coze-js/src/resources/audio/speech/speech.ts(1 hunks)packages/coze-js/src/resources/audio/voices/voices.ts(2 hunks)packages/coze-js/src/resources/websockets/types.ts(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-14.json
- packages/coze-js/package.json
🚧 Files skipped from review as they are similar to previous changes (4)
- packages/coze-js/src/resources/websockets/types.ts
- packages/coze-js/src/resources/audio/speech/speech.ts
- packages/coze-js/src/resources/audio/voices/voices.ts
- common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-11.json
🔇 Additional comments (2)
common/changes/@coze/api/feat-voice-emotion_2025-08-12-08-15.json (2)
1-11: Well-formed change file.JSON structure and Rush/Beachball change fields look correct: top-level packageName/email plus a single minor change entry.
1-11: All checks passed for the @coze/api voice‐emotion change
- Change file is correctly scoped to
@coze/api(located underpackages/coze-jswith name@coze/api).- The package exposes new emotion APIs (
emotion,emotion_scale,support_emotions,emotion_config), so bumping the minor version is appropriate.- No other
feat-voice-emotion_*.jsonfiles were found—no deduplication needed.
3 participants
Summary by CodeRabbit
New Features
Chores