Русская озвучка всех 525 озвученных записок и мини-историй (Ministory) Enshrouded. Голос — клон английского диктора игры, текст — официальный русский перевод игры. Мод ставится через EML (Enshrouded Mod Loader) и не трогает оригинальные файлы игры.


Версия	0.4.0 (игра 1.0, октябрь 2026)
Объём	525 записок, 425 минут, 467 МБ
Синтез	Qwen3-TTS 1.7B, дообучение `ru-stress-cf` с ударениями, ICL-клон диктора
Контроль	автоматический, без прослушивания: ударения 99,9 % по всем кускам; WER 2,4 % и MOS 3,45 на выборке из 60 записок

Озвучка — синтез, а не запись актёра. Голос повторяет тембр английского диктора, тексты принадлежат Keen Games. Это любительский мод: не продавайте его и не выдавайте за официальный.

Что в репозитории

mod/ru_voice_notes/   готовый мод: data/*.qoa (Git LFS), src/*.lua, mod.json
install.py            установка и удаление мода (только стандартная библиотека Python)
run.py                конвейер генерации по шагам (каждый шаг в своём окружении)
ensvoice/             ключевые скрипты конвейера
  extract.py            тексты и английский звук из файлов игры
  refs.py               референсы диктора, его тембр и паузы
  segments.py           текст для голоса: лексикон, ударения, нарезка по абзацам
  lexicon.py            ← главное место для правок: имена, ударения, сокращения
  render.py, tts/       синтез (локальный GPU или сервер media-node)
  qc.py, pick.py        автоматическая проверка дублей и отбор лучшего
  assemble.py, mod.py   склейка записок, QOA, сборка мода
  refbench.py           сравнение референсов голоса по метрикам
env/                  зависимости двух окружений
docs/GENERATION.md    как устроена генерация и как её улучшать
config.example.toml   пример настроек

В репозиторий не попадают данные, извлечённые из игры (work/), окружения (.venv-*), модели, бинарники EML (tools/) и config.toml: всё это перечислено в .gitignore.

Установка мода (для игрока)

Нужны Windows, Steam-версия Enshrouded, Python 3.11+, Git с Git LFS.

git clone https://git.shahovalov.ru/mikhail/enshrouded-ru-voice.git
cd enshrouded-ru-voice
git lfs pull
python install.py

В конце должна появиться строка [ru_voice] replaced 525 notes, 0 failed, затем INSTALLED. Игру запускать как обычно, из Steam. Язык озвучки в игре оставить английским: мод подменяет английскую дорожку записок, своего русского слота у озвучки в игре нет.

Удаление: python install.py --uninstall (или «Проверить целостность файлов» в Steam).

Инструкция для агента: установка

Агент выполняет шаги по порядку. После каждого шага есть проверка: если она не прошла, агент не идёт дальше и разбирает причину по таблице ниже. Команды даны для Git Bash или PowerShell 7 на Windows.

A. Только поставить мод (без генерации)

Проверить окружение.
```
python --version
git lfs version
```
Ожидаемо: Python 3.11 или новее, git-lfs 3.x. Если Python нет, поставить winget install Python.Python.3.12; если нет Git LFS, поставить winget install GitHub.GitLFS, затем выполнить git lfs install.
Клонировать и скачать звук.
```
git clone https://git.shahovalov.ru/mikhail/enshrouded-ru-voice.git
cd enshrouded-ru-voice
git lfs pull
```
Проверка: в mod/ru_voice_notes/data лежат 525 файлов .qoa, все больше 1 КБ, вместе около 467 МБ. Файлы меньше 1 КБ — это LFS-указатели: снова выполнить git lfs pull.
Спросить пользователя, закрыта ли игра и можно ли записать в папку игры dbghelp.dll и mods/ru_voice_notes. Без согласия дальше не идти.
Установить.
```
python install.py
```
Если игра стоит не в библиотеке Steam, добавить --game "<папка с enshrouded.kfc>". Ожидаемо: строки [ru_voice] replaced 525 notes, 0 failed и INSTALLED.
Сообщить пользователю: игру запускать из Steam, язык озвучки оставить английским, записки читаются по-русски. Откат: python install.py --uninstall.

B. Поставить конвейер генерации (чтобы дорабатывать)

Требования: NVIDIA GPU с 12 ГБ VRAM и больше (проверено на RTX 5080 16 ГБ и Tesla V100 32 ГБ), 32 ГБ RAM, около 35 ГБ на диске (модели около 10 ГБ, рабочая папка около 15 ГБ), свежий драйвер NVIDIA (CUDA 12.8), uv. Сначала выполнить раздел A до шага 2 включительно.

Проверить GPU и uv.
```
nvidia-smi
uv --version
```
Если uv нет: winget install astral-sh.uv.

Создать два окружения. Их два, потому что qwen-tts требует transformers 4.x, а модели контроля качества требуют 5.x.

uv venv -p 3.12 .venv-tts
uv pip install -p .venv-tts/Scripts/python.exe torch torchaudio --index-url https://download.pytorch.org/whl/cu128
uv pip install -p .venv-tts/Scripts/python.exe -r env/tts.txt
uv venv -p 3.12 .venv-qc
uv pip install -p .venv-qc/Scripts/python.exe torch torchaudio --index-url https://download.pytorch.org/whl/cu128
uv pip install -p .venv-qc/Scripts/python.exe -r env/qc.txt

На Linux путь к интерпретатору — .venv-tts/bin/python.

Настроить. Скопировать config.example.toml в config.toml и заполнить:
- paths.game — папка игры (её нашёл install.py, путь напечатан в строке game:);
- paths.work — папка на том же диске, что и игра (см. «Ловушки»), с 15 ГБ свободного места;
- tts.dtype — bfloat16 для RTX 30xx и новее, float16 для RTX 20xx, GTX 16xx, V100.
Инструменты EML. Если install.py ещё не запускался, скачать их через него, ответив пользователю по шагу A.3, либо взять kfc-parser.exe и emm.exe вручную из релиза Brabb3l/kfc-parser v0.2.0 в tools/.
Проверить установку.
```
python run.py check
```
Ожидаемо: две строки с версией torch, cuda True и именем GPU, затем CHECK_OK.
Пробный прогон на трёх записках, около 15 минут. Модели (около 10 ГБ) скачиваются с Hugging Face при первом запуске.
```
export ENSVOICE_NOTES=n016,n238,n363      # PowerShell: $env:ENSVOICE_NOTES="n016,n238,n363"
python run.py extract
python run.py refs
python run.py segments
python run.py render
python run.py qc
python run.py pick
python run.py assemble
```
Ожидаемо: после extract — notes 525 EN minutes 488; после refs — configured reference ... found; после pick — 'segments': 16, 'picked': 16; после assemble — ASSEMBLED 3 notes. Готовые WAV для проверки лежат в <work>/wav48/. Не запускать python run.py mod с переменной ENSVOICE_NOTES: собранный мод заменит в mod/ru_voice_notes все 525 записок тремя.
Снять переменную (unset ENSVOICE_NOTES) и сообщить пользователю, что конвейер работает. Полный прогон (python run.py all) на RTX 5080 занимает около суток (см. docs/GENERATION.md), его запускают по просьбе пользователя.

Ловушки и ошибки

Симптом	Причина и что делать
`extract`: `EN minutes` не 488, а около 425	В игре применён мод: EML пропатчил `enshrouded.kfc`, и прочиталась русская озвучка. `extract` сам берёт исходный индекс из `enshrouded.kfc.bak` через жёсткие ссылки — для этого `paths.work` должен быть на диске игры. Иначе: `tools/emm.exe restore -g "<игра>"` и повторить `extract`.
`install.py`: `close Enshrouded first`, `os error 32`	Игра запущена: закрыть её.
`.qoa` по 130 байт, `LFS pointers`	Не скачан LFS: `git lfs install`, затем `git lfs pull`.
`render`: `CUDA out of memory`	Уменьшить `tts.batch` до 4. Больше 8 не ставить: на RTX 5080 16 ГБ батч 16 упирается в видеопамять и работает в разы медленнее.
`bf16 is not supported` / NaN	GPU старше Ampere: `tts.dtype = "float16"`.
`qc` убит, `Killed`, MemoryError	Каждый процесс QC берёт 8–13 ГБ RAM: запускать меньше шардов.
`refs`: `configured reference ... NOT FOUND`	Другая версия игры: выбрать id из `<work>/refs.json` через `refbench`.
`extract`: `expected 525 voiced notes`	Обновление игры изменило записки: конвейер работает, но мод из репозитория может не подойти — собрать свой.

Как дорабатывать и делиться

Порядок работы и все приёмы описаны в docs/GENERATION.md. Коротко: правки идут в lexicon.py или конфиг, затем по цепочке segments → render → qc → pick → assemble → mod (заново считаются только изменённые куски) и python install.py.

Делиться результатом: ветка с изменениями кода, лексикона и обновлённым mod/ru_voice_notes плюс pull request. В описании PR привести числа из <work>/pick_report.json до и после (wer, stress, mos, weak): по ним видно, что правка улучшила озвучку, а не просто изменила её. Без доступа на запись в этот Gitea — форк или patch-файл с git format-patch.

Благодарности

Brabb3l/kfc-parser (распаковка и EML) · Qwen3-TTS · siriusfreak/qwen3-tts-12hz-1.7b-ru-stress-cf (ударения и meter2) · RUAccent · GigaAM · UTMOSv2 · WavLM

Код — MIT (см. LICENSE). Озвучка в mod/ — производная от материалов игры и не покрывается лицензией кода.

README.md Unescape Escape

Enshrouded — русская озвучка записок