От сценария до голоса в игре

VoiceDirector помогает готовить диалоги в редакторе Unreal. Вы предоставляете текст, выбираете голос или импортируете запись, слушаете результат и решаете, какой дубль попадёт в игру. Итогом становится обычный звуковой ассет Unreal SoundWave. При настройке контекстов диалога также можно получить DialogueWave.

Реплика - запись в сценарии. Вариант - эта реплика на одном языке. Дубль - одна её звуковая запись. Можно хранить несколько дублей и сравнивать их, сохраняя прежний звук в игре.

Создайте проект, если только знакомитесь с Unreal

1. Откройте Epic Games Launcher, перейдите в Unreal Engine > Library и запустите UE 5.5, 5.6, 5.7 или 5.8.
2. В окне создания проекта выберите Games > Third Person, затем Blueprint и Desktop. Blueprint - визуальная программа из соединённых узлов. Для этого руководства писать C++ не нужно.
3. Задайте имя проекта и папку, где есть свободное место, нажмите Create и дождитесь загрузки редактора.

Добавьте VoiceDirector

Выберите сборку плагина под вашу версию Unreal для Windows x64. При установке через Fab добавьте плагин в нужную версию движка из библиотеки Launcher. Для установки в отдельный проект закройте редактор и поместите всю папку плагина в Plugins внутри проекта. Если этой папки нет, создайте её.

YourProject/
  YourProject.uproject
  Plugins/
    VoiceDirector/
      VoiceDirector.uplugin
      Binaries/
      Source/

Файл описания должен находиться прямо в Plugins/VoiceDirector, без второй вложенной папки VoiceDirector. Проекту только на Blueprint нужен собранный пакет со всеми поставляемыми файлами сборки. Копия только с исходниками требует компилятора C++ и сборки.

1. Снова откройте проект. Выберите Edit > Plugins, найдите VoiceDirector и включите его.
2. Перезапустите редактор, если он попросит.
3. Откройте Tools > VoiceDirector. В одном окне появятся пять вкладок.

В этом уроке используется готовая запись. Настраивать Kokoro или ElevenLabs пока не требуется.

1. Откройте Settings. В Output Content folder (/Game/...) укажите /Game/VoiceDirector/Audio и нажмите Save Output Folder. /Game означает папку Content проекта, а не диск Windows.
2. Скачайте оба учебных файла в обычную папку, которую легко найти.
3. В Lines раскройте Import script. В поле Import SourceId укажите MyScript, нажмите Import CSV и выберите учебный CSV.
4. Просмотрите изменения и нажмите Apply Import. Для этого урока оставьте Full snapshot выключенным.
5. Выберите реплику L-001 с языком en. Нажмите Import WAV и выберите учебный WAV. Справа появится карточка дубля.
6. Если нужно, нажмите Select take, затем Play. Прозвучит «Keep your voice down.» Кнопка Stop останавливает прослушивание.
7. Нажмите Approve take. Теперь дубль одобрен; публикация выполняется отдельно.
8. Откройте вкладку Publish или нажмите Review publishing. Нажмите Refresh Preview, отметьте строку нового SoundWave и нажмите Apply Selected Approved.
9. Откройте нижнюю панель Content Drawer сочетанием Ctrl + Space. Перейдите в Content > VoiceDirector > Audio. Новый SoundWave готов. Далее подключите его к игре.

В узком окне раскройте Sources & filters для импорта и Take review для дублей. Проверку также можно открыть двойным щелчком по реплике.

Напишите реплики в таблице или текстовом редакторе. VoiceDirector читает ваш текст, а не создаёт его. Сохраните CSV в UTF-8 с разделителем-запятой. Обязательные имена столбцов:

LineId,CharacterId,Culture,Text,Context
L-001,rowan,en,Keep your voice down.,At the city gate
L-002,mara,en,The gate is sealed.,Speaking calmly

Откройте Lines > Import script, задайте постоянный Import SourceId, выберите Import CSV, проверьте Added / Changed / Archived / Unchanged и нажмите Apply Import. Сам предварительный просмотр ничего не меняет.

Для обновления импортируйте сценарий снова с теми же SourceId и LineId. Идентификаторы и старые дубли сохраняются. Один LineId допустим на разных языках, но пара LineId и Culture должна быть уникальной внутри источника. Для переводов одной реплики сохраняйте того же персонажа.

Для CSV действуют пределы: 16 MiB и 10 000 строк.

Текст с запятой заключайте в двойные кавычки. Кавычка внутри ячейки записывается дважды: "Он сказал ""Стой.""". Табличный редактор обычно делает это сам. Если он выгрузил CSV с точкой с запятой, сохраните файл заново с запятыми.

DataTable - таблица со строками прямо внутри Unreal. Если сценарий уже хранится в такой таблице, выберите её в интерфейсе. CSV и ручной JSON не нужны.

1. Откройте Settings и выберите ассет в Script DataTable.
2. Сопоставьте столбцы с LineId, CharacterId, Culture, Text и при необходимости с Context и SpokenText. Поддерживаются типы String, Name и Text. Значение @RowName берёт LineId из имени строки таблицы.
3. Источник определяется автоматически по пути ассета DataTable. Нажмите Preview DataTable Import.
4. Просмотрите изменения во вкладке Lines и нажмите Apply Import.

Создание таблицы с нуля

В Content Browser создайте Blueprint Structure. Добавьте поля String LineId, CharacterId, Culture и поля Text Text, Context, SpokenText. Сохраните структуру. Создайте Data Table, выберите эту структуру как тип строки, добавьте строку и заполните её значениями из примера выше.

В DataTable допускается не более 10 000 строк.

Плагин также предоставляет тип VoiceDirectorScriptRow для импорта в редакторе. Если таблица нужна самой упакованной игре, используйте собственную структуру, доступную во время игры. Опубликованные SoundWave являются обычными игровыми ассетами.

Голос провайдера - готовый голос из Kokoro или ElevenLabs. Назначение в VoiceDirector связывает его с парой CharacterId + Culture. Это не создание новой голосовой модели.

1. Настройте провайдера по следующим разделам.
2. Откройте Voices, выберите провайдера и нажмите Check Connection / List Voices. Кнопка читает каталог без генерации речи.
3. Укажите CharacterId и Culture из сценария, выберите Voice и Model, настройте доступные параметры и нажмите Save Voice Assignment.
4. Вернитесь в Lines, выберите подходящий вариант и нажмите Generate new take.

Для примера: CharacterId rowan, Culture en, голос Kokoro af_heart, модель kokoro. Выбирайте голос, поддерживающий нужный язык. Для импорта WAV назначение голоса не требуется.

Изменение назначения влияет на следующую генерацию. Предыдущие дубли сохраняют исходные голоса и параметры.

Увеличить скриншот ↗

Kokoro-FastAPI работает отдельно на вашем компьютере либо на доступном сервере. VoiceDirector подключается к нему, но не устанавливает и не запускает сервер. Для зависимостей и моделей нужно свободное место.

1. Выполните официальную инструкцию Kokoro-FastAPI v0.9.0. Для варианта Windows CPU установите необходимые компоненты, загрузите модель и запустите .start-cpu.ps1 из папки сервера.
2. Дождитесь запуска и загрузки модели. При стандартной локальной установке откройте в браузере http://127.0.0.1:8880/docs, чтобы проверить ответ сервера.
3. В Settings плагина укажите Kokoro-FastAPI base URL: http://127.0.0.1:8880/v1. Нажмите Save Settings.
4. В Voices загрузите каталог Kokoro и сохраните назначение. Начните с af_heart, модели kokoro, английского en и скорости 1.0.

Скорость Kokoro доступна в диапазоне 0.5-2.0. Языки зависят от моделей и голосов сервера. Русский текст сценария и импорт русских WAV поддерживаются, но эта интеграция Kokoro не генерирует русскую речь. Для неё используйте подходящего другого провайдера или запись.

Нужны ваша учётная запись ElevenLabs, доступные кредиты и ключ с нужными разрешениями. Запросы расходуют лимит вашей учётной записи. Перед большой очередью ознакомьтесь с текущими тарифами провайдера.

1. В ElevenLabs откройте Developers > API Keys и создайте ключ. Включите Voices: Read и Text to Speech: Access. Если ключ ограничивает доступ к моделям, разрешите выбранную модель.
2. В поиске меню «Пуск» Windows найдите Изменение переменных среды текущего пользователя. В разделе пользовательских переменных нажмите Создать. Имя: VOICEDIRECTOR_ELEVENLABS_KEY. Значение: ваш ключ. Подтвердите все окна.
3. Полностью закройте Unreal Editor и Epic Games Launcher, включая процесс в системном трее. Откройте их заново, чтобы они получили новую переменную.
4. Во вкладке Voices выберите ElevenLabs, нажмите Check Connection / List Voices и выберите доступные вашей учётной записи голос и модель.
5. Сохраните назначение персонажа и языка. Сначала сгенерируйте одну короткую реплику и прослушайте результат.

VoiceDirector запрашивает pcm_24000 и преобразует полученный PCM в WAV. Чтение каталога само по себе не подтверждает право генерации этого формата. Скорость доступна в диапазоне 0.7-1.2; стиль и speaker boost доступны при поддержке выбранной моделью.

Для готового ключа откройте More Actions (...) > Edit и измените права. Подробности есть в официальной инструкции по ключам. Ошибки прав, квоты или регионального доступа нужно устранить у провайдера до повторной генерации.

1. Во вкладке Lines выберите один или несколько вариантов. Для нескольких используйте Ctrl или Shift.
2. Нажмите Generate selected. Проверьте подтверждение: провайдер, количество запросов, символов и доступная оценка стоимости. Подтвердите подходящую очередь.
3. Во вкладке Jobs следите за прогрессом. Pause приостанавливает новые отправки, Resume продолжает их, Cancel отменяет оставшуюся очередь.
4. У задания со статусом Completed нажмите Open take. Плагин откроет именно эту реплику и запись в Lines, убрав скрывающие её фильтры.

В очереди допускается не более 1 000 вариантов, в одном TTS-запросе - не более 5 000 символов.

При одном выбранном варианте кнопка называется Generate new take, при нескольких - Generate selected.

Завершённый дубль готов к проверке. Он не одобряется и не публикуется автоматически. При ошибке рядом с заданием появляется диагностика, которую можно скопировать.

Увеличить скриншот ↗

Справа у реплики показаны доступные дубли: произнесённый текст, происхождение, время, длительность и волна, рассчитанная по настоящему WAV. При выборе другой реплики открывается её история.

Нажмите Select take, затем Play или Stop. Когда исполнение подходит, нажмите Approve take. Все дубли остаются доступны для сравнения. Волна помогает увидеть речь и паузы; её масштаб подбирается для читаемости, поэтому громкость сравнивайте на слух.

Импорт своей записи

Выберите один вариант и нажмите Import WAV. Нужен RIFF WAV с порядком байтов little-endian: PCM 16 бит, 24 или 48 кГц, моно либо стерео, не более 64 MiB. MP3, WAV с плавающей точкой и PCM 24 бита предварительно преобразуйте.

В More line actions доступны блокировка, проверка перевода, переименование с сохранением ID и привязки диалога. Перед заменой одобрения разблокируйте вариант. Для нового дубля с теми же входными данными включите Create another take even if input matches.

Увеличить скриншот ↗

Публикация создаёт или обновляет ассеты Unreal из одобренных дублей. Генерация, импорт и одобрение сами по себе сохраняют прежний звук игры.

1. Откройте Publish и нажмите Refresh Preview.
2. Проверьте путь и действие в каждой строке. Create создаёт ассет, Update обновляет управляемый ассет, Conflict требует устранить причину.
3. Отметьте одобренные строки для применения. Включите необходимые базовые SoundWave и зависимости диалога.
4. Нажмите Apply Selected Approved и проверьте результат. Copy копирует путь ассета.

Плагин не перезаписывает ассеты с внешними изменениями, несохранёнными правками или доступом только для чтения. Устраните конфликт и обновите просмотр. Общей кнопки принудительной перезаписи нет. Для устаревшего одобренного дубля требуется отдельный флажок разрешения; сначала прослушайте запись и сравните её текст.

Увеличить скриншот ↗

SoundWave - стандартный звуковой ассет Unreal. Для первой проверки подключите его к узлу Blueprint:

1. Откройте уровень. В меню Blueprints основной панели выберите Open Level Blueprint.
2. Найдите Event BeginPlay. Если узла нет, щёлкните правой кнопкой по графу и найдите его через поиск.
3. Протяните соединение из белого выходного контакта исполнения, найдите Play Sound 2D и создайте узел.
4. В поле Sound этого узла выберите опубликованный SoundWave из папки вывода.
5. Нажмите Compile, сохраните Blueprint и уровень. Вернитесь в редактор и нажмите Play.

Реплика прозвучит при запуске уровня. Для персонажа в пространстве используйте узлы позиционного звука Unreal и свою логику разговора. VoiceDirector готовит ассеты, а игровая логика определяет момент воспроизведения.

Сохраните ссылку на опубликованный ассет в игре, чтобы он попал в сборку. Во время игры не нужны редакторные модули VoiceDirector, API-ключ и работающий сервер TTS. Подробнее: документация Epic по Play Sound 2D.

Добавьте переводы с теми же LineId и CharacterId, но другим Culture. Например, L-001,rowan,en и L-001,rowan,fr - два языковых варианта одной реплики. Подготовьте свой перевод и подходящий голос либо запись для каждого языка.

Исходный язык по умолчанию - en. Публикуйте базовый SoundWave вместе с новыми локализованными вариантами. Локализованные ассеты используют стандартную структуру Unreal /Game/L10N/<culture>/.... В игре ссылайтесь на базовый ассет, а локализацию выбирайте через активную культуру Unreal.

В Project Settings > Packaging добавьте нужные культуры в сборку и выберите соответствующие данные интернационализации. Смена языка интерфейса редактора сама по себе не настраивает язык диалогов игры.

DialogueWave

Для стандартных контекстов диалога создайте ассеты DialogueVoice говорящего и, при необходимости, слушателей. У реплики откройте More line actions, выберите Dialogue speaker, слушателей и постоянный Context key. Нажмите Save Dialogue Context и опубликуйте необходимые строки SoundWave и DialogueWave вместе.

DialogueVoice хранит сведения о персонаже в диалоге, а не голосовую модель. Поддерживается один контекст на LineId. Если нужны разные контексты разговора, используйте отдельные ID реплик.

1. Подготовьте сценарий и в Settings нажмите Export Actor Manifest CSV.
2. Передайте манифест исполнителю. Попросите сохранить идентификаторы и ожидаемые имена WAV, а также записать файлы в поддерживаемом формате.
3. Получив записи, выберите Choose Actor Manifest и Choose Returned WAV Folder в Settings.
4. Нажмите Preview Actor Matching. Проверьте готовые, отсутствующие и неоднозначные совпадения. Сначала исправьте имена или получите недостающие записи.
5. Выберите нужные готовые строки и нажмите Import Selected Actor WAVs. Прослушайте, одобрите и опубликуйте записи обычным способом.

Дубли сохраняют текст того манифеста, по которому записывался актёр. Если за это время сценарий изменился, полученный дубль может стать устаревшим. Сравните произнесённые слова с текущим сценарием.

В Settings находятся URL Kokoro, папка вывода, сопоставление DataTable, инструменты актёрских записей и лимиты очереди. Подключение и параметры генерации сохраняйте кнопкой Save Settings, папку вывода - кнопкой Save Output Folder.

Ограничения запросов и символов помогают задать размер очереди. Для оценки в долларах самостоятельно укажите цену провайдера за 1 000 символов. Значение -1 для цены означает, что она неизвестна; -1 для бюджета отключает ограничение в долларах. Если бюджет включён, а цена неизвестна, облачная генерация блокируется до возможности расчёта.

Настройки являются локальными предпочтениями редактора. Для обычной работы править JSON не нужно. Пользуйтесь видимыми полями и выбором ассетов, а не редактированием внутренних записей проекта.

Увеличить скриншот ↗

Сохраняйте резервную копию всего проекта, включая эти папки:

Сохраняйте данные дублей вместе с опубликованными ассетами. Один SoundWave не позволяет восстановить всю историю сценария и проверок.

В проект пишет только один редактор. Второй экземпляр может открыть VoiceDirector только для чтения. Закройте другой редактор и перезапустите текущий Unreal Editor, чтобы получить доступ к записи. Не удаляйте блокировку записи, пока проект используется другим процессом.

После прерывания генерации откройте Jobs. Уже отправленный запрос может иметь неизвестный результат и автоматически не повторяется. Перед новой попыткой проверьте провайдера.

Во вкладке Publish выберите Review interrupted publication для обнаруженной операции либо Restore From Publish Journal и журнал этого проекта Saved/VoiceDirector/Publish/<batch>/Journal.json. Прочитайте подтверждение перед восстановлением.

Для прерванной публикации сохраняются журнал и резервные копии. Не удаляйте их до завершения восстановления. Внешние изменения считаются конфликтами; после восстановления прежнего состояния новые ассеты могут остаться на диске для проверки. Если нужна помощь, сохраните копию проекта и передайте диагностическое сообщение в поддержку.

Напишите на nexusforgeuesupport@gmail.com. Укажите версии VoiceDirector и Unreal, провайдера, действия до проблемы, текст ошибки и приложите скриншот нужной вкладки.

Не присылайте API-ключи. Для проблемы с текстом или записью полезен небольшой пример, который можно передать, а не весь закрытый проект. Перед исследованием проблемы восстановления сохраните резервную копию.