Objetos de áudio

Os objetos de áudio modulares do Roblox permitem que você tenha controle dinâmico sobre o som e o chat de voz em suas experiências. Quase todos os objetos de áudio correspondem a um dispositivo de áudio do mundo real, e todos funcionam juntos para capturar e reproduzir áudio como seus equivalentes físicos.

Por exemplo, cada objeto de áudio conceitualmente se enquadra nas seguintes categorias:

• Objetos que produzem streams de áudio, como players de áudio.
• Objetos que consomem streams de áudio, como emissores de áudio.
• Objetos que modificam streams de áudio, como efeitos de áudio.
• Objetos que transportam streams de áudio de um objeto de áudio para outro, como fios.

Conforme você lê este guia e aprende sobre como todos esses objetos de áudio funcionam juntos para emitir som, você aprenderá como capturar e fornecer com precisão música, efeitos sonoros e a voz humana da experiência para o jogador e vice-versa.

Tocar áudio

Para tocar áudio em sua experiência, é importante entender o papel de cada objeto de áudio disponível:

• Um AudioPlayer carrega e reproduz o arquivo de áudio usando um ID de ativo de áudio definido.
• Um AudioEmitter é um alto-falante virtual que emite áudio no ambiente 3D.
• Um AudioListener é um microfone virtual que capta áudio do ambiente 3D.
• Um AudioDeviceOutput é um dispositivo de hardware físico no mundo real, como um alto-falante ou fones de ouvido.
• Um AudioDeviceInput é um microfone físico no mundo real.
• O objeto AudioTextToSpeech converte texto em áudio usando uma voz humana artificial.
• O objeto AudioSpeechToText converte áudio falado em texto.
• Um Wire transporta streams de áudio de um objeto de áudio para outro.

Como você emparelha esses objetos de áudio depende se você deseja emitir áudio diretamente para o alto-falante ou fones de ouvido do jogador ou de objetos no espaço 3D. As seções a seguir detalham ambos os cenários.

Áudio 2D

O áudio 2D é um som não direcional que toca de nenhuma localização específica, mantendo o mesmo volume independentemente da posição ou orientação do jogador no espaço 3D. Esse tipo de áudio requer três objetos de áudio:

• Um player de áudio para produzir uma stream de áudio.
• Um dispositivo de hardware físico para reproduzir a stream de áudio no mundo real.
• Um fio para transportar a stream de áudio do player de áudio para o dispositivo de saída.

Para demonstrar como configurar esses objetos de áudio no Studio para áudio 2D, o diagrama a seguir compara cada objeto com seu correspondente de dispositivo de áudio do mundo real. Em resumo:

• O AudioPlayer carrega e toca seu ativo de áudio com as configurações especificadas.
• O AudioDeviceOutput permite que o jogador ouça o áudio através de seu alto-falante ou fones de ouvido.
• O Wire se conecta ao player de áudio com sua propriedade SourceInstance, e ao dispositivo de hardware físico com sua propriedade TargetInstance. Ele então atua como uma ponte para transportar a stream de áudio do player de áudio para o dispositivo de saída do jogador.

Para tocar áudio não direcional:

1. Na janela Explorer, vá para SoundService e insira o seguinte:

   1. Um objeto AudioPlayer para criar uma fonte de áudio.
   2. Um objeto AudioDeviceOutput para criar um alto-falante que toca por toda a experiência.
   3. Um objeto Wire para conectar a stream do player de áudio ao alto-falante.
2. Na janela Properties do objeto AudioPlayer:

   1. Defina AssetID para um ID de ativo de áudio válido. Se você não tem seu próprio áudio personalizado, pode encontrar ativos de áudio de uso livre na Creator Store.
   2. Ative Looping se você quiser que seu áudio repita continuamente.
   3. Defina Volume para a unidade de amplitude que você deseja reproduzir seu áudio.
3. Na janela Properties do objeto Wire:

   1. Defina SourceInstance para o AudioPlayer para especificar que você quer tocar o áudio dentro deste player de áudio específico.
   2. Defina TargetInstance para o AudioDeviceOutput para especificar que você quer tocar o áudio deste alto-falante específico.

A partir daqui, você pode acionar seu áudio não direcional com scripts para tocar quando jogadores entrarem na experiência ou como resultado de um evento de gameplay ou interação de UI. Para referências de amostras de código para esses casos de uso, veja o tutorial Adicionar áudio 2D.

Áudio 3D

O áudio 3D é um som direcional que toca de uma localização específica no espaço 3D, aumentando ou diminuindo de volume dependendo da posição e orientação do jogador em relação ao som. Esse tipo de áudio requer seis objetos de áudio:

• Um player de áudio para produzir uma stream de áudio.
• Um emissor de áudio para emitir a stream de áudio dentro do ambiente.
• Um ouvinte para captar a stream de áudio do ambiente.
• Um dispositivo de hardware físico para reproduzir a stream de áudio no mundo real.
• Dois fios: um para transportar a stream de áudio do player de áudio para o emissor, e outro para transportar do ouvinte para o dispositivo de saída.

Para demonstrar como configurar esses objetos de áudio no Studio para áudio 3D, o diagrama a seguir compara cada objeto com seu correspondente de dispositivo de áudio do mundo real. Em resumo:

• O AudioPlayer carrega e toca seu ativo de áudio com as configurações especificadas.
• A posição do pai do AudioEmitter no espaço 3D determina onde aquele áudio é emitido dentro do ambiente.
• O AudioListener capta áudio do emissor a partir da câmera local ou dentro da Humanoid.RootPart do personagem do jogador, dependendo de onde você definir a posição padrão do ouvinte.
• O AudioDeviceOutput permite que o jogador ouça o áudio através de seu alto-falante ou fones de ouvido.
• O primeiro Wire se conecta ao player de áudio com sua propriedade SourceInstance, e ao emissor com sua propriedade TargetInstance. Ele então atua como uma ponte para transportar a stream de áudio do player de áudio para o emissor.
• O segundo Wire se conecta ao ouvinte com sua propriedade SourceInstance, e ao dispositivo de hardware físico com sua propriedade TargetInstance. Ele então atua como uma ponte para transportar a stream de áudio do ouvinte para o dispositivo de saída do jogador.

Para tocar áudio posicional:

1. Escolha onde você deseja criar um AudioListener quando os jogadores nascerem na experiência.

   1. Na janela Explorer, selecione SoundService.
   2. Na janela Properties, defina ListenerLocation para uma das seguintes opções:

      • Default - Cria e associa o ouvinte à Workspace.CurrentCamera em experiências que habilitam o chat de voz.
      • None - Não cria um ouvinte. Esta opção é útil se você deseja criar um ouvinte através de um script.
      • Character - Cria e associa um ouvinte ao personagem local do jogador.
      • Camera - Cria e associa o ouvinte à Workspace.CurrentCamera.

   Quando você define ListenerLocation como Character ou Camera, o motor cria automaticamente um objeto AudioDeviceOutput sob SoundService em tempo de execução.

2. Na janela Explorer, vá para o objeto 3D que você deseja emitir áudio e insira o seguinte:

   1. Um objeto AudioPlayer para criar uma fonte de áudio.
   2. Um objeto AudioEmitter para emitir uma stream posicional do objeto 3D.
   3. Um objeto Wire para conectar a stream do gerador de áudio ao emissor de áudio.

3. Na janela Properties do objeto AudioPlayer:

   1. Defina AssetID para um ID de ativo de áudio válido. Se você não tem seu próprio áudio personalizado, pode encontrar ativos de áudio de uso livre na Creator Store.
   2. Ative Looping se você quiser que seu áudio repita continuamente.
   3. Defina Volume para a unidade de amplitude que você deseja reproduzir seu áudio.

4. Na janela Properties do objeto AudioEmitter, defina DistanceAttenuation para uma curva de volume ao longo da distância que determina quão alto o ouvinte ouve o emissor de acordo com a distância entre eles.

   Por exemplo, a seguinte curva diminui o volume do áudio pela metade quando o ouvinte está a 50 studs de distância do emissor, depois diminui abruptamente o volume para zero quando o ouvinte está a 70 studs de distância.

   

5. Na janela Properties do objeto Wire:

   1. Defina SourceInstance para o AudioPlayer para especificar que você quer tocar o áudio dentro deste player de áudio específico.
   2. Defina TargetInstance para o AudioEmitter para especificar que você quer tocar o áudio deste emissor de áudio específico.

A partir daqui, você pode acionar seu áudio direcional com scripts para tocar quando jogadores entrarem na experiência ou como resultado de um evento de gameplay ou interação de UI. Para referências de amostras de código para esses casos de uso, veja o tutorial Adicionar áudio 3D.

Texto para fala

Texto para fala (TTS) é uma forma de tecnologia assistiva que converte strings de texto em sons de fala usando uma voz artificial. Esse tipo de áudio requer cinco objetos de áudio:

• Um gerador de fala para carregar e converter texto em áudio.
• Um emissor de áudio para emitir a stream de áudio dentro do ambiente.
• Um ouvinte para captar a stream de áudio do ambiente.
• Um dispositivo de hardware físico para reproduzir a stream de áudio no mundo real.
• Para áudio 2D - Um fio para transportar a stream de áudio do gerador de fala para o dispositivo de saída.
• Para áudio 3D - Dois fios: um para transportar a stream de áudio do gerador de fala para o emissor, e outro para transportar do ouvinte para o dispositivo de saída.

Como você configura esses objetos depende se você deseja criar áudio TTS 2D ou 3D. Para mais detalhes sobre qualquer um dos processos, clique entre as seguintes abas.

Para demonstrar como configurar esses objetos de áudio no Studio para áudio TTS 2D, o diagrama a seguir compara cada objeto com seu correspondente de dispositivo de áudio do mundo real. Em resumo:

• O objeto AudioTextToSpeech carrega e converte strings de texto em sons de fala.
• O AudioDeviceOutput permite que o jogador ouça o áudio através de seu alto-falante ou fones de ouvido.
• O Wire se conecta ao gerador de fala com sua propriedade SourceInstance, e ao dispositivo de hardware físico com sua propriedade TargetInstance. Ele então atua como uma ponte para transportar a stream de áudio do gerador de fala para o dispositivo de saída do jogador.

Para tocar áudio de texto para fala 2D:

1. Na janela Explorer, vá para SoundService e insira o seguinte:

   1. Um objeto AudioTextToSpeech para criar um gerador de fala de áudio.
   2. Um objeto AudioDeviceOutput para criar um alto-falante que toca por toda a experiência.
   3. Um objeto Wire para conectar a stream do gerador de fala ao alto-falante.
2. Na janela Properties do objeto AudioTextToSpeech:

   1. Defina Text para qualquer coisa que você queira que a voz diga. Há um limite de 300 caracteres por solicitação.

   2. Defina VoiceId como um número entre 1 e 10, dependendo de qual voz artificial você deseja usar na tabela a seguir.

      Lista de vozes artificiais

      VoiceID	Descrição da Voz	Exemplo de Áudio
      1	Masculino Britânico
      2	Feminino Britânico
      3	Masculino dos Estados Unidos #1
      4	Feminino dos Estados Unidos #1
      5	Masculino dos Estados Unidos #2
      6	Feminino dos Estados Unidos #2
      7	Masculino Australiano
      8	Feminino Australiano
      9	Voz Retro #1
      10	Voz Retro #2
      11	Voz de Anfitrião
      101	Masculino Espanhol
      102	Feminino Espanhol
      201	Masculino Alemão
      202	Feminino Alemão
      301	Masculino Italiano
      302	Feminino Italiano
      401	Masculino Francês
      402	Feminino Francês

      
      

   3. Defina Volume para a unidade de amplitude que você deseja reproduzir seu áudio.

3. Na janela Properties do objeto Wire:

   1. Defina SourceInstance para o AudioTextToSpeech para especificar que você quer tocar o áudio dentro deste gerador de fala específico.
   2. Defina TargetInstance para o AudioDeviceOutput para especificar que você quer tocar o áudio deste alto-falante específico.

A partir daqui, você pode acionar seu áudio TTS com scripts. Para referências de amostras de código para áudio TTS, incluindo como configurar TTS consciente do contexto que se adapta em relação ao jogador, ao estado de seu ambiente, ou status de gameplay, veja o tutorial Adicionar texto para fala.

Fala para texto

Fala para texto (STT) é uma forma de tecnologia que gera automaticamente strings de texto a partir de sons de fala. Esse tipo de áudio requer três objetos de áudio:

• Um gerador de texto para carregar e converter áudio em texto.
• Um dispositivo de hardware físico como um microfone para capturar a entrada de áudio.
• Um fio para transportar a stream de áudio do dispositivo de entrada para o gerador de texto.

Todos esses objetos de áudio trabalham juntos para gerar texto STT em resposta às ações do jogador. Por exemplo, se o jogador estiver usando um fone de ouvido enquanto joga em um laptop:

• O AudioDeviceInput captura a fala do jogador, conforme falada em seu microfone e como uma stream de áudio.
• Um Wire transporta a stream de áudio do AudioDeviceInput para o AudioSpeechToText.
• O AudioSpeechToText converte a fala do jogador em texto.
• A experiência lê este texto e realiza uma ação, como exibir o texto falado na tela ou abrir uma porta a comando do jogador.

Para implementar fala para texto em sua experiência:

1. Habilite o uso da API mais recente para voz.

   1. Na janela Explorer, selecione o VoiceChatService.
   2. Na janela Properties, defina UseAudioApi como Enabled.
2. Na janela Explorer, vá para SoundService e insira o seguinte:

   1. Um AudioDeviceInput para capturar fala.
   2. Um AudioSpeechToText para converter a fala em texto.
   3. Um Wire para transportar a stream do dispositivo de entrada de áudio para a instância STT.
3. Na janela Properties do objeto AudioSpeechToText, defina o estado Enabled como ativo.
4. Na janela Properties do objeto Wire:

   1. Defina SourceInstance para seu novo AudioDeviceInput para especificar que você deseja que o fio transporte áudio desta instância de áudio específica.
   2. Defina TargetInstance para seu novo AudioSpeechToText para especificar que você deseja que o fio transporte áudio para esta instância de áudio específica.
5. Defina a propriedade Player do dispositivo de entrada de áudio para o jogador local em tempo de execução com audioDeviceInput.Player = game.Players.LocalPlayer. Isso informa ao Roblox de qual usuário capturar áudio do microfone.

Depois de configurar STT em sua experiência, você pode acioná-lo com scripts. Para referências de amostras de código, veja o tutorial Adicionar fala para texto.

Idiomas suportados

Nenhuma configuração é necessária para habilitar idiomas suportados. O Roblox detecta automaticamente o idioma falado a partir do áudio e o transcreve.

STT suporta os seguintes idiomas:

• Árabe
• Chinês (Simplificado)
• Chinês (Tradicional)
• Inglês
• Francês
• Alemão
• Indonésio
• Italiano
• Japonês
• Coreano
• Polonês
• Português
• Espanhol
• Russo
• Turco
• Tailandês
• Vietname

Filtro para palavras semelhantes

Quando você implementa STT em sua experiência, pode querer melhorar a precisão da correspondência filtrando palavras que soam similares às palavras que você realmente deseja que o jogador diga. Para fazer isso, você pode comparar as palavras reconhecidas pelo AudioSpeechToText com listas de palavras conhecidas:

1. Sanitizar e tokenizar a saída de Text do AudioSpeechToText para criar uma tabela de strings em minúsculas que podem ser analisadas e comparadas.

   1. Remover caracteres de pontuação.
   2. Converter toda a string para minúsculas.
   3. Dividir a string por espaços em branco para produzir uma tabela de palavras.
2. Gerar tabelas de candidatos para preparar suas strings para comparação.

   1. Sanitizar e tokenizar cada string de referência.
   2. Armazenar essas palavras processadas em uma tabela separada.
3. Comparar e corresponder as palavras em ambas as tabelas para reconhecer as entradas de fala que estão próximas às suas frases-alvo, mesmo que incluam pequenas variações.

   • Para verificações simples, verifique se as strings são exatamente as mesmas.
   • Para correspondência mais flexível, você pode escrever lógica personalizada para aceitar substituições (como "cor" em vez de "cor") ou combinar um subconjunto de palavras e calcular uma pontuação de similaridade.

Personalizar áudio

Os efeitos de áudio permitem que você modifique ou melhore streams de áudio de forma não destrutiva antes que elas cheguem aos ouvidos do jogador. Você pode aplicar esses efeitos para tornar seu áudio mais imersivo dentro das experiências, como usar um objeto AudioEqualizer para fazer a chuva soar abafada, um objeto AudioCompressor para controlar o volume máximo de um som, ou AudioReverb para adicionar reflexos sonoros mais realistas em espaços internos.

Para instruções sobre como configurar efeitos de áudio, bem como comparações lado a lado do antes e depois de personalizar seu áudio, veja Efeitos de áudio.

Acionar áudio

Você pode acionar áudio contextualmente a partir de um script chamando Play() em um objeto AudioPlayer que está corretamente conectado. Por exemplo, se você anexar um script a um player de áudio, poderá acionar o ativo de áudio através de algo como isto:

local audio = script.Parent
local something = ...
something.SomeEvent:Connect(function()
    audio:Play()
end)

Para amostras de código mais complexas para acionar áudio, como feedback de gameplay, interações de UI e ruído de fundo em loop, veja os tutoriais Adicionar áudio 2D, Adicionar áudio 3D e Adicionar texto para fala.