# Sounds O som é uma ótima maneira de fornecer feedback às ações e eventos do jogador; sons de fundo também podem dar mais contexto à tua scene e melhorar a imersão do jogador nela. {% hint style="warning" %} **📔 Nota**: Tem em mente que os sons só são ouvidos pelos players que estiverem dentro dos parcels que compõem a scene onde o som foi gerado, mesmo que de outra forma estivessem dentro do alcance de audição. Os players também podem optar por desativar todos os sons nas suas settings. {% endhint %} Os formatos de som suportados variam consoante o browser, mas é recomendável usar *.mp3*. *.wav* ficheiros também são suportados, mas geralmente não são recomendados, pois são significativamente mais pesados. ## Tocar sons A forma mais fácil de tocar um som é adicionar um **Audio Source** component visualmente no [Scene Editor no Creator Hub](/creator/content-creator-pt/scene-editor/comecar/about-editor.md) e defini-lo para **Start Playing** e **Loop**. Vê [Add Components](/creator/content-creator-pt/scene-editor/construir/components.md#add-components). ![](/files/345e6caec8ff4ac0ad9546eb170d0db159950b98) Também podes acionar a reprodução de um som de forma no-code através de **Actions**, vê [Torne qualquer item smart](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md). Para tocar um som via code, usa a `AudioSource.playSound` function. ```ts // Criar entity const sourceEntity = engine.addEntity() // Tocar som AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3') ``` O ficheiro de som deve estar dentro da pasta do projeto. No exemplo acima, o ficheiro de áudio está localizado numa pasta `assets/sounds` que se encontra ao nível da raiz da pasta do projeto da scene. {% hint style="warning" %} **📔 Nota**: O `AudioSource` component deve ser importado através de > `import { AudioSource } from "@dcl/sdk/ecs"` Veja [Imports](/creator/content-creator-pt/scenes-sdk7/comecar/coding-scenes.md#imports) para saber como lidar facilmente com estes casos. {% endhint %} O `AudioSource.playSound()` function recebe os seguintes argumentos: * `entity`: Em que entity aplicar o som. O som será ouvido a partir da posição desta entity, o que significa que fica mais alto à medida que o player se aproxima. * `src`: A localização do ficheiro de som dentro do teu projeto. {% hint style="info" %} **💡 Dica**: Para maior clareza, recomendamos manter os teus ficheiros de som separados numa pasta `assets/sounds` dentro da tua scene. {% endhint %} * `resetCursor`: *(opcional)* Se for true, o som começa sempre do início. Caso contrário, continua a partir da posição atual do cursor. Útil para pausar e retomar. Outra forma de tocar sons é criar manualmente um `AudioSource` component numa entity. Usa esta abordagem para teres mais controlo sobre o som, por exemplo para o fazer em loop ou definir o volume. ```ts // Criar entity const sourceEntity = engine.addEntity() // Criar componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', loop: true, playing: true, }) ``` As seguintes propriedades podem ser definidas: * `audioClipUrl`: A localização do ficheiro de som dentro do teu projeto. * `playing`: Se for true, o som começa a tocar. Podes criar um som com `playing` definido para false e, mais tarde, defini-lo para true. * `volume`: *(opcional)* O volume do ficheiro de som. Por predefinição é 1, que corresponde ao volume máximo. * `pitch`: *(opcional)* Modifica o pitch de um som. 1 é o valor predefinido; diminui-o para um som mais grave e aumenta-o para um som mais agudo. {% hint style="info" %} **💡 Dica**: Para evitar que um efeito sonoro se torne demasiado repetitivo durante um jogo, é útil aleatorizar pequenas variações no pitch do som sempre que ele toca. {% endhint %} * `currentTime`: *(opcional)* 0 por predefinição. Define este valor para evitar começar do início do ficheiro de som. Cada entity só pode ter um único `AudioSource` component, que só pode tocar um único clip de cada vez. Esta limitação pode ser facilmente contornada modificando a fonte de áudio no momento de tocar um novo som, ou incluindo múltiplas entities-filhas invisíveis, cada uma com o seu próprio som. {% hint style="warning" %} **📔 Nota**: Os sons são reproduzidos na instância local de cada player. Outros players próximos não ouvirão os mesmos sons, a menos que a sua scene local também os reproduza explicitamente. {% endhint %} ### Pré-carregar um Som Se uma entity usar um som, mas este não for tocado imediatamente no runtime da scene, pode demorar algum tempo a transferir. Ele pode ficar disponível no runtime da scene usando o `AssetLoad` componente. ```ts import { AssetLoad } from "@dcl/sdk/ecs" AssetLoad.create(engine.RootEntity, { assets: [ "assets/scene/bundle1/explosionSound.mp3", ], }) ``` Para mais informações, consulta a documentação de [Pre Load Resources](/creator/content-creator-pt/scenes-sdk7/otimizacao/pre-load-resources.md) . ## Parar sons Para impedir que uma entity reproduza o seu som, usa a `AudioSource.stopSound()` function. Só precisas de especificar a entity, uma vez que cada entity tem um único `AudioSource` component, e cada `AudioSource` component reproduz um único ficheiro de cada vez. ```ts AudioSource.stopSound(sourceEntity) ``` Outra forma de parar um som é definir a `playing` propriedade para false. ```ts // Criar entity const sourceEntity = engine.addEntity() // Criar componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/explosion.mp3', playing: true, }) // Definir uma function simples function stopSound(entity: Entity) { // obter a versão mutável do componente de fonte de áudio const audioSource = AudioSource.getMutable(entity) // modificar o seu valor playing audioSource.playing = false } // chamar function stopSound(sourceEntity) ``` ## Looping Para manter um som a tocar num loop contínuo, define o `loop` campo do `AudioSource` component para *true* antes de começares a reproduzi-lo. ```ts // Criar entity const sourceEntity = engine.addEntity() // Criar componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', playing: true, loop: true, }) ``` Tocar sons em loop é especialmente útil para adicionar música de fundo ou outros sons de fundo. ## Definir volume Podes definir a `volume` propriedade do `AudioSource` component para alterar o volume de um som. O volume é expresso como um número de *0* a *1*. ```ts // Criar entity const sourceEntity = engine.addEntity() // Criar componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', playing: true, volume: 0.5, }) ``` {% hint style="warning" %} **📔 Nota**: Claro, o volume de um som também é afetado pela distância do player à fonte de áudio. À medida que o player se afasta, o volume será menor. {% endhint %} ## Sons globais Por predefinição, todos os sons de um `AudioSource` são posicionais. Isto significa que parecem ser gerados a partir da posição do `Transform` component, e soarão mais alto à medida que o player se aproxima. Mas também podes configurar um som como global, para que o volume seja constante, independentemente de onde o player esteja. Isto é ideal para usar em música de fundo, sons de notificação e outros sons não posicionais. {% hint style="warning" %} **📔 Nota**: Global Sounds é uma feature apenas suportada no cliente desktop DCL 2.0. {% endhint %} Para tornar um som global, define a `global` propriedade para *true*. ```ts AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/music.mp3', playing: true, global: true, }) ``` ## Tocar um segmento de um som Para tocar um segmento de um ficheiro de som mais longo, usa o `playSoundSegment()` na biblioteca SDK Utils. Vê [SDK7 Utils](https://github.com/decentraland/sdk7-utils). Também podes conseguir isto ao definir explicitamente a `currentTime` propriedade num `AudioSource` component, e depois pará-lo após esperar um período de tempo. ## Streaming de áudio Veja [Streaming de áudio](/creator/content-creator-pt/scenes-sdk7/media/audio-streaming.md) para aprender como podes reproduzir um stream de áudio em direto a partir de uma source externa. ## Análise de áudio Veja [Análise de áudio](/creator/content-creator-pt/scenes-sdk7/media/audio-analysis.md) para aprender a ler dados de amplitude e frequência em tempo real a partir de um `AudioSource` e criar visuais reativos a partir disso, como cubos que pulsam com o baixo ou visualizadores de barras ao estilo equalizador. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/sounds.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.