calx/README.md

🦉 乘法口诀大闯关

小学生乘法口诀语音背诵小程序：自动读题 → 小朋友开口说答案 → 离线语音识别判分，全程免手。 支持顺序闯关 / 随机挑战（错题动态加权，练熟自动减少）/ 双人抢答，限时作答、正/负反馈动效音效。

语音识别用 whisper.cpp 本地离线模型，不联网、不花钱、不上传任何数据到云端。

---

一、迁移到新电脑需要的文件

calx/
├── index.html            # 前端（单页面）
├── server.js             # 后端（零 npm 依赖，纯 Node）
├── start.sh              # 一键启动
├── bootstrap.sh          # 新机一键部署
├── grammar/              # whisper 解码语法约束
└── models/
    ├── ggml-small.bin    # 中文识别模型（默认，较准，465MB）
    └── ggml-base.bin     # 备用模型（较快，141MB）

没有 node_modules。models/ 建议一起拷，或到新机器重新下载（见下）。

二、新电脑需要的运行环境

# 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 start.sh
# 或： node server.js

• 本机运行：浏览器打开 http://localhost:8000，麦克风直接可用（localhost 是浏览器认可的安全上下文）。
• 对外部署：浏览器只在安全上下文里放行麦克风，把服务挂在支持 HTTPS 的反向代理（如 nginx / Caddy / 云平台）后面即可，其余零改动。

四、参数配置

• 前端：index.html 顶部 CONFIG（读题开关、限时秒数、口诀范围、随机题数、错题加权、抢答参数、静音检测灵敏度等），或首页「⚙️ 家长设置」里直接改常用项。
• 后端模型：默认 ggml-small.bin。想更快可切 base：

  WHISPER_MODEL=models/ggml-base.bin node server.js
  

• 端口：环境变量 PORT（默认 8000）。

五、常见问题

• 点“开始”没弹麦克风授权：不是安全上下文——本机请用 http://localhost:8000，对外部署须走 HTTPS 反向代理。
• 识别不准 / 没反应：确认终端有 [stt] ... -> "xxx" 日志；模型加载 ✅；小朋友吐字清楚、环境别太吵。
• iOS 上没声音读题：iOS 要求首次交互才解锁语音，点过“开始”后即正常。
• 完全不想用语音：点游戏里「⌨️ 用手写」，或环境不支持时会自动切数字键盘。