# 项目使用说明

本项目是运行于 **Linux** 平台的 JoyInside 语音交互程序，通过 **WebSocket (wss)** 与京东 JoyInside 云端建立实时语音对话。主要流程及功能：

- 麦克风采集（ALSA）→ 重采样 → Opus 编码 → 上行到云端
- 云端 TTS（Opus）→ 解码 → 重采样 → 喇叭播放
- 解析云端事件：ASR / TTS / 打断 / 有声书（HTTP/HTTPS MP3 流式播放）
- 断线指数退避重连、应用层心跳、会话空闲超时管理
- 有声书子模块：HTTP 流式拉取 MP3 → minimp3 解码 → speexdsp 重采样 → 播放

## 文档索引

| 文档 | 说明 |
| --- | --- |
| [01-project-structure.md](01-project-structure.md) | 目录结构、源文件职责说明 |
| [02-build-and-deploy.md](02-build-and-deploy.md) | 编译、部署与运行步骤 |
| [03-usage-notes.md](03-usage-notes.md) | 使用注意事项、代码修改指南与常见问题 |

## 快速接入 JoyInside

### 1. 获取接入凭证

联系 JoyInside 技术支持或参考 [JoyInside 开发者平台](https://joyinside.com/docs/#/zh-cn/api_overview) 申请：

| 参数 | 说明 |
| --- | --- |
| `bot_id` | 对话设备 ID（预创建，或通过设备注册接口获取） |
| `access_key_id` | 访问密钥 ID |
| `access_key_secret` | 访问密钥（需保密） |

### 2. 配置凭证

三种方式（优先级从高到低）：

1. **命令行参数**：`./joyinside_demo --bot_id=xxx --access_key_id=xxx --access_key_secret=xxx`
2. **配置文件**：复制 `conf/joyinside.conf.example` 为 `joyinside.conf` 放在工作目录，填入凭证
3. **环境变量**：`JOYINSIDE_BOT_ID` / `JOYINSIDE_ACCESS_KEY_ID` / `JOYINSIDE_ACCESS_KEY_SECRET`

### 3. 编译部署

见 [02-build-and-deploy.md](02-build-and-deploy.md)。
