> 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/media/audio-streaming.md).

# Streaming de Áudio

Reproduza streams de áudio ao vivo na sua scene.

Pode transmitir áudio a partir de um URL. Isto é útil para reproduzir música diretamente de uma rádio na internet ou transmitir uma conferência para a sua Scene.

{% hint style="info" %}
**💡 Dica**: No [Scene Editor no Creator Hub](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md), pode usar um **Audio Stream** [Smart Item](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/smart-items.md) para fazer isto sem código.
{% endhint %}

O áudio na origem tem de estar num dos seguintes formatos: `.mp3`, `ogg`, ou `aac`. A origem também tem de ser um URL *https*  (os URL*http*  não são suportados) e deve ter [políticas CORS (Cross-Origin Resource Sharing)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) que permitam o acesso externo. Caso contrário, poderá ter de configurar um servidor para funcionar como proxy e disponibilizar o stream de forma válida.

{% hint style="warning" %}
**📔 Nota**: Para reproduzir um som pré-gravado na sua Scene, consulte [Sons](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md).
{% endhint %}

Para adicionar um stream de áudio à sua Scene, basta adicionar um componente `AudioStream` a uma entidade:

```ts
const streamEntity = engine.addEntity()

AudioStream.create(streamEntity, {
	url: 'https://icecast.ravepartyradio.org/ravepartyradio-192.mp3',
	playing: true,
	volume: 0.8,
})
```

{% hint style="warning" %}
**📔 Nota**: O som transmitido não é posicional; será ouvido com um volume constante em toda a sua Scene. Se um jogador sair da Scene, deixará de ouvir o stream.
{% endhint %}

Defina o volume do componente `AudioStream` alterando a propriedade `volume` .

Ative ou desative o componente `AudioStream` definindo a propriedade `playing` como *true* ou *false*.

{% hint style="info" %}
**📔 Nota**: Nem todos os serviços de streaming permitem reproduzir o respetivo áudio fora do site. Eis alguns exemplos que funcionam em Decentraland:

```ts
DELTA = "https://cdn.instream.audio/:9069/stream?_=171cd6c2b6e"
GRAFFITI = "https://n07.radiojar.com/2qm1fc5kb.m4a?1617129761=&rj-tok=AAABeIR7VqwAilDFeUM39SDjmw&rj-ttl=5"
ISLA NEGRA = "https://radioislanegra.org/listen/up/basic.aac"
```

{% endhint %}

## Estado do stream

Pode monitorizar o estado de um stream de áudio usando `audioEventsSystem` (baseado em callback, recomendado) ou através de polling com `AudioStream.getAudioState()`.

### Usar audioEventsSystem (recomendado)

Registe um callback que é acionado apenas quando o estado do stream muda. Este é o mesmo sistema usado para entidades `AudioSource` (consulte [Detetar quando um som termina](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md#detect-when-a-sound-finishes)).

```ts
import { engine, AudioStream, MediaState } from '@dcl/sdk/ecs'
import { audioEventsSystem } from '@dcl/sdk/ecs'

export function main() {
	const entity = engine.addEntity()

	AudioStream.create(entity, {
		playing: true,
		volume: 1,
		url: 'https://audio-edge-es6pf.mia.g.radiomast.io/ref-128k-mp3-stereo',
	})

	audioEventsSystem.registerAudioEventsEntity(entity, (event) => {
		console.log('Stream state: ', event.state)

		if (event.state === MediaState.MS_ERROR) {
			// Tentar restabelecer a ligação
		}
	})
}
```

### Fazer polling com getAudioState

Também pode consultar o estado de um stream a cada frame usando `AudioStream.getAudioState()`. Este método devolve um objeto `PBAudioEvent` (ou `undefined` se ainda não tiver sido comunicado nenhum estado), com um campo `state` e um campo `timestamp` . O campo `state` é um valor do enum `MediaState` :

* `MS_NONE`
* `MS_LOADING`
* `MS_READY`
* `MS_PLAYING`
* `MS_PAUSED`
* `MS_BUFFERING`
* `MS_SEEKING`
* `MS_ERROR`

```ts
export function main() {
	const entity = engine.addEntity()

	AudioStream.create(entity, {
		playing: true,
		volume: 1,
		url: 'https://audio-edge-es6pf.mia.g.radiomast.io/ref-128k-mp3-stereo',
	})

	let lastState: MediaState | undefined = undefined
	engine.addSystem(() => {
		const currentState = AudioStream.getAudioState(entity)?.state
		if (lastState !== currentState) {
			console.log('Stream state: ', currentState)
			lastState = currentState

			if (currentState == MediaState.MS_ERROR) {
				// Tentar restabelecer a ligação
			}
		}
	})
}
```

## Áudio espacial

Por predefinição, o áudio de um `AudioStream` O componente é global, o que significa que será ouvido com um volume constante em toda a sua Scene. Se um jogador sair da Scene, não ouvirá o streaming.

Para tornar o áudio espacial, defina a propriedade `spatial` como *true*.

```ts
AudioStream.create(entity, {
	url: 'https://radioislanegra.org/listen/up/stream',
    playing: true,
	spatial: true,
})
```

O áudio será agora ouvido a partir da posição da Entity que contém o componente `AudioStream` e ficará mais alto à medida que o jogador se aproximar.

Controle o áudio espacial com as seguintes propriedades:

* `spatialMinDistance`: a distância mínima a partir da qual o áudio se torna espacial. Se o jogador estiver mais perto, o áudio será ouvido no volume máximo. *0* por predefinição.
* `spatialMaxDistance`: a distância máxima a partir da qual o áudio é ouvido. Se o jogador estiver mais longe, o áudio será ouvido com volume 0. *60* por predefinição

```ts
const audioStreamEntity = engine.addEntity();

Transform.create(audioStreamEntity, {
    position: Vector3.create(8, 0, 8),
});

AudioStream.create(audioStreamEntity, {
    url: 'https://radioislanegra.org/listen/up/stream',
    playing: true,
    volume: 1.0,
    spatial: true,
    spatialMinDistance: 5,
    spatialMaxDistance: 10
});
```

{% hint style="warning" %}
**📔 Nota**: Alguns formatos de áudio não são compatíveis com áudio espacial. Certifique-se de que o áudio do streaming está codificado em *mp3*, *AAC-LC* ou *FLAC*.
{% endhint %}

## Análise de áudio

Pode ler dados de amplitude e frequência em tempo real a partir de uma Entity com o componente `AudioStream` para criar elementos visuais reativos, como equalizadores ou luzes que pulsam ao ritmo da música. Consulte [Análise de áudio](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/audio-analysis.md).


---

# 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/media/audio-streaming.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.
