239 lines
10 KiB
Markdown
239 lines
10 KiB
Markdown
# SoundGame — 从零环境搭建手册
|
||
|
||
本文档描述在一台全新的 WSL2（Ubuntu）机器上，如何以**纯用户态（无 sudo）**方式
|
||
复现本项目的全部开发环境：Android 构建链、Qwen3-TTS 对白生成、Stable Audio 3
|
||
音效生成、ffmpeg 音频处理。
|
||
|
||
前置条件：
|
||
|
||
- WSL2 + Ubuntu，能访问外网（部分站点需走镜像，见文末速查表）
|
||
- NVIDIA GPU（本项目用 RTX 3090 24GB）+ Windows 侧已装 NVIDIA 驱动
|
||
（WSL2 透传 CUDA，无需在 WSL 内装驱动，只需 `nvidia-smi` 能跑通）
|
||
- 项目放在 `/home/ubuntu/SoundGame`，下文所有路径以此为准
|
||
|
||
## 为什么不用 apt
|
||
|
||
- 本机**没有 sudo 权限**，`apt install` 直接不可用；
|
||
- 即使可用，Ubuntu 仓库的 JDK / Android SDK / ffmpeg 版本也偏旧，
|
||
且会污染系统目录，不利于把整个环境收进项目目录随仓库一起搬走；
|
||
- 所有工具因此都装在 `/home/ubuntu/SoundGame/tools/` 或用户目录下，
|
||
通过 `env.d/*.sh` 注入 PATH 使用，不开 shell 不污染环境。
|
||
|
||
## 1. uv（Python 包/环境管理）
|
||
|
||
```bash
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh # 装到 ~/.local/bin
|
||
~/.local/bin/uv --version # 实测 0.12.7 (x86_64-unknown-linux-gnu)
|
||
```
|
||
|
||
uv 自带 `python` 管理和虚拟环境管理，后续两个 venv 都由它创建。
|
||
注意 uv 不在默认 PATH，`env.d/sfx.sh` 里有 `export PATH="$HOME/.local/bin:$PATH"`。
|
||
|
||
## 2. JDK 17（用户态）
|
||
|
||
```bash
|
||
# 来源：华为云镜像的 Oracle OpenJDK 17.0.2（Adoptium 官方源在本机过慢）
|
||
# https://repo.huaweicloud.com/openjdk/17.0.2/openjdk-17.0.2_linux-x64_bin.tar.gz
|
||
cd /home/ubuntu/SoundGame/tools
|
||
curl -LO https://repo.huaweicloud.com/openjdk/17.0.2/openjdk-17.0.2_linux-x64_bin.tar.gz
|
||
tar xzf openjdk-17.0.2_linux-x64_bin.tar.gz
|
||
mv jdk-17.0.2 jdk17
|
||
tools/jdk17/bin/java -version # openjdk 17.0.2
|
||
```
|
||
|
||
## 3. Android SDK（cmdline-tools，无 Android Studio）
|
||
|
||
```bash
|
||
cd /home/ubuntu/SoundGame/tools
|
||
# 来源：Google 官方 dl.google.com（commandlinetools-linux-15859902_latest.zip）
|
||
curl -LO https://dl.google.com/android/repository/commandlinetools-linux-15859902_latest.zip
|
||
unzip commandlinetools-linux-15859902_latest.zip -d android-sdk-tmp
|
||
# 官方要求目录结构必须是 cmdline-tools/latest/，否则 sdkmanager 报路径错误
|
||
mkdir -p android-sdk/cmdline-tools
|
||
mv android-sdk-tmp/cmdline-tools android-sdk/cmdline-tools/latest
|
||
rm -rf android-sdk-tmp commandlinetools-linux-15859902_latest.zip
|
||
|
||
source /home/ubuntu/SoundGame/env.d/android.sh # 注入 JAVA_HOME/ANDROID_HOME/PATH
|
||
yes | sdkmanager --licenses
|
||
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
|
||
```
|
||
|
||
安装结果（与 `env.d/android.md` 一致）：platform-tools 37.0.1、android-36、
|
||
build-tools 36.0.0。
|
||
|
||
## 4. ffmpeg / ffprobe（静态构建）
|
||
|
||
```bash
|
||
# 来源：BtbN/FFmpeg-Builds 的 linux-x86_64 静态版（crosstool-NG 构建，零依赖）
|
||
# https://github.com/BtbN/FFmpeg-Builds/releases （ffmpeg-master-latest-linux64-gpl.tar.xz）
|
||
mkdir -p /home/ubuntu/SoundGame/tools/bin
|
||
# 解压后把 ffmpeg / ffprobe 两个二进制放进 tools/bin/ 即可
|
||
/home/ubuntu/SoundGame/tools/bin/ffmpeg -version
|
||
# 实测版本 N-126303-g9f35e220ff-20260827，含 libvorbis/libmp3lame/libopus
|
||
```
|
||
|
||
必须用含 `libvorbis` 的构建（资产出片格式是 ogg vorbis），GPL 版静态包自带。
|
||
|
||
## 5. Gradle
|
||
|
||
不需要单独安装：项目用 Gradle Wrapper，首次 `./gradlew` 自动下载。
|
||
本机 dl.google.com / services.gradle.org 均较慢，wrapper 已指向腾讯镜像：
|
||
|
||
```
|
||
# gradle/wrapper/gradle-wrapper.properties
|
||
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.13-bin.zip
|
||
```
|
||
|
||
首次构建：
|
||
|
||
```bash
|
||
source /home/ubuntu/SoundGame/env.d/android.sh
|
||
cd /home/ubuntu/SoundGame
|
||
./gradlew assembleDebug # 首次下载依赖较慢属正常，daemon 有缓存
|
||
```
|
||
|
||
## 6. Qwen3-TTS 对白环境（.venv-tts）
|
||
|
||
```bash
|
||
cd /home/ubuntu/SoundGame
|
||
~/.local/bin/uv venv .venv-tts --python 3.12 # 实测 Python 3.12.14
|
||
# PyPI 走阿里云镜像，torch 需 cu128 轮子
|
||
~/.local/bin/uv pip install --python .venv-tts/bin/python \
|
||
--index-url https://mirrors.aliyun.com/pypi/simple/ \
|
||
qwen-tts soundfile transformers
|
||
~/.local/bin/uv pip install --python .venv-tts/bin/python \
|
||
torch torchaudio --index-url https://download.pytorch.org/whl/cu128
|
||
```
|
||
|
||
实测版本：`torch 2.11.0+cu128`、`torchaudio 2.11.0+cu128`、`qwen-tts 0.1.1`、
|
||
`transformers 4.57.3`。
|
||
|
||
**⚠ torch 必须钉版本**（2026-09 踩坑）：`uv pip install torch torchaudio` 不带
|
||
版本号时，cu128 源会解析到最新版（2.13.0+**cu130**，CUDA 13 轮子），驱动
|
||
CUDA 12.8 带不动，报 "NVIDIA driver on your system is too old (found version
|
||
12080)"。且 uv 只升 torch 不动 torchaudio 时会出现混搭（torchaudio 链接
|
||
libcudart.so.13 加载失败）。正确做法按上面命令钉死 `==2.11.0`；若已装坏：
|
||
|
||
```bash
|
||
~/.local/bin/uv pip install --python .venv-tts/bin/python 'torch==2.11.0' 'torchaudio==2.11.0' \
|
||
--index-url https://download.pytorch.org/whl/cu128
|
||
~/.local/bin/uv pip install --python .venv-tts/bin/python --reinstall 'torchaudio==2.11.0' \
|
||
--index-url https://download.pytorch.org/whl/cu128 # torchaudio 必要时强制重装
|
||
```
|
||
|
||
模型下载（共 3 个仓库，缓存在 `models/hf`，由 `HF_HOME` 指定）：
|
||
|
||
```bash
|
||
source /home/ubuntu/SoundGame/env.d/tts.sh # HF_HOME + HF_ENDPOINT=https://hf-mirror.com
|
||
.venv-tts/bin/python -c "
|
||
from huggingface_hub import snapshot_download
|
||
for repo in ['Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice',
|
||
'Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign',
|
||
'Qwen/Qwen3-TTS-Tokenizer-12Hz']:
|
||
snapshot_download(repo); print('ok', repo)
|
||
"
|
||
```
|
||
|
||
**镜像注意事项**：本机连不通 huggingface.co，公开模型必须走
|
||
`HF_ENDPOINT=https://hf-mirror.com`（tts.sh 已设好）。Qwen 三个仓库均为公开
|
||
仓库，经镜像下载无障碍；gated 模型则不能走镜像，见下节。
|
||
|
||
冒烟测试：
|
||
|
||
```bash
|
||
source env.d/tts.sh
|
||
.venv-tts/bin/python tools/tts_smoke_test.py
|
||
# 输出 tools/samples/tts_test.wav（约 2s，24kHz）
|
||
```
|
||
|
||
详细用法（CustomVoice / VoiceDesign / 预置音色表）见 `env.d/tts.md`。
|
||
|
||
## 7. Stable Audio 3 音效环境（gated 模型）
|
||
|
||
```bash
|
||
cd /home/ubuntu/SoundGame/tools
|
||
git clone <stable-audio-3 仓库> stable-audio-3 # 项目内已有副本
|
||
cd stable-audio-3
|
||
cp /home/ubuntu/SoundGame/env.d/sfx.example.sh /home/ubuntu/SoundGame/env.d/sfx.sh
|
||
# 编辑 sfx.sh 填入真实 HF_TOKEN（见下）
|
||
source /home/ubuntu/SoundGame/env.d/sfx.sh
|
||
uv sync --extra ui # Python 3.10 venv，PyPI 走阿里云镜像（sfx.sh 已设）
|
||
```
|
||
|
||
实测：Python 3.10.6，`torch 2.7.1+cu126`，CUDA 验证通过。
|
||
|
||
### gated 模型 token 获取流程
|
||
|
||
`stabilityai/stable-audio-3-small-sfx` 是 **gated（auto 批准）** 仓库：
|
||
|
||
1. 注册/登录 HuggingFace 账号；
|
||
2. 打开 https://huggingface.co/stabilityai/stable-audio-3-small-sfx
|
||
接受 **Stable Audio Community License**（auto 模式立即通过，无需人工审核）；
|
||
3. 在 https://huggingface.co/settings/tokens 创建 **read** 权限 token；
|
||
4. 填入 `env.d/sfx.sh` 的 `HF_TOKEN`（该文件已被 .gitignore 忽略，不会入库）。
|
||
|
||
### 坑：hf-mirror 对 gated 模型的 308 重定向
|
||
|
||
**gated 模型不能走 hf-mirror**：镜像会把带 token 的请求 308 重定向回
|
||
huggingface.co，本机直连官方又不可达时会直接失败。因此 `env.d/sfx.sh` 里
|
||
**故意不设 `HF_ENDPOINT`**（直连官方端点，当前实测 huggingface.co 对该域名
|
||
可达）。如果以后直连失效且只下公开模型，可临时取消脚本里的镜像注释。
|
||
|
||
Qwen3-TTS（公开）走镜像、Stable Audio 3（gated）走直连——这就是
|
||
`tts.sh` 与 `sfx.sh` 的 `HF_ENDPOINT` 配置相反的原因。两个环境不要同时 source。
|
||
|
||
## 8. Mureka BGM API（可选，需付费 key）
|
||
|
||
```bash
|
||
cp env.d/mureka.example.sh env.d/mureka.sh # 填入 https://platform.mureka.ai 的 key
|
||
source env.d/mureka.sh
|
||
python3 tools/mureka_gen.py --prompt "..." --out tools/mureka_out/xxx
|
||
```
|
||
|
||
`env.d/mureka.sh` 含真实 API key，已被 .gitignore 忽略。计费与调用记录见
|
||
`tools/mureka_log.md`，完整流程见 `docs/asset-pipeline.md`。
|
||
|
||
## 网络镜像速查表
|
||
|
||
| 用途 | 镜像 | 配置位置 |
|
||
|---|---|---|
|
||
| HuggingFace 公开模型 | `https://hf-mirror.com` | `HF_ENDPOINT`（tts.sh / gen 脚本内） |
|
||
| HuggingFace gated 模型 | **不可用**，直连官方 | sfx.sh 故意不设 HF_ENDPOINT |
|
||
| PyPI | `https://mirrors.aliyun.com/pypi/simple/` | `UV_DEFAULT_INDEX` / `uv pip --index-url` |
|
||
| Gradle 发行包 | `https://mirrors.cloud.tencent.com/gradle/` | `gradle/wrapper/gradle-wrapper.properties` |
|
||
| JDK | `https://repo.huaweicloud.com/openjdk/` | 手动下载 |
|
||
|
||
## 常见故障排查
|
||
|
||
**`sdkmanager` 提示路径/找不到**
|
||
cmdline-tools 必须位于 `android-sdk/cmdline-tools/latest/`，多一层少一层都会报错。
|
||
|
||
**Gradle 下载卡住**
|
||
确认 wrapper 用的是腾讯镜像（见上）；依赖仓库（google/mavenCentral）本机直连可用，
|
||
如不行可在 `settings.gradle.kts` 临时加阿里云 maven 镜像。
|
||
|
||
**`qwen-tts` 打印 sox 警告**
|
||
系统无 `sox` 二进制（无 sudo 装不了），警告可忽略，不影响生成；
|
||
只有用到 sox 音频处理链路时才需要它。
|
||
|
||
**HF 下载 403 / 401**
|
||
模型是 gated 的（Stable Audio 3）：先接受许可再带 token；且 gated 模型经
|
||
hf-mirror 会被 308 回官网，见第 7 节。
|
||
|
||
**HF 下载卡住不动**
|
||
确认 `HF_ENDPOINT=https://hf-mirror.com` 已生效（`source env.d/tts.sh`），
|
||
并关掉 hf_transfer（`HF_HUB_ENABLE_HF_TRANSFER=0`，tts.sh 已设）。
|
||
|
||
**TTS / SFX 同时抢 GPU**
|
||
所有 GPU 任务必须用 `flock /home/ubuntu/SoundGame/.gpu.lock` 串行
|
||
（各 gen_voice.py 头部注释都有标准命令）。Stable Audio 3 small 峰值显存约
|
||
2.4GB，Qwen3-TTS 1.7B bf16 也远低于 24GB，理论上可共存，但仍建议串行省心。
|
||
|
||
**WSL2 里 `adb devices` 看不到手机**
|
||
WSL2 不能直接访问 USB。用无线调试（`adb pair` + `adb connect`）或让 adb server
|
||
跑在 Windows 侧，详见 `env.d/android.md`。
|
||
|
||
**真机上第一个音效没声音**
|
||
SoundPool 加载是异步的，首个音效会被吞。三个游戏都已在 `onStart` 里用
|
||
音量 0 预播预热（搜索源码里的 `prewarm`），新增音效记得加进预热清单。
|