小智Web客户端介绍与使用指南一、项目概述xiaozhi-web-client是一个开源的小智Web客户端实现提供了语音对话功能。该项目通过WebSocket实现实时通信支持Opus音频编码让用户可以在浏览器中直接与小智进行语音交互。项目说明链接xiaozhi-esp32-server小智ESP32服务器端xiaozhi-esp32-serverxiaozhi-web-client小智ESP32客户端xiaozhi-web-client项目地址xiaozhi-web-client注意该项目目前暂停维护但仍可使用。官方推荐使用开源的安卓端获得更好的体验。启动客户端的的时候最好是已经启动好咯服务端。二、功能特点功能说明实时语音对话通过麦克风进行语音交互支持实时录音和播放文字消息支持可以直接在输入框输入文字进行对话WebSocket通信使用WebSocket协议实现低延迟的双向通信Opus音频编码采用高效的Opus编码保证音质的同时减少带宽占用自动重连机制连接断开后自动尝试重连流式音频播放支持音频流的实时播放无需等待完整下载设备认证支持可配置Token进行身份验证三、项目架构核心文件说明xiaozhi-web-client/ ├── app.py # Web服务器提供Web界面并管理代理服务 ├── proxy.py # WebSocket代理服务器处理音频转换和数据转发 ├── get_valid_code.py # 获取六位验证码的工具脚本 ├── templates/index.html # 前端界面 ├── static/ # 静态资源目录 │ ├── audio-processor.js # 音频处理模块 │ └── styles.css # 样式文件 ├── .env # 环境配置文件 └── .env.example # 环境配置示例文件工作流程浏览器 (Web界面) ↓ WebSocket连接 本地代理服务器 (proxy.py, 端口5002) ↓ 音频编码/解码 数据转发 远程服务器 (xiaozhi-esp32-server)四、快速开始方式一源码运行1. 配置环境变量首先从.env.example创建.env文件cp.env.example .env2. 安装依赖推荐方式 - 使用 Poetrypoetryinstallpoetry run python app.py直接运行pipinstall-rrequirements.txt python app.py方式二Docker运行使用 docker-compose推荐# 构建并启动docker-composeup-d# 查看日志docker-composelogs-f# 停止服务docker-composedown直接使用 Docker# 构建镜像dockerbuild-txiaozhi-web.# 运行容器dockerrun-d\--namexiaozhi-web\-p5001:5001\-p5002:5002\-eWS_URLws://your_server_address:9005\-eDEVICE_TOKENyour_token\xiaozhi-web启动后访问http://localhost:5001即可使用。五、.env 文件配置详解.env文件是项目的核心配置文件控制着服务器地址、认证信息等关键参数。配置参数说明序号参数说明默认值示例1WS_URLWebSocket服务器地址ws://localhost:9005ws://your_server:8000/xiaozhi/v1/2DEVICE_TOKEN设备认证令牌123从服务器获取的Token3WEB_PORTWeb服务器端口500150014PROXY_PORTWebSocket代理端口500250025ENABLE_TOKEN是否启用Token验证truetrue/false6LOCAL_PROXY_URL本地代理地址ws://localhost:5002ws://localhost:50027CLIENT_ID客户端唯一标识自动生成UUID6d6ca305-10ac-4349-8609-6ca6330d092c配置示例完整配置启用认证# 1. WebSocket服务器地址 WS_URLws://your_server_address:8000/xiaozhi/v1/ # 2. 设备认证令牌从服务器获取 DEVICE_TOKENyour_valid_token # 3. Web服务器端口 WEB_PORT5001 # 4. WebSocket代理端口 PROXY_PORT5002 # 5. 启用Token验证 ENABLE_TOKENtrue # 6. 本地代理地址 LOCAL_PROXY_URLws://localhost:5002 # 7. 客户端唯一标识首次运行自动生成 CLIENT_ID6d6ca305-10ac-4349-8609-6ca6330d092c配置要点WS_URL如果你使用 xiaozhi-esp32-server地址格式为ws://服务器地址:端口/xiaozhi/v1/ENABLE_TOKEN设为false可跳过Token验证适合本地测试CLIENT_ID首次运行时自动生成并写入配置用于标识客户端身份六、如何获取六位有效验证码概述当服务器启用设备认证时新设备首次连接需要获取六位验证码进行激活。本项目提供了get_valid_code.py脚本用于获取验证码。工作原理验证码获取流程1. 获取设备MAC地址作为设备ID 2. 构造OTA请求模拟ESP32设备 3. 向服务器OTA接口发送请求 4. 服务器返回激活码如设备未认证 5. 使用验证码完成设备激活使用方法1. 确保服务器正在运行确保你的 xiaozhi-esp32-server 已启动OTA接口默认端口为8002。2. 修改脚本中的服务器地址编辑get_valid_code.py将ota_http_url改为你的服务器地址ota_http_urlhttp://127.0.0.1:8002/xiaozhi/ota/如果服务器在其他地址改为ota_http_urlhttp://your_server_ip:8002/xiaozhi/ota/3. 运行脚本获取验证码python get_valid_code.py4. 输出结果脚本会输出以下信息已认证设备输出6位有效验证码...已认证未认证设备输出具体的六位验证码如6位有效验证码...123456获取验证码后在Web界面的设置面板中输入验证码或直接将验证码配置到.env文件的DEVICE_TOKEN参数设备激活后后续连接无需再次验证源码解析importrequestsimportjsonfromloguruimportloggerfromappimportget_mac_addressdefload_param():device_idget_mac_address()# e:7a:00:f1:4a:2bota_headers{Device-Id:device_id,Content-Type:application/json}ota_post_data{flash_size:16777216,minimum_free_heap_size:8318916,mac_address:device_id,chip_model_name:esp32,chip_info:{model:9,cores:2,revision:2,features:18},application:{name:xiaozhi,version:1.0.1},partition_table:[],ota:{label:factory},board:{type:demo,ip:127.0.0.1,mac:device_id}}returndevice_id,ota_headers,ota_post_datadefget_ota_version(ota_http_url,device_id,ota_headers,ota_post_data):responserequests.post(ota_http_url,headersota_headers,datajson.dumps(ota_post_data))response_dataresponse.json()logger.info(fdevice_id....................................{device_id})ifresponse_data.get(activation,):logger.info(f6位有效验证码..................................已认证)else:valid_coderesponse_data.get(activation,).get(code,123321)logger.info(f6位有效验证码.........................................{valid_code})returnresponse# 获取六位有效验证嘛if__name____main__:ota_http_urlhttp://127.0.0.1:8002/xiaozhi/ota/device_id,ota_headers,ota_post_dataload_param()responseget_ota_version(ota_http_url,device_id,ota_headers,ota_post_data)七、使用说明基本操作语音对话点击绿色的开始通话按钮开始录音再次点击结束录音文字对话直接在输入框输入文字按回车或点击发送按钮设置面板点击右上角齿轮图标可配置服务器地址和认证信息注意事项注意点说明浏览器权限需要允许浏览器访问麦克风HTTPS要求生产环境建议使用HTTPS否则部分浏览器可能限制麦克风访问浏览器推荐建议使用Chrome或Firefox浏览器端口占用确保5001和5002端口没有被其他程序占用服务器配置确保WS_URL和DEVICE_TOKEN配置正确八、常见问题Q1: 无法连接WebSocket解决方案检查.env文件中的WS_URL是否正确确认服务器已启动并可访问检查网络连接和防火墙设置Q2: 麦克风无法访问解决方案确保浏览器已授权麦克风访问使用localhost或配置HTTPS部分浏览器限制非HTTPS环境的麦克风访问检查麦克风设备是否正常工作Q3: Token验证失败解决方案运行get_valid_code.py获取正确的验证码将验证码配置到.env文件的DEVICE_TOKEN或将ENABLE_TOKEN设为false跳过验证九、项目展示聊天界面支持文字和语音交互界面简洁直观。设置面板可配置服务器地址、本地代理地址和认证信息支持Token开关。语音通话实时语音对话模式带有波形动画反馈增强交互体验。十、总结xiaozhi-web-client 提供了一个便捷的Web界面来使用小智语音助手。通过简单的配置你可以快速启动服务并开始语音对话。关键配置步骤包括配置 .env 文件- 设置服务器地址和端口获取验证码- 如果服务器启用认证使用get_valid_code.py获取六位验证码启动服务- 使用 Poetry 或 Docker 运行开始使用- 打开浏览器访问 Web 界面如果你在部署过程中遇到问题可以参考上述常见问题的解决方案或查看项目的 GitHub Issues。