> 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 forma de ofrecer comentarios sobre las acciones y los eventos de los jugadores. Además, los sonidos de fondo pueden aportar más contexto a la escena y mejorar la inmersión del jugador.

{% hint style="warning" %}
**📔 Nota**: Ten en cuenta que solo escucharán los sonidos los jugadores que estén dentro de las parcelas que componen la escena donde se generó el sonido, aunque de otro modo estuvieran dentro del alcance auditivo. Los jugadores también pueden optar por desactivar todos los sonidos en la configuración.
{% endhint %}

Los formatos de sonido compatibles varían según el navegador, pero se recomienda usar *.mp3*.

*.wav* Los archivos también son compatibles, pero por lo general no se recomiendan, ya que ocupan mucho más espacio.

## Reproducir sonidos

La forma más sencilla de reproducir un sonido es añadir un componente **Audio Source** visualmente en el [Scene Editor en Creator Hub](https://docs.decentraland.org/creator/content-creator-es/scene-editor/primeros-pasos/about-editor.md) y configurarlo para que **empiece a reproducirse** y **se repita**. Consulta [Añadir componentes](https://docs.decentraland.org/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-cf1d382199d0518859ab3a850b5a34b869e334f6%2FAudioSource-component.webp?alt=media)

También puedes activar la reproducción de un sonido sin código mediante **Actions**, consulta [Convertir cualquier elemento en interactivo](https://docs.decentraland.org/creator/content-creator-es/scene-editor/interactividad/make-any-item-smart.md).

Para reproducir un sonido mediante código, usa la función `AudioSource.playSound` .

```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 componente `AudioSource` también necesita un componente `Transform`, incluidos los sonidos globales. Sin él, no se reproduce nada ni se registra ningún error, por lo que puede ser difícil detectar el problema. Los elementos colocados en el Scene Editor siempre tienen un componente `Transform`, así que esto solo afecta a las entidades que creas mediante 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 la carpeta `assets/sounds` , ubicada en el directorio raíz de la carpeta del proyecto de la escena.

{% hint style="warning" %}
**📔 Nota**: El componente `AudioSource` debe importarse mediante

> `import { AudioSource } from "@dcl/sdk/ecs"`

Consulta [Importaciones](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para saber cómo gestionarlas fácilmente.
{% endhint %}

La función `AudioSource.playSound()` acepta los siguientes argumentos:

* `entity`: Entidad a la que se aplica el sonido. El sonido se escuchará desde la posición de esta entidad; es decir, aumentará de volumen 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 carpeta `assets/sounds` dentro de tu escena.
{% endhint %}

* `resetCursor`: *(opcional)* Si es true, el sonido siempre empieza desde el principio. De lo contrario, continúa desde la posición actual del cursor. Es útil para pausar y reanudar.

`playSound()` crea el componente `AudioSource` si la entidad aún no tiene uno. Si ya tiene uno, `playSound()` conserva sus otros valores, como `volume`, `pitch`, `loop` y `global`, para que puedas configurarlos una vez y luego llamar a `playSound()` cada vez que quieras reproducir el sonido. Si vuelves a llamarla con el mismo archivo, el sonido se reproduce de nuevo. Siempre devuelve `true`.

Otra forma de reproducir sonidos es crear manualmente un componente `AudioSource` en una entidad. Usa este método para tener más control sobre el sonido, por ejemplo, para hacer que se repita o ajustar el volumen.

```ts
// Crear entidad
const sourceEntity = engine.addEntity()
Transform.create(sourceEntity, { position: Vector3.create(8, 1, 8) })

// Crear el componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/sound-effect.mp3',
	loop: true,
	playing: true,
})
```

Se pueden configurar las siguientes propiedades:

* `audioClipUrl`: La ubicación del archivo de sonido dentro de tu proyecto.
* `playing`: Si es true, el sonido empieza a reproducirse. Puedes crear un sonido con `playing` establecido en false y luego cambiarlo a true más adelante.
* `volume`: *(opcional)* El volumen del archivo de sonido. Es 1 de forma predeterminada, lo que corresponde al volumen máximo.
* `pitch`: *(opcional)* Modifica el tono de un sonido. El valor predeterminado es 1; usa un valor más bajo para obtener un sonido más grave y uno más alto para obtener un tono más agudo.

{% hint style="info" %}
**💡 Consejo**: Para evitar que un efecto de sonido se vuelva demasiado repetitivo durante un juego, resulta útil aleatorizar ligeramente el tono cada vez que se reproduce.
{% endhint %}

* `currentTime`: *(opcional)* El valor predeterminado es 0. Establece este valor para evitar empezar desde el principio del archivo de sonido.

Cada entidad solo puede tener un único componente `AudioSource` y este solo puede reproducir un clip a la vez. Esta limitación se puede superar fácilmente modificando la fuente de audio al reproducir un sonido nuevo o incluyendo varias entidades secundarias 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 escena local también los reproduzca explícitamente.
{% endhint %}

### Precargar un sonido

Si una Entity utiliza un sonido, pero este no se reproduce inmediatamente al ejecutarse la escena, la descarga podría tardar un poco. Puede estar disponible al ejecutarse la escena si se utiliza el `AssetLoad` Component.

```ts
import { AssetLoad } from "@dcl/sdk/ecs"

AssetLoad.create(engine.RootEntity, {
  assets: [
    "assets/scene/bundle1/explosionSound.mp3",
  ],
})
```

Para obtener más información, consulta la documentación de [Precargar recursos](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/optimizacion/pre-load-resources.md) .

## Detener sonidos

Para detener la reproducción del sonido de una Entity, utiliza la función `AudioSource.stopSound()` . Solo tienes que especificar la Entity, ya que cada Entity tiene un único `AudioSource` Component y cada `AudioSource` Component reproduce un único archivo a la vez.

```ts
AudioSource.stopSound(sourceEntity)
```

`stopSound()` devuelve `false` si la Entity no tiene un `AudioSource` Component.

Otra forma de detener un sonido es establecer la propiedad `playing` en false.

```ts
// Crear entidad
const sourceEntity = engine.addEntity()

// Crear el componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/explosion.mp3',
	playing: true,
})

// Define una función sencilla
function stopSound(entity: Entity) {
	// obtiene la versión mutable del componente de fuente de audio
	const audioSource = AudioSource.getMutable(entity)

	// modifica su valor playing
	audioSource.playing = false
}

// llama a la función
stopSound(sourceEntity)
```

## Detectar cuándo termina un sonido

Cuando un sonido que no está en bucle termina de reproducirse por sí solo, el Engine establece la propiedad `playing` del `AudioSource` Component en *false*. El código de tu escena puede leer este valor para saber cuándo terminó el sonido; por ejemplo, para reproducir otro sonido o ejecutar otra 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('sound finished playing')
		// react here: play another sound, advance a sequence, etc.
	}

	wasPlaying = isPlaying
})
```

{% hint style="warning" %}
**📔 Nota**: Al consultar el componente en cada fotograma, léelo siempre con `AudioSource.get()` (solo lectura). Usar `AudioSource.getMutable()` marcaría el componente como modificado en cada fotograma, lo que provocaría trabajo de sincronización innecesario.

La `playing` propiedad solo cambia de valor por acción del motor cuando el sonido termina por sí solo. Si la escena detiene el sonido explícitamente (mediante `AudioSource.stopSound()` o estableciendo `playing` en *false*), ese cambio proviene de tu propio código. Además, los sonidos en bucle se reproducen hasta que se detienen, así que nunca cambian el valor de la propiedad por sí solos.
{% endhint %}

Como alternativa, usa `audioEventsSystem.registerAudioEventsEntity` para definir una función que se ejecute cada vez que cambie el estado de reproducción del audio de la entidad, igual que los [eventos de video](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/media/video-playing.md#video-events) para videos. La función recibe un evento con un campo `state` , que utiliza el enum `MediaState` .

```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('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
	}
})
```

Una transición de `MS_PLAYING` a `MS_READY` significa que el sonido dejó de reproducirse. El enum completo `MediaState` también incluye `MS_NONE`, `MS_LOADING`, `MS_PAUSED`, `MS_BUFFERING`, `MS_SEEKING` y `MS_ERROR`, y cada evento incluye una `timestamp` que indica cuándo se produjo el cambio de estado. También puedes consultar en cualquier momento el último estado notificado con `audioEventsSystem.getAudioState(entity)`, cancelar el registro de la devolución de llamada con `audioEventsSystem.removeAudioEventsEntity(entity)`, o comprobar si una entidad está registrada con `audioEventsSystem.hasAudioEventsEntity(entity)`. El mismo sistema también funciona con entidades que tienen un componente [`AudioStream`](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/media/audio-streaming.md) .

{% hint style="warning" %}
**📔 Nota**: Estas funciones solo son compatibles con el cliente de escritorio.
{% endhint %}

## Reproducción en bucle

Para que un sonido se reproduzca en un bucle continuo, establece el campo `loop` del componente `AudioSource` en *true* antes de empezar a reproducirlo.

```ts
// Crear entidad
const sourceEntity = engine.addEntity()

// Crear el componente AudioSource
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/sound-effect.mp3',
	playing: true,
	loop: true,
})
```

La reproducción en bucle resulta especialmente útil para añadir música de fondo u otros sonidos ambientales.

## Establecer el volumen

Puedes establecer la propiedad `volume` del componente `AudioSource` para cambiar el volumen de un sonido.

El volumen se expresa como un número entre *0* y *1*.

```ts
// Crear entidad
const sourceEntity = engine.addEntity()

// Crear el 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 depende de la distancia entre el jugador y la fuente de audio. A medida que el jugador se aleja, el volumen disminuye.
{% endhint %}

## Sonidos globales

De forma predeterminada, todos los sonidos de un componente `AudioSource` son posicionales. Esto significa que parecen originarse en la posición del componente `Transform` y suenan más fuerte cuando el jugador se acerca. Sin embargo, también puedes configurar un sonido como global para que el volumen sea constante, independientemente de dónde se encuentre el jugador. Esto resulta ideal para la música de fondo, los sonidos de notificación y otros sonidos no posicionales.

{% hint style="warning" %}
**📔 Nota**: Los sonidos globales solo son compatibles con el cliente de escritorio DCL 2.0.
{% endhint %}

Para hacer que un sonido sea global, establece la propiedad `global` en *true*.

```ts
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/music.mp3',
	playing: true,
	global: true,
})
```

Un sonido global sigue necesitando un `Transform` en su Entity, aunque su posición ya no afecta lo que oye el jugador. Cualquier posición sirve.

## Reproducir un segmento de un sonido

Para reproducir un segmento de un archivo de sonido más largo, usa `playSoundSegment()` de la biblioteca SDK Utils. Consulta [SDK7 Utils](https://github.com/decentraland/sdk7-utils).

También puedes hacerlo estableciendo explícitamente la `currentTime` propiedad de un componente `AudioSource` y deteniéndolo después de esperar un tiempo.

## Transmisión de audio

Consulta [Transmisión de audio](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/media/audio-streaming.md) para aprender a reproducir una transmisión de audio en directo desde una fuente externa.

## Análisis de audio

Consulta [Análisis de audio](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/media/audio-analysis.md) para aprender a leer datos de amplitud y frecuencia en tiempo real de un componente `AudioSource` y crear efectos visuales reactivos a partir de ellos, como cubos que pulsan al ritmo de los graves o visualizadores de barras al estilo de un 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=<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.
