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

package/dist/index.esm.js

@@ -1019,6 +1019,7 @@ const ENV_MAP = {
 /**
  * 获取指定环境的配置
  * @param env - 环境类型，默认为'dev'
+ * @param withApiModule - 是否包含API模块路径
  * @returns 返回对应环境的配置对象
  * @example
  * ```typescript
@@ -1026,11 +1027,11 @@ const ENV_MAP = {
  * console.log(config.apiBaseUrl); // https://aiip.zeewain.com/api/dh-talker
  * ```
  */
-function getEnvConfig(env = 'dev', withModule = true) {
+function getEnvConfig(env = 'dev', withApiModule = true) {
     const baseUrl = ENV_MAP[env];
     if (baseUrl) {
         return {
-            apiBaseUrl: `${baseUrl.apiBaseUrl}${withModule ? '/api' : ''}`
+            apiBaseUrl: `${baseUrl.apiBaseUrl}${withApiModule ? '/api' : ''}`
         };
     }
     return null;
@@ -1100,17 +1101,17 @@ class ConfigManager {
     }
     /**
      * 获取API基础URL
-     * @param withModule 是否包含模块路径
+     * @param withApiModule 是否包含模块路径
      * @returns string API基础URL
      * @description 根据当前环境配置获取API基础URL
      */
-    getApiBaseUrl(withModule = true) {
+    getApiBaseUrl(withApiModule = true) {
         var _a, _b, _c, _d;
         if (((_a = this.config) === null || _a === void 0 ? void 0 : _a.env) === 'custom' && ((_b = this.config) === null || _b === void 0 ? void 0 : _b.apiUrl)) {
             // 如果环境为自定义，则直接返回配置的API，无需添加模块路径
-            return this.config.apiUrl;
+            return `${this.config.apiUrl}${withApiModule ? '/api' : ''}`;
         }
-        return ((_d = getEnvConfig(((_c = this.config) === null || _c === void 0 ? void 0 : _c.env) || 'prod', withModule)) === null || _d === void 0 ? void 0 : _d.apiBaseUrl) || '';
+        return ((_d = getEnvConfig(((_c = this.config) === null || _c === void 0 ? void 0 : _c.env) || 'prod', withApiModule)) === null || _d === void 0 ? void 0 : _d.apiBaseUrl) || '';
     }
     /**
      * 获取自定义API URL
@@ -1506,6 +1507,20 @@ var BroadcastType;
  * @fileoverview 流式播报服务重构实现模块
  * @description 提供流式播报服务的重构实现，继承Unity基础服务，支持文本转语音和自定义音频播报
  */
+/**
+ * 播报任务状态枚举
+ */
+var BroadcastTaskStatus;
+(function (BroadcastTaskStatus) {
+    /** 请求中 */
+    BroadcastTaskStatus["REQUESTING"] = "requesting";
+    /** 已完成 */
+    BroadcastTaskStatus["COMPLETED"] = "completed";
+    /** 失败 */
+    BroadcastTaskStatus["FAILED"] = "failed";
+    /** 已取消 */
+    BroadcastTaskStatus["CANCELLED"] = "cancelled";
+})(BroadcastTaskStatus || (BroadcastTaskStatus = {}));
 /**
  * 流式播报服务重构类
  * @class BroadcastServiceRefactored
@@ -1535,12 +1550,20 @@ class BroadcastService extends UnityBaseService {
         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 });
     }
@@ -1589,8 +1612,9 @@ class BroadcastService extends UnityBaseService {
     /**
      * 开始播报
      * @param params - 播报参数
+     * @param isAppend - 是否追加播报
      * @returns Promise<void> 播报操作的Promise
-     * @description 开始流式播报，支持文本转语音和自定义音频播报
+     * @description 开始流式播报，支持文本转语音和自定义音频播报。使用队列机制确保音频按序播报
      * @throws {SDKError} 当参数验证失败或播报失败时抛出错误
      * @example
      * ```typescript
@@ -1604,130 +1628,54 @@ class BroadcastService extends UnityBaseService {
      *   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: 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 === BroadcastType.TEXT) {
-                    requestBody.text = params.text;
-                    requestBody.voiceCode = params.voiceCode;
-                }
-                else if (params.type === 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: 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 === 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: 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(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
+            });
         });
     }
     /**
@@ -1788,12 +1736,12 @@ class BroadcastService extends UnityBaseService {
      */
     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', BroadcastOperationType.STOP_BROADCAST, {});
                 this.logger.info('Broadcast stopped successfully');
@@ -1816,15 +1764,23 @@ class BroadcastService extends UnityBaseService {
     /**
      * 获取播报状态
      * @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
+            }
         };
     }
     /**
@@ -1832,15 +1788,268 @@ class BroadcastService extends UnityBaseService {
      * @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 === BroadcastType.TEXT) {
+                    requestBody.text = task.params.text;
+                    requestBody.voiceCode = task.params.voiceCode;
+                }
+                else if (task.params.type === 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 === 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: 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';
@@ -2129,13 +2338,15 @@ class ZEEAvatarSDK {
                 // 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);
@@ -2223,12 +2434,13 @@ class ZEEAvatarSDK {
     /**
      * 开始播报
      * @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);
         });
     }
     /**