> 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-ko/sdk7/3d/sounds.md). # 사운드 씬에 사운드를 추가하는 방법을 알아봅니다. 사운드는 플레이어의 동작과 이벤트에 피드백을 제공하는 좋은 방법이며, 배경 소리도 장면에 더 많은 맥락을 부여하고 플레이어의 몰입감을 높일 수 있습니다. {% hint style="warning" %} **📔 참고**: 사운드는 사운드가 생성된 장면을 이루는 파셀 안에 서 있는 플레이어만 들을 수 있다는 점을 기억하세요. 비록 청취 범위 안에 있더라도 마찬가지입니다. 플레이어는 설정에서 모든 사운드를 끄도록 선택할 수도 있습니다. {% endhint %} 지원되는 사운드 형식은 브라우저에 따라 다르지만, 사용하는 것이 권장됩니다 *.mp3*. *.wav* 파일도 지원되지만 훨씬 더 무겁기 때문에 일반적으로 권장되지는 않습니다. ## 사운드 재생 사운드를 재생하는 가장 쉬운 방법은 ...을 추가하는 것입니다 **오디오 소스** 구성 요소를 시각적으로 ... 위에 [Creator Hub의 Scene Editor](/creator/content-creator-ko/scene-editor/get-started/about-editor.md) 로 설정합니다 **재생 시작** 과 **반복**. 참고: [컴포넌트 추가](/creator/content-creator-ko/scene-editor/build/components.md#add-components). ![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-ae588633ad20c357cfcb71a63216e4b8e02802ae%2FAudioSource-component.png?alt=media\&token=266f32b9-95c4-4d4b-a7c0-bd84d50c2dfe) 코드 없이 다음을 통해 사운드 재생을 트리거할 수도 있습니다 **동작**, 참고: [모든 항목을 스마트 아이템으로 만들기](/creator/content-creator-ko/scene-editor/interactivity/make-any-item-smart.md). 코드로 사운드를 재생하려면 다음을 사용하세요 `AudioSource.playSound` 함수. ```ts // 엔터티 생성 const sourceEntity = engine.addEntity() // 사운드 재생 AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3') ``` 사운드 파일은 프로젝트 폴더 안에 있어야 합니다. 위 예시에서 오디오 파일은 다음 위치의 `assets/sounds` 폴더에 있으며, 이 폴더는 장면 프로젝트 폴더의 루트 수준에 있습니다. {% hint style="warning" %} **📔 참고**: `AudioSource` 구성 요소는 다음을 통해 import해야 합니다 > `import { AudioSource } from "@dcl/sdk/ecs"` 다음 [가져오기](/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 를 참고해 쉽게 처리하는 방법을 확인하세요. {% endhint %} 이 `AudioSource.playSound()` 함수는 다음 인수를 사용합니다: * `엔티티`: 사운드를 어떤 엔터티에 적용할지. 사운드는 이 엔터티의 위치에서 들리며, 플레이어가 가까이 갈수록 더 크게 들립니다. * `src`: 프로젝트 내에서 사운드 파일의 위치. {% hint style="info" %} **💡 팁**: 더 명확하게 하기 위해, 사운드 파일을 장면 내부의 별도 `assets/sounds` 폴더에 분리해 두는 것을 권장합니다. {% endhint %} * `resetCursor`: *(선택 사항)* true이면 사운드는 항상 처음부터 시작합니다. 그렇지 않으면 현재 커서 위치에서 계속됩니다. 일시 중지 및 재개에 유용합니다. 사운드를 재생하는 또 다른 방법은 엔터티에 다음을 수동으로 생성하는 것입니다 `AudioSource` 구성 요소입니다. 이 접근 방식을 사용하면 사운드를 더 세밀하게 제어할 수 있습니다. 예를 들어 반복 재생하거나 볼륨을 설정할 수 있습니다. ```ts // 엔터티 생성 const sourceEntity = engine.addEntity() // AudioSource 구성 요소 생성 AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', loop: true, playing: true, }) ``` 다음 속성을 설정할 수 있습니다: * `audioClipUrl`: 프로젝트 내에서 사운드 파일의 위치. * `playing`: true이면 사운드 재생이 시작됩니다. 사운드를 다음과 같이 생성할 수 있습니다 `playing` 를 false로 설정한 뒤, 나중에 true로 설정할 수 있습니다. * `volume`: *(선택 사항)* 사운드 파일의 볼륨입니다. 기본값은 1이며, 이는 최대 볼륨을 의미합니다. * `pitch`: *(선택 사항)* 사운드의 피치를 조정합니다. 기본값은 1이며, 더 낮게 설정하면 더 깊은 소리가 나고 더 높게 설정하면 더 높은 피치의 소리가 납니다. {% hint style="info" %} **💡 팁**: 게임 중에 사운드 효과가 너무 반복적으로 들리지 않도록, 재생할 때마다 사운드의 피치를 약간씩 무작위로 변동시키는 것이 유용합니다. {% endhint %} * `currentTime`: *(선택 사항)* 기본값은 0입니다. 사운드 파일의 처음부터 시작하지 않도록 하려면 이 값을 설정하세요. 각 엔터티는 하나의 `AudioSource` 구성 요소만 가질 수 있으며, 한 번에 하나의 클립만 재생할 수 있습니다. 이 제한은 새 사운드를 재생할 때 오디오 소스를 수정하거나, 각각 고유한 사운드를 가진 여러 개의 보이지 않는 자식 엔터티를 포함시켜 쉽게 극복할 수 있습니다. {% hint style="warning" %} **📔 참고**: 사운드는 각 플레이어의 로컬 인스턴스에서 재생됩니다. 다른 근처 플레이어는 자신의 로컬 장면에서도 명시적으로 재생하지 않는 한 같은 사운드를 들을 수 없습니다. {% endhint %} ### 사운드 미리 로드 엔터티가 사운드를 사용하지만 장면 런타임에 즉시 재생되지 않으면 다운로드하는 데 시간이 걸릴 수 있습니다. 다음을 사용하면 장면 런타임에 사용할 수 있습니다 `AssetLoad` 컴포넌트를 추가해야 합니다. ```ts import { AssetLoad } from "@dcl/sdk/ecs" AssetLoad.create(engine.RootEntity, { assets: [ "assets/scene/bundle1/explosionSound.mp3", ], }) ``` 자세한 내용은 다음을 확인하세요 [리소스 미리 로드](/creator/content-creator-ko/sdk7/optimizing/pre-load-resources.md) 문서를 참고하세요. ## 사운드 중지 엔터티의 사운드 재생을 중지하려면 다음을 사용하세요 `AudioSource.stopSound()` 함수입니다. 각 엔터티에는 하나의 `AudioSource` 구성 요소만 있으므로 엔터티만 지정하면 됩니다. 그리고 각 `AudioSource` 구성 요소는 한 번에 하나의 파일만 재생합니다. ```ts AudioSource.stopSound(sourceEntity) ``` 사운드를 중지하는 또 다른 방법은 다음을 false로 설정하는 것입니다 `playing` 속성을 false로 설정하는 것입니다. ```ts // 엔터티 생성 const sourceEntity = engine.addEntity() // AudioSource 구성 요소 생성 AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/explosion.mp3', playing: true, }) // 간단한 함수 정의 function stopSound(entity: Entity) { // 오디오 소스 구성 요소의 mutable 버전 가져오기 const audioSource = AudioSource.getMutable(entity) // playing 값을 수정 audioSource.playing = false } // 함수 호출 stopSound(sourceEntity) ``` ## 사운드가 끝났는지 감지 루프 재생되지 않는 사운드가 스스로 재생을 마치면, 엔진은 다음 값을 설정합니다 `playing` 의 속성을 `AudioSource` 구성 요소를 다시 *false*. 장면의 코드는 이 값을 읽어 사운드가 언제 끝났는지 알 수 있으며, 예를 들어 바로 뒤에 다른 사운드나 동작을 연결할 수 있습니다. ```ts let wasPlaying = false engine.addSystem(() => { const audio = AudioSource.get(sourceEntity) const isPlaying = audio.playing ?? false if (wasPlaying && !isPlaying) { console.log('sound finished playing') // 여기서 반응: 다른 사운드 재생, 시퀀스 진행 등 } wasPlaying = isPlaying }) ``` {% hint style="warning" %} **📔 참고**: 프레임마다 구성 요소를 폴링할 때는 항상 다음으로 읽으세요 `AudioSource.get()` (읽기 전용). 다음을 사용하면 `AudioSource.getMutable()` 는 매 프레임마다 구성 요소를 변경된 것으로 표시하게 되어 불필요한 동기화 작업이 발생합니다. 이 `playing` 속성은 사운드가 스스로 끝날 때에만 엔진에 의해 바뀝니다. 장면이 사운드를 명시적으로 중지하면( `AudioSource.stopSound()` 또는 다음을 설정하여 `playing` 를 *false*), 해당 변경은 사용자의 코드에서 비롯된 것이며, 루프 사운드는 중지될 때까지 재생되므로 스스로는 이 속성을 바꾸지 않습니다. {% endhint %} 대신 다음을 사용하세요 `audioEventsSystem.registerAudioEventsEntity` 엔터티의 오디오 재생 상태가 바뀔 때마다 실행되는 함수를 정의합니다. 이는 다음과 같습니다 [비디오 이벤트](/creator/content-creator-ko/sdk7/media/video-playing.md#video-events) 비디오용입니다. 함수는 다음을 포함한 이벤트를 받습니다 `state` 필드를 가지며, 다음을 사용합니다 `MediaState` 열거형. ```ts import { engine, AudioSource, audioEventsSystem, MediaState } from '@dcl/sdk/ecs' // ... AudioSource 구성 요소가 있는 sourceEntity 생성 ... 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 } }) ``` 다음에서의 전환 `MS_PLAYING` 를 `MS_READY` 는 사운드가 재생을 중지했음을 의미합니다. 전체 `MediaState` 열거형에는 또한 다음이 포함됩니다 `MS_NONE`, `MS_LOADING`, `MS_PAUSED`, `MS_BUFFERING`, `MS_SEEKING` 과 `MS_ERROR`, 그리고 각 이벤트에는 `타임스탬프` 가 상태 변경이 발생한 시점을 나타냅니다. 또한 언제든지 다음으로 최신 보고 상태를 조회할 수 있습니다 `audioEventsSystem.getAudioState(entity)`, 콜백을 등록 해제하려면 다음을 사용하세요 `audioEventsSystem.removeAudioEventsEntity(entity)`, 또는 엔터티가 등록되어 있는지 확인하려면 다음을 사용하세요 `audioEventsSystem.hasAudioEventsEntity(entity)`. 동일한 시스템은 다음을 가진 엔터티에도 작동합니다 [`AudioStream`](/creator/content-creator-ko/sdk7/media/audio-streaming.md) 컴포넌트를 추가해야 합니다. {% hint style="warning" %} **📔 참고**: 이러한 기능은 Desktop 클라이언트에서만 지원됩니다. {% endhint %} ## 루프 재생 사운드를 계속해서 반복 재생하려면 다음을 설정하세요 `loop` 필드를 `AudioSource` 구성 요소의 값을 *true* 재생을 시작하기 전에 ```ts // 엔터티 생성 const sourceEntity = engine.addEntity() // AudioSource 구성 요소 생성 AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', playing: true, loop: true, }) ``` 루프 사운드는 배경 음악이나 기타 배경 소리를 추가할 때 특히 유용합니다. ## 볼륨 설정 다음을 설정하여 `volume` 의 속성을 `AudioSource` 구성 요소로 사운드의 볼륨을 변경할 수 있습니다. 볼륨은 다음 범위의 숫자로 표현됩니다 *0* 를 *1*. ```ts // 엔터티 생성 const sourceEntity = engine.addEntity() // AudioSource 구성 요소 생성 AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', playing: true, volume: 0.5, }) ``` {% hint style="warning" %} **📔 참고**: 물론 사운드의 볼륨은 플레이어와 오디오 소스 사이의 거리에도 영향을 받습니다. 플레이어가 멀어질수록 볼륨은 더 낮아집니다. {% endhint %} ## 전역 사운드 기본적으로 다음에서 재생되는 모든 사운드는 `AudioSource` 위치 기반입니다. 즉, 사운드가 다음의 위치에서 발생하는 것처럼 들립니다 `Transform` 구성 요소이며, 플레이어가 가까이 갈수록 더 크게 들립니다. 하지만 사운드를 전역으로 구성하여 플레이어가 어디에 서 있든 볼륨이 일정하도록 만들 수도 있습니다. 이는 배경 음악, 알림 소리 및 기타 비위치 기반 사운드에 사용하기에 이상적입니다. {% hint style="warning" %} **📔 참고**: 전역 사운드는 DCL 2.0 데스크톱 클라이언트에서만 지원되는 기능입니다. {% endhint %} 사운드를 전역으로 만들려면 다음을 설정하세요 `global` 속성을 *true*. ```ts AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/music.mp3', playing: true, global: true, }) ``` ## 사운드의 일부 구간 재생 더 긴 사운드 파일의 일부 구간을 재생하려면 다음을 사용하세요 `playSoundSegment()` SDK Utils 라이브러리의. 참고: [SDK7 Utils](https://github.com/decentraland/sdk7-utils). 또한 다음을 명시적으로 설정하여 이를 달성할 수도 있습니다 `currentTime` 속성을 다음의 `AudioSource` 구성 요소에 설정한 뒤, 일정 시간 기다린 후 중지합니다. ## 오디오 스트리밍 다음 [오디오 스트리밍](/creator/content-creator-ko/sdk7/media/audio-streaming.md) 외부 소스에서 라이브 오디오 스트림을 재생하는 방법을 알아보세요. ## 오디오 분석 다음 [오디오 분석](/creator/content-creator-ko/sdk7/media/audio-analysis.md) 다음에서 실시간 진폭 및 주파수 데이터를 읽고 `AudioSource` 이를 바탕으로 베이스에 맞춰 펄스하는 큐브나 이퀄라이저 스타일 막대 시각화기와 같은 반응형 비주얼을 구현하는 방법을 알아보세요. --- # 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-ko/sdk7/3d/sounds.md?ask=&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.