chat-a2e-manager

1. 项目概述

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

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

2. 快速开始

安装依赖

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

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','voice1');
     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 为表情权重数组
   });
   
    // 监听播放结束
    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. 文本对话控制

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

5. 语音对话控制

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

6. 数据录制与回放

   // 开启数据录制 (将对话音频和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 来自定义音频参数：

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 引入：

<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';

发布

• 运行构建：

npm run build

• 发布到 npm：

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

npm publish

许可协议

MIT License