chat-a2e-manager

1. 项目概述

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

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

2. 快速开始

环境准备

• Node.js：>= 18.0.0

安装依赖

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

npm install chat-a2e-manager

项目启动/运行

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

1. 引入库

   import ChatManager from 'chat-a2e-manager';

2. 创建实例与连接

   // 初始化实例，指定服务器地址
   const chatManager = new ChatManager('ws://localhost:8080');
   
   // 连接服务器 (可选传入用户ID)
   try {
     await chatManager.connect('user-001');
     console.log('连接成功');
   } catch (err) {
     console.error('连接失败', err);
   }

3. 监听核心事件

   // 监听字幕消息
   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 为表情权重数组
   });

4. 控制录音

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

3. 功能特性

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

4. 配置说明

初始化配置

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

const options = {
  sampleRate: 16000, // 录音采样率 (默认 16000)
  bitRate: 16, // 录音比特率 (默认 16)
  numChannels: 1, // 声道数 (默认 1)
  playerSampleRate: 16000, // 播放器采样率 (默认 16000)
};

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

关键配置文件

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

5. 开发指南

代码结构简要说明

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

浏览器 UMD 使用（自包含）

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

<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），同样可以：

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

Building

• 运行构建：

npm run build

产物输出至 dist/：

• ESM：dist/index.es.js
• CJS：dist/index.cjs.js
• 类型：dist/index.d.ts

发布前检查清单

• README.md 与对外 API 是否更新完整。
• npm run build 是否输出正确的 ES/CJS/UMD 与类型定义。
• .npmignore 限制只发布必要文件。

许可协议

MIT License