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

package/README.md

@@ -48,7 +48,7 @@
 >   - 示例：SDK版本为 2.1.3，则 `assetsUrl` 应配置为：`https://cdn.zeewain3d.com/webgl/2.1`
 > 
 > **3. 动作资源扩展（可选）**
-> - 动作资源可单独从开放平台下载**（版本号前两位也必须跟SDK版本号一致）**，下载后解压到资源包所在目录即可。
+> - 动作资源可单独从开放平台下载（**版本号前两位也必须跟SDK版本号一致**），下载后解压到资源包所在目录即可（**覆盖合并**）。
 > - 新增的动作将自动集成到现有资源体系中。
 > 
 > **⚠️ 版本兼容性要求**
@@ -516,6 +516,7 @@ interface IAvatarSDKConfig {
   env?: 'dev' | 'test' | 'prod' | 'custom';  // 运行环境，默认'prod'
   apiUrl?: string;            // 自定义API地址（env='custom'时需要）
   idleMotionList?: string[];  // 待机动作编码列表，随机播放（排重方式），可选
+  operationTimeout?: number;  // 操作超时时间（毫秒），默认30000ms，可选
   
   // 回调函数
   onProgress?: (progress: number) => void;  // 加载进度回调，可选
@@ -690,9 +691,39 @@ interface IBroadcastParams {
 **🚀 播报队列特性：**
 - **智能排队**：多次追加播报自动按调用顺序排队
 - **顺序保证**：即使网络响应乱序，也确保音频按序播报
-- **高效处理**：支持并发请求，同时保证播报顺序
+- **串行请求**：队列中的任务按顺序依次请求，避免占用过多并发
 - **自动清理**：已播报内容自动从队列中移除，节省内存
 
+**💡 队列播报最佳实践（GPT流式场景）：**
+
+针对大模型流式响应的播报队列场景，推荐以下分段策略以优化首句响应速度和服务调用次数：
+
+| 段落序号 | 建议字数 | 说明 |
+|:--------:|:--------:|:-----|
+| 第1段 | 20-30字 | 快速响应，减少用户等待时间 |
+| 第2段 | 80字左右 | 适中长度，平衡响应速度 |
+| 第3段及以后 | 200-250字 | 较长文本，节省服务调用次数 |
+
+```javascript
+// 示例：智能分段播报
+async function smartBroadcast(textStream) {
+  const segments = splitTextSmartly(textStream); // 按上述策略分段
+  
+  for (let i = 0; i < segments.length; i++) {
+    await sdk.startBroadcast({
+      type: BroadcastType.TEXT,
+      humanCode: 'avatar001',
+      text: segments[i],
+      voiceCode: 'VOICE001',
+      volume: 1.0,
+      isSubtitle: false
+    }, i > 0); // 第一段 isAppend=false，后续 isAppend=true
+  }
+}
+```
+
+> **优势**：此策略能在不影响播放流畅度的情况下，有效减少API调用次数，降低服务成本。
+
 **使用示例：**
 ```javascript
 // 开始新的播报（清空队列）
@@ -806,9 +837,10 @@ getBroadcastStatus(): {
   hasReceivedAudio: boolean;
   queueInfo?: {
     totalTasks: number;              // 队列中总任务数
+    pendingTasks: number;            // 等待请求的任务数
     requestingTasks: number;         // 正在请求中的任务数
     completedTasks: number;          // 已完成的任务数
-    failedTasks: number;            // 失败的任务数
+    failedTasks: number;             // 失败的任务数
     totalPendingResponses: number;   // 待发送的响应总数
     currentSendingSequence: number;  // 当前发送的序号
   };
@@ -823,6 +855,7 @@ getBroadcastStatus(): {
 - `hasReceivedAudio`: 是否已收到至少一条音频数据
 - `queueInfo`: 队列详细信息
   - `totalTasks`: 队列中的总任务数
+  - `pendingTasks`: 等待请求的任务数（尚未开始请求）
   - `requestingTasks`: 正在发起SSE请求的任务数
   - `completedTasks`: 已完成的任务数（即将被清理）
   - `failedTasks`: 失败的任务数
@@ -838,6 +871,7 @@ console.log('播报服务状态:', {
   活跃状态: status.isActive,
   正在生成: status.isGeneratingAudio,
   队列任务数: status.queueInfo?.totalTasks || 0,
+  等待请求: status.queueInfo?.pendingTasks || 0,
   待发送响应: status.queueInfo?.totalPendingResponses || 0
 });
 
@@ -845,7 +879,7 @@ console.log('播报服务状态:', {
 setInterval(() => {
   const status = sdk.getBroadcastStatus();
   if (status.queueInfo && status.queueInfo.totalTasks > 0) {
-    console.log(`队列进度: ${status.queueInfo.completedTasks}/${status.queueInfo.totalTasks} 已完成`);
+    console.log(`队列进度: 等待${status.queueInfo.pendingTasks} / 请求中${status.queueInfo.requestingTasks} / 已完成${status.queueInfo.completedTasks}`);
   }
 }, 1000);
 ```

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.2",
+    "@zeewain/3d-avatar-sdk": "^2.1.4",
     "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.2",
+    "@zeewain/3d-avatar-sdk": "^2.1.4",
     "dayjs": "^1.11.13",
     "element-plus": "^2.10.4",
     "vite-plugin-html": "^3.2.2",

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

@@ -463,6 +463,7 @@ async function handleTextBroadcast(params: {
   voiceCode?: string;
   speed?: number;
   broadcastMotionString?: string;
+  isAppend?: boolean; // 队列播报模式下会传递此参数
 }): Promise<void> {
   if (!sdk.value) return;
 
@@ -481,9 +482,12 @@ async function handleTextBroadcast(params: {
       motionPlayMode: 'random'
     };
 
-    console.warn('handleTextBroadcast: ', broadcastParams, sdkStatus.isStartBroadcast);
-    await sdk.value.startBroadcast(broadcastParams, sdkStatus.isStartBroadcast);
-    addLog('文本播报已开始', 'success');
+    // 队列播报模式下使用传入的isAppend参数，单次播报模式下使用sdkStatus.isStartBroadcast
+    const isAppend = params.isAppend !== undefined ? params.isAppend : sdkStatus.isStartBroadcast;
+
+    console.warn('handleTextBroadcast: ', broadcastParams, isAppend);
+    addLog(`${isAppend ? '追加播报' : '开始播报'}:${JSON.stringify({'isAppend': isAppend})}`, 'success');
+    await sdk.value.startBroadcast(broadcastParams, isAppend);
     // ElMessage.success('文本播报已开始');
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

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

@@ -54,7 +54,16 @@
 
           <!-- 文本播报表单 -->
           <div v-if="broadcastMode === 'text'" class="form-content">
-            <el-form :model="textFormData" label-width="80px" size="default">
+            <!-- 文本播报子模式选择 -->
+            <div class="text-mode-tabs">
+              <el-tabs v-model="textBroadcastMode" type="card">
+                <el-tab-pane label="单次播报" name="single" />
+                <el-tab-pane label="队列播报" name="queue" />
+              </el-tabs>
+            </div>
+
+            <!-- 单次播报表单 -->
+            <el-form v-if="textBroadcastMode === 'single'" :model="textFormData" label-width="80px" size="default">
               <el-form-item label="播报文本" required>
                 <el-input
                   v-model="textFormData.text"
@@ -129,6 +138,120 @@
                 </div>
               </el-form-item>
             </el-form>
+
+            <!-- 队列播报表单 -->
+            <el-form v-if="textBroadcastMode === 'queue'" :model="queueFormData" label-width="80px" size="default">
+              <el-form-item label="队列文本" required>
+                <el-input
+                  v-model="queueFormData.queueTexts"
+                  type="textarea"
+                  :rows="8"
+                  placeholder="请输入多段播报文本，每行一段（模拟GPT流式输出）..."
+                  :disabled="!sdkStatus.canBroadcast || isQueueBroadcasting"
+                  maxlength="2000"
+                  show-word-limit
+                />
+                <div class="input-help">
+                  <span class="help-text">
+                    每行一段文本，将按顺序依次播报，默认每间隔500ms调用一次SDK
+                  </span>
+                </div>
+              </el-form-item>
+
+              <el-form-item label="音色编码" required>
+                <el-input
+                  v-model="queueFormData.voiceCode"
+                  placeholder="请输入音色编码"
+                  prefix-icon="microphone"
+                  :disabled="!sdkStatus.canBroadcast || isQueueBroadcasting"
+                />
+              </el-form-item>
+
+              <el-form-item label="音量" required>
+                <el-slider
+                  v-model="queueFormData.volume"
+                  :min="0"
+                  :max="1"
+                  :step="0.1"
+                  :disabled="!sdkStatus.canBroadcast || isQueueBroadcasting"
+                  show-input
+                />
+              </el-form-item>
+
+              <el-form-item label="语速">
+                <el-slider
+                  v-model="queueFormData.speed"
+                  :min="0.5"
+                  :max="2.0"
+                  :step="0.1"
+                  :disabled="!sdkStatus.canBroadcast || isQueueBroadcasting"
+                  show-input
+                />
+              </el-form-item>
+
+              <el-form-item label="动作列表">
+                <el-input
+                  v-model="queueFormData.broadcastMotionString"
+                  placeholder="请输入动作列表"
+                  :disabled="isQueueBroadcasting"
+                />
+                <div class="input-help">
+                  <span class="help-text">
+                    动作编码列表，多个动作编码用逗号分隔
+                  </span>
+                </div>
+              </el-form-item>
+
+              <el-form-item label="发送间隔">
+                <el-input-number
+                  v-model="queueFormData.interval"
+                  :min="100"
+                  :max="5000"
+                  :step="100"
+                  :disabled="isQueueBroadcasting"
+                />
+                <span class="interval-unit">毫秒</span>
+                <div class="input-help">
+                  <span class="help-text">
+                    每段文本之间的发送间隔（模拟GPT流式输出），建议100-1000ms
+                  </span>
+                </div>
+              </el-form-item>
+
+              <!-- 队列播报进度 -->
+              <el-form-item v-if="isQueueBroadcasting || queueProgress.total > 0" label="队列进度">
+                <div class="queue-progress">
+                  <el-progress
+                    :percentage="queueProgressPercent"
+                    :status="queueProgress.current === queueProgress.total ? 'success' : ''"
+                  />
+                  <span class="progress-text">
+                    已发送{{ queueProgress.current }} / 总数{{ queueProgress.total }}
+                  </span>
+                </div>
+              </el-form-item>
+
+              <el-form-item class="action-buttons">
+                <div class="action-buttons-container">
+                  <el-button
+                    type="primary"
+                    :loading="isQueueBroadcasting"
+                    :disabled="!sdkStatus.canBroadcast || !queueFormData.queueTexts.trim() || !queueFormData.voiceCode || !globalConfig.avatarCode || isQueueBroadcasting"
+                    @click="handleQueueBroadcast"
+                  >
+                    {{ isQueueBroadcasting ? `播报中 (${queueProgress.current}/${queueProgress.total})...` : '执行队列播报' }}
+                  </el-button>
+                  <el-button
+                    type="info"
+                    size="default"
+                    style="width: 170px;"
+                    :disabled="isQueueBroadcasting"
+                    @click="handleGetBroadcastStatus">
+                        获取播报状态
+                   </el-button>
+                </div>
+              </el-form-item>
+            </el-form>
           </div>
 
           <!-- 音频播报表单 -->
@@ -295,7 +418,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, reactive, watch, onMounted } from 'vue';
+import { ref, reactive, watch, onMounted, computed } from 'vue';
 import { ElMessage } from 'element-plus';
 import { VideoPause, VideoPlay, Close, Refresh } from '@element-plus/icons-vue';
 import { loadFromCache, saveToCache } from '@/utils';
@@ -323,12 +446,15 @@ const emit = defineEmits<{
 
 // 本地缓存键名常量
 const BROADCAST_MODE_CACHE_KEY = 'broadcast-mode';
+const TEXT_BROADCAST_MODE_CACHE_KEY = 'text-broadcast-mode';
 const TEXT_FORM_CACHE_KEY = 'broadcast-text-form-data';
+const QUEUE_FORM_CACHE_KEY = 'broadcast-queue-form-data';
 const AUDIO_FORM_CACHE_KEY = 'broadcast-audio-form-data';
 
 
 // 初始化表单数据，优先从缓存加载
 const broadcastMode = ref<'text' | 'audio'>(loadFromCache(BROADCAST_MODE_CACHE_KEY, 'text')!);
+const textBroadcastMode = ref<'single' | 'queue'>(loadFromCache(TEXT_BROADCAST_MODE_CACHE_KEY, 'single')!);
 
 const textFormData = reactive(loadFromCache(TEXT_FORM_CACHE_KEY, {
   text: '欢迎使用ZEEAvatarSDK智能体播报功能。这是一个强大的数字人解决方案，支持文本和音频两种播报模式，让您的应用更具互动性！',
@@ -338,6 +464,16 @@ const textFormData = reactive(loadFromCache(TEXT_FORM_CACHE_KEY, {
   broadcastMotionString: 'DH_ACTION_MODEL103_000003,DH_ACTION_MODEL103_000005',
 })!);
 
+// 队列播报表单数据
+const queueFormData = reactive(loadFromCache(QUEUE_FORM_CACHE_KEY, {
+  queueTexts: '你好，欢迎使用队列播报功能。\n这是第二段文本，将在指定间隔后发送。\n第三段文本模拟GPT流式输出。\n最后一段文本，队列播报即将完成。',
+  volume: 1.0,
+  speed: 1.0,
+  voiceCode: 'VOICE_EXT_W_000011',
+  broadcastMotionString: 'DH_ACTION_MODEL103_000003,DH_ACTION_MODEL103_000005',
+  interval: 500, // 发送间隔，默认500ms
+})!);
+
 const audioFormData = reactive(loadFromCache(AUDIO_FORM_CACHE_KEY, {
   audioText: '欢迎使用ZEEAvatarSDK智能体播报功能',
   audioUrl: 'https://example.com/audio/sample.mp3',
@@ -354,6 +490,17 @@ const pauseLoading = ref(false);
 const resumeLoading = ref(false);
 const stopLoading = ref(false);
 
+// 队列播报相关状态
+const isQueueBroadcasting = ref(false);
+const queueProgress = reactive({
+  current: 0,
+  total: 0
+});
+const queueProgressPercent = computed(() => {
+  if (queueProgress.total === 0) return 0;
+  return Math.round((queueProgress.current / queueProgress.total) * 100);
+});
+
 // 监听表单数据变化，自动保存到本地缓存
 watch(
   broadcastMode,
@@ -362,6 +509,13 @@ watch(
   }
 );
 
+watch(
+  textBroadcastMode,
+  (newMode) => {
+    saveToCache(TEXT_BROADCAST_MODE_CACHE_KEY, newMode);
+  }
+);
+
 watch(
   textFormData,
   (newData) => {
@@ -370,6 +524,14 @@ watch(
   { deep: true }
 );
 
+watch(
+  queueFormData,
+  (newData) => {
+    saveToCache(QUEUE_FORM_CACHE_KEY, newData);
+  },
+  { deep: true }
+);
+
 watch(
   audioFormData,
   (newData) => {
@@ -382,7 +544,9 @@ watch(
 onMounted(() => {
   console.log('BroadcastAPI: 已从本地缓存加载表单数据', {
     broadcastMode: broadcastMode.value,
+    textBroadcastMode: textBroadcastMode.value,
     textFormData: textFormData,
+    queueFormData: queueFormData,
     audioFormData: audioFormData
   });
 });
@@ -417,6 +581,75 @@ async function handleTextBroadcast() {
   }
 }
 
+async function handleQueueBroadcast() {
+  const { queueTexts, volume, speed, voiceCode, broadcastMotionString, interval } = queueFormData;
+  const { avatarCode } = props.globalConfig;
+
+  if (!avatarCode) {
+    result.value = '❌ 请先在全局配置中设置Avatar Code';
+    ElMessage.warning('请先设置Avatar Code');
+    return;
+  }
+
+  if (!queueTexts.trim() || !voiceCode) {
+    result.value = '❌ 队列文本和音色编码不能为空';
+    ElMessage.warning('请填写完整的播报信息');
+    return;
+  }
+
+  // 解析文本为数组，过滤空行
+  const textLines = queueTexts.split('\n').filter(line => line.trim());
+  if (textLines.length === 0) {
+    result.value = '❌ 请至少输入一段播报文本';
+    ElMessage.warning('请至少输入一段播报文本');
+    return;
+  }
+
+  isQueueBroadcasting.value = true;
+  queueProgress.current = 0;
+  queueProgress.total = textLines.length;
+
+  result.value = `🔄 开始队列播报...\n📝 共 ${textLines.length} 段文本\n🎤 音色编码: ${voiceCode}\n🔊 音量: ${volume}\n⚡ 语速: ${speed}\n⏱️ 发送间隔: ${interval}ms\n\n📡 模拟GPT流式输出...`;
+
+  try {
+    for (let i = 0; i < textLines.length; i++) {
+      const text = textLines[i].trim();
+      const isAppend = i > 0; // 第一个不是追加，后续都是追加
+
+      queueProgress.current = i + 1;
+      result.value = `🔄 队列播报中...\n📝 正在发送第 ${i + 1}/${textLines.length} 段\n📄 文本: ${text.substring(0, 30)}${text.length > 30 ? '...' : ''}\n${isAppend ? '📎 追加模式' : '🆕 新播报'}\n\n⏳ 进度: ${queueProgress.current}/${queueProgress.total}`;
+
+      // 发送播报请求
+      emit('text-broadcast', {
+        avatarCode,
+        text,
+        volume,
+        speed,
+        voiceCode,
+        broadcastMotionString,
+        isAppend
+      });
+
+      // 如果不是最后一个，等待配置的间隔时间再发送下一个
+      if (i < textLines.length - 1) {
+        await new Promise(resolve => setTimeout(resolve, interval));
+      }
+    }
+
+    result.value = `✅ 队列播报请求已全部发送完成\n📋 共发送 ${textLines.length} 段文本\n📡 SDK正在按顺序处理队列...\n\n📝 说明：\n- 第一段以新播报方式发送\n- 后续段落以追加模式发送\n- 每段间隔${interval}ms发送\n- 请查看右侧日志面板获取详细信息`;
+
+    // 延迟重置状态，让用户看到完成提示
+    setTimeout(() => {
+      isQueueBroadcasting.value = false;
+    }, 1000);
+
+  } catch (error: any) {
+    isQueueBroadcasting.value = false;
+    result.value = `❌ 队列播报失败: ${error.message}\n\n🔍 可能的原因：\n- 网络连接问题\n- 音色编码不存在\n- 服务器繁忙`;
+    ElMessage.error(`队列播报失败: ${error.message}`);
+  }
+}
+
 async function handleAudioBroadcast() {
   const { audioText, audioUrl, volume, broadcastMotionString } = audioFormData;
   const { avatarCode } = props.globalConfig;
@@ -559,6 +792,18 @@ function clearResult() {
           }
         }
         .form-content {
+          .text-mode-tabs {
+            margin-bottom: 15px;
+            :deep(.el-tabs__header) {
+              margin-bottom: 0;
+            }
+            :deep(.el-tabs__item) {
+              font-weight: 500;
+              &.is-active {
+                color: #409eff;
+              }
+            }
+          }
           .el-form-item {
             margin-bottom: 18px;
             :deep(.el-form-item__label) {
@@ -587,6 +832,29 @@ function clearResult() {
                 line-height: 1.4;
               }
             }
+            .interval-unit {
+              margin-left: 8px;
+              font-size: 13px;
+              color: #606266;
+            }
+            .queue-progress {
+              display: flex;
+              align-items: center;
+              gap: 15px;
+              width: 100%;
+              .el-progress {
+                flex: 1;
+                :deep(.el-progress__text) {
+                  min-width: 20px;
+                }
+              }
+              .progress-text {
+                font-size: 12px;
+                color: #606266;
+                font-weight: 500;
+                white-space: nowrap;
+              }
+            }
           }
         }