> 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-es/scenes-sdk7/fundamentos-del-contenido-3d/sounds.md). # Sonidos Aprende cómo añadir sonidos a tu escena. El sonido es una excelente manera de proporcionar retroalimentación a las acciones y eventos del jugador; los sonidos de fondo también pueden dar a tu scene más contexto y mejorar la inmersión del jugador en ella. {% hint style="warning" %} **📔 Nota**: Ten en cuenta que los sonidos solo los oyen los jugadores que están dentro de los parcels que componen la scene donde se generó el sonido, incluso si de otro modo estuvieran dentro del alcance auditivo. Los jugadores también pueden elegir desactivar todos los sonidos en sus settings. {% endhint %} Los formatos de sonido compatibles varían según el navegador, pero se recomienda usar *.mp3*. *.wav* también son compatibles, pero en general no se recomiendan, ya que son significativamente más pesados. ## Reproducir sonidos La forma más sencilla de reproducir un sonido es añadir un **Audio Source** componente visualmente en el [Scene Editor en Creator Hub](/creator/content-creator-es/scene-editor/primeros-pasos/about-editor.md) y configúralo en **Start Playing** y **Loop**. Consulta [Add Components](/creator/content-creator-es/scene-editor/construir/components.md#add-components). ![](https://1216664193-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) También puedes activar la reproducción de un sonido sin código a través de **Actions**, consulta [Convierte cualquier item en smart](/creator/content-creator-es/scene-editor/interactividad/make-any-item-smart.md). Para reproducir un sonido mediante código, usa la `AudioSource.playSound` función. ```ts // Crear entidad const sourceEntity = engine.addEntity() Transform.create(sourceEntity, { position: Vector3.create(8, 1, 8) }) // Reproducir sonido AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3') ``` {% hint style="warning" %} **📔 Nota**: Toda entidad con un `AudioSource` también necesita un `Transform`, incluidos los sonidos globales. Sin uno, no se reproduce nada y no se registra ningún error, lo que hace que sea un problema difícil de detectar. Los items colocados en el Scene Editor siempre tienen un `Transform`, así que esto solo afecta a las entidades que creas en código. {% endhint %} El archivo de sonido debe estar dentro de la carpeta del proyecto. En el ejemplo anterior, el archivo de audio se encuentra en una `assets/sounds` carpeta, que se encuentra en el nivel raíz de la carpeta del proyecto de la scene. {% hint style="warning" %} **📔 Nota**: El `AudioSource` componente debe importarse mediante > `import { AudioSource } from "@dcl/sdk/ecs"` Consulta [Imports](/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para ver cómo manejarlos fácilmente. {% endhint %} La `AudioSource.playSound()` función toma los siguientes argumentos: * `entity`: Sobre qué entity aplicar el sonido. El sonido se oirá desde la posición de esta entity, lo que significa que sonará más fuerte a medida que el jugador se acerque. * `src`: La ubicación del archivo de sonido dentro de tu proyecto. {% hint style="info" %} **💡 Consejo**: Para mayor claridad, recomendamos mantener tus archivos de sonido separados en una `assets/sounds` carpeta dentro de tu scene. {% endhint %} * `resetCursor`: *(opcional)* Si es true, el sonido siempre comienza desde el inicio. De lo contrario, continúa desde la posición actual del cursor. Útil para pausar y reanudar. Otra forma de reproducir sonidos es crear manualmente un `AudioSource` componente en una entity. Usa este enfoque para tener más control sobre el sonido, por ejemplo para hacer que se repita en loop o establecer el volumen. ```ts // Crear entidad const sourceEntity = engine.addEntity() Transform.create(sourceEntity, { position: Vector3.create(8, 1, 8) }) // Crear componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', loop: true, playing: true, }) ``` Se pueden establecer las siguientes propiedades: * `audioClipUrl`: La ubicación del archivo de sonido dentro de tu proyecto. * `playing`: Si es true, el sonido comienza a reproducirse. Puedes crear un sonido con `playing` establecido en false y luego configurarlo en true más adelante. * `volume`: *(opcional)* El volumen del archivo de sonido. 1 por defecto, que es el volumen máximo. * `pitch`: *(opcional)* Modifica el pitch de un sonido. 1 es el valor predeterminado; bájalo para un sonido más grave y súbelo para un sonido más agudo. {% hint style="info" %} **💡 Consejo**: Para evitar que un efecto de sonido se vuelva demasiado repetitivo durante una partida, es útil aleatorizar algunas ligeras variaciones en el pitch del sonido cada vez que se reproduce. {% endhint %} * `currentTime`: *(opcional)* 0 por defecto. Establece este valor para evitar empezar desde el comienzo del archivo de sonido. Cada entity solo puede tener un único `AudioSource` componente, que solo puede reproducir un único clip a la vez. Esta limitación puede superarse fácilmente modificando la fuente de audio en el momento de reproducir un nuevo sonido, o incluyendo varias entidades hijas invisibles, cada una con su propio sonido. {% hint style="warning" %} **📔 Nota**: Los sonidos se reproducen en la instancia local de cada jugador. Los demás jugadores cercanos no oirán los mismos sonidos a menos que su scene local también los reproduzca explícitamente. {% endhint %} ### Precargar un sonido Si una entity usa un sonido, pero no se reproduce inmediatamente en el runtime de la scene, puede tardar un tiempo en descargarse. Puede estar disponible en tiempo de ejecución de la scene usando el `AssetLoad` componente. ```ts import { AssetLoad } from "@dcl/sdk/ecs" AssetLoad.create(engine.RootEntity, { assets: [ "assets/scene/bundle1/explosionSound.mp3", ], }) ``` Para más información, consulta la [Pre Load Resources](/creator/content-creator-es/scenes-sdk7/optimizacion/pre-load-resources.md) documentación. ## Detener sonidos Para impedir que una entity reproduzca su sonido, usa la `AudioSource.stopSound()` función. Solo necesitas especificar la entity, ya que cada entity tiene un único `AudioSource` componente, y cada `AudioSource` componente reproduce un único archivo a la vez. ```ts AudioSource.stopSound(sourceEntity) ``` Otra forma de detener un sonido es establecer la `playing` propiedad en false. ```ts // Crear entidad const sourceEntity = engine.addEntity() // Crear componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/explosion.mp3', playing: true, }) // Definir una función simple function stopSound(entity: Entity) { // obtener la versión mutable del componente AudioSource const audioSource = AudioSource.getMutable(entity) // modificar su valor playing audioSource.playing = false } // llamar a la función stopSound(sourceEntity) ``` ## Detectar cuándo termina un sonido Cuando un sonido que no se repite termina de reproducirse por sí solo, el engine establece la `playing` propiedad del `AudioSource` componente de nuevo en *false*. El código de tu scene puede leer este valor para saber cuándo terminó el sonido, por ejemplo para encadenar otro sonido o acción justo después. ```ts let wasPlaying = false engine.addSystem(() => { const audio = AudioSource.get(sourceEntity) const isPlaying = audio.playing ?? false if (wasPlaying && !isPlaying) { console.log('el sonido terminó de reproducirse') // reacciona aquí: reproduce otro sonido, avanza una secuencia, etc. } wasPlaying = isPlaying }) ``` {% hint style="warning" %} **📔 Nota**: Cuando consultes el componente en cada frame, léelo siempre con `AudioSource.get()` (solo lectura). `AudioSource.getMutable()` marcaría el componente como cambiado en cada frame, lo que provocaría un trabajo de sincronización innecesario. La `playing` La propiedad solo la cambia el engine cuando el sonido termina por sí mismo. Si la scene detiene el sonido explícitamente (mediante `AudioSource.stopSound()` o estableciendo `playing` en *false*), ese cambio proviene de tu propio código, y los sonidos en loop se reproducen hasta que se detienen, así que nunca cambian la propiedad por sí solos. {% endhint %} Como alternativa, usa `audioEventsSystem.registerAudioEventsEntity` para definir una función que se ejecute cada vez que cambia el estado de reproducción del audio de la entity, igual que [los eventos de video](/creator/content-creator-es/scenes-sdk7/media/video-playing.md#video-events) para los videos. La función recibe un evento con un `state` campo, usando el `MediaState` enum. ```ts import { engine, AudioSource, audioEventsSystem, MediaState } from '@dcl/sdk/ecs' // ... Crear sourceEntity con un componente AudioSource ... audioEventsSystem.registerAudioEventsEntity(sourceEntity, (audioEvent) => { switch (audioEvent.state) { case MediaState.MS_LOADING: console.log('evento de audio - el sonido se está CARGANDO') break case MediaState.MS_READY: console.log('evento de audio - el sonido está LISTO (cargado o ha terminado de reproducirse)') break case MediaState.MS_PLAYING: console.log('evento de audio - el sonido comenzó a reproducirse') break case MediaState.MS_ERROR: console.log('evento de audio - ERROR de sonido (por ejemplo, el archivo no se pudo cargar)') break } }) ``` Una transición de `MS_PLAYING` en `MS_READY` significa que el sonido dejó de reproducirse. El `MediaState` enum completo también incluye `MS_NONE`, `MS_LOADING`, `MS_PAUSED`, `MS_BUFFERING`, `MS_SEEKING` y `MS_ERROR`, y cada evento lleva un `timestamp` de cuándo ocurrió el cambio de estado. También puedes consultar en cualquier momento el último estado reportado con `audioEventsSystem.getAudioState(entity)`, cancela el registro de la callback con `audioEventsSystem.removeAudioEventsEntity(entity)`, o comprobar si una entity está registrada con `audioEventsSystem.hasAudioEventsEntity(entity)`. El mismo sistema también funciona para entities con un [`AudioStream`](/creator/content-creator-es/scenes-sdk7/media/audio-streaming.md) componente. {% hint style="warning" %} **📔 Nota**: Estas funciones solo son compatibles con el cliente de escritorio. {% endhint %} ## Repetición en loop Para mantener un sonido reproduciéndose en un loop continuo, configura el `loop` campo del `AudioSource` componente en *true* antes de empezar a reproducirlo. ```ts // Crear entidad const sourceEntity = engine.addEntity() // Crear componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', playing: true, loop: true, }) ``` Repetir sonidos en loop es especialmente útil para añadir música de fondo u otros sonidos de fondo. ## Establecer volumen Puedes configurar el `volume` propiedad del `AudioSource` componente para cambiar el volumen de un sonido. El volumen se expresa como un número de *0* en *1*. ```ts // Crear entidad const sourceEntity = engine.addEntity() // Crear componente AudioSource AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/sound-effect.mp3', playing: true, volume: 0.5, }) ``` {% hint style="warning" %} **📔 Nota**: Por supuesto, el volumen de un sonido también se ve afectado por la distancia del jugador a la fuente de audio. A medida que el jugador se aleja, el volumen será menor. {% endhint %} ## Sonidos globales Por defecto, todos los sonidos de un `AudioSource` son posicionales. Esto significa que parecen generarse desde la posición del `Transform` componente, y sonarán más fuertes a medida que el jugador se acerque. Pero también puedes configurar un sonido para que sea global, de modo que el volumen sea constante, sin importar dónde se encuentre el jugador. Esto es ideal para usar en música de fondo, sonidos de notificación y otros sonidos no posicionales. {% hint style="warning" %} **📔 Nota**: Global Sounds es una función que solo es compatible con el cliente de escritorio DCL 2.0. {% endhint %} Para hacer que un sonido sea global, establece la `global` propiedad en *true*. ```ts AudioSource.create(sourceEntity, { audioClipUrl: 'sounds/music.mp3', playing: true, global: true, }) ``` Un sonido global todavía necesita un `Transform` en su entity, aunque su posición ya no afecte a lo que oye el jugador. Cualquier posición servirá. ## Reproducir un segmento de un sonido Para reproducir un segmento de un archivo de sonido más largo, usa la `playSoundSegment()` en la biblioteca SDK Utils. Consulta [SDK7 Utils](https://github.com/decentraland/sdk7-utils). También puedes lograr esto estableciendo explícitamente la `currentTime` propiedad en un `AudioSource` componente y luego deteniéndolo después de esperar un período de tiempo. ## Streaming de audio Consulta [Streaming de audio](/creator/content-creator-es/scenes-sdk7/media/audio-streaming.md) para aprender cómo puedes reproducir un stream de audio en vivo desde una fuente externa. ## Análisis de audio Consulta [Análisis de audio](/creator/content-creator-es/scenes-sdk7/media/audio-analysis.md) para aprender a leer datos de amplitud y frecuencia en tiempo real desde un `AudioSource` y generar visuales reactivos a partir de él, como cubos que pulsan con el bajo o visualizadores de barras estilo ecualizador. --- # 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-es/scenes-sdk7/fundamentos-del-contenido-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.