YANG JIANKUAN
7147914a78
补充 eval.js/grammar 文件说明、三种模式与口诀范围介绍、 /stt 带题目参数的示例、多音色评测的音色全名注意事项 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
73 lines
3.6 KiB
Markdown
73 lines
3.6 KiB
Markdown
# 🦉 乘法口诀大闯关
|
||
|
||
小学生乘法口诀语音背诵小程序：**自动读题 → 小朋友开口说答案 → 离线语音识别判分**，全程免手。
|
||
|
||
- **🐢 顺序闯关**：按口诀表顺序背，答错重问同题
|
||
- **🎲 随机挑战**：打乱抽题，错题/慢题动态加权多练，练熟自动减少
|
||
- **🆚 双人抢答**：键盘或蓝牙手柄按键抢答（可自定义绑定），抢到者限时开口作答，答对 +5、答错/超时 −2，一局结束加冕冠军
|
||
- **📖 口诀范围**：家长设置里可全局限定「几开头～几开头」（比如只练到 4 的口诀），三种模式共用
|
||
- 界面面向 **PC / Pad**（多邻国风格），麦克风不可用时自动降级为数字键盘
|
||
|
||
语音识别用 **whisper.cpp 本地离线模型**（按题动态语法约束解码 + 方言发音兼容），不联网、不花钱、不上传任何数据到云端。
|
||
|
||
---
|
||
|
||
## 一、迁移到新电脑需要的文件
|
||
|
||
```
|
||
calx/
|
||
├── index.html # 前端（单页面，含全部 UI/逻辑）
|
||
├── server.js # 后端（零 npm 依赖，纯 Node）
|
||
├── start.sh # 一键启动
|
||
├── bootstrap.sh # 新机一键部署（装依赖 → 补模型 → 启动）
|
||
├── eval.js # 识别准确率回归评测（开发用，见 CLAUDE.md）
|
||
├── grammar/ # whisper 解码语法约束（静态兜底）
|
||
└── models/ # 识别模型（git 不追踪，bootstrap 自动下载）
|
||
├── ggml-small.bin # 中文识别模型（默认，较准，465MB）
|
||
└── ggml-base.bin # 备用模型（较快，141MB）
|
||
```
|
||
|
||
没有 `node_modules`。`models/` 建议一起拷，或到新机器重新下载（见下）。
|
||
|
||
## 二、新电脑需要的运行环境
|
||
|
||
```bash
|
||
# 1) Node.js（v16+ 即可，本项目用 v22 验证）
|
||
node -v
|
||
|
||
# 2) 系统命令：ffmpeg（转码）+ whisper-cli（识别）
|
||
brew install ffmpeg whisper-cpp
|
||
|
||
# 3) 模型（若没一起拷贝 models/）
|
||
mkdir -p models && cd models
|
||
curl -L -o ggml-small.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin
|
||
curl -L -o ggml-base.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin
|
||
cd ..
|
||
```
|
||
|
||
## 三、启动与访问
|
||
|
||
```bash
|
||
bash start.sh
|
||
# 或： node server.js
|
||
```
|
||
|
||
- **本机运行**：浏览器打开 `http://localhost:8000`，麦克风直接可用（localhost 是浏览器认可的安全上下文）。
|
||
- **对外部署**：浏览器只在安全上下文里放行麦克风，把服务挂在支持 **HTTPS 的反向代理**（如 nginx / Caddy / 云平台）后面即可，其余零改动。
|
||
|
||
## 四、参数配置
|
||
|
||
- 前端：`index.html` 顶部 `CONFIG`（读题开关、限时秒数、口诀范围、随机题数、错题加权、抢答参数、静音检测灵敏度等），或首页「⚙️ 家长设置」里直接改常用项。
|
||
- 后端模型：默认 `ggml-small.bin`。想更快可切 base：
|
||
```bash
|
||
WHISPER_MODEL=models/ggml-base.bin node server.js
|
||
```
|
||
- 端口：环境变量 `PORT`（默认 8000）。
|
||
|
||
## 五、常见问题
|
||
|
||
- **点“开始”没弹麦克风授权**：不是安全上下文——本机请用 `http://localhost:8000`，对外部署须走 HTTPS 反向代理。
|
||
- **识别不准 / 没反应**：确认终端有 `[stt] ... -> "xxx"` 日志；模型加载 `✅`；小朋友吐字清楚、环境别太吵。
|
||
- **iOS 上没声音读题**：iOS 要求首次交互才解锁语音，点过“开始”后即正常。
|
||
- **完全不想用语音**：点游戏里「⌨️ 用手写」，或环境不支持时会自动切数字键盘。
|