@zeewain/3d-avatar-sdk 2.1.4 → 2.2.1

package/README.md

@@ -770,6 +770,139 @@ await sdk.startBroadcast({
 }, true); // isAppend = true
 ```
 
+##### startStreamBroadcast()
+
+```typescript
+async startStreamBroadcast(params: IBroadcastParams, forceRestart?: boolean): Promise<void>
+```
+
+流式播报方法，**专为 ChatGPT 等大模型对话场景设计**。SDK 内部自动维护播报状态，开发者无需手动判断和传递 `isAppend` 参数。
+
+**参数：**
+- `params`: 播报参数（与 `startBroadcast` 相同）
+- `forceRestart`: 是否强制重新开始，默认 `false`
+  - `false`：SDK 自动判断，空闲时开始新播报，播报中自动追加
+  - `true`：强制停止当前播报并开始新的（用于用户发起新一轮对话）
+
+**🆚 与 startBroadcast 的区别：**
+
+| 特性 | startBroadcast | startStreamBroadcast |
+|:-----|:---------------|:---------------------|
+| **适用场景** | 通用播报场景 | ChatGPT 流式对话场景 |
+| **状态管理** | 开发者手动管理 `isAppend` | SDK 自动管理 |
+| **首次调用** | 需传 `isAppend=false` | 自动判断 |
+| **后续调用** | 需传 `isAppend=true` | 自动追加 |
+| **新对话开始** | 需先停止再开始 | 传 `forceRestart=true` |
+
+**💡 使用场景：ChatGPT 流式响应**
+
+当接入大模型（如 ChatGPT、文心一言等）流式响应时，文本会分段返回。使用 `startStreamBroadcast` 可以大幅简化代码：
+
+```javascript
+// （不推荐） 使用 startBroadcast 的复杂写法（需要手动维护状态）
+let isFirstSegment = true;
+
+async function onGPTResponse(text) {
+  await sdk.startBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: text,
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  }, !isFirstSegment); // 需要手动判断是否是第一段
+  
+  isFirstSegment = false;
+}
+
+// 用户发起新对话时需要重置状态
+function onNewConversation() {
+  isFirstSegment = true;
+  sdk.stopBroadcast();
+}
+```
+
+```javascript
+// ✅ 使用 startStreamBroadcast 的简洁写法（SDK 自动管理状态）
+async function onGPTResponse(text) {
+  // 直接调用，SDK 自动判断是否追加
+  await sdk.startStreamBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: text,
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  });
+}
+
+// 用户发起新对话时
+async function onNewConversation(firstText) {
+  // forceRestart=true 会停止当前播报并开始新的
+  await sdk.startStreamBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: firstText,
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  }, true); // forceRestart = true
+}
+```
+
+**完整示例：ChatGPT 流式对话集成**
+
+```javascript
+class ChatGPTAvatar {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  // 处理 GPT 流式响应的每个文本片段
+  async handleStreamChunk(text) {
+    await this.sdk.startStreamBroadcast({
+      type: BroadcastType.TEXT,
+      humanCode: 'avatar001',
+      text: text,
+      voiceCode: 'VOICE001',
+      volume: 1.0,
+      isSubtitle: false
+    });
+  }
+
+  // 用户发送新消息，开始新一轮对话
+  async startNewConversation(firstResponse) {
+    await this.sdk.startStreamBroadcast({
+      type: BroadcastType.TEXT,
+      humanCode: 'avatar001',
+      text: firstResponse,
+      voiceCode: 'VOICE001',
+      volume: 1.0,
+      isSubtitle: false
+    }, true); // 强制重新开始
+  }
+}
+
+// 使用示例
+const chatAvatar = new ChatGPTAvatar(sdk);
+
+// 模拟 GPT 流式响应
+const gptResponses = [
+  '您好！',
+  '我是您的 AI 助手，',
+  '很高兴为您服务。',
+  '请问有什么可以帮助您的吗？'
+];
+
+// 依次播报每个片段，SDK 自动管理队列
+for (const text of gptResponses) {
+  await new Promise(resolve => setTimeout(resolve, 200)); // 间隔200毫秒模拟响应
+  await chatAvatar.handleStreamChunk(text);
+}
+```
+
+> **推荐**：对于 ChatGPT 等流式对话场景，**优先使用 `startStreamBroadcast`**，可减少状态管理代码，降低出错概率。
+
 ##### pauseBroadcast()
 
 ```typescript

package/dist/examples/test-vue2/package.json

@@ -16,7 +16,7 @@
     "lint:all-fix": "npm run lint:fix && npm run lint:css-fix"
   },
   "dependencies": {
-    "@zeewain/3d-avatar-sdk": "^2.1.4",
+    "@zeewain/3d-avatar-sdk": "^2.2.1",
     "core-js": "^3.8.3",
     "element-ui": "^2.15.13",
     "vue": "^2.6.14"

package/dist/examples/test-vue3/package.json

@@ -24,7 +24,7 @@
     "@element-plus/icons-vue": "^2.3.1",
     "@vueuse/core": "^13.5.0",
     "@vueuse/integrations": "^13.5.0",
-    "@zeewain/3d-avatar-sdk": "^2.1.4",
+    "@zeewain/3d-avatar-sdk": "^2.2.1",
     "dayjs": "^1.11.13",
     "element-plus": "^2.10.4",
     "vite-plugin-html": "^3.2.2",

package/dist/examples/test-vue3/src/App.vue

@@ -333,6 +333,7 @@ function initializeSDKConfig(): ZEEAvatarSDK | null {
       },
       onError: (error:any) => {
         sdkStatus.isStartBroadcast = false;
+        broadcastAPI.value?.reset();
         addLog(`播报失败: ${error.message}`, 'error');
       },
       onPause: () => {
@@ -487,7 +488,11 @@ async function handleTextBroadcast(params: {
 
     console.warn('handleTextBroadcast: ', broadcastParams, isAppend);
     addLog(`${isAppend ? '追加播报' : '开始播报'}:${JSON.stringify({'isAppend': isAppend})}`, 'success');
-    await sdk.value.startBroadcast(broadcastParams, isAppend);
+    // 方案一：使用普通播报接口，搭配`isAppend`参数控制播报模式
+    // await sdk.value.startBroadcast(broadcastParams, isAppend);
+
+    // 方案二：直接使用流式播报接口，内部自动维护播报状态（支持多次调用，自动追加到播报队列）
+    await sdk.value.startStreamBroadcast(broadcastParams);
     // ElMessage.success('文本播报已开始');
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/dist/examples/test-vue3/src/components/BroadcastAPI.vue

@@ -632,6 +632,7 @@ async function handleQueueBroadcast() {
 
       // 如果不是最后一个，等待配置的间隔时间再发送下一个
       if (i < textLines.length - 1) {
+        if(queueProgress.total !== 0)
         await new Promise(resolve => setTimeout(resolve, interval));
       }
     }
@@ -641,6 +642,8 @@ async function handleQueueBroadcast() {
     // 延迟重置状态，让用户看到完成提示
     setTimeout(() => {
       isQueueBroadcasting.value = false;
+      queueProgress.current = 0;
+      queueProgress.total = 0;
     }, 1000);
 
   } catch (error: any) {
@@ -732,6 +735,14 @@ function clearResult() {
   result.value = '等待播报操作...\n\n新版SDK特性：\n- 支持流式播报，实时响应\n- 内置事件回调机制\n- token统一管理，无需重复传递\n- 支持音量和语速控制\n- 实时播报控制（暂停/恢复/停止）\n\n💾 表单数据已启用自动缓存功能';
 }
 
+function reset() {
+  queueProgress.current = 0;
+  queueProgress.total = 0;
+}
+
+defineExpose({
+  reset
+});
 </script>
 
 <style lang="scss" scoped>

package/dist/index.d.ts

@@ -718,13 +718,14 @@ declare class BroadcastService extends UnityBaseService<BroadcastOperationType>
      */
     private handleError;
     /**
-     * 处理播报错误
+     * 创建播报请求错误对象
      * @param errorCode - 错误码
      * @param errorMessage - 错误消息
-     * @description 处理播报过程中的错误
+     * @returns SDKError 错误对象
+     * @description 根据错误码创建对应的 SDKError 对象
      * @private
      */
-    private handleBroadcastError;
+    private createBroadcastError;
     /**
      * 启动下一个待处理任务的请求
      * @description 在当前任务请求完成或失败后，检查并启动下一个待处理任务
@@ -1347,12 +1348,20 @@ declare class ZEEAvatarSDK {
      */
     setCamera(cameraType: AvatarCameraType): Promise<IAvatarCallbackResponse>;
     /**
-     * 开始播报
+     * 开始播报（适用于普通播报场景）
      * @param params 播报参数
      * @param isAppend 是否追加播报
      * @returns Promise<void> 播报操作的Promise
      */
     startBroadcast(params: IBroadcastParams, isAppend?: boolean): Promise<void>;
+    /**
+     * 开始流式播报（适用于ChatGPT等对话场景）
+     * @param params 播报参数
+     * @param forceRestart 是否强制重新开始（停止当前播报并开始新的）
+     * @returns Promise<void> 播报操作的Promise
+     * @description SDK内部自动维护播报状态，首次调用或空闲时使用 isAppend=false，后续调用自动使用 isAppend=true
+     */
+    startStreamBroadcast(params: IBroadcastParams, forceRestart?: boolean): Promise<void>;
     /**
      * 暂停播报
      * @param resetIdle 是否重置空闲状态
@@ -1432,7 +1441,7 @@ declare class ZEEAvatarSDK {
  * SDK 版本号
  * @const {string} SDK_VERSION
  */
-declare const SDK_VERSION = "2.1.4";
+declare const SDK_VERSION = "2.2.1";
 
 export { AvatarCameraType, AvatarOperationType, AvatarService, BroadcastOperationType, BroadcastService, BroadcastType, ConfigErrorCode, ERROR_CODE_MAP, ErrorCategory, NetworkErrorCode, OperationErrorCode, ResourceErrorCode, SDKError, SDK_VERSION, SystemErrorCode, UnityOperationStatus, ZEEAvatarLoader, ZEEAvatarSDK, getErrorInfo };
 export type { IAvatarAPI, IAvatarCallbackResponse, IAvatarSDKConfig, IBroadcastAPI, IBroadcastCallbacks, IBroadcastParams, IBroadcastResponse, IBroadcastServiceConfig, IUnityCallbackManager, IUnityCallbackResponse, IUnityInstance, IUnityMessageSender, IUnityServiceConfig, SDKErrorCode, TOperationType };