Del guion a una voz en tu juego

VoiceDirector organiza la producción de diálogos en el editor de Unreal. Tú aportas el texto, eliges una voz o importas una grabación, escuchas las tomas y decides cuál usar en el juego. El resultado es un asset de audio normal de Unreal: SoundWave. Con enlaces de diálogo también puedes crear DialogueWave.

Una línea es una entrada del guion; una variante, esa línea en un idioma; una toma, una grabación. Puedes guardar varias tomas sin sustituir aún el sonido del juego.

Crear tu primer proyecto Unreal

1. Abre Epic Games Launcher > Unreal Engine > Library y ejecuta UE 5.5, 5.6, 5.7 o 5.8.
2. Elige Games > Third Person, después Blueprint y Desktop. Blueprint es programación visual mediante nodos conectados; no necesitas escribir C++ para esta guía.
3. Elige nombre y carpeta con espacio libre, pulsa Create y espera al editor.

Añadir VoiceDirector

Usa la compilación para tu versión de UE en Windows x64. Si instalas desde Fab, añádela a la versión del motor elegida desde la biblioteca del Launcher. Para instalar en un proyecto, cierra el editor y coloca la carpeta completa en YourProject/Plugins/VoiceDirector/. Crea Plugins si falta.

YourProject/Plugins/VoiceDirector/VoiceDirector.uplugin

No dupliques la carpeta VoiceDirector dentro de sí misma. Un proyecto solo Blueprint necesita el paquete compilado con todos los archivos de compilación incluidos. Las fuentes solas requieren un compilador C++ y compilarlas.

1. Reabre el proyecto. En Edit > Plugins, busca VoiceDirector y actívalo.
2. Reinicia el editor si lo pide.
3. Abre Tools > VoiceDirector.

Esta lección usa una grabación preparada. No hace falta configurar Kokoro ni ElevenLabs.

1. En Settings, fija Output Content folder (/Game/...) en /Game/VoiceDirector/Audio y pulsa Save Output Folder. /Game es la carpeta Content del proyecto, no una unidad de Windows.
2. Descarga ambos ejemplos a una carpeta fácil de localizar.
3. En Lines > Import script, escribe MyScript en Import SourceId, pulsa Import CSV y selecciona el CSV.
4. Revisa la vista previa y pulsa Apply Import. Deja Full snapshot desactivado.
5. Selecciona L-001 con idioma en. Pulsa Import WAV y elige el ejemplo.
6. Si hace falta, pulsa Select take y después Play. Oirás «Keep your voice down.». Stop detiene la reproducción.
7. Pulsa Approve take.
8. Abre Publish o Review publishing. Pulsa Refresh Preview, marca el nuevo SoundWave y Apply Selected Approved.
9. Abre Content Drawer con Ctrl + Space, ve a Content > VoiceDirector > Audio y sigue con la reproducción en el juego.

Escribe los diálogos en una hoja de cálculo o editor. Exporta CSV UTF-8 separado por comas.

LineId,CharacterId,Culture,Text,Context
L-001,rowan,en,Keep your voice down.,At the city gate

En Lines > Import script fija un Import SourceId estable, elige Import CSV, revisa Added / Changed / Archived / Unchanged y pulsa Apply Import. La vista previa sola no modifica líneas.

Reimporta con los mismos SourceId y LineId para mantener identidades y tomas. LineId puede existir en varios idiomas, pero LineId/Culture debe ser único dentro de la fuente. Mantén el personaje de la frase entre idiomas.

Encierra entre comillas las celdas con comas y duplica las comillas internas: "Dijo ""Espera.""". Convierte a comas los CSV separados por punto y coma. Límites: 16 MiB y 10 000 filas.

Una DataTable contiene filas dentro de Unreal. Selecciónala directamente, sin CSV ni JSON manual.

1. En Settings > Script DataTable, selecciona el asset.
2. Relaciona columnas con LineId, CharacterId, Culture, Text y, opcionalmente, Context, SpokenText. Se aceptan String, Name y Text. @RowName usa el nombre de fila como LineId.
3. La fuente se determina automáticamente por la ruta de la DataTable. Pulsa Preview DataTable Import.
4. Revisa Lines y pulsa Apply Import.

Crear una tabla nueva

En Content Browser crea una Blueprint Structure. Añade campos String LineId, CharacterId, Culture y Text Text, Context, SpokenText. Guarda, crea una Data Table con esa estructura y rellena una fila del ejemplo. Máximo: 10 000 filas.

También existe VoiceDirectorScriptRow para importar en el editor. Si el juego empaquetado necesita la tabla, usa una estructura propia de ejecución. Los SoundWave publicados son assets normales.

Las voces ya existen en Kokoro o ElevenLabs. La asignación vincula una voz a CharacterId + Culture; no crea un modelo nuevo.

1. Configura el proveedor con las siguientes secciones.
2. En Voices, selecciónalo y pulsa Check Connection / List Voices. Solo lee el catálogo.
3. Introduce CharacterId y Culture del guion, elige Voice y Model, ajusta opciones y pulsa Save Voice Assignment.
4. En Lines, selecciona una variante y Generate new take.

Ejemplo: rowan, en, voz Kokoro af_heart, modelo kokoro. La voz debe admitir el idioma. Importar WAV no requiere asignación. Los cambios afectan a generaciones futuras; las tomas existentes conservan los ajustes originales.

Ampliar captura ↗

Kokoro-FastAPI funciona aparte, en tu equipo o un servidor accesible. VoiceDirector no lo instala ni inicia. Reserva espacio para dependencias y modelos.

1. Sigue la instalación oficial de Kokoro-FastAPI v0.9.0. Para Windows CPU instala requisitos, descarga el modelo y ejecuta .start-cpu.ps1 desde su carpeta.
2. Espera a que cargue. Con la instalación local predeterminada, comprueba http://127.0.0.1:8880/docs en el navegador.
3. En Settings, fija Kokoro-FastAPI base URL en http://127.0.0.1:8880/v1 y Save Settings.
4. En Voices, carga el catálogo y empieza con af_heart, kokoro, en y velocidad 1.0.

Velocidad Kokoro: 0.5-2.0. Los idiomas dependen de modelo y voz. Puedes importar texto y WAV rusos, pero esta integración no genera voz rusa; usa otra fuente compatible.

Necesitas tu cuenta, créditos y una clave autorizada. Las solicitudes consumen tu cuota. Consulta los precios antes de lotes grandes.

1. En ElevenLabs abre Developers > API Keys. Crea una clave con Voices: Read y Text to Speech: Access. Si restringes modelos, autoriza el elegido.
2. En Windows busca Editar las variables de entorno de esta cuenta. En variables de usuario pulsa Nueva: nombre VOICEDIRECTOR_ELEVENLABS_KEY, valor tu clave. Confirma los diálogos.
3. Cierra Unreal y Epic Games Launcher completamente, incluida la bandeja del sistema, y vuelve a abrirlos.
4. En Voices, elige ElevenLabs, pulsa Check Connection / List Voices y selecciona voz y modelo disponibles.
5. Guarda la asignación y genera primero una frase corta.

VoiceDirector pide pcm_24000 y construye un WAV PCM. Leer el catálogo no garantiza permisos para ese formato. Velocidad: 0.7-1.2; estilo y speaker boost dependen del modelo.

Edita claves existentes en More Actions (...) > Edit. Consulta la guía oficial. Resuelve con el proveedor los errores de permisos, cuota o acceso regional antes de reintentar.

1. Selecciona variantes en Lines, con Ctrl o Shift para varias.
2. Pulsa Generate new take para una o Generate selected para varias. Revisa proveedor, solicitudes, caracteres y coste antes de confirmar.
3. En Jobs, Pause detiene nuevos envíos, Resume continúa y Cancel detiene lo pendiente.
4. Al ver Completed, Open take abre esa grabación en Lines y elimina filtros que la oculten.

Una toma completada aún debe escucharse, aprobarse y publicarse. Puedes copiar los diagnósticos. Máximo: 1 000 variantes por lote y 5 000 caracteres por solicitud TTS.

Ampliar captura ↗

El panel muestra texto grabado, origen, fecha, duración y forma de onda calculada con el WAV real. Otra frase abre su propia historia.

Usa Select take, Play, Stop y Approve take. Todas las tomas siguen disponibles. La onda se escala para leerla; compara volumen escuchando.

Importar tu grabación

Selecciona una variante y Import WAV. Formato: RIFF WAV little-endian, PCM de 16 bits, 24 o 48 kHz, mono o estéreo, hasta 64 MiB. Convierte antes MP3, WAV flotante y PCM de 24 bits.

More line actions ofrece bloqueo, revisión de traducción, renombrado con ID estable y contextos. Desbloquea antes de cambiar aprobación. Para otra toma con las mismas entradas activa Create another take even if input matches.

Ampliar captura ↗

Solo publicar modifica el sonido usado por el juego. Generar, importar y aprobar mantiene el audio previo.

1. Abre Publish > Refresh Preview.
2. Revisa ruta y acción: Create crea, Update actualiza, Conflict requiere resolver.
3. Marca filas aprobadas y las dependencias de SoundWave base o diálogo que necesiten.
4. Pulsa Apply Selected Approved y revisa el resultado. Copy copia la ruta.

No se sobrescriben sin más assets modificados externamente, sin guardar o de solo lectura. Resuelve el conflicto y actualiza. Una toma antigua aprobada requiere la opción explícita para stale takes; compara texto y audio primero.

Ampliar captura ↗

1. Abre el nivel y Blueprints > Open Level Blueprint en la barra principal.
2. Busca Event BeginPlay; si falta, créalo con clic derecho y búsqueda.
3. Arrastra desde su pin blanco de ejecución y crea Play Sound 2D.
4. En Sound, elige el SoundWave publicado.
5. Pulsa Compile, guarda Blueprint y nivel y pulsa Play en el editor.

La frase suena al empezar el nivel. Para personajes en el espacio, usa nodos de audio posicional y tu lógica de conversación. Referencia el asset en el juego para incluirlo al empaquetar.

Reproducirlo no requiere módulos de editor, clave ni servidor TTS. Consulta Play Sound 2D de Epic.

Traduce conservando LineId y CharacterId y cambiando Culture: L-001,rowan,en y L-001,rowan,fr. Aporta traducción y voz o grabación apropiadas.

La cultura de origen predeterminada es en. Publica el SoundWave base junto con las nuevas variantes localizadas. Unreal usa /Game/L10N/<culture>/.... Referencia el asset base y deja que la cultura activa seleccione la localización.

Incluye culturas y datos de internacionalización necesarios en Project Settings > Packaging. Cambiar el idioma del editor no configura los diálogos del juego.

DialogueWave

Crea assets DialogueVoice del hablante y oyentes opcionales. En More line actions, elige Dialogue speaker, oyentes y un Context key estable, luego Save Dialogue Context. Publica juntos SoundWave y DialogueWave necesarios.

DialogueVoice es metadato, no un modelo de voz. Hay un contexto por LineId; usa IDs separados para otros contextos.

1. Prepara el guion y pulsa Settings > Export Actor Manifest CSV.
2. Envía el manifiesto al intérprete conservando IDs y nombres WAV pedidos. Solicita formato compatible.
3. Usa Choose Actor Manifest para el original y Choose Returned WAV Folder para las grabaciones recibidas.
4. Pulsa Preview Actor Matching. Revisa coincidencias listas, ausentes o ambiguas y arregla archivos antes de importar.
5. Selecciona las listas y Import Selected Actor WAVs. Escucha, aprueba y publica.

Las tomas conservan el texto del manifiesto original. Si cambió el guion, pueden quedar antiguas. Compara las palabras grabadas.

Settings reúne URL Kokoro, salida, DataTable, herramientas de actores y límites. Save Settings guarda conexión y generación; Save Output Folder guarda la salida.

Limita solicitudes y caracteres. Para estimar USD introduce precio por 1 000 caracteres. Precio -1: desconocido; presupuesto -1: sin tope monetario. Si hay tope con precio desconocido, se bloquea la generación cloud hasta poder calcular.

Son preferencias locales del editor. El uso normal no exige editar JSON.

Ampliar captura ↗

Respalda el proyecto completo:

Un SoundWave solo no reconstruye todo el historial. Solo un editor escribe por proyecto. Si otro está en solo lectura, cierra el editor que escribe y reinicia también el actual para adquirir acceso.

Tras interrumpir generación revisa Jobs. Las solicitudes enviadas con resultado desconocido no se repiten automáticamente; consulta al proveedor.

En Publish, usa Review interrupted publication para una operación detectada o Restore From Publish Journal con Saved/VoiceDirector/Publish/<batch>/Journal.json del proyecto. Lee la confirmación. Conserva diarios y copias hasta resolver. Cambios externos causan conflictos y pueden quedar assets nuevos para revisar. Guarda una copia y pide ayuda si es necesario. No borres un bloqueo usado por otro proceso.

Escribe a nexusforgeuesupport@gmail.com con versiones VoiceDirector/Unreal, proveedor, pasos, error y captura de la pestaña.

No envíes claves API. Un ejemplo pequeño que puedas compartir resulta más útil que todo un proyecto privado. Conserva copia antes de investigar recuperación.