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

package/dist/index.umd.cjs

@@ -1513,6 +1513,20 @@
      * @fileoverview 流式播报服务重构实现模块
      * @description 提供流式播报服务的重构实现，继承Unity基础服务，支持文本转语音和自定义音频播报
      */
+    /**
+     * 播报任务状态枚举
+     */
+    var BroadcastTaskStatus;
+    (function (BroadcastTaskStatus) {
+        /** 请求中 */
+        BroadcastTaskStatus["REQUESTING"] = "requesting";
+        /** 已完成 */
+        BroadcastTaskStatus["COMPLETED"] = "completed";
+        /** 失败 */
+        BroadcastTaskStatus["FAILED"] = "failed";
+        /** 已取消 */
+        BroadcastTaskStatus["CANCELLED"] = "cancelled";
+    })(BroadcastTaskStatus || (BroadcastTaskStatus = {}));
     /**
      * 流式播报服务重构类
      * @class BroadcastServiceRefactored
@@ -1542,12 +1556,20 @@
             super(config);
             /** 事件回调函数集合 */
             this.callbacks = {};
-            /** 请求控制器，用于取消请求 */
-            this.activeController = null;
+            /** 播报任务队列 */
+            this.taskQueue = [];
+            /** 任务序号计数器 */
+            this.taskSequence = 0;
+            /** 当前发送任务的序号 */
+            this.currentSendingSequence = 0;
             /** 是否正在生成音频 */
             this.isGeneratingAudio = false;
             /** 是否已经收到音频 */
             this.hasReceivedAudio = false;
+            /** 队列处理定时器 */
+            this.queueProcessTimer = null;
+            /** 主请求控制器（兼容性保留） */
+            this.activeController = null;
             this.callbacks = config.callbacks || {};
             this.logger.info('Broadcast service initialized', { config });
         }
@@ -1596,8 +1618,9 @@
         /**
          * 开始播报
          * @param params - 播报参数
+         * @param isAppend - 是否追加播报
          * @returns Promise<void> 播报操作的Promise
-         * @description 开始流式播报，支持文本转语音和自定义音频播报
+         * @description 开始流式播报，支持文本转语音和自定义音频播报。使用队列机制确保音频按序播报
          * @throws {SDKError} 当参数验证失败或播报失败时抛出错误
          * @example
          * ```typescript
@@ -1611,130 +1634,54 @@
          *   isSubtitle: true
          * });
          *
-         * // 自定义音频播报
+         * // 追加播报（会进入队列按序播报）
          * await broadcastService.startBroadcast({
-         *   type: BroadcastType.AUDIO,
+         *   type: BroadcastType.TEXT,
          *   humanCode: 'human001',
-         *   audioUrl: 'https://example.com/audio.mp3',
+         *   text: '这是第二段内容',
+         *   voiceCode: 'voice001',
          *   volume: 0.8,
-         *   isSubtitle: false
-         * });
+         *   isSubtitle: true
+         * }, true);
          * ```
          */
-        startBroadcast(params) {
+        startBroadcast(params, isAppend) {
             return __awaiter(this, void 0, void 0, function* () {
                 var _a, _b;
-                this.logger.info(`Starting broadcast: ${params.type}`, { humanCode: params.humanCode });
+                this.logger.info(`Starting broadcast: ${params.type}`, {
+                    humanCode: params.humanCode,
+                    isAppend,
+                    queueLength: this.taskQueue.length
+                });
                 // 验证参数
                 this.validateBroadcastParams(params);
-                // 先停止当前播报
-                yield this.stopBroadcast();
-                // 创建新的请求控制器
-                this.activeController = new AbortController();
-                // 监听中断信号
-                this.activeController.signal.addEventListener('abort', () => {
-                    var _a, _b;
-                    console.warn('abort');
-                    // 如果正在生成音频，触发中断回调
-                    if (this.isGeneratingAudio) {
-                        (_b = (_a = this.callbacks).onAbort) === null || _b === void 0 ? void 0 : _b.call(_a);
-                    }
-                    // 重置状态
-                    this.isGeneratingAudio = false;
-                    this.hasReceivedAudio = false;
-                    this.activeController = null;
-                });
-                // 通知Unity开始新任务（清空队列）
-                this.sendMessage('StartBroadcast', {
-                    callbackFun: this.uniqueCallbackName,
-                    operationType: exports.BroadcastOperationType.START_BROADCAST,
-                    motionList: params.motionList,
-                    motionPlayMode: params.motionPlayMode
-                });
-                try {
-                    const apiUrl = `${ConfigManager.getInstance().getApiBaseUrl(true)}${this.getBroadcastApiPath(params.type)}`;
-                    const requestBody = {
-                        humanCode: params.humanCode,
-                        speed: params.speed,
-                        volume: params.volume >= 0 ? params.volume * 100 : undefined, // 转换为百分比
-                        isSubtitle: params.isSubtitle
-                    };
-                    // 根据播报类型设置特定参数
-                    if (params.type === exports.BroadcastType.TEXT) {
-                        requestBody.text = params.text;
-                        requestBody.voiceCode = params.voiceCode;
-                    }
-                    else if (params.type === exports.BroadcastType.AUDIO) {
-                        requestBody.text = params.text;
-                        requestBody.audioUrl = params.audioUrl;
-                    }
-                    this.logger.debug('Sending broadcast request', { apiUrl, requestBody });
+                // 非追加模式下需要初始化播报
+                if (!isAppend) {
+                    // 先停止当前播报并清空队列
+                    yield this.stopBroadcast();
+                    // 重置序号计数器
+                    this.taskSequence = 0;
+                    this.currentSendingSequence = 0;
+                    // 通知Unity开始新任务（清空队列）
+                    this.sendMessage('StartBroadcast', {
+                        callbackFun: this.uniqueCallbackName,
+                        operationType: exports.BroadcastOperationType.START_BROADCAST,
+                        motionList: params.motionList,
+                        motionPlayMode: params.motionPlayMode
+                    });
                     // 触发开始回调
                     (_b = (_a = this.callbacks).onStart) === null || _b === void 0 ? void 0 : _b.call(_a);
                     this.isGeneratingAudio = true;
-                    // 发起流式播报请求
-                    yield fetchEventSource(apiUrl, {
-                        method: 'POST',
-                        headers: {
-                            'Content-Type': 'application/json',
-                            'x_auth_token': ConfigManager.getInstance().getToken()
-                        },
-                        body: JSON.stringify(requestBody),
-                        signal: this.activeController.signal,
-                        openWhenHidden: true,
-                        onmessage: (event) => {
-                            const response = JSON.parse(event.data);
-                            // 错误处理
-                            if (response.code !== 0) {
-                                this.handleBroadcastError(response.code);
-                                return;
-                            }
-                            // 流式播报
-                            if (response.data) {
-                                // 未完成播报时，更新任务ID
-                                if (!response.data.done) {
-                                    this.hasReceivedAudio = true;
-                                }
-                                // 自定义音频播报时，如果服务器未返回音频URL，使用传入的audioUrl
-                                if (params.type === exports.BroadcastType.AUDIO && params.audioUrl && !response.data.voiceUrl) {
-                                    response.data.voiceUrl = params.audioUrl;
-                                }
-                                // 如果有音频URL，发送到Unity
-                                if (response.data.voiceUrl) {
-                                    this.sendMessage('AppendBroadcast', {
-                                        response,
-                                        callbackFun: this.uniqueCallbackName,
-                                        operationType: exports.BroadcastOperationType.APPEND_BROADCAST
-                                    });
-                                }
-                                if (response.data.done) {
-                                    this.isGeneratingAudio = false;
-                                    this.hasReceivedAudio = false;
-                                    this.activeController = null;
-                                }
-                            }
-                        },
-                        onclose: () => {
-                            var _a;
-                            // 如果不是由abort触发的关闭，需要处理
-                            if (this.isGeneratingAudio) {
-                                (_a = this.activeController) === null || _a === void 0 ? void 0 : _a.abort();
-                            }
-                            // 流结束时调用完成回调
-                            this.logger.debug('Broadcast stream closed');
-                        },
-                        onerror: (error) => {
-                            this.logger.error('Broadcast stream error', error);
-                            const sdkError = new SDKError(exports.OperationErrorCode.OPERATION_FAILED, '服务出错了', error);
-                            this.handleError(sdkError);
-                            // 必须抛出错误，否则会循环重试请求
-                            throw new Error(`服务出错了${sdkError.message}`);
-                        }
-                    });
-                }
-                catch (error) {
-                    this.handleError(error);
                 }
+                // 创建新的播报任务
+                const task = this.createBroadcastTask(params);
+                // 添加任务到队列
+                this.addTaskToQueue(task);
+                this.logger.debug('Broadcast task created and queued', {
+                    taskId: task.id,
+                    sequence: task.sequence,
+                    isAppend
+                });
             });
         }
         /**
@@ -1795,12 +1742,12 @@
          */
         stopBroadcast() {
             return __awaiter(this, void 0, void 0, function* () {
-                this.logger.info('Stopping broadcast');
-                // 取消流式请求
-                if (this.activeController) {
-                    this.activeController.abort();
-                    this.activeController = null;
-                }
+                this.logger.info('Stopping broadcast and clearing queue', { queueLength: this.taskQueue.length });
+                // 取消所有队列中的任务
+                this.cancelAllTasks();
+                // 重置状态
+                this.isGeneratingAudio = false;
+                this.hasReceivedAudio = false;
                 try {
                     yield this.sendAsyncMessage('StopBroadcast', exports.BroadcastOperationType.STOP_BROADCAST, {});
                     this.logger.info('Broadcast stopped successfully');
@@ -1823,15 +1770,23 @@
         /**
          * 获取播报状态
          * @returns 播报状态信息
-         * @description 获取当前播报服务的状态信息
+         * @description 获取当前播报服务的状态信息，包括队列状态
          */
         getStatus() {
             return {
-                isActive: this.activeController !== null,
+                isActive: this.taskQueue.length > 0 || this.isGeneratingAudio,
                 isGeneratingAudio: this.isGeneratingAudio,
                 hasReceivedAudio: this.hasReceivedAudio,
                 pendingCallbacks: this.getPendingCallbackCount(),
-                hasController: this.activeController !== null
+                hasController: this.activeController !== null,
+                queueInfo: {
+                    totalTasks: this.taskQueue.length,
+                    requestingTasks: this.taskQueue.filter((t) => t.status === BroadcastTaskStatus.REQUESTING).length,
+                    completedTasks: this.taskQueue.filter((t) => t.status === BroadcastTaskStatus.COMPLETED).length,
+                    failedTasks: this.taskQueue.filter((t) => t.status === BroadcastTaskStatus.FAILED).length,
+                    totalPendingResponses: this.taskQueue.reduce((sum, t) => sum + t.pendingResponses.length, 0),
+                    currentSendingSequence: this.currentSendingSequence
+                }
             };
         }
         /**
@@ -1839,15 +1794,268 @@
          * @description 清理所有资源和回调
          */
         destroy() {
-            // 停止当前播报
-            if (this.activeController) {
-                this.activeController.abort();
-                this.activeController = null;
+            // 清理队列处理定时器
+            if (this.queueProcessTimer) {
+                clearInterval(this.queueProcessTimer);
+                this.queueProcessTimer = null;
             }
+            // 取消所有任务
+            this.cancelAllTasks();
             // 调用基类销毁方法
             super.destroy();
             this.logger.info('Broadcast service destroyed');
         }
+        /**
+         * 创建播报任务
+         * @param params - 播报参数
+         * @returns IBroadcastTask 播报任务对象
+         * @description 创建新的播报任务并分配唯一ID和序号
+         * @private
+         */
+        createBroadcastTask(params) {
+            const task = {
+                id: `broadcast_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+                sequence: ++this.taskSequence,
+                params,
+                status: BroadcastTaskStatus.REQUESTING,
+                controller: new AbortController(),
+                pendingResponses: [],
+                isGenerationComplete: false,
+                createdAt: new Date()
+            };
+            this.logger.debug('Created broadcast task', { taskId: task.id, sequence: task.sequence });
+            return task;
+        }
+        /**
+         * 添加任务到队列
+         * @param task - 播报任务
+         * @description 将任务添加到队列并立即开始请求
+         * @private
+         */
+        addTaskToQueue(task) {
+            this.taskQueue.push(task);
+            this.logger.debug('Task added to queue', { taskId: task.id, queueLength: this.taskQueue.length });
+            // 立即开始该任务的请求
+            this.startTaskRequest(task);
+            // 开始处理队列
+            this.processQueue();
+        }
+        /**
+         * 处理队列
+         * @description 处理队列中的任务，发起请求生成音频
+         * @private
+         */
+        processQueue() {
+            // 启动队列处理定时器（如果尚未启动）
+            if (!this.queueProcessTimer) {
+                this.queueProcessTimer = setInterval(() => {
+                    this.processQueueStep();
+                }, 100); // 每100ms检查一次队列状态
+            }
+            // 立即处理一次
+            this.processQueueStep();
+        }
+        /**
+         * 队列处理步骤
+         * @description 处理队列中的单个步骤，包括发起请求和发送音频
+         * @private
+         */
+        processQueueStep() {
+            // 按序号找到下一个要处理的任务
+            const nextTask = this.taskQueue.find((task) => task.sequence === this.currentSendingSequence + 1
+                && task.pendingResponses.length > 0);
+            if (nextTask) {
+                this.sendNextResponse(nextTask);
+            }
+            // 清理已完成的任务
+            this.cleanupCompletedTasks();
+            // 如果队列为空，停止定时器
+            if (this.taskQueue.length === 0 && this.queueProcessTimer) {
+                clearInterval(this.queueProcessTimer);
+                this.queueProcessTimer = null;
+            }
+        }
+        /**
+         * 开始任务请求
+         * @param task - 播报任务
+         * @description 为任务发起流式请求生成音频
+         * @private
+         */
+        startTaskRequest(task) {
+            return __awaiter(this, void 0, void 0, function* () {
+                task.status = BroadcastTaskStatus.REQUESTING;
+                this.logger.debug('Starting task request', { taskId: task.id });
+                try {
+                    const apiUrl = `${ConfigManager.getInstance().getApiBaseUrl(true)}${this.getBroadcastApiPath(task.params.type)}`;
+                    const requestBody = {
+                        humanCode: task.params.humanCode,
+                        speed: task.params.speed,
+                        volume: task.params.volume >= 0 ? task.params.volume * 100 : undefined,
+                        isSubtitle: task.params.isSubtitle
+                    };
+                    // 根据播报类型设置特定参数
+                    if (task.params.type === exports.BroadcastType.TEXT) {
+                        requestBody.text = task.params.text;
+                        requestBody.voiceCode = task.params.voiceCode;
+                    }
+                    else if (task.params.type === exports.BroadcastType.AUDIO) {
+                        requestBody.text = task.params.text;
+                        requestBody.audioUrl = task.params.audioUrl;
+                    }
+                    // 发起流式请求
+                    fetchEventSource(apiUrl, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'x_auth_token': ConfigManager.getInstance().getToken()
+                        },
+                        body: JSON.stringify(requestBody),
+                        signal: task.controller.signal,
+                        openWhenHidden: true,
+                        onmessage: (event) => {
+                            this.handleTaskResponse(task, event.data);
+                        },
+                        onclose: () => {
+                            this.handleTaskClose(task);
+                        },
+                        onerror: (error) => {
+                            this.handleTaskError(task, error);
+                            throw new Error(`Task ${task.id} request failed: ${error}`);
+                        }
+                    });
+                }
+                catch (error) {
+                    this.handleTaskError(task, error);
+                }
+            });
+        }
+        /**
+         * 处理任务响应
+         * @param task - 播报任务
+         * @param data - 响应数据
+         * @description 处理任务的流式响应数据
+         * @private
+         */
+        handleTaskResponse(task, data) {
+            try {
+                const response = JSON.parse(data);
+                // 错误处理
+                if (response.code !== 0) {
+                    this.handleBroadcastError(response.code);
+                    return;
+                }
+                // 处理音频数据
+                if (response.data && response.data.voiceUrl) {
+                    // 自定义音频播报时，如果服务器未返回音频URL，使用传入的audioUrl
+                    if (task.params.type === exports.BroadcastType.AUDIO && task.params.audioUrl && !response.data.voiceUrl) {
+                        response.data.voiceUrl = task.params.audioUrl;
+                    }
+                    // 添加处理后的响应对象到待发送队列
+                    task.pendingResponses.push(response);
+                    this.logger.debug('Response added to task', { taskId: task.id, pendingCount: task.pendingResponses.length });
+                }
+                // 检查是否完成
+                if (response.data && response.data.done) {
+                    task.isGenerationComplete = true;
+                    this.logger.debug('Task generation completed', { taskId: task.id, totalResponses: task.pendingResponses.length });
+                    // 任务完成生成，保持REQUESTING状态直到所有响应发送完毕
+                }
+            }
+            catch (error) {
+                this.handleTaskError(task, error);
+            }
+        }
+        /**
+         * 发送下一个响应
+         * @param task - 播报任务
+         * @description 发送任务中的第一个待发送响应到Unity，发送后立即删除
+         * @private
+         */
+        sendNextResponse(task) {
+            var _a;
+            if (task.pendingResponses.length === 0) {
+                return;
+            }
+            // 取出第一个待发送的响应
+            const response = task.pendingResponses.shift();
+            this.logger.debug('Sending response to Unity', {
+                taskId: task.id,
+                remainingResponses: task.pendingResponses.length,
+                voiceUrl: (_a = response.data) === null || _a === void 0 ? void 0 : _a.voiceUrl
+            });
+            // 发送响应到Unity
+            this.sendMessage('AppendBroadcast', {
+                response,
+                callbackFun: this.uniqueCallbackName,
+                operationType: exports.BroadcastOperationType.APPEND_BROADCAST
+            });
+            // 如果任务已完成且没有更多待发送响应，标记任务完成并推进序号
+            if (task.isGenerationComplete && task.pendingResponses.length === 0) {
+                task.status = BroadcastTaskStatus.COMPLETED;
+                this.currentSendingSequence = task.sequence;
+                this.logger.debug('Task completed', { taskId: task.id });
+            }
+        }
+        /**
+         * 处理任务关闭
+         * @param task - 播报任务
+         * @description 处理任务的流式连接关闭
+         * @private
+         */
+        handleTaskClose(task) {
+            this.logger.debug('Task stream closed', { taskId: task.id });
+            // 如果还没有标记为完成，则标记为完成
+            if (!task.isGenerationComplete && task.status === BroadcastTaskStatus.REQUESTING) {
+                task.isGenerationComplete = true;
+            }
+        }
+        /**
+         * 处理任务错误
+         * @param task - 播报任务
+         * @param error - 错误对象
+         * @description 处理任务执行过程中的错误
+         * @private
+         */
+        handleTaskError(task, error) {
+            var _a, _b;
+            task.status = BroadcastTaskStatus.FAILED;
+            task.error = error;
+            this.logger.error(`Task failed - ${task.id}`, error);
+            // 触发错误回调
+            (_b = (_a = this.callbacks).onError) === null || _b === void 0 ? void 0 : _b.call(_a, error);
+        }
+        /**
+         * 清理已完成的任务
+         * @description 从队列中移除已完成、失败或取消的任务
+         * @private
+         */
+        cleanupCompletedTasks() {
+            const beforeLength = this.taskQueue.length;
+            this.taskQueue = this.taskQueue.filter(task => task.status !== BroadcastTaskStatus.COMPLETED
+                && task.status !== BroadcastTaskStatus.FAILED
+                && task.status !== BroadcastTaskStatus.CANCELLED);
+            const removedCount = beforeLength - this.taskQueue.length;
+            if (removedCount > 0) {
+                this.logger.debug('Cleaned up completed tasks', { removedCount, remainingTasks: this.taskQueue.length });
+            }
+        }
+        /**
+         * 取消所有任务
+         * @description 取消队列中的所有任务
+         * @private
+         */
+        cancelAllTasks() {
+            for (const task of this.taskQueue) {
+                if (task.status !== BroadcastTaskStatus.COMPLETED && task.status !== BroadcastTaskStatus.FAILED) {
+                    task.controller.abort();
+                    task.status = BroadcastTaskStatus.CANCELLED;
+                }
+            }
+            this.taskQueue = [];
+            this.taskSequence = 0;
+            this.currentSendingSequence = 0;
+            this.logger.debug('All tasks cancelled and queue cleared');
+        }
         /** 全局回调函数名称 */
         get callbackFunctionName() {
             return 'uniBroadcastCallback';
@@ -2136,13 +2344,15 @@
                     // 4. 创建带有唯一标识符的Avatar服务
                     this.avatarService = new AvatarService({
                         unityInstance: this.unityInstance,
-                        instanceId: this.instanceId
+                        instanceId: this.instanceId,
+                        enableDebugLog: this.config.enableDebugLog
                     });
                     // 5. 创建带有唯一标识符的播报服务
                     this.broadcastService = new BroadcastService({
                         unityInstance: this.unityInstance,
                         instanceId: this.instanceId,
-                        callbacks: this.config.broadcastCallbacks
+                        callbacks: this.config.broadcastCallbacks,
+                        enableDebugLog: this.config.enableDebugLog
                     });
                     // 6. 初始化数字人
                     const result = yield this.avatarService.initializeAvatar(avatarCode, cameraType);
@@ -2230,12 +2440,13 @@
         /**
          * 开始播报
          * @param params 播报参数
+         * @param isAppend 是否追加播报
          * @returns Promise<void> 播报操作的Promise
          */
-        startBroadcast(params) {
+        startBroadcast(params, isAppend) {
             return __awaiter(this, void 0, void 0, function* () {
                 this.ensureInitialized();
-                return yield this.broadcastService.startBroadcast(params);
+                return yield this.broadcastService.startBroadcast(params, isAppend);
             });
         }
         /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zeewain/3d-avatar-sdk",
   "type": "module",
-  "version": "1.2.3",
+  "version": "1.2.4-0",
   "description": "SDK for ZEE Avatar WebGL integration",
   "author": "ZEEWain",
   "license": "MIT",