feat: 添加华为交互数字人SDK集成示例项目
添加完整的华为交互数字人SDK集成示例项目，包括： - 项目配置文件package.json - 详细说明文档README.md - 主页面index.html - 核心逻辑脚本main.js - 样式文件main.css - SDK类型定义文件HwICSUiSdk.d.ts - 相关图片资源
This commit is contained in:
195
README.md
Normal file
195
README.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 华为交互数字人 - HwICSUiSdk 标准集成项目
|
||||
|
||||
这是一个基于 HwICSUiSdk 的华为交互数字人标准集成示例项目，展示了如何在前端项目中集成和使用数字人交互功能。
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
antiwear-web/
|
||||
├── hwICSUiSdk/ # SDK 目录（已提供）
|
||||
│ ├── HwICSUiSdk.esm.js # ESM 模块入口
|
||||
│ ├── HwICSUiSdk.d.ts # TypeScript 类型定义
|
||||
│ ├── HwICSUiSdk.css # SDK 样式
|
||||
│ └── ...
|
||||
├── scripts/
|
||||
│ └── main.js # 主逻辑代码
|
||||
├── styles/
|
||||
│ └── main.css # 自定义样式
|
||||
├── index.html # 主页面
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 环境要求
|
||||
|
||||
- 现代浏览器（Chrome、Firefox、Edge、Safari 最新版本）
|
||||
- 支持 WebRTC 和 WebSocket
|
||||
- 需要麦克风权限（用于语音交互）
|
||||
|
||||
### 2. 配置参数
|
||||
|
||||
#### 默认参数（已预填）
|
||||
| 参数 | 默认值 |
|
||||
|------|--------|
|
||||
| 服务器地址 | `metastudio-api.cn-north-4.myhuaweicloud.com` |
|
||||
| 机器人ID | `2c9084bf9c9cc1c0019db2c4ca2a5c89` |
|
||||
|
||||
#### 需要填写的参数
|
||||
| 参数 | 说明 | 必填 |
|
||||
|------|------|------|
|
||||
| 一次性授权码 | 用于身份验证的临时授权码 | 是 |
|
||||
|
||||
> **如何获取授权码**：通过华为云 MetaStudio 控制台或 API 获取一次性授权码（有效期5分钟）
|
||||
|
||||
### 3. 启动项目
|
||||
|
||||
由于使用了 ES Modules，需要通过本地服务器运行：
|
||||
|
||||
```bash
|
||||
# 使用 Python 3
|
||||
python -m http.server 8080
|
||||
|
||||
# 或使用 Node.js 的 http-server
|
||||
npx http-server -p 8080
|
||||
|
||||
# 或使用 VS Code Live Server 插件
|
||||
```
|
||||
|
||||
然后在浏览器中访问 `http://localhost:8080`
|
||||
|
||||
### 4. 使用流程
|
||||
|
||||
1. **获取授权码**：通过华为云控制台获取一次性授权码
|
||||
2. **填写配置**：在页面中输入授权码
|
||||
3. **初始化 SDK**：点击 "初始化 SDK" 开始使用
|
||||
|
||||
## 📖 功能说明
|
||||
|
||||
### 核心功能
|
||||
|
||||
1. **SDK 初始化与销毁**
|
||||
- 初始化：配置服务器地址、机器人ID等参数
|
||||
- 销毁：释放资源，清理数字人实例
|
||||
|
||||
2. **对话控制**
|
||||
- 开始对话：启动数字人交互会话
|
||||
- 停止对话：结束当前会话
|
||||
|
||||
3. **语音交互**
|
||||
- 开始说话：启动语音识别，用户语音输入
|
||||
- 停止说话：结束语音识别
|
||||
|
||||
4. **文本交互**
|
||||
- 发送文本消息给数字人
|
||||
|
||||
5. **其他控制**
|
||||
- 打断说话：立即中断数字人当前说话
|
||||
- 静音/取消静音：控制远程音频
|
||||
|
||||
### 事件监听
|
||||
|
||||
SDK 提供了丰富的事件回调：
|
||||
|
||||
| 事件 | 说明 |
|
||||
|------|------|
|
||||
| ERROR | 错误事件 |
|
||||
| JOB_INFO_CHANGE | 任务信息变更 |
|
||||
| SPEAKING_START | 数字人开始说话 |
|
||||
| SPEAKING_STOP | 数字人停止说话 |
|
||||
| SPEECH_RECOGNIZED | 语音识别结果 |
|
||||
| SEMANTIC_RECOGNIZED | 语义识别结果 |
|
||||
| ENTER_SLEEP | 进入休眠状态 |
|
||||
| ENTER_ACTIVE | 进入激活状态 |
|
||||
| JOB_END | 任务结束 |
|
||||
|
||||
## 🔧 开发指南
|
||||
|
||||
### 引入 SDK
|
||||
|
||||
```javascript
|
||||
import { HwICSUiSdk, ICSEventKey, InteractionMode, ConfigKey } from './hwICSUiSdk/HwICSUiSdk.esm.js';
|
||||
```
|
||||
|
||||
### 初始化 SDK
|
||||
|
||||
```javascript
|
||||
await HwICSUiSdk.create({
|
||||
serverAddress: 'your-server-address',
|
||||
containerId: 'digitalHumanBox',
|
||||
robotId: 'your-robot-id',
|
||||
onceCode: 'your-once-code',
|
||||
config: {
|
||||
[ConfigKey.ENABLE_CAPTION]: true,
|
||||
[ConfigKey.ENABLE_CHAT_BTN]: true
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 注册事件监听
|
||||
|
||||
```javascript
|
||||
HwICSUiSdk.addEventListeners({
|
||||
[ICSEventKey.SPEAKING_START]: () => {
|
||||
console.log('数字人开始说话');
|
||||
},
|
||||
[ICSEventKey.SPEECH_RECOGNIZED]: (data) => {
|
||||
console.log('识别结果:', data);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 开始对话
|
||||
|
||||
```javascript
|
||||
await HwICSUiSdk.startChat({
|
||||
interactionMode: InteractionMode.AUDIO
|
||||
});
|
||||
```
|
||||
|
||||
### 发送文本消息
|
||||
|
||||
```javascript
|
||||
await HwICSUiSdk.sendTextQuestion({
|
||||
text: '你好，数字人！'
|
||||
});
|
||||
```
|
||||
|
||||
## ⚙️ 配置选项
|
||||
|
||||
SDK 支持多种配置项：
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| ENABLE_CAPTION | boolean | true | 启用字幕显示 |
|
||||
| ENABLE_CHAT_BTN | boolean | true | 启用聊天按钮 |
|
||||
| ENABLE_HOT_ISSUES | boolean | true | 启用热点问题 |
|
||||
| SHOW_LANGUAGE_UI | boolean | true | 显示语言切换UI |
|
||||
| ENABLE_DEVICE_SETTING | boolean | true | 启用设备设置 |
|
||||
| ENABLE_NETWORK_CHECK | boolean | true | 启用网络检查 |
|
||||
| AUTO_PLAY_REMOTE_VIDEO | boolean | true | 自动播放远程视频 |
|
||||
| DEFAULT_MUTE_REMOTE_AUDIO | boolean | false | 默认静音远程音频 |
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
1. **HTTPS 要求**：在生产环境中，WebRTC 功能需要在 HTTPS 环境下运行
|
||||
2. **浏览器权限**：首次使用需要授权麦克风和摄像头权限
|
||||
3. **资源释放**：页面卸载时务必调用 `destroy()` 方法释放资源
|
||||
4. **错误处理**：建议对所有异步操作添加错误处理
|
||||
|
||||
## 🔍 调试技巧
|
||||
|
||||
1. 使用浏览器开发者工具查看控制台日志
|
||||
2. 调整日志级别查看详细信息：
|
||||
```javascript
|
||||
HwICSUiSdk.setLogLevel('debug'); // debug | info | warn | error | none
|
||||
```
|
||||
3. 查看网络面板监控 WebSocket 连接
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目仅供学习和参考使用。
|
||||
|
||||
## 🤝 技术支持
|
||||
|
||||
如有问题，请参考 HwICSUiSdk 官方文档或联系技术支持。
|
||||
Reference in New Issue
Block a user