> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md). # Sons Saiba como adicionar sons à sua scene. O som é uma ótima maneira de fornecer feedback para ações e eventos do jogador; 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ó são ouvidos pelos jogadores que estiverem dentro dos parcels que compõem a cena onde o som foi gerado, mesmo que estivessem dentro do alcance auditivo. Os jogadores também podem escolher desativar todos os sons nas suas configurações. {% endhint %} Os formatos de som suportados variam dependendo do navegador, mas recomenda-se usar *.mp3*. *.wav* arquivos também são suportados, mas geralmente não são recomendados, pois são significativamente maiores. ## Reproduzir sons A maneira mais fácil de reproduzir um som é adicionar um **Audio Source** componente visualmente no [Scene Editor in Creator Hub](/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md) e defini-lo como **Start Playing** e **Loop**. Veja [Add Components](/creator/content-creator-pt/scene-editor/construir/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\&token=266f32b9-95c4-4d4b-a7c0-bd84d50c2dfe) Você também pode acionar a reprodução de um som sem código por meio de **Actions**, veja [Make any item smart](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md). Para reproduzir um som via código, use a `AudioSource.playSound` função. ```ts // Criar entity const sourceEntity = engine.addEntity() Transform.create(sourceEntity, { position: Vector3.create(8, 1, 8) }) // Reproduzir som AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3') ``` {% hint style="warning" %} **📔 Nota**: Toda entity com um `AudioSource` também precisa de um `Transform`, incluindo sons globais. Sem um, nada é reproduzido e nenhum erro é registrado, o que torna esse problema difícil de identificar. Os itens colocados no Scene Editor sempre têm um `Transform`Transform {% endhint %} 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 fica 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](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com isso facilmente. {% endhint %} A `AudioSource.playSound()` função recebe os seguintes argumentos: * `entity`: Em que entity aplicar o som. O som será ouvido a partir da posição dessa entity, ou seja, ficará mais alto à medida que o jogador se aproximar dela. * `src`: A localização do arquivo de som dentro do seu projeto. {% hint style="info" %} **💡 Dica**: Para maior clareza, recomendamos manter os seus arquivos de som separados em uma `assets/sounds` pasta dentro da sua cena. {% endhint %} * `resetCursor`: *(opcional)* Se true, o som sempre começa do início. Caso contrário, ele continua a partir da posição atual do cursor. Útil para pausar e retomar. Outra maneira de reproduzir sons é criar manualmente um `AudioSource` componente em uma entity. Use essa abordagem para ter mais controle sobre o som, por exemplo, para fazê-lo entrar em loop ou definir o volume. ```ts // Criar entity const sourceEntity = engine.addEntity() Transform.create(sourceEntity, { position: Vector3.create(8, 1, 8) }) // 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 arquivo de som dentro do seu projeto. * `playing`: Se true, o som começa a ser reproduzido. Você pode criar um som com `playing` definido como false e depois defini-lo como true em um momento posterior. * `volume`: *(opcional)* O volume do arquivo de som. 1 por padrão, que é o volume máximo. * `pitch`: *(opcional)* Modifique o pitch de um som. 1 é o padrão; reduza-o para um som mais grave e aumente-o para um som mais agudo. {% hint style="info" %} **💡 Dica**: Para evitar que um efeito sonoro se torne demasiado repetitivo durante um jogo, é útil randomizar pequenas variações no pitch do som sempre que ele for reproduzido. {% endhint %} * `currentTime`: *(opcional)* 0 por padrão. Defina este valor para evitar começar do início do arquivo de som. Cada entity pode ter apenas um único `AudioSource` componente, que só pode reproduzir um único clip por vez. Essa limitação pode ser facilmente contornada modificando a source de áudio no momento de reproduzir um novo som ou incluindo várias child entities 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 jogador. Outros jogadores próximos não ouvirão os mesmos sons, a menos que a sua cena local também os reproduza explicitamente. {% endhint %} ### Pré-carregando um som Se uma entity usar um som, mas ele não for reproduzido imediatamente no runtime da cena, pode levar algum tempo para fazer o download. Ele pode ficar disponível no runtime 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, consulte a [Pré-carregar recursos](/creator/content-creator-pt/scenes-sdk7/otimizacao/pre-load-resources.md) documentação. ## Parar sons Para impedir que uma entity reproduza o seu som, use a `AudioSource.stopSound()` função. Você só precisa especificar a entity, pois cada entity 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 `playing` propriedade como false. ```ts // Criar entity const sourceEntity = engine.addEntity() // Criar componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/explosion.mp3', playing: true, }) // Definir uma função simples function stopSound(entity: Entity) { // obter a versão mutável do componente de source de áudio const audioSource = AudioSource.getMutable(entity) // modificar o seu valor playing audioSource.playing = false } // chamar a função stopSound(sourceEntity) ``` ## Detectar quando um som termina Quando um som sem loop termina de ser reproduzido por si só, o engine define a `playing` propriedade do `AudioSource` componente novamente como *false*. O código da sua cena pode ler esse valor para saber quando o som terminou, por exemplo para encadear outro som ou ação logo em seguida. ```ts let wasPlaying = false engine.addSystem(() => { const audio = AudioSource.get(sourceEntity) const isPlaying = audio.playing ?? false if (wasPlaying && !isPlaying) { console.log('som terminou de ser reproduzido') // reagir aqui: reproduzir outro som, avançar uma sequência, etc. } wasPlaying = isPlaying }) ``` {% hint style="warning" %} **📔 Nota**: Ao verificar o componente a cada frame, leia-o sempre com `AudioSource.get()` (somente leitura). Usar `AudioSource.getMutable()` marcaria o componente como alterado em cada frame, causando trabalho desnecessário de sincronização. A `playing` A propriedade só é invertida pelo engine quando o som termina por si só. Se a cena parar o som explicitamente (via `AudioSource.stopSound()` ou definindo `playing` como *false*), essa alteração vem do seu próprio código, e os sons em loop reproduzem-se até serem parados, por isso nunca invertem a propriedade por conta própria. {% endhint %} Como alternativa, use `audioEventsSystem.registerAudioEventsEntity` para definir uma função que é executada toda vez que o estado de reprodução do áudio da entity muda, assim como [eventos de vídeo](/creator/content-creator-pt/scenes-sdk7/media/video-playing.md#video-events) para vídeos. A função recebe um evento com um `state` campo, usando o `MediaState` enum. ```ts import { engine, AudioSource, audioEventsSystem, MediaState } from '@dcl/sdk/ecs' // ... Criar sourceEntity com um componente AudioSource ... audioEventsSystem.registerAudioEventsEntity(sourceEntity, (audioEvent) => { switch (audioEvent.state) { case MediaState.MS_LOADING: console.log('evento de áudio - o som está A CARREGAR') break case MediaState.MS_READY: console.log('evento de áudio - o som está PRONTO (carregado ou terminou de ser reproduzido)') break case MediaState.MS_PLAYING: console.log('evento de áudio - o som começou a ser REPRODUZIDO') break case MediaState.MS_ERROR: console.log('evento de áudio - ERRO no som (por exemplo, o arquivo falhou ao carregar)') break } }) ``` Uma transição de `MS_PLAYING` como `para MS_READY significa que o som parou de ser reproduzido. O enum completo também inclui` MS\_NONE `MediaState` MS\_LOADING `MS_PAUSED`, `MS_BUFFERING`, `MS_SEEKING`, `MS_ERROR`, `e cada evento carrega um` e `timestamp`de quando ocorreu a mudança de estado. Você também pode consultar o último estado reportado a qualquer momento com `timestamp` audioEventsSystem.getAudioState(entity) `audioEventsSystem.getAudioState(entity)`, remova o callback com `audioEventsSystem.removeAudioEventsEntity(entity)`, ou verificar se uma entity está registada com `audioEventsSystem.hasAudioEventsEntity(entity)`. O mesmo sistema também funciona para entities com um [`AudioStream`](/creator/content-creator-pt/scenes-sdk7/media/audio-streaming.md) componente. {% hint style="warning" %} **📔 Nota**: Estas funcionalidades são suportadas apenas no cliente Desktop. {% endhint %} ## Em loop Para manter um som a ser reproduzido em loop contínuo, defina o `loop` campo do `AudioSource` componente como *true* antes de começar 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, }) ``` Reproduzir sons em loop é especialmente útil para adicionar música de fundo ou outros sons de fundo. ## Definir volume Você pode definir o `volume` propriedade do `AudioSource` componente para alterar o volume de um som. O volume é expresso como um número de *0* como *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 jogador à source 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 parecem ser gerados a partir da posição do `Transform` componente e soarão mais altos à medida que o jogador se aproximar. Mas você também pode configurar um som para ser global, de modo que o volume seja constante, independentemente de onde o jogador esteja. Isso é ideal para usar em música de fundo, sons de notificação e outros sons não posicionais. {% hint style="warning" %} **📔 Nota**: Sons globais são um recurso suportado apenas no cliente Desktop DCL 2.0. {% endhint %} Para tornar um som global, defina o `global` propriedade como *true*. ```ts AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/music.mp3', playing: true, global: true, }) ``` Um som global ainda precisa de um `Transform` na sua entity, embora a sua posição já não afete o que o jogador ouve. Qualquer posição serve. ## Reproduzir um segmento de um som Para reproduzir um segmento de um arquivo de som maior, use a `playSoundSegment()` na biblioteca SDK Utils. Veja [SDK7 Utils](https://github.com/decentraland/sdk7-utils). Você também pode conseguir isso definindo explicitamente a `currentTime` propriedade em um `AudioSource` componente e depois parando-o após esperar por 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 reproduzir um stream de áudio ao vivo a partir de uma fonte externa. ## Análise de áudio Veja [Análise de áudio](/creator/content-creator-pt/scenes-sdk7/media/audio-analysis.md) para aprender como ler dados de amplitude e frequência em tempo real de um `AudioSource` e criar visuais reativos a partir dele, como cubos que pulsam com o baixo ou visualizadores em barras no estilo equalizador. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.