> 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 forma de dar feedback às ações e aos eventos dos jogadores. Os sons de fundo também podem dar mais contexto à sua cena e aumentar a imersão dos jogadores nela.

{% hint style="warning" %}
**📔 Nota**: Tenha em mente que os sons só são ouvidos pelos jogadores que estão dentro das parcelas que compõem a cena onde o som foi gerado, mesmo que, de outra forma, estivessem ao alcance da audição. Os jogadores também podem optar por desativar todos os sons nas configurações.
{% endhint %}

Os formatos de som compatíveis variam conforme o navegador, mas recomenda-se usar *.mp3*.

*.wav* Os arquivos também são compatíveis, mas geralmente não são recomendados, pois ocupam muito mais espaço.

## Reproduzir sons

A forma mais fácil de reproduzir um som é adicionar um componente **Audio Source** visualmente no [Scene Editor no Creator Hub](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md) e configurá-lo para **Start Playing** e **Loop**. Consulte [Adicionar componentes](https://docs.decentraland.org/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-cf1d382199d0518859ab3a850b5a34b869e334f6%2FAudioSource-component.webp?alt=media)

Também é possível acionar a reprodução de um som sem código usando **Actions**, consulte [Tornar qualquer item inteligente](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md).

Para reproduzir um som usando código, use a função `AudioSource.playSound` .

```ts
// Create entity
const sourceEntity = engine.addEntity()
Transform.create(sourceEntity, { position: Vector3.create(8, 1, 8) })

// Play sound
AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3')
```

{% hint style="warning" %}
**📔 Nota**: Cada entidade com um componente `AudioSource` também precisa de um componente `Transform`, inclusive para sons globais. Sem ele, nada é reproduzido e nenhum erro é registado, o que torna difícil identificar o problema. Os itens colocados no Scene Editor têm sempre um componente `Transform`, por isso isto só afeta as entidades que cria no código.
{% endhint %}

O ficheiro de som tem de estar dentro da pasta do projeto. No exemplo acima, o ficheiro de áudio está numa pasta `assets/sounds` , que se encontra no nível raiz da pasta do projeto da cena.

{% hint style="warning" %}
**📔 Nota**: O componente `AudioSource` tem de ser importado através de

> `import { AudioSource } from "@dcl/sdk/ecs"`

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

A função `AudioSource.playSound()` aceita os seguintes argumentos:

* `entity`: A entidade à qual aplicar o som. O som será ouvido a partir da posição dessa entidade, ficando mais alto à medida que o jogador se aproxima.
* `src`: A localização do ficheiro de som no seu projeto.

{% hint style="info" %}
**💡 Sugestão**: Para maior clareza, recomendamos que mantenha os seus ficheiros de som separados numa `assets/sounds` pasta dentro da sua cena.
{% 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.

`playSound()` cria o componente `AudioSource` se a entidade ainda não tiver um. Se já tiver, `playSound()` mantém os outros valores, como `volume`, `pitch`, `loop` e `global`, para que possa defini-los uma vez e, em seguida, chamar `playSound()` sempre que quiser reproduzir o som. Se for chamada novamente com o mesmo ficheiro, o som é reproduzido outra vez. A função devolve sempre `true`.

Outra forma de reproduzir sons consiste em criar manualmente um componente `AudioSource` numa entidade. Utilize esta abordagem para ter mais controlo sobre o som, por exemplo, para o colocar em loop ou definir o volume.

```ts
// Create 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,
})
```

É possível definir as seguintes propriedades:

* `audioClipUrl`: A localização do ficheiro de som no seu projeto.
* `playing`: Se for true, o som começa a ser reproduzido. Pode criar um som com `playing` definido como false e, em seguida, defini-lo como true mais tarde.
* `volume`: *(opcional)* O volume do ficheiro de som. Por predefinição, é 1, que corresponde ao volume máximo.
* `pitch`: *(opcional)* Altera a altura do som. O valor predefinido é 1. Defina um valor mais baixo para obter um som mais grave e um valor mais alto para obter um som mais agudo.

{% hint style="info" %}
**💡 Sugestão**: Para evitar que um efeito sonoro se torne demasiado repetitivo durante um jogo, é útil aplicar pequenas variações aleatórias à altura do som sempre que este é reproduzido.
{% endhint %}

* `currentTime`: *(opcional)* O valor predefinido é 0. Defina este valor para evitar começar do início do ficheiro de som.

Cada entidade só pode ter um único componente `AudioSource` e este só pode reproduzir um único clip de cada vez. É fácil contornar esta limitação modificando a fonte de áudio quando se reproduz um novo som ou incluindo várias entidades-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 jogador. Os outros jogadores nas proximidades não ouvirão os mesmos sons, a menos que a cena local deles também os reproduza explicitamente.
{% endhint %}

### Pré-carregar um som

Se uma entidade usar um som que não seja reproduzido imediatamente durante a execução da cena, o download poderá levar algum tempo. O som pode ficar disponível durante a 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 obter mais informações, consulte a [documentação sobre pré-carregamento de recursos](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/pre-load-resources.md) .

## Parar sons

Para impedir que uma entidade reproduza o som, use a `AudioSource.stopSound()` função. Basta especificar a entidade, pois cada entidade tem um único componente `AudioSource` e cada componente `AudioSource` reproduz um único ficheiro de cada vez.

```ts
AudioSource.stopSound(sourceEntity)
```

`stopSound()` devolve `false` se a entidade não tiver um componente `AudioSource` .

Outra forma de parar um som é definir a propriedade `playing` como false.

```ts
// Create entity
const sourceEntity = engine.addEntity()

// Criar componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/explosion.mp3',
	playing: true,
})

// Define uma função simples
function stopSound(entity: Entity) {
	// obter a versão mutável do componente de origem de áudio
	const audioSource = AudioSource.getMutable(entity)

	// modificar o valor de playing
	audioSource.playing = false
}

// chamar a função
stopSound(sourceEntity)
```

## Detetar quando um som termina

Quando um som sem repetição termina de ser reproduzido, o motor define novamente a propriedade `playing` do componente `AudioSource` como *false*. O código da sua cena pode ler este valor para saber quando o som terminou, por exemplo, para reproduzir outro som ou executar uma ação logo a seguir.

```ts
let wasPlaying = false

engine.addSystem(() => {
	const audio = AudioSource.get(sourceEntity)
	const isPlaying = audio.playing ?? false

	if (wasPlaying && !isPlaying) {
		console.log('sound finished playing')
		// reagir aqui: reproduzir outro som, avançar uma sequência, etc.
	}

	wasPlaying = isPlaying
})
```

{% hint style="warning" %}
**📔 Nota**: Ao consultar o componente em cada frame, leia-o sempre com `AudioSource.get()` (só de leitura). Usar `AudioSource.getMutable()` marcaria o componente como alterado em cada frame, causando trabalho de sincronização desnecessário.

A propriedade `playing` só é alterada pelo motor quando o som termina por si só. Se a cena parar o som explicitamente (através de `AudioSource.stopSound()` ou definindo `playing` como *false*), essa alteração é feita pelo seu próprio código. Além disso, os sons em loop são reproduzidos até serem parados, pelo que não alteram a propriedade por si só.
{% endhint %}

Em alternativa, use `audioEventsSystem.registerAudioEventsEntity` para definir uma função que é executada sempre que o estado de reprodução do áudio da entidade muda, tal como acontece com [os eventos de vídeo](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/video-playing.md#video-events) para vídeos. A função recebe um evento com um campo `state` , que usa o enum `MediaState` .

```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('audio event - sound is LOADING')
			break
		case MediaState.MS_READY:
			console.log('audio event - sound is READY (loaded, or finished playing)')
			break
		case MediaState.MS_PLAYING:
			console.log('audio event - sound started PLAYING')
			break
		case MediaState.MS_ERROR:
			console.log('audio event - sound ERROR (e.g. the file failed to load)')
			break
	}
})
```

Uma transição de `MS_PLAYING` para `MS_READY` significa que o som deixou de ser reproduzido. O enum `MediaState` completo também inclui `MS_NONE`, `MS_LOADING`, `MS_PAUSED`, `MS_BUFFERING`, `MS_SEEKING` e `MS_ERROR`, e cada evento inclui um `timestamp` que indica quando ocorreu a alteração de estado. Também pode consultar o estado mais recente comunicado a qualquer momento com `audioEventsSystem.getAudioState(entity)`, remover o registo do callback com `audioEventsSystem.removeAudioEventsEntity(entity)`, ou verificar se uma entidade está registada com `audioEventsSystem.hasAudioEventsEntity(entity)`. O mesmo sistema também funciona com entidades que tenham um componente [`AudioStream`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/audio-streaming.md) .

{% hint style="warning" %}
**📔 Nota**: estas funcionalidades só são suportadas no cliente para computador.
{% endhint %}

## Repetição contínua

Para manter um som em reprodução num ciclo contínuo, defina o campo `loop` do componente `AudioSource` como *true* antes de iniciar a reprodução.

```ts
// Create entity
const sourceEntity = engine.addEntity()

// Criar componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/sound-effect.mp3',
	playing: true,
	loop: true,
})
```

A repetição contínua de sons é especialmente útil para adicionar música de fundo ou outros sons ambientes.

## Definir o volume

Pode definir a propriedade `volume` do componente `AudioSource` para alterar o volume de um som.

O volume é expresso como um número entre *0* e *1*.

```ts
// Create 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**: naturalmente, o volume de um som também é afetado pela distância entre o jogador e a fonte de áudio. À medida que o jogador se afasta, o volume diminui.
{% endhint %}

## Sons globais

Por predefinição, todos os sons de um componente `AudioSource` são posicionais. Isto significa que parecem ser emitidos a partir da posição do componente `Transform` e soam mais alto à medida que o jogador se aproxima. No entanto, também pode configurar um som como global, para que o volume seja constante, independentemente do local onde o jogador se encontra. Esta opção é ideal para música de fundo, sons de notificações e outros sons não posicionais.

{% hint style="warning" %}
**📔 Nota**: os sons globais são uma funcionalidade suportada apenas no cliente para computador DCL 2.0.
{% endhint %}

Para tornar um som global, defina a propriedade `global` como *true*.

```ts
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/music.mp3',
	playing: true,
	global: true,
})
```

Um som global continua a precisar de um `Transform` na sua Entity, embora a 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 ficheiro de som mais longo, use `playSoundSegment()` na biblioteca SDK Utils. Consulte [SDK7 Utils](https://github.com/decentraland/sdk7-utils).

Também pode fazê-lo definindo explicitamente a `currentTime` propriedade num componente `AudioSource` e, em seguida, parando-o após aguardar um determinado período de tempo.

## Transmissão de áudio

Consulte [Transmissão de áudio](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/audio-streaming.md) para saber como reproduzir uma transmissão de áudio em direto a partir de uma fonte externa.

## Análise de áudio

Consulte [Análise de áudio](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/audio-analysis.md) para saber como ler dados de amplitude e frequência em tempo real de um `AudioSource` e criar elementos visuais reativos a partir deles, como cubos que pulsam ao ritmo dos graves ou visualizadores de barras ao estilo de um 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=<question>&goal=<user_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.
