@xmov/avatar 2.4.0 → 2.5.0-alpha.1

package/README.md

@@ -15,7 +15,7 @@ npm install @xmov/avatar --registry=https://npm.xmov.ai
 ## 快速开始
 
 ```typescript
-import XmovAvatar from '@xmov/avatar';
+import XmovAvatar, { InitModel } from '@xmov/avatar';
 
 const avatar = new XmovAvatar({
   containerId: '#container',
@@ -32,12 +32,12 @@ const avatar = new XmovAvatar({
 // 初始化
 await avatar.init({
   onDownloadProgress: (progress) => console.log('下载进度:', progress),
-  initModel: 'normal', // 或 'invisible' 进入隐身模式
+  initModel: InitModel.normal, // 或 InitModel.invisible
 });
 
 // 播放文本（SSML）
 avatar.speak('<speak>你好，世界！</speak>', true, true, {
-  client_speak_id: 'unique-id'
+  client_speak_id: 'unique-id', client_frame: 0
 });
 
 // 状态切换
@@ -73,10 +73,20 @@ await avatar.destroy('user');
 | `showDebugInfo()`                      | 显示调试浮层       |
 | `hideDebugInfo()`                      | 隐藏调试浮层       |
 | `getSessionId()`                       | 获取会话id       |
+| `getRenderState()` | 获取渲染状态 |
+| `changeWalkConfig(config)` | 更新行走配置 |
+| `restartWebGL()` | 手动恢复 WebGL，返回 boolean |
+| `startRecoder()` / `stopRecoder()` / `exportVideo()` | deprecated 兼容录制；导出触发下载，不返回 Blob |
+
+静态 `XmovAvatar.checkCapability(audioOnlyMode?)` 返回能力报告。`getStatus()` 返回 `AvatarStatus` 数值枚举或初始值 `-1`；`-1` 表示尚未收到有效状态，不能单独用于判断初始化完成。初始化请等待 `init()`。
+
+录制用法见 [录制说明](./docs/sdk.md)。高级配置、录制三方法、`onStateChange` 和 Agent 的 `speakByE2E/getState` 本轮保留，删除版本待定，不承诺下一大版本删除。
 
 ## 配置项
 
 ```typescript
+import XmovAvatar from '@xmov/avatar';
+
 const avatar = new XmovAvatar({
   // 基础配置
   containerId: '#container',        // 容器元素选择器
@@ -105,14 +115,14 @@ const avatar = new XmovAvatar({
 | 回调                                              | 说明                                                            |
 | ----------------------------------------------- | ------------------------------------------------------------- |
 | `onMessage(error)`                              | 错误消息回调                                                        |
-| `onStatusChange(status)`                        | 状态变化：`online` / `offline` / `close` / `visible` / `invisible` |
+| `onStatusChange(status)`                        | 状态变化：`AvatarStatus` 数值枚举（非字符串） |
 | `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）                                                 |
+| `onDownloadProgress(progress)`                  | `init` 参数中的下载进度回调（0-100）                                                 |
 | `onFPSUpdate(stats)`                            | FPS 统计信息回调                                                    |
 | `onStateChange(state)`                          | 通用状态变化回调                                                      |
 | `onStateRenderChange(state, duration)`          | 渲染状态变化回调                                                      |
@@ -160,7 +170,11 @@ pnpm app
 ### 构建
 
 ```bash
-# 生产构建
+# 仅本地构建，不上传
+pnpm run build:local
+pnpm run build:demo:internal
+
+# 以下命令包含上传，仅用于已批准发布
 pnpm run build
 
 # Lite 版本
@@ -247,3 +261,17 @@ refactor(api): 重构初始化接口              # 修订号递增
 ## License
 
 ISC
+
+## Agent UMD 加载
+
+包内 `agent/index.umd.js` 是全局适配器，不能独立加载。将同一版本的以下两个文件从安装包复制到站点后，按顺序引入（不要使用 async）：
+
+```html
+<script src="/sdk/package-dist/agent/avatar.umd.js"></script>
+<script src="/sdk/package-dist/agent/index.umd.js"></script>
+<script>
+  // 此时可使用 window.XingyunAvatarAgent
+</script>
+```
+
+`@xmov/avatar/agent/umd` 指向第二个文件；不承诺可通过未导出的包子路径 import 第一个文件。需要单 script 接入时使用维护文档说明的独立 E2E CDN 构建。Agent CJS 当前返回构造函数，没有运行时命名枚举导出；将来新增枚举须同步更新多格式包装及测试。