@zeewain/3d-avatar-sdk 1.2.3 → 1.2.4-0

package/README.md

@@ -125,6 +125,17 @@ async function initializeAvatar() {
         speed: 1.0,
         isSubtitle: false
       });
+
+      // 5. 追加播报（演示队列功能）
+      await sdk.startBroadcast({
+        type: BroadcastType.TEXT,
+        humanCode: 'avatar001',
+        text: '这里展示了智能播报队列的强大功能。',
+        voiceCode: 'VOICE001',
+        volume: 1.0,
+        speed: 1.0,
+        isSubtitle: false
+      }, true); // isAppend = true，追加到播报队列
     }
   } catch (error) {
     console.error('初始化失败:', error);
@@ -204,7 +215,7 @@ class AvatarApp {
   }
 
   // 文本播报
-  async speakText(text, voiceCode = 'VOICE001') {
+  async speakText(text, voiceCode = 'VOICE001', isAppend = false) {
     if (!this.isInitialized) {
       console.warn('SDK未初始化');
       return;
@@ -219,8 +230,35 @@ class AvatarApp {
         volume: 1.0,
         speed: 1.0,
         isSubtitle: false
-      });
-      console.log('播报开始');
+      }, isAppend);
+      console.log(isAppend ? '播报已追加到队列' : '播报开始');
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 批量播报（演示队列功能）
+  async speakMultiple(textList, voiceCode = 'VOICE001') {
+    if (!this.isInitialized) {
+      console.warn('SDK未初始化');
+      return;
+    }
+
+    if (!Array.isArray(textList) || textList.length === 0) {
+      console.warn('文本列表为空');
+      return;
+    }
+
+    try {
+      // 第一段作为新播报开始
+      await this.speakText(textList[0], voiceCode, false);
+      
+      // 其余内容追加到队列
+      for (let i = 1; i < textList.length; i++) {
+        await this.speakText(textList[i], voiceCode, true);
+      }
+      
+      console.log(`✅ 已添加 ${textList.length} 段内容到播报队列`);
     } catch (error) {
       this.handleError(error);
     }
@@ -354,6 +392,16 @@ class AvatarApp {
       const text = document.getElementById('text-input').value;
       this.speakText(text);
     });
+    document.getElementById('speak-multiple-btn').addEventListener('click', () => {
+      // 演示批量播报
+      const textList = [
+        '欢迎来到ZEE 3D Avatar SDK演示',
+        '这里展示了智能播报队列功能',
+        '多段内容会按顺序播报',
+        '感谢您的观看'
+      ];
+      this.speakMultiple(textList);
+    });
     document.getElementById('pause-btn').addEventListener('click', () => this.pauseBroadcast());
     document.getElementById('resume-btn').addEventListener('click', () => this.resumeBroadcast());
     document.getElementById('stop-btn').addEventListener('click', () => this.stopBroadcast());
@@ -585,10 +633,10 @@ try {
 ##### startBroadcast()
 
 ```typescript
-async startBroadcast(params: IBroadcastParams): Promise<void>
+async startBroadcast(params: IBroadcastParams, isAppend?: boolean): Promise<void>
 ```
 
-开始播报，支持文本转语音和音频播报两种模式。
+开始播报，支持文本转语音和音频播报两种模式。内置智能队列机制，确保多次追加播报按序执行。
 
 **参数：**
 ```typescript
@@ -606,9 +654,19 @@ interface IBroadcastParams {
 }
 ```
 
+- `isAppend`: 是否追加播报，默认false
+  - `false`：开始新的播报（会停止当前播报并清空队列）
+  - `true`：追加到当前播报队列（按序播报，不会中断当前播报）
+
+**🚀 播报队列特性：**
+- **智能排队**：多次追加播报自动按调用顺序排队
+- **顺序保证**：即使网络响应乱序，也确保音频按序播报
+- **高效处理**：支持并发请求，同时保证播报顺序
+- **自动清理**：已播报内容自动从队列中移除，节省内存
+
 **使用示例：**
 ```javascript
-// 文本播报
+// 开始新的播报（清空队列）
 await sdk.startBroadcast({
   type: BroadcastType.TEXT,
   humanCode: 'avatar001',
@@ -619,7 +677,29 @@ await sdk.startBroadcast({
   isSubtitle: false
 });
 
-// 音频播报
+// 追加播报（进入队列按序播报）
+await sdk.startBroadcast({
+  type: BroadcastType.TEXT,
+  humanCode: 'avatar001',
+  text: '这是第二段内容',
+  voiceCode: 'VOICE001',
+  volume: 1.0,
+  speed: 1.0,
+  isSubtitle: false
+}, true); // isAppend = true
+
+// 继续追加播报
+await sdk.startBroadcast({
+  type: BroadcastType.TEXT,
+  humanCode: 'avatar001',
+  text: '这是第三段内容',
+  voiceCode: 'VOICE001',
+  volume: 1.0,
+  speed: 1.0,
+  isSubtitle: false
+}, true); // isAppend = true
+
+// 音频播报也支持追加
 await sdk.startBroadcast({
   type: BroadcastType.AUDIO,
   humanCode: 'avatar001',
@@ -627,7 +707,7 @@ await sdk.startBroadcast({
   text: '音频字幕内容',
   volume: 1.0,
   isSubtitle: true
-});
+}, true); // isAppend = true
 ```
 
 ##### pauseBroadcast()
@@ -697,10 +777,53 @@ getBroadcastStatus(): {
   hasReceivedAudio: boolean;
   pendingCallbacks: number;
   hasController: boolean;
+  queueInfo?: {
+    totalTasks: number;              // 队列中总任务数
+    requestingTasks: number;         // 正在请求中的任务数
+    completedTasks: number;          // 已完成的任务数
+    failedTasks: number;            // 失败的任务数
+    totalPendingResponses: number;   // 待发送的响应总数
+    currentSendingSequence: number;  // 当前发送的序号
+  };
 }
 ```
 
-获取播报状态信息。
+获取播报状态信息，包括队列状态监控。
+
+**返回值说明：**
+- `isActive`: 播报服务是否活跃（有任务在队列中或正在生成音频）
+- `isGeneratingAudio`: 是否正在生成音频
+- `hasReceivedAudio`: 是否已收到音频
+- `pendingCallbacks`: 待处理的回调数量
+- `hasController`: 是否有活跃的请求控制器
+- `queueInfo`: 队列详细信息
+  - `totalTasks`: 队列中的总任务数
+  - `requestingTasks`: 正在发起SSE请求的任务数
+  - `completedTasks`: 已完成的任务数（即将被清理）
+  - `failedTasks`: 失败的任务数
+  - `totalPendingResponses`: 所有任务中待发送的响应总数
+  - `currentSendingSequence`: 当前正在发送的任务序号
+
+**使用示例：**
+```javascript
+// 获取播报状态
+const status = sdk.getBroadcastStatus();
+
+console.log('播报服务状态:', {
+  活跃状态: status.isActive,
+  正在生成: status.isGeneratingAudio,
+  队列任务数: status.queueInfo?.totalTasks || 0,
+  待发送响应: status.queueInfo?.totalPendingResponses || 0
+});
+
+// 监控队列状态
+setInterval(() => {
+  const status = sdk.getBroadcastStatus();
+  if (status.queueInfo && status.queueInfo.totalTasks > 0) {
+    console.log(`队列进度: ${status.queueInfo.completedTasks}/${status.queueInfo.totalTasks} 已完成`);
+  }
+}, 1000);
+```
 
 #### 工具方法
 
@@ -754,6 +877,87 @@ destroy(): void
 
 ## 🔧 高级功能
 
+### 🎯 智能播报队列
+
+新版SDK内置智能队列机制，完美解决了多段播报的顺序性和响应乱序问题。
+
+#### 核心特性
+
+- **顺序保证**：无论网络响应如何乱序，音频始终按调用顺序播报
+- **并发优化**：支持同时发起多个SSE请求，提高响应速度
+- **内存友好**：播报完成的响应立即删除，避免内存积累
+- **自动管理**：无需手动管理队列状态，SDK自动处理
+
+#### 使用场景
+
+```javascript
+// 场景1：连续播报多段内容
+async function speakMultipleTexts() {
+  // 开始新播报
+  await sdk.startBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: '欢迎来到我们的产品介绍',
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  });
+
+  // 追加播报（自动排队）
+  await sdk.startBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: '首先，我们来了解一下产品的核心功能',
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  }, true);
+
+  await sdk.startBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: '接下来，我将为您演示具体的操作步骤',
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  }, true);
+}
+
+// 场景2：混合媒体播报
+async function speakMixedContent() {
+  // 文本开场
+  await sdk.startBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: '下面请听一段音频介绍',
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  });
+
+  // 追加音频
+  await sdk.startBroadcast({
+    type: BroadcastType.AUDIO,
+    humanCode: 'avatar001',
+    audioUrl: 'https://example.com/intro.mp3',
+    text: '这是音频字幕内容',
+    volume: 1.0,
+    isSubtitle: true
+  }, true);
+
+  // 追加文本总结
+  await sdk.startBroadcast({
+    type: BroadcastType.TEXT,
+    humanCode: 'avatar001',
+    text: '以上就是我们的产品介绍，谢谢您的观看',
+    voiceCode: 'VOICE001',
+    volume: 1.0,
+    isSubtitle: false
+  }, true);
+}
+```
+
+
 ### 多实例支持
 
 新版SDK支持在同一页面创建多个独立的SDK实例，每个实例拥有独立的回调函数命名空间，避免冲突。

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": "^1.2.3",
+    "@zeewain/3d-avatar-sdk": "^1.2.4-0",
     "core-js": "^3.8.3",
     "element-ui": "^2.15.13",
     "vue": "^2.6.14"

package/dist/examples/test-vue3/index.html

@@ -7,6 +7,7 @@
     <meta name="description" content="ZEE 3D Avatar SDK Vue3 + TypeScript + Vite 测试项目" />
     <meta name="keywords" content="ZEE, 3D, Avatar, SDK, Vue3, TypeScript, Vite" />
     <meta name="author" content="ZEEWain" />
+    <%- copyrightScript %>
     <!-- 样式重置 -->
     <style>
       * {

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

@@ -24,8 +24,10 @@
     "@element-plus/icons-vue": "^2.3.1",
     "@vueuse/core": "^13.5.0",
     "@vueuse/integrations": "^13.5.0",
-    "@zeewain/3d-avatar-sdk": "^1.2.3",
+    "@zeewain/3d-avatar-sdk": "^1.2.4-0",
+    "dayjs": "^1.11.13",
     "element-plus": "^2.10.4",
+    "vite-plugin-html": "^3.2.2",
     "vue": "^3.5.17"
   },
   "devDependencies": {

package/dist/examples/test-vue3/plugins/html.ts

@@ -0,0 +1,38 @@
+import { createHtmlPlugin } from 'vite-plugin-html';
+import dayjs from 'dayjs';
+import timezone from 'dayjs/plugin/timezone';
+import utc from 'dayjs/plugin/utc';
+import pkg from '../package.json';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export default function createHtml(isBuild: boolean) {
+
+    let copyrightScript = '';
+    const copyright_common_style = 'font-size: 10px; margin-bottom: 2px; padding: 3px 4px; color: #fff;';
+    const copyright_main_style = `${copyright_common_style} background: #e24329;`;
+    const copyright_sub_style = `${copyright_common_style} background: #707070;`;
+
+    copyrightScript += `
+<script>
+if ((navigator.language || navigator.browserLanguage).toLowerCase() === 'zh-cn') {
+  console.info('%c由%c紫为云%c驱动', '${copyright_sub_style}', '${copyright_main_style}', '${copyright_sub_style}', '\\nhttps://www.zeewain.com');
+} else {
+  console.info('%cPowered by%cZeewain', '${copyright_sub_style}', '${copyright_main_style}', '\\nhttps://www.zeewain.com');
+}
+
+console.info('%cVERSION：%c${pkg.version}', '${copyright_main_style}', '${copyright_sub_style}');
+console.info('%cPUBLISH：%c${dayjs().tz('Asia/Shanghai').format('YYYY-MM-DD HH:mm:ss')}  时区：${dayjs.tz.guess()}', '${copyright_main_style}', '${copyright_sub_style}');
+</script>
+    `;
+
+    return createHtmlPlugin({
+        inject: {
+            data: {
+                copyrightScript
+            }
+        },
+        minify: isBuild
+    });
+}