# chat-a2e-manager

## 1. 项目概述

Chat A2E Manager 是一个实时对话库，主要用于处理前端文本或音频对话、与 WebSocket 对话服务器的双向通信，以及播放携带表情数据（BlendShapes）的音频流。

- **主要用途**：为数字人、语音助手等应用提供实时语音交互与口型同步能力。

## 2. 快速开始

### 安装依赖

在项目根目录下执行以下命令安装库：

```bash
npm install chat-a2e-manager
```

### 项目启动/运行

本库作为依赖集成到您的前端项目中。以下是基本使用流程：

1. **引入库**

   ```typescript
   import ChatManager from 'chat-a2e-manager';
   ```

2. **创建实例与连接**

   ```typescript
   // 初始化实例，指定服务器地址
   const chatManager = new ChatManager('ws://localhost:8080');

   // 连接服务器 (可选传入用户ID,音色名称)
   try {
     await chatManager.connect('user-001','voice1');
     console.log('连接成功');
   } catch (err) {
     console.error('连接失败', err);
   }
   ```

3. **监听核心事件**

   ```typescript
   // 监听字幕消息
   chatManager.addEventListener(ChatManager.SUBTITLE_EVENT, (event) => {
     const { sub, is_first_sentence } = (event as CustomEvent).detail;
     console.log('字幕:', sub);
   });

   // 监听表情数据 (用于驱动数字人面部)
   chatManager.addEventListener(ChatManager.BLEND_SHAPE_EVENT, (event) => {
     const { bs } = (event as CustomEvent).detail;
     // bs 为表情权重数组
   });

    // 监听播放结束
    chatManager.addEventListener(ChatManager.PLAY_END_EVENT, () => {
        console.log('播放结束');
    });

    // 监听聊天服务器连接断开
    chatManager.addEventListener(ChatManager.DIS_CONNECT_EVENT, () => {
        console.log('聊天服务器连接断开');  
    });

    //监听聊天服务器满员
    chatManager.addEventListener(ChatManager.CLIENTS_FULL_EVENT, () => {
        console.log('聊天服务器满员！！！');
    });

   ```

4. **文本对话控制**

   ```typescript
    // 发送文本消息到聊天服务器
    chatManager.sendTextData("文本内容");

    // 发送TTS文本消息到聊天服务器进行无脑阅读
    chatManager.sendTtsTextData("文本内容");

   ```

5. **语音对话控制**

   ```typescript
   // 开始录音 (通常绑定到按钮点击事件)
   await chatManager.startMic();

   // 停止录音
   await chatManager.stopMic();
   ```

6. **数据录制与回放**

   ```typescript
   // 开启数据录制 (将对话音频和BS数据保存为本地JSON文件)
   // 文件保存于浏览器 OPFS (Origin Private File System) 中
   chatManager.enableA2ESaving = true;

   // 保存A2E数据到本地JSON文件
   await chatManager.saveA2EJson();

   // 播放本地/网络 JSON 格式的音频与表情数据
   // 数据格式需为包含 { audio: base64, bs: [] } 对象的数组
   await chatManager.playA2EJson('/path/to/a2e.json');

   ```

## 3. 功能特性

- **WebSocket通信**：实时双向传输音频与文本数据
- **流式播放**：支持服务端下发的音频流排队播放
- **表情同步**：音频播放与 BlendShape 数据帧精确对齐
- **功率监控**：实时回调录音音量功率用于UI展示
- **自动唤醒**：处理移动端 AudioContext 自动恢复机制
- **文本对话**：支持直接发送文本消息进行对话
- **状态管理**：提供完整的连接与录音状态查询接口
- **数据录制**：支持将对话过程中的音频与表情数据保存为本地 JSON 文件
- **本地回放**：支持加载并播放本地 JSON 格式的音频与表情数据

## 4. 配置说明

### 初始化配置

在创建 `ChatManager` 实例时，可以传入第二个参数 `AudioConfigOptions` 来自定义音频参数：

```typescript
const options = {
  sampleRate: 16000,          // 录音采样率 (默认 16000)
  frameMs: 600,               // 录音帧毫秒 (默认 600)
  silenceThreshold: 1,        // 静音阈值（默认：1）
  silenceDuration: 1000,      // 静音持续毫秒数（默认：1000）
  playerSampleRate: 16000,    // 播放采样率（默认：16000）
  echoCancellation: true,     // 回声消除（AEC）(默认:true)
  noiseSuppression: true,     // 噪声抑制 (默认:true)
  autoGainControl: false,     // 自动增益控制 (默认:false)
};

const chatManager = new ChatManager('ws://server-url', options);
```

### 关键配置文件

- **`src/AudioConfig.ts`**：定义了所有音频相关的默认配置参数，如采样率、静音阈值等。若需修改默认值，可在此文件或通过构造函数参数调整。

## 5. 开发指南

### 代码结构简要说明

```
src/
├── ChatManager.ts    # [核心] 统筹管理 WebSocket、录音与播放
├── AudioRecorder.ts  # [录音] 处理麦克风采集
├── AudioPlayer.ts    # [播放] 基于 Web Audio API，处理音频与表情同步
├── AudioConfig.ts    # [配置] 音频参数配置类
└── index.ts          # [入口] 模块导出定义
```

## 浏览器 UMD 使用（自包含）

UMD已自包含依赖，在浏览器可直接通过 CDN 引入：

```html
<script src="https://cdn.jsdelivr.net/npm/chat-a2e-manager/dist/index.umd.js"></script>
<script>
  const { ChatManager, AudioRecorder, AudioPlayer, AudioConfig } = window.ChatA2EManager;
  // 直接使用，无需额外依赖
</script>
```

若使用打包器（ESM/CJS），同样可以：

```ts
import { ChatManager } from 'chat-a2e-manager';
```

### 发布

- 运行构建：

```bash
npm run build
```

- 发布到 npm：

```bash
npm config set //registry.npmjs.org/:_authToken "npm_..."

npm publish

```

## 许可协议

MIT License