初始提交：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 模板
2026-08-29 13:00:34 +08:00
commit f0f0a9b50e
446 changed files with 2627836 additions and 0 deletions
@@ -0,0 +1,69 @@
+# SoundGame — Android 开发环境使用说明
+
+全部软件安装在用户目录，无需 sudo。`source` 环境变量文件后即可使用：
+
+```bash
+source /home/ubuntu/SoundGame/env.d/android.sh
+```
+
+## 已安装组件
+
+| 组件 | 版本 | 位置 |
+|---|---|---|
+| JDK (OpenJDK) | 17.0.2 | `tools/jdk17` |
+| Android cmdline-tools | latest (15859902) | `tools/android-sdk/cmdline-tools/latest` |
+| platform-tools (adb) | 37.0.1 | `tools/android-sdk/platform-tools` |
+| Android SDK Platform | android-36 | `tools/android-sdk/platforms/android-36` |
+| build-tools | 36.0.0 | `tools/android-sdk/build-tools/36.0.0` |
+| ffmpeg / ffprobe（静态） | N-126303 (2026-08-27) | `tools/bin/` |
+
+## 常用命令
+
+```bash
+adb devices                          # 查看已连接设备
+sdkmanager --list_installed          # 查看已安装 SDK 组件
+sdkmanager "platforms;android-36"    # 安装其他组件
+ffmpeg -i in.mp3 -c:a aac out.m4a    # 音频转码
+```
+
+Gradle 项目可在 `local.properties` 中写：
+```
+sdk.dir=/home/ubuntu/SoundGame/tools/android-sdk
+```
+
+## 真机调试（WSL2 无法直接访问 USB，推荐以下两种方式）
+
+### 方式一：无线调试（推荐，Android 11+）
+
+手机和电脑连同一 Wi-Fi。手机上：开发者选项 → 无线调试。
+
+```bash
+# 1. 配对（手机“无线调试”→“使用配对码配对”，会显示 IP:端口 和 6 位配对码）
+adb pair 192.168.x.x:37027
+# 输入配对码
+
+# 2. 连接（用无线调试首页显示的 IP:端口，注意与配对端口不同）
+adb connect 192.168.x.x:43215
+
+# 3. 验证
+adb devices
+```
+
+Android 10 及以下可先在有 root/电脑的机器上执行 `adb tcpip 5555`，再 `adb connect <手机IP>:5555`。
+
+### 方式二：Windows 侧 adb server（备选）
+
+WSL2 默认看不到 USB 设备。可让 adb server 跑在 Windows 侧：
+
+1. Windows 安装 platform-tools，手机开 USB 调试并连上 Windows，确认 Windows 的 `adb devices` 能看到手机。
+2. Windows 上执行：`adb -a -P 5037 nodaemon server`（监听所有网卡）。
+3. WSL2 中获取 Windows 主机 IP（`ip route show | awk '/default/ {print $3}'`），然后：
+   ```bash
+   export ADB_SERVER_SOCKET=tcp:<Windows主机IP>:5037
+   adb devices   # 现在走的是 Windows 的 server
+   ```
+
+## 备注
+
+- JDK 实际用的是华为云镜像的 Oracle OpenJDK 17.0.2（Adoptium 官方源在本机过慢），对 Gradle/Android 构建完全够用。
+- 未修改 `~/.bashrc`；每次新开 shell 需重新 `source env.d/android.sh`。
@@ -0,0 +1,13 @@
+# SoundGame Android 开发环境（纯用户态，无 sudo）
+# 用法: source /home/ubuntu/SoundGame/env.d/android.sh
+
+export JAVA_HOME=/home/ubuntu/SoundGame/tools/jdk17
+export ANDROID_HOME=/home/ubuntu/SoundGame/tools/android-sdk
+# 兼容旧工具的变量名
+export ANDROID_SDK_ROOT="$ANDROID_HOME"
+
+export PATH="$JAVA_HOME/bin:$PATH"
+export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"
+export PATH="$ANDROID_HOME/platform-tools:$PATH"
+# ffmpeg / ffprobe 静态构建
+export PATH="/home/ubuntu/SoundGame/tools/bin:$PATH"
@@ -0,0 +1,7 @@
+# Mureka 线上音乐生成 API (歌曲/BGM)（模板）
+# 用法: cp env.d/mureka.example.sh env.d/mureka.sh，填入真实 key 后 source env.d/mureka.sh
+# 注意: env.d/mureka.sh 含真实 API key，已被 .gitignore 忽略，切勿提交
+# 平台: https://platform.mureka.ai  (key 泄露时去 Dashboard 吊销换新的)
+export MUREKA_API_KEY=op_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# 国际站 endpoint; 若网络不通改 https://api.mureka.cn
+export MUREKA_API_BASE=https://api.mureka.ai
@@ -0,0 +1,14 @@
+# Stable Audio 3 small-sfx 音效生成环境变量（模板）
+# 用法: cp env.d/sfx.example.sh env.d/sfx.sh，填入真实 HF_TOKEN 后 source env.d/sfx.sh
+# 注意: env.d/sfx.sh 含真实 token，已被 .gitignore 忽略，切勿提交
+export PATH="$HOME/.local/bin:$PATH"
+export HF_HOME=/home/ubuntu/SoundGame/models/hf
+# 注意: hf-mirror 镜像会把 gated 模型 308 重定向回 huggingface.co 导致下载失败。
+# Stable Audio 3 是 gated 模型, 必须直连官方端点。
+# 若以后直连失效且只用公开模型, 可临时改回镜像:
+# export HF_ENDPOINT=https://hf-mirror.com
+# 本机 pypi.org 直连极慢, 重装/更新依赖时走阿里云镜像 (uv sync 用)
+export UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/
+# 接受 https://huggingface.co/stabilityai/stable-audio-3-small-sfx 的许可后,
+# 在 https://huggingface.co/settings/tokens 创建 read 权限 token 填入:
+export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -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 后重跑上面的冒烟测试
@@ -0,0 +1,96 @@
+# Qwen3-TTS 本地对白生成环境使用说明
+
+## 环境位置
+
+- 虚拟环境：`/home/ubuntu/SoundGame/.venv-tts`（Python 3.12.14，uv 创建）
+- 关键包：`torch 2.11.0+cu128`、`torchaudio 2.11.0+cu128`、`qwen-tts 0.1.1`、`soundfile`、`transformers 4.57.3`
+- 模型缓存：`/home/ubuntu/SoundGame/models/hf`（HF_HOME）
+  - `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice`（预置音色 + 情感指令，主力）
+  - `Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign`（文字描述造音色）
+  - `Qwen/Qwen3-TTS-Tokenizer-12Hz`（语音编解码器，上面两个模型自带副本，这个是独立的）
+
+## 启用环境
+
+```bash
+source /home/ubuntu/SoundGame/env.d/tts.sh   # 设置 HF_HOME / HF_ENDPOINT(hf-mirror 镜像)
+source /home/ubuntu/SoundGame/.venv-tts/bin/activate
+```
+
+注意：本机连不通 huggingface.co，必须走 `HF_ENDPOINT=https://hf-mirror.com`（tts.sh 已设好）。
+
+## 生成对白（CustomVoice：预置音色 + 情感指令）
+
+```python
+import torch, soundfile as sf
+from qwen_tts import Qwen3TTSModel
+
+model = Qwen3TTSModel.from_pretrained(
+    "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
+    device_map="cuda:0",
+    dtype=torch.bfloat16,
+)
+wavs, sr = model.generate_custom_voice(
+    text="快躲开！它来了！",
+    language="Chinese",
+    speaker="Vivian",
+    instruct="用惊恐、急促的语气大声喊出来",   # 不需要情感控制时省略
+)
+sf.write("out.wav", wavs[0], sr)   # sr = 24000
+```
+
+支持批量：`text`/`language`/`speaker`/`instruct` 均可传等长 list。
+可透传 HF `generate` 参数，如 `max_new_tokens=2048`。
+
+## VoiceDesign（文字描述造音色）
+
+```python
+model = Qwen3TTSModel.from_pretrained(
+    "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
+    device_map="cuda:0", dtype=torch.bfloat16,
+)
+wavs, sr = model.generate_voice_design(
+    text="哥哥，你回来啦！",
+    language="Chinese",
+    instruct="撒娇稚嫩的萝莉女声，音调偏高且起伏明显",
+)
+```
+
+## 预置音色查询
+
+代码查询：
+
+```python
+model.get_supported_speakers()   # ['aiden','dylan','eric','ono_anna','ryan','serena','sohee','uncle_fu','vivian']
+model.get_supported_languages()  # auto/chinese/english/french/german/italian/japanese/korean/portuguese/russian/spanish
+```
+
+中文对白推荐音色（母语中文）：
+
+| speaker | 描述 |
+|---|---|
+| Vivian | 明亮略带锋芒的年轻女声 |
+| Serena | 温暖柔和的年轻女声 |
+| Uncle_Fu | 低沉醇厚的中年男声 |
+| Dylan | 北京话年轻男声 |
+| Eric | 四川话活泼男声，略带沙哑 |
+
+（其余：Ryan/Aiden 英语男声，Ono_Anna 日语女声，Sohee 韩语女声）
+
+## 冒烟测试
+
+```bash
+/home/ubuntu/SoundGame/.venv-tts/bin/python /home/ubuntu/SoundGame/tools/tts_smoke_test.py
+# 输出 /home/ubuntu/SoundGame/tools/samples/tts_test.wav（实测 1.92s, 24kHz）
+```
+
+## Web UI（可选）
+
+```bash
+qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000
+```
+
+## 已知事项
+
+- 未装 `flash-attn`（可选加速，编译耗时长；RTX 3090 24GB 不装也完全够用，加载+生成一句仅十几秒）。
+- 系统无 `sox` 命令行二进制（无 sudo 装不了），qwen-tts 会打印警告但**不影响生成**；只有用到 sox 音频处理链路时才需要它。
+- 显存占用：1.7B 模型 bf16 推理远低于 24GB，充足。
@@ -0,0 +1,7 @@
+# Qwen3-TTS 环境变量（用法: source /home/ubuntu/SoundGame/env.d/tts.sh）
+export HF_HOME=/home/ubuntu/SoundGame/models/hf
+# huggingface.co 本机连不通，使用国内镜像
+export HF_ENDPOINT=https://hf-mirror.com
+export HF_HUB_ENABLE_HF_TRANSFER=0
+# 便捷别名
+alias venv-tts='source /home/ubuntu/SoundGame/.venv-tts/bin/activate'