오디오 분석

씬에서 재생 중인 오디오의 실시간 진폭 및 주파수 데이터를 읽어 반응형 비주얼을 구동합니다.

이 AudioAnalysis 구성 요소는 장면에서 재생 중인 오디오 소스에서 실시간 데이터를 읽어와, 음악으로 비주얼을 구동할 수 있게 합니다. 각 프레임마다 전체 진폭 값과 8개의 주파수 대역 (낮은 것부터 높은 것까지)를 엔티티의 크기를 조절하거나, 색을 바꾸거나, 애니메이션을 적용하는 데 사용할 수 있습니다.

일반적인 용도:

베이스에 맞춰 튀는 큐브.
비트에 맞춰 맥동하는 조명.
이퀄라이저 스타일의 막대 시각화.
음악에 반응하는 머티리얼이나 크기가 조절되는 소품.

AudioAnalysis 읽기 전용 피드입니다 — 장면은 값만 소비하고, 런타임이 값을 채워 넣습니다. 이는 오디오를 재생하는 엔티티에서 작동합니다. 다음을 통해 AudioSource, 그리고 AudioStream, 또는 다음의 오디오 VideoPlayer.

📔 참고: AudioAnalysis 현재는 공식 Decentraland 데스크톱 앱에서만 지원됩니다. 다른 클라이언트에서는 구성 요소의 값이 채워지지 않으므로, 데이터가 끝내 도착하지 않아도 장면이 계속 동작하는지 확인하세요.

최소 예제

다음 장면은 사운드를 재생하고, AudioAnalysis 를 같은 엔티티에 연결한 다음, 오디오의 진폭을 사용해 매 프레임 큐브의 크기를 조절합니다.

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

export function main() {
  // 엔티티에서 사운드 재생
  const audioEntity = engine.addEntity();
  Transform.create(audioEntity);
  AudioSource.create(audioEntity, {
    audioClipUrl: "sounds/music.mp3",
    playing: true,
    loop: true,
  });

  // 분석 데이터를 받기 시작하려면 같은 엔티티에 AudioAnalysis를 연결합니다
  AudioAnalysis.createAudioAnalysis(audioEntity);

  // 매 프레임마다 구성 요소가 값을 기록할 재사용 가능한 뷰 객체
  const analysis: AudioAnalysisView = {
    amplitude: 0,
    bands: new Array<number>(8),
  };

  // 오디오 진폭에 맞춰 맥동하는 큐브
  const cube = engine.addEntity();
  MeshRenderer.setBox(cube);
  Transform.create(cube, { position: Vector3.create(8, 1, 8) });

  // 매 프레임마다 최신 분석 값을 읽어 큐브의 크기를 조절합니다
  engine.addSystem(() => {
    AudioAnalysis.readIntoView(audioEntity, analysis);
    const s = 1 + analysis.amplitude * 10;
    Transform.getMutable(cube).scale = Vector3.create(s, s, s);
  });
}

핵심 호출은 다음과 같습니다:

AudioAnalysis.createAudioAnalysis(entity) — 해당 AudioSource, AudioStream또는 VideoPlayer를 소유한 엔티티에 구성 요소를 연결합니다. 기본값은 로그 모드입니다(참조 모드).
AudioAnalysis.readIntoView(entity, analysis) — 최신 진폭 및 8개의 대역 값을 제공한 뷰 객체에 복사합니다.

📔 참고: 항상 대역 배열을 8개 요소로 미리 할당한 뒤 readIntoView를 호출하세요. 구성 요소가 배열 크기를 대신 조정해 주지 않습니다.

매 프레임 데이터 읽기

AudioAnalysis 는 시스템에서 프레임당 한 번 읽도록 설계되었습니다. 권장 패턴은 다음과 같습니다:

하나의 AudioAnalysisView 객체를 한 번만 할당합니다.
시스템에서 readIntoView 를 호출해 새로 고칩니다.
값을 직접 사용하거나, 여러 시스템이 같은 뷰를 공유하도록 하세요.

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

engine.addSystem(() => {
  AudioAnalysis.readIntoView(audioEntity, analysis);
  // analysis.amplitude 및 analysis.bands[0..7]에는 이제 최신 값이 들어 있습니다
});

분석 대상 엔티티에 아직 AudioAnalysis 구성 요소가 없을 수 있다면(예: 나중에 생성되거나 동적으로 제거되는 경우), 대신 tryReadIntoView 를 사용하세요. 이는 false 구성 요소가 없을 때는 true 을 반환하고, 값이 기록되었을 때는

engine.addSystem(() => {
  if (!AudioAnalysis.tryReadIntoView(audioEntity, analysis)) return;
  // 여기서 analysis를 안전하게 사용할 수 있습니다
});

💡 팁: readIntoView 를 한 번 호출해 같은 뷰 객체를 여러 시스템이 공유하게 하는 것이, 구성 요소를 반복해서 읽는 것보다 더 저렴합니다.

특정 주파수 대역에 반응하기

8개 대역은 가청 스펙트럼을 낮은 것부터 높은 것까지 커버합니다. bands[0] 가 가장 낮은 값(베이스)이고 bands[7] 가 가장 높은 값(트레블)입니다. 다양한 엔티티를 서로 다른 대역으로 구동해 고전적인 이퀄라이저를 만들 수 있습니다.

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

// 각 막대를 표시하고 어떤 대역을 추적하는지 기억하는 사용자 정의 구성 요소
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),
  };

  // 대역별로 하나씩 8개의 막대를 만듭니다
  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() });
  }

  // 프레임당 한 번 읽기
  engine.addSystem(() => {
    AudioAnalysis.readIntoView(audioEntity, analysis);
  });

  // 각 막대를 해당 대역에 맞춰 스케일 조정
  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
      );
    }
  });
}

이는 오디오 시각화 예제 씬에서 사용된 것과 같은 패턴이며, 핵심만 남겼습니다.

모드

AudioAnalysis 를 생성할 때 설정하는 두 가지 분석 모드를 지원합니다:

PBAudioAnalysisMode.MODE_LOGARITHMIC (기본값): 값은 로그 곡선으로 스케일되며, 이는 사람이 음량 변화를 인지하는 방식에 더 가깝습니다. 시각적 반응성에 가장 적합합니다.
PBAudioAnalysisMode.MODE_RAW: 가공되지 않은 진폭과 FFT 대역 값입니다. 직접 스케일링을 적용하고 싶을 때 사용하세요.

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

// 원시 값 사용
AudioAnalysis.createAudioAnalysis(audioEntity, PBAudioAnalysisMode.MODE_RAW);

로그 모드 조정하기

로그 모드에서는 두 개의 선택적 게인 배율을 전달할 수 있습니다:

amplitudeGain — 전체 진폭에 적용되는 배율입니다. 기본값은 5.
bandsGain — 8개 대역 전체에 적용되는 배율입니다. 기본값은 0.05.

게인이 높을수록 값이 더 민감하게 반응하고, 낮을수록 더 미묘해집니다.

// 더 강한 진폭 반응, 더 부드러운 대역 반응
AudioAnalysis.createAudioAnalysis(
  audioEntity,
  PBAudioAnalysisMode.MODE_LOGARITHMIC,
  10, // amplitudeGain
  0.03 // bandsGain
);

📔 참고: amplitudeGain 과 bandsGain 는 로그 모드에서만 적용됩니다. raw 모드에서는 무시됩니다.

기존 구성 요소 교체

createAudioAnalysis 는 엔티티에 이미 AudioAnalysis 구성 요소가 있으면 실패합니다. 런타임에 모드나 게인을 바꾸려면 createOrReplaceAudioAnalysis를 사용하세요. 시그니처는 같습니다.

// 장면 도중 raw 모드로 전환
AudioAnalysis.createOrReplaceAudioAnalysis(
  audioEntity,
  PBAudioAnalysisMode.MODE_RAW
);

구성 요소 참조

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

다음을 부착합니다 AudioAnalysis 구성 요소의 값을 엔티티. 구성 요소가 이미 있으면 실패합니다.

엔티티 (Entity): 다음을 소유한 엔티티 AudioSource, AudioStream또는 VideoPlayer 분석하려는
mode (PBAudioAnalysisMode, 선택 사항): MODE_LOGARITHMIC (기본값) 또는 MODE_RAW.
amplitudeGain (number, 선택 사항): 로그 모드 진폭 배율입니다. 기본값 5.
bandsGain (number, 선택 사항): 로그 모드 대역 배율입니다. 기본값 0.05.

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

위와 같지만, 기존 AudioAnalysis 구성 요소를 실패 대신 엔티티에서 교체합니다.

`AudioAnalysis.readIntoView(entity, out)`

최신 값을 out에 읽어들입니다. 다음이면 예외를 던집니다 엔티티 에 AudioAnalysis 컴포넌트를 추가해야 합니다.

엔티티 (Entity): 구성 요소가 있는 엔티티
out (AudioAnalysisView): 제공하는 뷰 객체입니다. 8개의 숫자로 대역 미리 할당되어 있어야 합니다.

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

다음과 동일하지만 readIntoView, false 엔티티에 AudioAnalysis 구성 요소가 없으면 예외를 던지지 않고 true 값이 기록되면

`AudioAnalysisView`

분석 데이터를 받기 위해 직접 할당하는 일반 객체:

type AudioAnalysisView = {
  amplitude: number; // 전체 신호 강도
  bands: number[]; // 8개의 주파수 대역, 낮음(0)에서 높음(7)까지
};

참고 및 제한 사항

8개 대역, 고정. 주파수 대역 수는 8로 고정되어 있습니다. 더 많거나 적은 대역을 요청하는 API는 없습니다.
분석당 오디오 소스 하나. 각 AudioAnalysis 구성 요소는 연결된 엔티티의 오디오를 분석합니다. 여러 소스를 분석하려면 AudioAnalysis 를 각각에 연결하세요.
실시간 비디오 스트림은 분석되지 않습니다. 다음과 같은 알려진 문제가 있습니다 AudioAnalysis 다음일 때 데이터를 받지 못합니다 VideoPlayer 소스가 다음과 같은 비진행형 스트림인 경우 .m3u8 HLS URL: 스트림 오디오는 재생되지만, 분석 값은 0으로 유지됩니다. 다음과 같은 비디오 파일은 .mp4는 올바르게 분석됩니다.
일시 중지된 오디오는 업데이트를 보고하지 않습니다. 기저 오디오가 중지되거나 일시 중지되면 구성 요소 값의 변화도 멈춥니다. 마지막으로 읽은 값은 오디오가 다시 재생될 때까지 뷰 객체에 남아 있습니다.
저렴하지만 공짜는 아닙니다. 프레임별 분석은 비용이 적게 들도록 설계되었습니다(데스크톱에서는 소스당 1밀리초 미만). AudioAnalysis 데이터가 필요하지 않다면 한 번에 너무 많은 소스에 연결하지 마세요. 시각화 도구가 보이지 않을 때는 구성 요소를 제거하세요.

이전미디어

다음오디오 스트리밍

마지막 업데이트 2일 전