From a script to a voice in your game

VoiceDirector is an editor tool for producing dialogue. You supply the words, choose a voice or import a recording, listen to the results and decide which take goes into the game. The result is a standard Unreal SoundWave audio asset; dialogue bindings can also produce DialogueWave assets.

A line is an entry in your script. A variant is that line in one language. A take is one recording of the variant. You can keep several takes without replacing the audio already used in the game.

Create a project if you are new to Unreal

1. Open Epic Games Launcher, go to Unreal Engine > Library and launch UE 5.5, 5.6, 5.7 or 5.8.
2. In the project browser choose Games > Third Person, then Blueprint and Desktop. A Blueprint is a visual program made from connected nodes; you do not need to write C++ for this guide.
3. Choose a project name and a folder with free space, then click Create. Wait for the editor to finish loading.

Add VoiceDirector

Use the plugin build for your Unreal version on Windows x64. When installing through Fab, add it to the selected engine version from your launcher library. For a project installation, close the editor and put the entire plugin folder inside your project's Plugins folder. Create Plugins if necessary.

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

The descriptor must be directly inside Plugins/VoiceDirector, without a second nested VoiceDirector folder. A Blueprint-only project needs the compiled package, including its supplied build files. A source-only copy requires a C++ compiler and rebuilding.

1. Reopen the project. Choose Edit > Plugins, search for VoiceDirector and enable it.
2. Restart the editor if requested.
3. Open Tools > VoiceDirector. Its five tabs appear in one window.

This lesson uses the provided recording. You can finish it without configuring Kokoro or ElevenLabs.

1. Open Settings. Set Output Content folder (/Game/...) to /Game/VoiceDirector/Audio and click Save Output Folder. /Game means the project's Content folder, not a Windows drive.
2. Download both example files to an ordinary folder you can find again.
3. In Lines, open Import script. Set Import SourceId to MyScript, click Import CSV and choose the example CSV.
4. Review the import preview and click Apply Import. Leave Full snapshot off for this lesson.
5. Select L-001 in language en. Click Import WAV and choose the example WAV. A take appears in the review panel.
6. Click Select take if needed, then Play. You should hear “Keep your voice down.” Use Stop to stop playback.
7. Click Approve take. Approval records your choice; publishing is the next step.
8. Open Publish or click Review publishing. Click Refresh Preview, check the row for the new SoundWave and click Apply Selected Approved.
9. Open the Content Drawer with Ctrl + Space. Go to Content > VoiceDirector > Audio. Your new SoundWave is ready. Continue with playing it in the game.

In a narrow window, open Sources & filters for the import controls and Take review for the recordings, or double-click the line.

Create text in a spreadsheet or text editor. VoiceDirector reads it; it does not invent it. Export a UTF-8 CSV with commas. The required column names are:

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

In Lines > Import script, enter a stable Import SourceId, choose Import CSV, review Added / Changed / Archived / Unchanged and use Apply Import. Previewing alone changes no lines.

To update the script, import again with the same SourceId and LineId. Old takes and stable identities are retained. The same LineId can appear in different languages, but the LineId and Culture pair must be unique inside a source. Keep the character consistent across languages.

CSV imports accept up to 16 MiB and 10,000 rows.

If text contains a comma, put the cell in double quotes. Represent a quote inside a cell as two quotes: "He said ""Wait.""". Spreadsheet tools usually handle this for you. A semicolon-separated export must be saved again with commas.

A DataTable stores rows inside Unreal. If your dialogue already lives in one, import it through the asset picker instead of preparing CSV or JSON.

1. Open Settings and select the asset under Script DataTable.
2. Map your columns to LineId, CharacterId, Culture, Text and, optionally, Context and SpokenText. String, Name and Text columns are supported. @RowName can supply LineId from the row name.
3. The source is derived automatically from the DataTable asset path. Click Preview DataTable Import.
4. Review the changes in Lines and click Apply Import.

Create a table from scratch

In the Content Browser, create a Blueprint Structure. Add String fields LineId, CharacterId, Culture and Text fields Text, Context, SpokenText. Save it, create a Data Table and choose that structure as its row type. Add a row and fill it with the sample values above.

DataTable imports accept up to 10,000 rows.

The plugin also provides VoiceDirectorScriptRow as an editor import row type. For a table the packaged game itself needs, use your own runtime structure. Published SoundWave assets are ordinary game assets.

A provider voice is an existing voice in Kokoro or ElevenLabs. A VoiceDirector assignment connects that voice to a CharacterId + Culture pair. It is not a new voice model.

1. Configure a provider using the next sections.
2. Open Voices, choose the provider and click Check Connection / List Voices. This reads the catalog without generating speech.
3. Enter your script's CharacterId and Culture, choose a Voice and Model, adjust available controls and click Save Voice Assignment.
4. Return to Lines, select the matching variant and choose Generate new take.

For the example: CharacterId rowan, Culture en, Kokoro voice af_heart, model kokoro. Match the voice to the language supported by the provider. Imported WAVs do not require an assignment.

Changing an assignment affects future generation. Previous takes retain their original voice and settings.

Enlarge screenshot ↗

Kokoro-FastAPI runs separately on your computer or on a reachable server. VoiceDirector connects to it; it does not install or start the backend. Local processing needs disk space for dependencies and model files.

1. Follow the official Kokoro-FastAPI v0.9.0 setup. For the Windows CPU route, install its prerequisites, obtain the model and run .start-cpu.ps1 in the backend folder.
2. Wait for startup and model loading. For a local default installation, open http://127.0.0.1:8880/docs in a browser to check that the server responds.
3. In VoiceDirector Settings, set Kokoro-FastAPI base URL to http://127.0.0.1:8880/v1. Click Save Settings.
4. In Voices, list Kokoro voices and save an assignment. Start with af_heart, kokoro, English en and speed 1.0.

Kokoro speed is 0.5-2.0. Available languages depend on its models and voices. Russian text and Russian WAV imports work in the script, but this Kokoro integration does not provide Russian speech generation. Use an appropriate other provider or recording for it.

ElevenLabs requires your own account, available credits and a key with the necessary permissions. Requests use your account's allowance. Review the provider's current pricing before a batch.

1. In your ElevenLabs account open Developers > API Keys and create a key. Enable Voices: Read and Text to Speech: Access. If the key has restricted model access, allow the model you intend to use.
2. On Windows search the Start menu for Edit environment variables for your account. In User variables, click New. Set the name to VOICEDIRECTOR_ELEVENLABS_KEY and the value to your key. Confirm the dialogs.
3. Fully close Unreal Editor and Epic Games Launcher, including its tray process, and reopen them so they inherit the variable.
4. Open Voices, choose ElevenLabs, click Check Connection / List Voices and select a voice and model available to your account.
5. Save the character/language assignment. Generate one short line first and listen to the new take.

VoiceDirector requests pcm_24000 and creates a PCM WAV from the response. Catalog access alone does not prove that your account can generate this format. Speed is 0.7-1.2; style and speaker boost are available only when the model supports them.

For an existing key, open its More Actions (...) > Edit menu to change permissions. See the official key guide. If the API reports a permissions, quota or regional-access error, resolve that condition with the provider before generating again.

1. In Lines, select one or several variants. Use Ctrl or Shift for multiple selection.
2. Click Generate selected. Review the confirmation: provider, request count, character count and available cost estimate. Confirm when the batch is right.
3. Open Jobs to follow progress. Pause stops new sends; Resume continues them; Cancel stops the remaining queue.
4. When a job is Completed, click Open take. VoiceDirector opens the exact line and recording in Lines, clearing filters that would hide it.

A batch can contain at most 1,000 variants. Each TTS request can contain at most 5,000 characters.

For one selected variant the button is Generate new take; for multiple variants it is Generate selected.

A completed take is ready for review, not automatically approved or published. A failed task includes a diagnostic that you can copy.

Enlarge screenshot ↗

Each line's review panel shows its available takes with the recorded words, origin, time, duration and a waveform calculated from the actual WAV. Select a different line to see its history.

Use Select take, then Play and Stop. When satisfied, click Approve take. All takes remain available for comparison. A waveform helps locate speech and silence; its display is scaled for readability, so compare loudness by listening.

Import your own recording

Select one variant and click Import WAV. Use a little-endian RIFF WAV containing 16-bit PCM, 24 or 48 kHz, mono or stereo, up to 64 MiB. MP3, floating-point WAV and 24-bit PCM must be converted before import.

More line actions offers locking, translation review, stable-ID renaming and dialogue bindings. Unlock a variant before replacing its approval. To make another take with identical inputs, enable Create another take even if input matches.

Enlarge screenshot ↗

Publishing creates or updates Unreal assets from approved takes. Generating, importing and approving alone leave the game's existing audio in place.

1. Open Publish and click Refresh Preview.
2. Read the path and planned action for each row. Create adds a new asset; Update updates a managed one; Conflict needs attention first.
3. Check the approved rows you want to apply. Include their required base SoundWave or dialogue dependencies.
4. Click Apply Selected Approved and inspect the result. Copy copies an asset path.

The plugin avoids overwriting externally changed, unsaved or read-only assets. Resolve a conflict, then refresh the preview. It does not offer a blanket overwrite button. A stale approved take requires the explicit stale-take option; listen to it and compare its recorded text first.

Enlarge screenshot ↗

A SoundWave is Unreal's native sound asset. For your first playback test, connect it to a Blueprint node:

1. Open your level. In the main toolbar's Blueprints menu, choose Open Level Blueprint.
2. Find Event BeginPlay. If it is missing, right-click the graph and search for it.
3. Drag from its white execution pin, search for Play Sound 2D and create the node.
4. In the node's Sound field, select the published SoundWave from your output folder.
5. Click Compile, save the Blueprint and the level, then return to the editor and click Play.

The line should play when the level begins. For a character in the scene, use Unreal's positional audio nodes and your own conversation logic. VoiceDirector prepares assets; your gameplay decides when they play.

Keep the published asset referenced by the game so it is included when packaging. Runtime playback does not require the VoiceDirector editor modules, an API key or a running TTS server. See Epic's Play Sound 2D documentation.

Add translated rows using the same LineId and CharacterId with a different Culture. For example, L-001,rowan,en and L-001,rowan,fr are two language variants of one line. Supply your own translated words and an appropriate voice or recording for each.

The default source culture is en. Publish the base SoundWave and its new localized variants together. Localized assets use Unreal's native /Game/L10N/<culture>/... structure. Reference the base asset in gameplay and let Unreal's active culture choose the localization.

When packaging, include the required cultures under Project Settings > Packaging and the appropriate internationalization data. Changing the editor language alone does not establish the game's dialogue culture.

DialogueWave

For native dialogue contexts, create Unreal DialogueVoice assets for the speaker and any listeners. On a line open More line actions, choose Dialogue speaker, optional listeners and a stable Context key, then click Save Dialogue Context. Publish the required SoundWave and DialogueWave rows together.

A DialogueVoice is dialogue metadata, not a generated vocal model. VoiceDirector supports one context per LineId; use separate line IDs when your conversation needs separate contexts.

1. Prepare the script, then in Settings click Export Actor Manifest CSV.
2. Send the manifest to the performer. Keep the identifiers and requested WAV filenames unchanged, and request the supported WAV format.
3. After receiving the files, choose Choose Actor Manifest and Choose Returned WAV Folder in Settings.
4. Click Preview Actor Matching. Review ready, missing and ambiguous matches; fix filenames or missing recordings first.
5. Select the intended ready rows and click Import Selected Actor WAVs. Listen, approve and publish them through the normal workflow.

The imported takes preserve the manifest's recorded script. If you edited the current script while the actor was recording, the returned take can be marked stale. Compare the words instead of assuming the recording matches the latest script.

Settings holds the Kokoro URL, output folder, DataTable import mapping, actor tools and queue limits. Save connection and generation preferences with Save Settings; save the output root with Save Output Folder.

Request and character limits help bound a batch. For a USD estimate, enter the provider rate per 1,000 characters yourself. -1 means unknown rate; -1 for the USD budget means no USD cap. If a USD cap is enabled while the rate is unknown, cloud generation is blocked until the estimate can be made.

Settings are local editor preferences. There is no need to edit JSON for the normal workflow. Use the output asset picker and visible controls rather than modifying internal project records.

Enlarge screenshot ↗

Back up the whole project, including these folders:

Keep take data as well as published assets. A SoundWave alone cannot reconstruct all script and review history.

Only one editor writes a project at a time. A second instance may open VoiceDirector read-only. Close the other editor, then restart the current Unreal Editor to acquire write access; do not delete a writer lock while another process is using the project.

After an interrupted generation, reopen Jobs. A request already sent can have an unknown remote outcome and is not automatically sent again. Check the provider before retrying.

In Publish, use Review interrupted publication for a detected batch, or Restore From Publish Journal and select this project's Saved/VoiceDirector/Publish/<batch>/Journal.json. Review the confirmation before restoring.

Interrupted publishing uses a journal and backups for recovery. Keep those files until recovery is resolved. External changes are treated as conflicts; restoring a previous state may leave newly created assets on disk for you to inspect. If recovery needs help, preserve the project copy and contact support with the diagnostic.

Write to nexusforgeuesupport@gmail.com. Include the VoiceDirector and Unreal versions, provider, steps that led to the problem, the visible error and a screenshot of the relevant tab.

Do not include API keys. If the issue concerns a script or recording, a small example you are allowed to share is more useful than an entire private project. Keep a backup before changing files to investigate a recovery issue.