@xmov/avatar 2.0.0-beta.10 → 2.0.0-beta.12

package/README.md

@@ -1,139 +1,249 @@
 # 有灵离线数字人 JS-SDK
 
-## 开发模式
+基于 Web 技术的 3D 虚拟人渲染和交互 SDK，支持离线渲染、低延迟交互、多端适配。
 
-use `pnpm`
-
-- 根目录和 `app/`目录安装 packages:
+## 安装
 
 ```bash
-pnpm install
-cd app/ && pnpm install
-```
+# npm 官方源
+npm install @xmov/avatar
 
-- 根目录启动 SDK 实时编译：
+# 或内网源
+npm install @xmov/avatar --registry=https://npm.xmov.ai
+```
 
-```bash
-pnpm sdk
+## 快速开始
+
+```typescript
+import XmovAvatar from '@xmov/avatar';
+
+const avatar = new XmovAvatar({
+  containerId: '#container',
+  appId: 'your-app-id',
+  appSecret: 'your-app-secret',
+  gatewayServer: 'http://your-gateway-server',
+  enableClientInterrupt: false,
+  enableDebugger: false,
+  hardwareAcceleration: 'default',
+  onMessage: (error) => console.error('错误:', error),
+  onStatusChange: (status) => console.log('状态变化:', status),
+});
+
+// 初始化
+await avatar.init({
+  onDownloadProgress: (progress) => console.log('下载进度:', progress),
+  initModel: 'normal', // 或 'invisible' 进入隐身模式
+});
+
+// 播放文本（SSML）
+avatar.speak('<speak>你好，世界！</speak>', true, true, {
+  client_speak_id: 'unique-id'
+});
+
+// 状态切换
+avatar.idle();              // 空闲状态
+avatar.listen();            // 监听状态
+avatar.think();             // 思考状态
+avatar.interactiveidle();   // 交互空闲状态
+
+// 打断当前操作
+avatar.interrupt('speak');
+
+// 销毁 SDK
+await avatar.destroy('user');
 ```
 
-- 根目录启动 Demo 应用:
+## 核心 API
+
+| 方法                                     | 说明           |
+| -------------------------------------- | ------------ |
+| `init(params)`                         | 初始化 SDK，加载资源 |
+| `speak(ssml, is_start, is_end, extra)` | 播放文本（SSML）   |
+| `idle()`                               | 切换到空闲状态      |
+| `listen()`                             | 切换到监听状态      |
+| `think()`                              | 切换到思考状态      |
+| `interactiveidle()`                    | 切换到交互空闲状态    |
+| `interrupt(type)`                      | 打断当前操作       |
+| `destroy(reason)`                      | 销毁 SDK       |
+| `getStatus()`                          | 获取当前状态       |
+| `setVolume(volume)`                    | 设置音量（0-1）    |
+| `changeAvatarVisible(visible)`         | 改变数字人显隐      |
+| `changeLayout(layout)`                 | 改变布局         |
+| `switchInvisibleMode()`                | 切换隐身模式       |
+| `showDebugInfo()`                      | 显示调试浮层       |
+| `hideDebugInfo()`                      | 隐藏调试浮层       |
+| `getSessionId()`                       | 获取会话id       |
+
+## 配置项
+
+```typescript
+const avatar = new XmovAvatar({
+  // 基础配置
+  containerId: '#container',        // 容器元素选择器
+  appId: 'your-app-id',             // 应用 ID
+  appSecret: 'your-app-secret',     // 应用密钥
+  gatewayServer: 'http://...',      // 网关地址
+
+  // 渲染配置
+  hardwareAcceleration: 'default',   // 硬件加速：'default'
+  audioOnlyMode: false,             // 音频+事件模式（无渲染）
+  // 功能开关
+  enableClientInterrupt: false,     // 客户端打断
+
+  // 自定义请求头
+  headers: {},
+
+  // 回调事件（见下方详细说明）
+  onMessage: (error) => {},
+  onStatusChange: (status) => {},
+  // ...
+});
+```
 
-```bash
-pnpm app
+## 回调事件
+
+| 回调                                              | 说明                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------- |
+| `onMessage(error)`                              | 错误消息回调                                                        |
+| `onStatusChange(status)`                        | 状态变化：`online` / `offline` / `close` / `visible` / `invisible` |
+| `onRenderChange(state)`                         | 渲染状态：`init` / `rendering` / `paused` / `resumed` / `stopped`  |
+| `onVoiceStateChange(state, duration, speak_id)` | 语音状态变化                                                        |
+| `onSpeakStateChange(state, speak_id)`           | 播报状态变化                                                        |
+| `onWalkStateChange(state)`                      | 行走状态变化                                                        |
+| `onWidgetEvent(data)`                           | Widget 事件回调                                                   |
+| `onNetworkInfo(info)`                           | 网络信息回调（rtt、downlink、networkStatus）                            |
+| `onDownloadProgress(progress)`                  | 下载进度回调（0-100）                                                 |
+| `onFPSUpdate(stats)`                            | FPS 统计信息回调                                                    |
+| `onStateChange(state)`                          | 通用状态变化回调                                                      |
+| `onStateRenderChange(state, duration)`          | 渲染状态变化回调                                                      |
+| `proxyWidget`                                   | 自定义 Widget 代理                                                 |
+
+## Agent SDK
+
+Agent SDK 从 `@xmov/avatar/agent` 导入，在数字人渲染和 TTSA 能力上增加文本对话、麦克风 ASR、打断、状态 callbacks 和断线恢复。
+
+```typescript
+import XingyunAvatarAgent from '@xmov/avatar/agent';
 ```
 
-浏览器访问 `http://localhost:5173`
+- [快速接入](./docs/agent/developer-guide/quick-start.md)
+- [API 参考](./docs/agent/developer-guide/api-reference.md)
+- [高级功能](./docs/agent/developer-guide/advanced-features.md)
+- [常见问题](./docs/agent/developer-guide/faq.md)
+- [开发维护文档索引](./docs/agent/README.md)
 
-## 版本管理
+## 开发
 
-本项目采用 **语义化版本（SemVer）** + **自动化发布** 体系。
+### 环境要求
 
-### 版本规范
+- Node.js v16+
+- pnpm 包管理器
 
-| 版本类型 | 递增条件 | 示例 |
-|---------|---------|------|
-| **MAJOR** | 破坏性 API 变更 | 1.2.3 → 2.0.0 |
-| **MINOR** | 新功能（向后兼容） | 1.2.3 → 1.3.0 |
-| **PATCH** | Bug 修复（向后兼容） | 1.2.3 → 1.2.4 |
+### 启动开发
 
-### 分支与发布
+```bash
+# 安装依赖
+pnpm install
+cd app/ && pnpm install
 
-```
-feature/* → develop (alpha) → release (beta) → master (latest)
-```
+# 同时监听根 SDK 和 Agent SDK
+pnpm sdk
 
-| 分支 | 发布标签 | 版本格式 |
-|------|---------|---------|
-| `master` | @latest | `0.1.0` |
-| `release` | @beta | `0.1.0-beta.0` |
-| `develop` | @alpha | `0.1.0-alpha.0` |
+# 启动 Demo 应用
+pnpm app
 
-### 提交规范
+# 浏览器访问 http://localhost:5173
+```
 
-遵循 **约定式提交（Conventional Commits）**：
+`pnpm sdk` 会并行运行 `sdk:core` 和 `sdk:agent`。只需监听其中一个入口时，可以单独运行 `pnpm sdk:core` 或 `pnpm sdk:agent`。
 
-```bash
-# 新功能 - 次版本递增
-git commit -m "feat(audio): 新增 MSE 音频播放器"
+### 构建
 
-# Bug 修复 - 修订号递增
-git commit -m "fix(decoder): 修复视频解码超时问题"
+```bash
+# 生产构建
+pnpm run build
 
-# 破坏性变更 - 主版本递增
-git commit -m "refactor(api): 重构初始化接口
+# Lite 版本
+pnpm run lite
 
-BREAKING CHANGE: init() 方法参数结构调整"
+# 生成 Protobuf 文件
+pnpm run proto
 ```
 
-### 自动化发布
+### 构建 Demo 应用
 
-代码推送到对应分支后，GitLab CI 自动执行：
-1. 校验提交信息
-2. 计算新版本号
-3. 更新 CHANGELOG
-4. 构建 SDK
-5. 发布到 npm
-6. 创建 Git Tag
+```bash
+cd app/
 
-**详细规范请参考**：[版本管理规范](./docs/VERSION_MANAGEMENT.md)
+# 开发环境
+pnpm run build:dev
 
-## 更新日志
+# 测试环境
+pnpm run build:test
 
-详见 [CHANGELOG](./CHANGELOG.md)
+# 预发布环境
+pnpm run build:pre
 
-## SDK文档
+# 生产环境
+pnpm run build
+```
 
-[有灵Lite&Pro 数字人驱动 SDK 使用说明](https://rsjqcmnt5p.feishu.cn/wiki/BXOqwE0PtiduRxk79R9crAtwnRh)
+### Electron 应用
 
-### XingyunAvatarAgent M2
+```bash
+cd app/
+pnpm run dev:electron    # 开发模式
+pnpm run build-electron  # 构建桌面应用
+```
 
-Agent SDK 从 `@xmov/avatar/agent` 导入，在原有数字人渲染和 TTSA 能力上增加文本对话、麦克风 ASR、打断、状态 callbacks 和断线恢复。
+## 版本管理
 
-- [快速接入](./docs/agent/developer-guide/quick-start.md)
-- [API 参考](./docs/agent/developer-guide/api-reference.md)
-- [高级功能](./docs/agent/developer-guide/advanced-features.md)
-- [常见问题](./docs/agent/developer-guide/faq.md)
-- [开发维护文档索引](./docs/agent/README.md)
+采用 **语义化版本（SemVer）** + **自动化发布** 体系。
+
+### 分支与发布
 
-## SDK发布流程
+```
+feature/* → develop (alpha) → release (beta) → master (latest)
+```
+
+| 分支        | npm tag   | 版本格式            |
+| --------- | --------- | --------------- |
+| `master`  | `@latest` | `2.0.0`         |
+| `release` | `@beta`   | `2.0.0-beta.0`  |
+| `develop` | `@alpha`  | `2.0.0-alpha.0` |
 
-### 手动发布（不推荐）
+### 提交规范
+
+遵循 **约定式提交（Conventional Commits）**：
 
 ```bash
-# 1. 更新 changelog.md 增加版本号+描述当前修改的内容及修复的问题
-# 2. 更新 package.json 内的版本号（或使用自动化发布）
-# 3. 执行构建
-npm run build
+feat(audio): 新增 MSE 音频播放器          # 次版本递增
+fix(decoder): 修复视频解码超时问题         # 修订号递增
+refactor(api): 重构初始化接口              # 修订号递增
+  BREAKING CHANGE: init() 参数结构调整     # 主版本递增
+```
 
-# 4. 发布到 npm
-npm publish --tag latest       # 正式版
-npm publish --tag beta         # Beta 测试版
-npm publish --tag alpha        # Alpha 测试版
+### 自动化发布
 
-# 5. 通知星云发布 test/pre 环境
-# 6. 更新 oss sdk 静态包（xmovAvatar index.umd）
-npm run lite
+代码推送到对应分支后，GitLab CI 自动执行：
 
-# 7. 更新 oss sdk 静态包（LiteAvatar）
-```
+1. semantic-release 计算新版本号
+2. 更新 CHANGELOG
+3. 构建 SDK
+4. 发布到 npm 官方源 + 内网源（双发）
+5. 创建 Git Tag
 
-### 自动化发布（推荐）
+## 更新日志
 
-```bash
-# 1. 从 develop 创建功能分支
-git checkout develop
-git checkout -b feature/xxx
+详见 [CHANGELOG](./CHANGELOG.md)
 
-# 2. 编写代码，遵循约定式提交
-git add .
-git commit -m "feat(module): 新功能描述"
+## SDK 文档
 
-# 3. 推送到远端并创建 MR
-git push origin feature/xxx
+- [有灵Lite\&Pro 数字人驱动 SDK 使用说明](https://rsjqcmnt5p.feishu.cn/wiki/BXOqwE0PtiduRxk79R9crAtwnRh)
+- [test 发布记录](https://rsjqcmnt5p.feishu.cn/docx/IvQZdW3IIo7pF6xFvcCcGfG2nxd)
+- [pre 发布记录](https://rsjqcmnt5p.feishu.cn/docx/IthldRw5ioE7eAxUNeycauYpnuf)
+- [版本管理规范](./docs/VERSION_MANAGEMENT.md)
 
-# 4. MR 合并到 develop 后，自动发布 alpha 版本
-```
+## License
 
-[test发布记录](https://rsjqcmnt5p.feishu.cn/docx/IvQZdW3IIo7pF6xFvcCcGfG2nxd)
-[pre发布记录](https://rsjqcmnt5p.feishu.cn/docx/IthldRw5ioE7eAxUNeycauYpnuf)
+ISC

package/dist/baseRender/AvatarRenderer.d.ts

@@ -27,7 +27,6 @@ type Option = {
         body_id: number;
         id: number;
     }) => void;
-    onError: (error: any) => void;
     sendSdkPoint: (point: string, data: any) => void;
 };
 export default class AvatarRender {

package/dist/control/RenderScheduler.d.ts

@@ -122,6 +122,13 @@ export default class RenderScheduler {
     _offlineRun(): void;
     ttsaStateChangeHandle(state: StateChangeInfo): void;
     resume(): void;
+    /**
+     * app 切后台时暂停音频并清空对齐状态（复用断网离线时的 pause()）
+     * 不能保留缓存续播：Android 后台视频帧号持续递增而音频停留在暂停位置，
+     * 恢复后音画基准脱节；且后台期间可能下发新 speak 数据，旧缓存与新 sf 冲突。
+     * 恢复后依赖新下发音频的 sf 作为 firstFrameIndex 重新对齐
+     */
+    pauseForBackground(): void;
     /**
      * 设置数字人canvas的显隐状态
      * @param visible 是否可见