@xmov/avatar 2.0.0-beta.10 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +198 -90
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.modern.js +1 -1
  5. package/dist/index.modern.js.map +1 -1
  6. package/dist/index.module.js +1 -1
  7. package/dist/index.module.js.map +1 -1
  8. package/dist/index.umd.js +1 -1
  9. package/dist/index.umd.js.map +1 -1
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -1,139 +1,247 @@
1
1
  # 有灵离线数字人 JS-SDK
2
2
 
3
- ## 开发模式
3
+ 基于 Web 技术的 3D 虚拟人渲染和交互 SDK，支持离线渲染、低延迟交互、多端适配。
4
4
 
5
- use `pnpm`
6
-
7
- - 根目录和 `app/`目录安装 packages:
5
+ ## 安装
8
6
 
9
7
  ```bash
10
- pnpm install
11
- cd app/ && pnpm install
12
- ```
8
+ # npm 官方源
9
+ npm install @xmov/avatar
13
10
 
14
- - 根目录启动 SDK 实时编译：
11
+ # 或内网源
12
+ npm install @xmov/avatar --registry=https://npm.xmov.ai
13
+ ```
15
14
 
16
- ```bash
17
- pnpm sdk
15
+ ## 快速开始
16
+
17
+ ```typescript
18
+ import XmovAvatar from '@xmov/avatar';
19
+
20
+ const avatar = new XmovAvatar({
21
+ containerId: '#container',
22
+ appId: 'your-app-id',
23
+ appSecret: 'your-app-secret',
24
+ gatewayServer: 'http://your-gateway-server',
25
+ enableClientInterrupt: false,
26
+ enableDebugger: false,
27
+ hardwareAcceleration: 'default',
28
+ onMessage: (error) => console.error('错误:', error),
29
+ onStatusChange: (status) => console.log('状态变化:', status),
30
+ });
31
+
32
+ // 初始化
33
+ await avatar.init({
34
+ onDownloadProgress: (progress) => console.log('下载进度:', progress),
35
+ initModel: 'normal', // 或 'invisible' 进入隐身模式
36
+ });
37
+
38
+ // 播放文本（SSML）
39
+ avatar.speak('<speak>你好，世界！</speak>', true, true, {
40
+ client_speak_id: 'unique-id'
41
+ });
42
+
43
+ // 状态切换
44
+ avatar.idle(); // 空闲状态
45
+ avatar.listen(); // 监听状态
46
+ avatar.think(); // 思考状态
47
+ avatar.interactiveidle(); // 交互空闲状态
48
+
49
+ // 打断当前操作
50
+ avatar.interrupt('speak');
51
+
52
+ // 销毁 SDK
53
+ await avatar.destroy('user');
18
54
  ```
19
55
 
20
- - 根目录启动 Demo 应用:
56
+ ## 核心 API
57
+
58
+ | 方法 | 说明 |
59
+ | -------------------------------------- | ------------ |
60
+ | `init(params)` | 初始化 SDK，加载资源 |
61
+ | `speak(ssml, is_start, is_end, extra)` | 播放文本（SSML） |
62
+ | `idle()` | 切换到空闲状态 |
63
+ | `listen()` | 切换到监听状态 |
64
+ | `think()` | 切换到思考状态 |
65
+ | `interactiveidle()` | 切换到交互空闲状态 |
66
+ | `interrupt(type)` | 打断当前操作 |
67
+ | `destroy(reason)` | 销毁 SDK |
68
+ | `getStatus()` | 获取当前状态 |
69
+ | `setVolume(volume)` | 设置音量（0-1） |
70
+ | `changeAvatarVisible(visible)` | 改变数字人显隐 |
71
+ | `changeLayout(layout)` | 改变布局 |
72
+ | `switchInvisibleMode()` | 切换隐身模式 |
73
+ | `showDebugInfo()` | 显示调试浮层 |
74
+ | `hideDebugInfo()` | 隐藏调试浮层 |
75
+ | `getSessionId()` | 获取会话id |
76
+
77
+ ## 配置项
78
+
79
+ ```typescript
80
+ const avatar = new XmovAvatar({
81
+ // 基础配置
82
+ containerId: '#container', // 容器元素选择器
83
+ appId: 'your-app-id', // 应用 ID
84
+ appSecret: 'your-app-secret', // 应用密钥
85
+ gatewayServer: 'http://...', // 网关地址
86
+
87
+ // 渲染配置
88
+ hardwareAcceleration: 'default', // 硬件加速：'default'
89
+ audioOnlyMode: false, // 音频+事件模式（无渲染）
90
+ // 功能开关
91
+ enableClientInterrupt: false, // 客户端打断
92
+
93
+ // 自定义请求头
94
+ headers: {},
95
+
96
+ // 回调事件（见下方详细说明）
97
+ onMessage: (error) => {},
98
+ onStatusChange: (status) => {},
99
+ // ...
100
+ });
101
+ ```
21
102
 
22
- ```bash
23
- pnpm app
103
+ ## 回调事件
104
+
105
+ | 回调 | 说明 |
106
+ | ----------------------------------------------- | ------------------------------------------------------------- |
107
+ | `onMessage(error)` | 错误消息回调 |
108
+ | `onStatusChange(status)` | 状态变化：`online` / `offline` / `close` / `visible` / `invisible` |
109
+ | `onRenderChange(state)` | 渲染状态：`init` / `rendering` / `paused` / `resumed` / `stopped` |
110
+ | `onVoiceStateChange(state, duration, speak_id)` | 语音状态变化 |
111
+ | `onSpeakStateChange(state, speak_id)` | 播报状态变化 |
112
+ | `onWalkStateChange(state)` | 行走状态变化 |
113
+ | `onWidgetEvent(data)` | Widget 事件回调 |
114
+ | `onNetworkInfo(info)` | 网络信息回调（rtt、downlink、networkStatus） |
115
+ | `onDownloadProgress(progress)` | 下载进度回调（0-100） |
116
+ | `onFPSUpdate(stats)` | FPS 统计信息回调 |
117
+ | `onStateChange(state)` | 通用状态变化回调 |
118
+ | `onStateRenderChange(state, duration)` | 渲染状态变化回调 |
119
+ | `proxyWidget` | 自定义 Widget 代理 |
120
+
121
+ ## Agent SDK
122
+
123
+ Agent SDK 从 `@xmov/avatar/agent` 导入，在数字人渲染和 TTSA 能力上增加文本对话、麦克风 ASR、打断、状态 callbacks 和断线恢复。
124
+
125
+ ```typescript
126
+ import XingyunAvatarAgent from '@xmov/avatar/agent';
24
127
  ```
25
128
 
26
- 浏览器访问 `http://localhost:5173`
129
+ - [快速接入](./docs/agent/developer-guide/quick-start.md)
130
+ - [API 参考](./docs/agent/developer-guide/api-reference.md)
131
+ - [高级功能](./docs/agent/developer-guide/advanced-features.md)
132
+ - [常见问题](./docs/agent/developer-guide/faq.md)
133
+ - [开发维护文档索引](./docs/agent/README.md)
27
134
 
28
- ## 版本管理
135
+ ## 开发
29
136
 
30
- 本项目采用 **语义化版本（SemVer）** + **自动化发布** 体系。
137
+ ### 环境要求
31
138
 
32
- ### 版本规范
139
+ - Node.js v16+
140
+ - pnpm 包管理器
33
141
 
34
- | 版本类型 | 递增条件 | 示例 |
35
- |---------|---------|------|
36
- | **MAJOR** | 破坏性 API 变更 | 1.2.3 → 2.0.0 |
37
- | **MINOR** | 新功能（向后兼容） | 1.2.3 → 1.3.0 |
38
- | **PATCH** | Bug 修复（向后兼容） | 1.2.3 → 1.2.4 |
142
+ ### 启动开发
39
143
 
40
- ### 分支与发布
144
+ ```bash
145
+ # 安装依赖
146
+ pnpm install
147
+ cd app/ && pnpm install
41
148
 
42
- ```
43
- feature/* → develop (alpha) → release (beta) → master (latest)
44
- ```
149
+ # 启动 SDK 实时编译（监听模式）
150
+ pnpm sdk
45
151
 
46
- | 分支 | 发布标签 | 版本格式 |
47
- |------|---------|---------|
48
- | `master` | @latest | `0.1.0` |
49
- | `release` | @beta | `0.1.0-beta.0` |
50
- | `develop` | @alpha | `0.1.0-alpha.0` |
152
+ # 启动 Demo 应用
153
+ pnpm app
51
154
 
52
- ### 提交规范
155
+ # 浏览器访问 http://localhost:5173
156
+ ```
53
157
 
54
- 遵循 **约定式提交（Conventional Commits）**：
158
+ ### 构建
55
159
 
56
160
  ```bash
57
- # 新功能 - 次版本递增
58
- git commit -m "feat(audio): 新增 MSE 音频播放器"
59
-
60
- # Bug 修复 - 修订号递增
61
- git commit -m "fix(decoder): 修复视频解码超时问题"
161
+ # 生产构建
162
+ pnpm run build
62
163
 
63
- # 破坏性变更 - 主版本递增
64
- git commit -m "refactor(api): 重构初始化接口
164
+ # Lite 版本
165
+ pnpm run lite
65
166
 
66
- BREAKING CHANGE: init() 方法参数结构调整"
167
+ # 生成 Protobuf 文件
168
+ pnpm run proto
67
169
  ```
68
170
 
69
- ### 自动化发布
171
+ ### 构建 Demo 应用
70
172
 
71
- 代码推送到对应分支后，GitLab CI 自动执行：
72
- 1. 校验提交信息
73
- 2. 计算新版本号
74
- 3. 更新 CHANGELOG
75
- 4. 构建 SDK
76
- 5. 发布到 npm
77
- 6. 创建 Git Tag
173
+ ```bash
174
+ cd app/
78
175
 
79
- **详细规范请参考**：[版本管理规范](./docs/VERSION_MANAGEMENT.md)
176
+ # 开发环境
177
+ pnpm run build:dev
80
178
 
81
- ## 更新日志
179
+ # 测试环境
180
+ pnpm run build:test
82
181
 
83
- 详见 [CHANGELOG](./CHANGELOG.md)
182
+ # 预发布环境
183
+ pnpm run build:pre
84
184
 
85
- ## SDK文档
185
+ # 生产环境
186
+ pnpm run build
187
+ ```
86
188
 
87
- [有灵Lite&Pro 数字人驱动 SDK 使用说明](https://rsjqcmnt5p.feishu.cn/wiki/BXOqwE0PtiduRxk79R9crAtwnRh)
189
+ ### Electron 应用
88
190
 
89
- ### XingyunAvatarAgent M2
191
+ ```bash
192
+ cd app/
193
+ pnpm run dev:electron # 开发模式
194
+ pnpm run build-electron # 构建桌面应用
195
+ ```
90
196
 
91
- Agent SDK 从 `@xmov/avatar/agent` 导入，在原有数字人渲染和 TTSA 能力上增加文本对话、麦克风 ASR、打断、状态 callbacks 和断线恢复。
197
+ ## 版本管理
92
198
 
93
- - [快速接入](./docs/agent/developer-guide/quick-start.md)
94
- - [API 参考](./docs/agent/developer-guide/api-reference.md)
95
- - [高级功能](./docs/agent/developer-guide/advanced-features.md)
96
- - [常见问题](./docs/agent/developer-guide/faq.md)
97
- - [开发维护文档索引](./docs/agent/README.md)
199
+ 采用 **语义化版本（SemVer）** + **自动化发布** 体系。
200
+
201
+ ### 分支与发布
98
202
 
99
- ## SDK发布流程
203
+ ```
204
+ feature/* → develop (alpha) → release (beta) → master (latest)
205
+ ```
206
+
207
+ | 分支 | npm tag | 版本格式 |
208
+ | --------- | --------- | --------------- |
209
+ | `master` | `@latest` | `2.0.0` |
210
+ | `release` | `@beta` | `2.0.0-beta.0` |
211
+ | `develop` | `@alpha` | `2.0.0-alpha.0` |
100
212
 
101
- ### 手动发布（不推荐）
213
+ ### 提交规范
214
+
215
+ 遵循 **约定式提交（Conventional Commits）**：
102
216
 
103
217
  ```bash
104
- # 1. 更新 changelog.md 增加版本号+描述当前修改的内容及修复的问题
105
- # 2. 更新 package.json 内的版本号（或使用自动化发布）
106
- # 3. 执行构建
107
- npm run build
218
+ feat(audio): 新增 MSE 音频播放器 # 次版本递增
219
+ fix(decoder): 修复视频解码超时问题 # 修订号递增
220
+ refactor(api): 重构初始化接口 # 修订号递增
221
+ BREAKING CHANGE: init() 参数结构调整 # 主版本递增
222
+ ```
108
223
 
109
- # 4. 发布到 npm
110
- npm publish --tag latest # 正式版
111
- npm publish --tag beta # Beta 测试版
112
- npm publish --tag alpha # Alpha 测试版
224
+ ### 自动化发布
113
225
 
114
- # 5. 通知星云发布 test/pre 环境
115
- # 6. 更新 oss sdk 静态包（xmovAvatar index.umd）
116
- npm run lite
226
+ 代码推送到对应分支后，GitLab CI 自动执行：
117
227
 
118
- # 7. 更新 oss sdk 静态包（LiteAvatar）
119
- ```
228
+ 1. semantic-release 计算新版本号
229
+ 2. 更新 CHANGELOG
230
+ 3. 构建 SDK
231
+ 4. 发布到 npm 官方源 + 内网源（双发）
232
+ 5. 创建 Git Tag
120
233
 
121
- ### 自动化发布（推荐）
234
+ ## 更新日志
122
235
 
123
- ```bash
124
- # 1. 从 develop 创建功能分支
125
- git checkout develop
126
- git checkout -b feature/xxx
236
+ 详见 [CHANGELOG](./CHANGELOG.md)
127
237
 
128
- # 2. 编写代码，遵循约定式提交
129
- git add .
130
- git commit -m "feat(module): 新功能描述"
238
+ ## SDK 文档
131
239
 
132
- # 3. 推送到远端并创建 MR
133
- git push origin feature/xxx
240
+ - [有灵Lite\&Pro 数字人驱动 SDK 使用说明](https://rsjqcmnt5p.feishu.cn/wiki/BXOqwE0PtiduRxk79R9crAtwnRh)
241
+ - [test 发布记录](https://rsjqcmnt5p.feishu.cn/docx/IvQZdW3IIo7pF6xFvcCcGfG2nxd)
242
+ - [pre 发布记录](https://rsjqcmnt5p.feishu.cn/docx/IthldRw5ioE7eAxUNeycauYpnuf)
243
+ - [版本管理规范](./docs/VERSION_MANAGEMENT.md)
134
244
 
135
- # 4. MR 合并到 develop 后，自动发布 alpha 版本
136
- ```
245
+ ## License
137
246
 
138
- [test发布记录](https://rsjqcmnt5p.feishu.cn/docx/IvQZdW3IIo7pF6xFvcCcGfG2nxd)
139
- [pre发布记录](https://rsjqcmnt5p.feishu.cn/docx/IthldRw5ioE7eAxUNeycauYpnuf)
247
+ ISC