O áudio no Cave é pensado para ser muito simples: você importa um arquivo de áudio, o pré-visualiza no editor e o toca no seu jogo quando algo acontece.

Nesta lição, você vai aprender:

Como os assets de áudio funcionam no Asset Browser.
Como pré-visualizar um arquivo de áudio.
Como exportar ou substituir áudio em .ogg.
Como tocar áudio pelo Python.
O que volume e pitch significam.
Para que serve o handle de áudio retornado.
Como a aba Audio Monitor ajuda a depurar áudio.

Você não precisa de uma configuração complexa para começar. Se você consegue importar um som e tocá-lo quando um botão, porta, item coletável ou ação de personagem acontece, você já entende o fluxo principal.

Importando Áudio

O Cave pode importar arquivos de áudio para o projeto como assets de áudio. Como você viu na seção Importando Assets, o Cave suporta arquivos de áudio .ogg.

Depois que o áudio é importado, ele aparece no Asset Browser, assim como o restante do conteúdo do seu projeto. A partir daí, você pode usá-lo em scripts, callbacks da UI, Logic Bricks, eventos da timeline ou qualquer outro sistema que precise tocar um som.

Por exemplo, seu projeto pode ter assets de áudio como:

Button Click
Door Open
Pickup Coin
Footstep
Forest Ambience

Nomes legíveis são muito úteis aqui porque o áudio geralmente é referenciado pelo nome no Python.

Pré-visualizando Assets de Áudio

Depois de importar um arquivo de áudio, você pode pré-visualizá-lo diretamente dentro do Cave.

Existem duas formas simples de fazer isso:

Clique-duplo no asset de áudio no Asset Browser para tocar uma prévia rapidamente.
Clique único com o botão esquerdo para selecioná-lo e mostrar suas propriedades, onde você pode usar os controles de pré-visualização para tocar o áudio.

A visualização das propriedades é útil porque oferece mais controle ao pré-visualizar. Por exemplo, você pode testar como o áudio soa com diferentes valores de pitch antes de usar esse som no jogo.

Isso é especialmente útil para efeitos como passos, impactos, cliques de UI e sons de criaturas. Uma pequena mudança no pitch pode fazer os sons repetidos parecerem menos idênticos.

Exportando ou Substituindo Áudio

Assets de áudio também podem ser exportados como arquivos .ogg. Isso é útil quando você quer editar o áudio em uma ferramenta externa, por exemplo.

Você também pode substituir o asset de áudio por outro arquivo .ogg. Isso é prático quando a lógica já referencia o nome do asset, mas você quer mudar o som que está realmente sendo usado.

Por exemplo, seu jogo pode já usar um asset chamado Door Open. Se você substituir o áudio dentro desse asset, os scripts que tocam Door Open continuam funcionando sem precisar trocar o nome.

Tocar Áudio usando o Audio Component

Às vezes você quer tocar um som simples em loop para um ambiente sonoro, uma música para o menu principal, etc. Nesse caso, o audio component é suficiente:

Ele toca infinitamente o áudio que você especificar e permite controlar o volume, o pitch, se o som é 3D e a distância máxima. Note que ele não expõe mais opções, como quantas vezes queremos repetir o áudio, etc. Se precisar de mais customização, você deve tocar o áudio através do código.

Tocar Áudio pelo Python

A forma mais simples de tocar um asset de áudio pelo Python é com cave.playSound().

cave.playSound("Button Click")

Isso toca o asset de áudio chamado Button Click.

Você também pode passar um valor de volume:

cave.playSound("Door Open", volume=0.8)

O volume padrão é 1.0, que significa volume normal. Valores menores deixam o som mais baixo.

Por exemplo:

Volume	Significado
`2.0`	Volume extra alto.
`1.0`	Volume normal.
`0.5`	Metade do volume.
`0.0`	Silencioso.

Na maior parte das vezes, você começará com 1.0 e ajustará a partir daí.

Volume e Pitch

Volume controla o quão alto o som está.
Pitch controla o quão agudo ou grave o som parece. Ele também muda a velocidade de reprodução, então pitch mais alto soa mais rápido e agudo, enquanto pitch mais baixo soa mais lento e grave.

O valor padrão para volume e pitch é 1.0.

Por exemplo:

Valor	Resultado Volume	Resultado Pitch
`1.0`	Volume normal.	Pitch normal.
`0.5`	Mais baixo.	Mais grave e lento.
`1.5`	Mais alto se usado como volume.	Mais agudo e rápido.

Ao usar cave.playSound(), o volume é passado diretamente quando o som começa. O pitch geralmente é alterado pelo handle de áudio retornado pela função.

O Handle de Áudio

Quando você chama cave.playSound(), o Cave retorna um handle de áudio.

Esse handle representa a instância do som que está sendo tocada no momento.

sound = cave.playSound("Footstep Stone", volume=0.8)
sound.pitch = 1.0

Você pode usar esse handle para controlar o som depois que ele começa.

Por exemplo:

sound = cave.playSound("Cave Ambience", volume=0.6, loop=True)

# Alternativamente, você pode usar os getters e setters:
sound.setPitch(0.9)
sound.setVolume(0.4)

O handle pode ser usado para coisas como:

Mudar o volume.
Mudar o pitch.
Pausar o som.
Retomar o som.
Parar o som.
Verificar o progresso.
Fazer o som vir de uma entidade 3D.

Por exemplo, se um som de porta deve vir da entidade porta:

sound = cave.playSound("Door Open", volume=1.0)
sound.setSource3D(self.entity, maxDistance=20)

Você não precisa do handle para todo som. Se só quer tocar um clique rápido de botão, isso é suficiente:

cave.playSound("Button Click")

Use o handle quando precisar de controle extra.

É até possível randomizar um pouco o som do passo, dando mais variedade sem precisar de mais sons:

sd = cave.playSound("Footstep Stone")

# Definindo a fonte 3D para ser a entidade que está tocando o som:
sd.setSource3D(entity, 20)

# Randomizando pitch e volume:
sd.pitch  = cave.random.uniform(0.5, 1.5)
sd.volume = cave.random.uniform(0.1, 0.3)

O código acima é muito parecido com o que você encontra no callback de animação Walk and Run do Proto Character padrão, ao criar um novo Projeto Cave.

A Aba Audio Monitor

O Cave também inclui uma aba Audio Monitor para ajudar a depurar áudio enquanto seu jogo está rodando.

Você pode abri-la pelo menu Tabs no canto superior esquerdo do editor.

O Audio Monitor mostra informações sobre o áudio que está sendo reproduzido, incluindo progresso da reprodução. Você pode expandir as entradas para inspeccionar mais detalhes, o que é muito útil quando um projeto começa a ter muitos sons tocando ao mesmo tempo.

Por exemplo, o Audio Monitor pode te ajudar a responder perguntas como:

Esse som está realmente sendo tocado?
O mesmo som está tocando muitas vezes?
Um ambiente em loop ainda está ativo?
Em que ponto do som estamos?

Provavelmente você não vai precisar do Audio Monitor constantemente em um protótipo pequeno, mas ele se torna muito útil para depurar cenas mais complexas.

O Que Você Deve Lembrar

Áudio no Cave é simples: importe um arquivo de áudio, pré-visualize no Asset Browser e toque pelo Python com cave.playSound().

Use volume para controlar a intensidade, pitch para controlar quão agudo ou grave o som é, e guarde o handle retornado quando precisar controlar o som após o início.

Quando o áudio ficar difícil de acompanhar, abra a aba Audio Monitor pelo menu Tabs e verifique o que está tocando.

Cave: Guia de Introdução