Do roteiro à voz no seu jogo

VoiceDirector organiza a produção de diálogos no editor Unreal. Você fornece o texto, escolhe uma voz ou importa uma gravação, ouve as tomadas e decide qual entra no jogo. O resultado é um asset de áudio padrão do Unreal: SoundWave. Com vínculos de diálogo também é possível criar DialogueWave.

Uma fala é uma entrada do roteiro; uma variante, essa fala em um idioma; uma tomada, uma gravação. Várias tomadas podem ficar guardadas sem substituir o áudio atual do jogo.

Criar seu primeiro projeto Unreal

1. Abra Epic Games Launcher > Unreal Engine > Library e inicie UE 5.5, 5.6, 5.7 ou 5.8.
2. Escolha Games > Third Person, depois Blueprint e Desktop. Blueprint é programação visual com nós conectados; este guia não exige C++.
3. Escolha nome e pasta com espaço livre, clique em Create e aguarde o editor.

Adicionar VoiceDirector

Use a compilação da sua versão do Unreal para Windows x64. Na instalação via Fab, adicione o plugin à versão correta do motor pela biblioteca do Launcher. Para instalar no projeto, feche o editor e coloque toda a pasta em YourProject/Plugins/VoiceDirector/. Crie Plugins se necessário.

YourProject/Plugins/VoiceDirector/VoiceDirector.uplugin

Não coloque outra pasta VoiceDirector dentro da primeira. Um projeto só Blueprint precisa do pacote compilado com todos os arquivos de compilação fornecidos. Apenas fontes exigem compilador C++ e uma compilação própria.

1. Reabra o projeto, vá a Edit > Plugins, encontre VoiceDirector e ative-o.
2. Reinicie se o editor solicitar.
3. Abra Tools > VoiceDirector.

Esta lição usa uma gravação pronta. Não é preciso configurar Kokoro nem ElevenLabs.

1. Em Settings, defina Output Content folder (/Game/...) como /Game/VoiceDirector/Audio e clique em Save Output Folder. /Game significa a pasta Content do projeto, não uma unidade do Windows.
2. Baixe os dois exemplos para uma pasta fácil de encontrar.
3. Em Lines > Import script, coloque MyScript em Import SourceId, clique em Import CSV e escolha o CSV.
4. Confira a prévia e clique em Apply Import. Deixe Full snapshot desmarcado.
5. Selecione L-001, idioma en. Clique em Import WAV e escolha o exemplo.
6. Se necessário, clique em Select take e depois Play. Você ouvirá “Keep your voice down.” Stop interrompe a reprodução.
7. Clique em Approve take.
8. Abra Publish ou Review publishing, use Refresh Preview, marque o novo SoundWave e clique em Apply Selected Approved.
9. Abra Content Drawer com Ctrl + Space, vá a Content > VoiceDirector > Audio e siga para reproduzir no jogo.

Escreva as falas em uma planilha ou editor e exporte CSV UTF-8 separado por vírgulas.

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

Em Lines > Import script, defina um Import SourceId estável, use Import CSV, confira Added / Changed / Archived / Unchanged e Apply Import. Só a prévia não altera nada.

Reimporte com os mesmos SourceId e LineId para manter identidades e tomadas. A dupla LineId/Culture deve ser única por origem; o mesmo LineId pode existir em vários idiomas com o mesmo personagem.

Coloque células com vírgulas entre aspas e duplique aspas internas: "Ele disse ""Espere.""". Converta exportações com ponto e vírgula. Limites: 16 MiB e 10.000 linhas.

Uma DataTable guarda linhas no Unreal. Selecione-a diretamente sem preparar CSV ou JSON manual.

1. Escolha o asset em Settings > Script DataTable.
2. Mapeie colunas para LineId, CharacterId, Culture, Text e, opcionalmente, Context, SpokenText. String, Name e Text são aceitos. @RowName usa o nome da linha como LineId.
3. A origem é definida automaticamente pelo caminho do asset. Clique em Preview DataTable Import.
4. Confira Lines e clique em Apply Import.

Criar uma tabela

No Content Browser crie uma Blueprint Structure. Adicione campos String LineId, CharacterId, Culture e Text Text, Context, SpokenText. Salve, crie uma Data Table com essa estrutura e preencha uma linha do exemplo. Máximo: 10.000 linhas.

VoiceDirectorScriptRow também existe para importação no editor. Se o jogo empacotado precisar da tabela, use sua própria estrutura disponível em execução. SoundWaves publicados são assets normais do jogo.

As vozes já existem no catálogo Kokoro ou ElevenLabs. A atribuição liga uma voz a CharacterId + Culture; não cria um modelo vocal.

1. Configure o provedor pelas próximas seções.
2. Em Voices, selecione-o e clique em Check Connection / List Voices. Isso só lê o catálogo.
3. Informe CharacterId e Culture do roteiro, escolha Voice e Model, ajuste opções e clique em Save Voice Assignment.
4. Em Lines, selecione uma variante e Generate new take.

Exemplo: rowan, en, voz af_heart, modelo kokoro. A voz precisa suportar o idioma. Importar WAV não exige atribuição. Mudanças valem para futuras gerações; tomadas antigas preservam seus ajustes.

Ampliar captura ↗

Kokoro-FastAPI roda separadamente no computador ou em servidor acessível. VoiceDirector não o instala nem inicia. Reserve espaço para dependências e modelos.

1. Siga a instalação oficial do Kokoro-FastAPI v0.9.0. Para Windows CPU, instale pré-requisitos, baixe o modelo e execute .start-cpu.ps1 na pasta do serviço.
2. Aguarde o carregamento. Na instalação local padrão, teste http://127.0.0.1:8880/docs no navegador.
3. Em Settings, configure Kokoro-FastAPI base URL como http://127.0.0.1:8880/v1 e Save Settings.
4. Em Voices, carregue o catálogo e comece com af_heart, kokoro, en, velocidade 1.0.

Velocidade Kokoro: 0.5-2.0. Idiomas dependem do modelo e voz. Texto e WAV em russo podem ser importados, mas esta integração não gera russo; use outra fonte adequada.

Você precisa de conta própria, créditos e chave autorizada. As solicitações consomem sua cota. Confira preços antes de lotes grandes.

1. No ElevenLabs abra Developers > API Keys. Crie chave com Voices: Read e Text to Speech: Access. Se restringir modelos, autorize o escolhido.
2. No Windows procure Editar as variáveis de ambiente da sua conta. Em variáveis do usuário, clique em Novo: nome VOICEDIRECTOR_ELEVENLABS_KEY, valor sua chave. Confirme as janelas.
3. Feche Unreal e Epic Games Launcher completamente, incluindo a bandeja do sistema, e reabra.
4. Em Voices, selecione ElevenLabs, use Check Connection / List Voices e escolha voz e modelo disponíveis.
5. Salve a atribuição e gere primeiro uma fala curta.

O plugin pede pcm_24000 e cria um WAV PCM. Acesso ao catálogo não garante permissão para esse formato. Velocidade: 0.7-1.2; estilo e speaker boost dependem do modelo.

Edite chaves existentes em More Actions (...) > Edit. Veja o guia oficial. Resolva com o provedor erros de permissão, cota ou acesso regional antes de tentar de novo.

1. Selecione variantes em Lines; Ctrl ou Shift seleciona várias.
2. Use Generate new take para uma, Generate selected para várias. Confira provedor, solicitações, caracteres e custo antes de confirmar.
3. Em Jobs, Pause suspende novos envios, Resume continua e Cancel interrompe o restante.
4. Em Completed, Open take abre a gravação exata em Lines e remove filtros que a escondiam.

A tomada concluída ainda precisa de revisão, aprovação e publicação. Diagnósticos podem ser copiados. Máximo: 1.000 variantes por lote e 5.000 caracteres por solicitação TTS.

Ampliar captura ↗

O painel mostra texto gravado, origem, data, duração e forma de onda calculada do WAV real. Outra fala abre seu próprio histórico.

Use Select take, Play, Stop e Approve take. Todas as tomadas continuam disponíveis. A onda é ajustada para legibilidade; compare volume ouvindo.

Importar sua gravação

Selecione uma variante e Import WAV. Formato: RIFF WAV little-endian, PCM de 16 bits, 24 ou 48 kHz, mono ou estéreo, até 64 MiB. Converta antes MP3, WAV flutuante ou PCM de 24 bits.

More line actions oferece bloqueio, revisão de tradução, renomeação com ID estável e vínculos. Desbloqueie antes de trocar aprovação. Para outra tomada com entradas iguais, marque Create another take even if input matches.

Ampliar captura ↗

Só publicar altera o áudio usado pelo jogo. Gerar, importar e aprovar preserva os assets anteriores.

1. Abra Publish > Refresh Preview.
2. Confira caminho e ação: Create cria, Update atualiza, Conflict exige correção.
3. Marque as linhas aprovadas e as dependências de SoundWave base ou diálogo necessárias.
4. Clique em Apply Selected Approved e confira o resultado. Copy copia o caminho.

Assets alterados externamente, não salvos ou somente leitura não são simplesmente sobrescritos. Resolva o conflito e atualize. Uma tomada antiga aprovada exige a opção explícita para stale takes; compare áudio e texto antes.

Ampliar captura ↗

1. Abra o nível e Blueprints > Open Level Blueprint na barra principal.
2. Encontre Event BeginPlay; se faltar, crie com clique direito e busca.
3. Arraste do pino branco de execução e crie Play Sound 2D.
4. Em Sound, selecione o SoundWave publicado.
5. Clique em Compile, salve Blueprint e nível e use Play no editor.

A fala toca ao iniciar o nível. Para personagens no espaço, use nós de áudio posicional e sua lógica de conversa. Referencie o asset no jogo para que entre no pacote.

Reprodução não precisa de módulos de editor, chave nem servidor TTS. Veja Play Sound 2D da Epic.

Traduções mantêm LineId e CharacterId com outra Culture: L-001,rowan,en e L-001,rowan,fr. Forneça tradução e voz ou gravação adequadas.

A cultura de origem padrão é en. Publique SoundWave base junto das novas variantes localizadas. Unreal usa /Game/L10N/<culture>/.... Referencie o asset base e deixe a cultura ativa escolher a localização.

Em Project Settings > Packaging, inclua culturas e dados de internacionalização necessários. Alterar idioma do editor não configura o diálogo do jogo.

DialogueWave

Crie assets DialogueVoice para falante e ouvintes opcionais. Em More line actions, escolha Dialogue speaker, ouvintes e Context key estável, depois Save Dialogue Context. Publique SoundWave e DialogueWave necessários juntos.

DialogueVoice é metadado, não modelo vocal. Há um contexto por LineId; use IDs distintos para outros contextos.

1. Prepare o roteiro e use Settings > Export Actor Manifest CSV.
2. Envie o manifesto ao intérprete mantendo IDs e nomes WAV solicitados. Peça formato compatível.
3. Use Choose Actor Manifest para o original e Choose Returned WAV Folder para as gravações.
4. Clique em Preview Actor Matching. Confira correspondências prontas, ausentes e ambíguas; corrija arquivos primeiro.
5. Selecione as prontas e Import Selected Actor WAVs. Ouça, aprove e publique.

As tomadas preservam o texto do manifesto original. Se o roteiro mudou enquanto o ator gravava, elas podem ficar desatualizadas. Compare as palavras.

Settings reúne URL Kokoro, saída, DataTable, ferramentas de atores e limites. Save Settings salva conexão e geração; Save Output Folder salva destino.

Limite solicitações e caracteres. Para estimativa USD, informe preço por 1.000 caracteres. Preço -1: desconhecido; orçamento -1: sem limite monetário. Limite ativo com preço desconhecido bloqueia geração cloud até ser possível calcular.

São preferências locais do editor. Uso normal não exige editar JSON.

Ampliar captura ↗

Faça backup do projeto inteiro:

Um SoundWave sozinho não reconstrói todo o histórico. Só um editor escreve por projeto. Para sair de somente leitura, feche a outra instância e reinicie também o editor atual. Não remova um bloqueio usado por outro processo.

Após interrupção, examine Jobs. Solicitações enviadas com resultado desconhecido não são repetidas automaticamente; consulte o provedor.

Em Publish, use Review interrupted publication para uma operação detectada ou Restore From Publish Journal com Saved/VoiceDirector/Publish/<batch>/Journal.json do projeto. Leia a confirmação. Guarde diários e cópias até resolver. Alterações externas viram conflitos; assets novos podem permanecer para revisão. Preserve uma cópia e contate o suporte se precisar.

Escreva para nexusforgeuesupport@gmail.com com versões VoiceDirector/Unreal, provedor, passos, erro e captura da aba.

Não envie chaves API. Um exemplo pequeno que possa compartilhar é melhor que um projeto privado inteiro. Mantenha cópia antes de investigar recuperação.