Audio Analysis
Read real-time amplitude and frequency data from audio playing in your scene to drive reactive visuals.
Minimal example
import {
engine,
Transform,
MeshRenderer,
AudioSource,
AudioAnalysis,
AudioAnalysisView,
} from "@dcl/sdk/ecs";
import { Vector3 } from "@dcl/sdk/math";
export function main() {
// Play a sound on an entity
const audioEntity = engine.addEntity();
Transform.create(audioEntity);
AudioSource.create(audioEntity, {
audioClipUrl: "sounds/music.mp3",
playing: true,
loop: true,
});
// Attach AudioAnalysis to the same entity to start receiving analysis data
AudioAnalysis.createAudioAnalysis(audioEntity);
// A reusable view object that the component will write into each frame
const analysis: AudioAnalysisView = {
amplitude: 0,
bands: new Array<number>(8),
};
// A cube that pulses with the audio amplitude
const cube = engine.addEntity();
MeshRenderer.setBox(cube);
Transform.create(cube, { position: Vector3.create(8, 1, 8) });
// Each frame, read the latest analysis values and scale the cube
engine.addSystem(() => {
AudioAnalysis.readIntoView(audioEntity, analysis);
const s = 1 + analysis.amplitude * 10;
Transform.getMutable(cube).scale = Vector3.create(s, s, s);
});
}Reading the data each frame
React to specific frequency bands
Modes
Tuning the logarithmic mode
Replace an existing component
Component reference
AudioAnalysis.createAudioAnalysis(entity, mode?, amplitudeGain?, bandsGain?)
AudioAnalysis.createAudioAnalysis(entity, mode?, amplitudeGain?, bandsGain?)AudioAnalysis.createOrReplaceAudioAnalysis(entity, mode?, amplitudeGain?, bandsGain?)
AudioAnalysis.createOrReplaceAudioAnalysis(entity, mode?, amplitudeGain?, bandsGain?)AudioAnalysis.readIntoView(entity, out)
AudioAnalysis.readIntoView(entity, out)AudioAnalysis.tryReadIntoView(entity, out): boolean
AudioAnalysis.tryReadIntoView(entity, out): booleanAudioAnalysisView
AudioAnalysisViewNotes and limitations
Last updated