> 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-analysis.md).

# Análise de Áudio

Leia dados de amplitude e frequência em tempo real do áudio reproduzido na sua scene para acionar visuais reativos.

O `AudioAnalysis` componente lê dados em tempo real de uma fonte de áudio em reprodução na sua cena, permitindo criar efeitos visuais a partir da música. A cada frame, apresenta um valor geral de **amplitude** e **8 bandas de frequência** (das baixas às altas) que pode usar para alterar a escala, a cor ou animar entidades.

Usos comuns:

* Cubos que saltam ao ritmo dos graves.
* Luzes que pulsam ao ritmo da música.
* Visualizadores de barras ao estilo de um equalizador.
* Materiais reativos ou objetos com escala alterada que acompanham a música.

`AudioAnalysis` é um fluxo só de leitura — a sua cena apenas consome os valores, que são preenchidos pelo runtime. Funciona em entidades que reproduzem áudio através de um [AudioSource](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md), de um [AudioStream](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/audio-streaming.md)ou do áudio de um [VideoPlayer](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/video-playing.md).

{% hint style="warning" %}
**📔 Nota**: `AudioAnalysis` é atualmente compatível apenas com a aplicação oficial de desktop da Decentraland. Noutros clientes, os valores do componente nunca são preenchidos; por isso, certifique-se de que a sua cena continua a funcionar mesmo que os dados nunca cheguem.
{% endhint %}

## Exemplo mínimo

A cena seguinte reproduz um som, associa `AudioAnalysis` à mesma entidade e altera a escala de um cubo a cada frame, usando a amplitude do áudio.

```ts
import {
  engine,
  Transform,
  MeshRenderer,
  AudioSource,
  AudioAnalysis,
  AudioAnalysisView,
} from "@dcl/sdk/ecs";
import { Vector3 } from "@dcl/sdk/math";

export function main() {
  // Reproduz um som numa entidade
  const audioEntity = engine.addEntity();
  Transform.create(audioEntity);
  AudioSource.create(audioEntity, {
    audioClipUrl: "sounds/music.mp3",
    playing: true,
    loop: true,
  });

  // Associa AudioAnalysis à mesma entidade para começar a receber dados de análise
  AudioAnalysis.createAudioAnalysis(audioEntity);

  // Um objeto de visualização reutilizável no qual o componente escreverá a cada frame
  const analysis: AudioAnalysisView = {
    amplitude: 0,
    bands: new Array<number>(8),
  };

  // Um cubo que pulsa com a amplitude do áudio
  const cube = engine.addEntity();
  MeshRenderer.setBox(cube);
  Transform.create(cube, { position: Vector3.create(8, 1, 8) });

  // A cada frame, lê os valores de análise mais recentes e altera a escala do cubo
  engine.addSystem(() => {
    AudioAnalysis.readIntoView(audioEntity, analysis);
    const s = 1 + analysis.amplitude * 10;
    Transform.getMutable(cube).scale = Vector3.create(s, s, s);
  });
}
```

As chamadas principais são:

1. `AudioAnalysis.createAudioAnalysis(entity)` — associa o componente à entidade que contém o `AudioSource`, `AudioStream`, ou o `VideoPlayer`. O modo predefinido é o logarítmico (ver [Modos](#modes)).
2. `AudioAnalysis.readIntoView(entity, analysis)` — copia os valores mais recentes de `amplitude` e dos 8 valores de `bands` para um objeto de visualização fornecido por si.

{% hint style="warning" %}
**📔 Nota**: Aloque sempre previamente o array `bands` com **8 elementos** antes de chamar `readIntoView`. O componente não redimensiona o array por si.
{% endhint %}

## Ler os dados em cada frame

`AudioAnalysis` foi concebido para ser lido uma vez por frame a partir de um system. O padrão recomendado é:

1. Aloque um único objeto `AudioAnalysisView` uma vez.
2. Num system, chame `readIntoView` para o atualizar.
3. Use os valores diretamente ou partilhe a visualização entre vários systems.

```ts
const analysis: AudioAnalysisView = {
  amplitude: 0,
  bands: new Array<number>(8),
};

engine.addSystem(() => {
  AudioAnalysis.readIntoView(audioEntity, analysis);
  // analysis.amplitude e analysis.bands[0..7] contêm agora os valores mais recentes
});
```

Se a entidade analisada ainda não tiver um componente `AudioAnalysis` (por exemplo, se for criada mais tarde ou removida dinamicamente), use `tryReadIntoView` em vez disso. Devolve `false` quando o componente não existe, e `true` quando os valores são escritos.

```ts
engine.addSystem(() => {
  if (!AudioAnalysis.tryReadIntoView(audioEntity, analysis)) return;
  // pode usar analysis em segurança aqui
});
```

{% hint style="info" %}
**💡 Dica**: É mais económico chamar `readIntoView` uma vez e permitir que vários sistemas partilhem o mesmo objeto de visualização, em vez de ler o componente repetidamente.
{% endhint %}

## Reagir a bandas de frequência específicas

As 8 bandas abrangem o espectro audível, dos sons graves aos agudos. `bands[0]` é a mais baixa (graves) e `bands[7]` é a mais alta (agudos). Pode controlar diferentes Entities a partir de diferentes bandas para criar um equalizador clássico.

```ts
import {
  engine,
  Transform,
  MeshRenderer,
  Material,
  AudioSource,
  AudioAnalysis,
  AudioAnalysisView,
  Schemas,
} from "@dcl/sdk/ecs";
import { Color4, Vector3 } from "@dcl/sdk/math";

// Componente personalizado para identificar cada barra e guardar a banda que acompanha
const VisualBar = engine.defineComponent("visual-bar", {
  index: Schemas.Number,
});

const BARS_HEIGHT = 12;

export function main() {
  const audioEntity = engine.addEntity();
  Transform.create(audioEntity);
  AudioSource.create(audioEntity, {
    audioClipUrl: "sounds/music.mp3",
    playing: true,
    loop: true,
  });
  AudioAnalysis.createAudioAnalysis(audioEntity);

  const analysis: AudioAnalysisView = {
    amplitude: 0,
    bands: new Array<number>(8),
  };

  // Criar 8 barras, uma por banda
  for (let i = 0; i < 8; i++) {
    const bar = engine.addEntity();
    VisualBar.create(bar, { index: i });
    Transform.create(bar, { position: Vector3.create(4 + i, 0, 8) });
    MeshRenderer.setBox(bar);
    Material.setPbrMaterial(bar, { albedoColor: Color4.Yellow() });
  }

  // Ler uma vez por frame
  engine.addSystem(() => {
    AudioAnalysis.readIntoView(audioEntity, analysis);
  });

  // Redimensionar cada barra de acordo com a respetiva banda
  engine.addSystem(() => {
    for (const [entity] of engine.getEntitiesWith(VisualBar, Transform)) {
      const index = VisualBar.get(entity).index;
      const transform = Transform.getMutable(entity);
      transform.scale = Vector3.create(
        1,
        analysis.bands[index] * BARS_HEIGHT,
        1
      );
    }
  });
}
```

Este é o mesmo padrão utilizado na [cena de exemplo de visualização de áudio](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/88,-10-audio-visualization), reduzido ao essencial.

## Modos

`AudioAnalysis` suporta dois modos de análise, definidos ao criar o componente:

* `PBAudioAnalysisMode.MODE_LOGARITHMIC` (predefinido): os valores são ajustados segundo uma curva logarítmica, que se aproxima mais da forma como a audição humana perceciona as alterações de volume. Ideal para reatividade visual.
* `PBAudioAnalysisMode.MODE_RAW`: os valores de amplitude e das bandas FFT sem processamento. Utilize este modo se pretender aplicar o seu próprio ajuste de escala.

```ts
import { AudioAnalysis, PBAudioAnalysisMode } from "@dcl/sdk/ecs";

// Utilizar valores brutos
AudioAnalysis.createAudioAnalysis(audioEntity, PBAudioAnalysisMode.MODE_RAW);
```

### Ajustar o modo logarítmico

No modo logarítmico, pode indicar dois multiplicadores de ganho opcionais:

* `amplitudeGain` — multiplicador aplicado à amplitude geral. O valor predefinido é `5`.
* `bandsGain` — multiplicador aplicado às 8 bandas. O valor predefinido é `0.05`.

Ganhos mais elevados tornam os valores mais reativos; ganhos mais baixos tornam-nos mais subtis.

```ts
// Reação de amplitude mais intensa, reação das bandas mais suave
AudioAnalysis.createAudioAnalysis(
  audioEntity,
  PBAudioAnalysisMode.MODE_LOGARITHMIC,
  10, // amplitudeGain
  0.03 // bandsGain
);
```

{% hint style="warning" %}
**📔 Nota**: `amplitudeGain` e `bandsGain` só se aplicam no modo logarítmico. No modo bruto, são ignorados.
{% endhint %}

## Substituir um componente existente

`createAudioAnalysis` falha se a entidade já tiver um componente `AudioAnalysis` presente. Para alterar os modos ou os ganhos durante a execução, use `createOrReplaceAudioAnalysis`, que tem a mesma assinatura.

```ts
// Mudar para o modo bruto a meio da cena
AudioAnalysis.createOrReplaceAudioAnalysis(
  audioEntity,
  PBAudioAnalysisMode.MODE_RAW
);
```

## Referência do componente

### `AudioAnalysis.createAudioAnalysis(entity, mode?, amplitudeGain?, bandsGain?)`

Adiciona um componente `AudioAnalysis` a `entity`. Falha se já houver um componente presente.

* `entity` (`Entity`): a entidade que possui o `AudioSource`, `AudioStream`, ou o `VideoPlayer` que pretende analisar.
* `mode` (`PBAudioAnalysisMode`, opcional): `MODE_LOGARITHMIC` (predefinição) ou `MODE_RAW`.
* `amplitudeGain` (`number`, opcional): multiplicador de amplitude do modo logarítmico. Predefinição `5`.
* `bandsGain` (`number`, opcional): multiplicador de bandas do modo logarítmico. Predefinição `0.05`.

### `AudioAnalysis.createOrReplaceAudioAnalysis(entity, mode?, amplitudeGain?, bandsGain?)`

Igual ao anterior, mas substitui um componente `AudioAnalysis` componente na entidade em vez de falhar.

### `AudioAnalysis.readIntoView(entity, out)`

Lê os valores mais recentes para `out`. Lança uma exceção se `entity` não tiver um componente `AudioAnalysis` .

* `entity` (`Entity`): a entidade que tem o componente.
* `out` (`AudioAnalysisView`): um objeto de visualização que fornece. Tem de ter `bands` pré-alocado com 8 números.

### `AudioAnalysis.tryReadIntoView(entity, out): boolean`

Igual a `readIntoView`, mas devolve `false` se a entidade não tiver um componente `AudioAnalysis` em vez de lançar uma exceção. Devolve `true` quando os valores são escritos.

### `AudioAnalysisView`

Um objeto simples que aloca para receber os dados da análise:

```ts
type AudioAnalysisView = {
  amplitude: number; // intensidade global do sinal
  bands: number[]; // 8 bandas de frequência, da mais baixa (0) à mais alta (7)
};
```

## Notas e limitações

* **8 bandas, fixas.** O número de bandas de frequência é fixo: 8. Não existe uma API para pedir mais ou menos bandas.
* **Uma fonte de áudio por análise.** Cada `AudioAnalysis` componente analisa o áudio da entidade à qual está associado. Para analisar várias fontes, associe `AudioAnalysis` a cada uma delas.
* **As bandas sonoras dos vídeos também são analisadas.** `AudioAnalysis` lê o áudio de um [`VideoPlayer`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/video-playing.md) da mesma forma que lê o de um `AudioSource`, tanto para ficheiros de vídeo progressivo (como `.mp4`) como para streams HLS em direto (`.m3u8`). Attach `AudioAnalysis` à mesma entidade que contém o `VideoPlayer`.
* **O áudio em pausa não reporta atualizações.** Quando o áudio subjacente é parado ou colocado em pausa, os valores do componente deixam de mudar. Os últimos valores lidos permanecem no objeto de visualização até o áudio voltar a ser reproduzido.
* **É barato, mas não gratuito.** A análise por frame foi concebida para ter um custo reduzido (menos de um milissegundo por fonte em computadores de secretária). Evite anexar `AudioAnalysis` a muitas fontes ao mesmo tempo se não precisar dos dados. Remova o componente quando um visualizador não estiver visível.


---

# 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-analysis.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.
