# Sons O som é uma ótima maneira de fornecer feedback às ações e eventos dos jogadores; sons de fundo também podem dar mais contexto à sua cena e melhorar a imersão do jogador nela. {% hint style="warning" %} **📔 Nota**: Tenha em mente que os sons são ouvidos apenas pelos jogadores que estão parados dentro dos terrenos (parcels) que compõem a cena onde o som foi gerado, mesmo que, de outra forma, estivessem dentro do alcance auditivo. Os jogadores também podem optar por desligar todos os sons nas configurações. {% endhint %} Os formatos de som suportados variam conforme o navegador, mas é recomendado usar *.mp3*. *.wav* arquivos também são suportados, mas geralmente não são recomendados porque são significativamente mais pesados. ## Tocar sons A maneira mais fácil de tocar um som é adicionar um **Audio Source** componente visualmente no [Scene Editor in Creator Hub](https://github.com/decentraland/docs/blob/main/creator/sdk7/scene-editor/get-started/about-editor.md) e configurá-lo para **Start Playing** e **Loop**. Veja [Add Components](https://github.com/decentraland/docs/blob/main/creator/sdk7/scene-editor/build/components.md#add-components). ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-ae588633ad20c357cfcb71a63216e4b8e02802ae%2FAudioSource-component.png?alt=media) Você também pode acionar a reprodução de um som de forma no-code via **Actions**, veja [Make any item smart](https://github.com/decentraland/docs/blob/main/creator/sdk7/scene-editor/interactivity/make-any-item-smart.md). Para tocar um som via código, use a função `AudioSource.playSound` function. ```ts // Create entity const sourceEntity = engine.addEntity() // Play sound AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3') ``` O arquivo de som deve estar dentro da pasta do projeto. No exemplo acima, o arquivo de áudio está localizado em uma `assets/sounds` pasta, que está localizada no nível raiz da pasta do projeto da cena. {% hint style="warning" %} **📔 Nota**: O `AudioSource` componente deve ser importado via > `import { AudioSource } from "@dcl/sdk/ecs"` Veja [Imports](https://github.com/decentraland/docs/blob/main/creator/sdk7/sdk7/getting-started/coding-scenes.md#imports) para saber como lidar com isso facilmente. {% endhint %} A `AudioSource.playSound()` função aceita os seguintes argumentos: * `entity`: Em qual entidade aplicar o som. O som será ouvido a partir da posição desta entidade, o que significa que fica mais alto à medida que o jogador se aproxima. * `src`: A localização do arquivo de som dentro do seu projeto. {% hint style="info" %} **💡 Dica**: Para maior clareza, recomendamos manter seus arquivos de som separados em uma `assets/sounds` pasta dentro da sua cena. {% endhint %} * `resetCursor`: *(optional)* Se true, o som sempre começa desde o início. Caso contrário, continua a partir da posição atual do cursor. Útil para pausar e retomar. Outra maneira de tocar sons é criar manualmente um componente `AudioSource` em uma entidade. Use essa abordagem para ter mais controle sobre o som, por exemplo, para fazê-lo em loop ou ajustar o volume. ```ts // Create entity const sourceEntity = engine.addEntity() // Create AudioSource component AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', loop: true, playing: true, }) ``` As seguintes propriedades podem ser definidas: * `audioClipUrl`: A localização do arquivo de som dentro do seu projeto. * `playing`: Se true, o som começa a tocar. Você pode criar um som com `playing` set to false, and then set it to true at a later time. * `volume`: *(optional)* O volume do arquivo de som. 1 por padrão, que é volume total. * `pitch`: *(optional)* Modifica o pitch (altura) de um som. 1 é o padrão; diminua para um som mais grave e aumente para um som mais agudo. {% hint style="info" %} **💡 Dica**: Para evitar que um efeito sonoro se torne muito repetitivo durante um jogo, é útil randomizar pequenas variações no pitch do som a cada vez que ele toca. {% endhint %} * `currentTime`: *(optional)* 0 por padrão. Defina esse valor para evitar começar desde o início do arquivo de som. Cada entidade pode ter apenas um único `AudioSource` componente, que só pode reproduzir um único clipe por vez. Essa limitação pode ser facilmente contornada modificando a fonte de áudio no momento de reproduzir um novo som, ou incluindo múltiplas entidades filhas invisíveis, cada uma com seu próprio som. {% hint style="warning" %} **📔 Nota**: Os sons são reproduzidos na instância local de cada jogador. Outros jogadores próximos não ouvirão os mesmos sons a menos que a cena local deles também os reproduza explicitamente. {% endhint %} ### Pré-carregando um som Se uma entidade usa um som, mas ele não é reproduzido imediatamente em tempo de execução da cena, pode levar algum tempo para fazer o download. Ele pode estar disponível em tempo de execução da cena 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, confira a documentação de [Pre Load Resources](https://github.com/decentraland/docs/blob/main/creator/sdk7/optimizing/pre-load-resources.md) . ## Parando sons Para interromper a reprodução de som de uma entidade, use a função `AudioSource.stopSound()` . Você só precisa especificar a entidade, já que cada entidade tem um único `AudioSource` componente, e cada `AudioSource` componente reproduz um único arquivo por vez. ```ts AudioSource.stopSound(sourceEntity) ``` Outra maneira de parar um som é definir a propriedade `playing` para false. ```ts // Create entity const sourceEntity = engine.addEntity() // Create AudioSource component AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/explosion.mp3', playing: true, }) // Define a simple function function stopSound(entity: Entity) { // fetch mutable version of audio source component const audioSource = AudioSource.getMutable(entity) // modify its playing value audioSource.playing = false } // call function stopSound(sourceEntity) ``` ## Looping Para manter um som tocando em loop contínuo, defina o campo `loop` do `AudioSource` componente para *true* antes de começar a reproduzi-lo. ```ts // Create entity const sourceEntity = engine.addEntity() // Create AudioSource component AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', playing: true, loop: true, }) ``` Sons em loop são especialmente úteis para adicionar música de fundo ou outros sons de ambientação. ## Ajustar volume Você pode definir a propriedade `volume` do `AudioSource` componente para alterar o volume de um som. O volume é expresso como um número de *0* a *1*. ```ts // Create entity const sourceEntity = engine.addEntity() // Create AudioSource component 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 jogador à fonte de áudio. À medida que o jogador se afasta, o volume será menor. {% endhint %} ## Sons globais Por padrão, todos os sons de um `AudioSource` são posicionais. Isso significa que eles parecem originar-se da posição do componente `Transform` , e soarão mais altos à medida que o jogador se aproxima. Mas você também pode configurar um som para ser global, de modo que o volume seja constante, não importando onde o jogador esteja parado. Isso é ideal para música de fundo, sons de notificação e outros sons não posicionais. {% hint style="warning" %} **📔 Nota**: Global Sounds é um recurso suportado apenas no cliente desktop DCL 2.0. {% endhint %} Para tornar um som global, defina a propriedade `global` 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 arquivo de som mais longo, use o `playSoundSegment()` na biblioteca SDK Utils. Veja [SDK7 Utils](https://github.com/decentraland/sdk7-utils). Você também pode conseguir isso definindo explicitamente a propriedade `currentTime` em um `AudioSource` componente, e então parando-o após aguardar um período de tempo. ## Streaming de áudio Veja [Streaming de áudio](https://github.com/decentraland/docs/blob/main/creator/sdk7/sdk7/media/audio-streaming.md) para saber como você pode reproduzir uma transmissão de áudio ao vivo a partir de uma fonte externa.