初始提交：3 款纯音频游戏 + 共享引擎 + 完整文档与资产管线

- 共享引擎（app/src/main）：GestureEngine 6 手势识别、AudioEngine 三层音频
  （ExoPlayer BGM 交叉淡入 / 对白 ducking / SoundPool 低延迟）、Game/GameEngine
  状态机接口、MainActivity 全屏封面 + TalkBack
- 《声命线》storyline：末世互动广播剧，3 幕 8 抉择点 4 结局
- 《声东击西》reflex：听声辨位反应，12 波战斗 + BGM 三档 BPM 变速
- 《暗室》escape：3x3 网格密室逃脱，钥匙→铁柜→保险丝→电箱→大门谜题链
- 文档：setup（从零搭建）/ architecture（架构）/ engine-api（引擎 API）/
  asset-pipeline（资产流水线）/ games/*（三款游戏设计文档）
- 资产管线：Qwen3-TTS 对白 + 程序合成音效/BGM + Mureka BGM 的 gen 脚本与台账，
  全部 ogg 资产入库可复现
- env.d 环境脚本：android/tts 入库；sfx/mureka 含密钥不入库，仅提交 .example.sh 模板

env.d/sfx.md

@@ -0,0 +1,62 @@
+# Stable Audio 3 small-sfx — 本地音效生成
+
+## 位置
+- 代码仓库: `/home/ubuntu/SoundGame/tools/stable-audio-3`
+- Python 环境: `/home/ubuntu/SoundGame/tools/stable-audio-3/.venv`（uv 管理，Python 3.10）
+- PyTorch: 2.7.1+cu126（CUDA 可用，RTX 3090 已验证）
+- 模型缓存: `/home/ubuntu/SoundGame/models/hf`（通过 `HF_HOME` 指定）
+- 环境变量: `source /home/ubuntu/SoundGame/env.d/sfx.sh`
+
+## 首次使用：必须申请模型访问权限（gated repo）
+
+`stabilityai/stable-audio-3-small-sfx` 是 **gated（auto 批准）** 仓库，匿名下载返回 403，必须：
+
+1. 注册/登录 HuggingFace 账号（可用镜像 https://hf-mirror.com 浏览，但 accept 协议需在官网完成；官网打不开时可用镜像站对应的模型页 https://hf-mirror.com/stabilityai/stable-audio-3-small-sfx 登录后接受）。
+2. 打开模型页 **https://huggingface.co/stabilityai/stable-audio-3-small-sfx**，点击接受 **Stable Audio Community License**（auto 模式，提交后立即通过，无需人工审核）。
+3. 在 https://huggingface.co/settings/tokens 创建一个 **read** 权限的 token。
+4. 把 token 写入 `/home/ubuntu/SoundGame/env.d/sfx.sh` 最后一行的 `HF_TOKEN`（去掉注释）。
+
+注意：本机 huggingface.co 不可达，下载走 `HF_ENDPOINT=https://hf-mirror.com`（已在 sfx.sh 中设置），gated 模型带 token 经镜像下载是支持的。
+
+## 生成音效（CLI）
+
+```bash
+source /home/ubuntu/SoundGame/env.d/sfx.sh
+cd /home/ubuntu/SoundGame/tools/stable-audio-3
+
+# 3 秒冒烟测试
+uv run stable-audio --model small-sfx \
+  -p "footsteps on gravel, slow walking" \
+  --duration 3 \
+  -o /home/ubuntu/SoundGame/tools/samples/sfx_test.wav
+```
+
+- 提示词必须是**英文**（模型只懂英文）。
+- `--duration` 最长 120s；`--steps` 默认 8；small 模型峰值显存约 2.4GB（120s 时），与 TTS 共存无冲突。
+- 多个提示词可批量生成：`-p "prompt1" "prompt2" --duration 3 5`。
+- 其他功能：audio-to-audio（`--init-audio`）、inpainting（`--inpaint-audio/--inpaint-start/--inpaint-end`），详见 `uv run stable-audio --help`。
+
+## Gradio UI
+
+```bash
+cd /home/ubuntu/SoundGame/tools/stable-audio-3
+uv run python run_gradio.py --model small-sfx
+```
+
+## Python API
+
+```python
+from stable_audio_3 import StableAudioModel
+
+model = StableAudioModel.from_pretrained("small-sfx")
+audio = model.generate(prompt="thunder rumbling in the distance", duration=3)
+```
+
+## 提示词参考
+见仓库内 `docs/guides/prompting.md`。
+
+## 状态记录（2026-08-29）
+- [x] 仓库克隆 + `uv sync --extra ui` 完成（PyPI 走阿里云镜像，torch 走官方 cu126 源）
+- [x] torch CUDA 验证通过：`torch 2.7.1+cu126, cuda: True, NVIDIA GeForce RTX 3090`
+- [x] CLI 可用（flash_attn 未安装的警告可忽略，仅 medium 需要）
+- [ ] 模型权重下载被 gated 403 拦截 —— 待用户申请 token 后重跑上面的冒烟测试