Sounds

Aprende cómo agregar sounds a tu scene.

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 más contexto a tu scene y mejorar la inmersión del jugador en ella.

📔 Nota: Ten en cuenta que los sonidos solo son escuchados por los jugadores que están dentro de los parcels que conforman la scene donde se generó el sonido, incluso si de otro modo estuvieran dentro del alcance de audición. Los jugadores también pueden elegir desactivar todos los sonidos en sus settings.

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

.wav Los archivos también son compatibles, pero generalmente no se recomiendan porque son significativamente más pesados.

Reproducir sonidos

La forma más fácil de reproducir un sonido es agregar un Audio Source component visualmente en el Scene Editor en Creator Hub y configurarlo como Start Playing y Loop. Ver Add Components.

También puedes activar la reproducción de un sonido de forma no-code a través de Actions, ver Haz cualquier item smart.

Para reproducir un sonido mediante código, usa la AudioSource.playSound function.

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

// Reproducir sonido
AudioSource.playSound(sourceEntity, 'assets/sounds/sound-effect.mp3')

El archivo de sonido debe estar dentro de la carpeta del proyecto. En el ejemplo anterior, el archivo de audio se encuentra en una carpeta assets/sounds que está ubicada en el nivel raíz de la carpeta del proyecto de la scene.

📔 Nota: El AudioSource component debe importarse mediante

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

Consulta Imports para ver cómo manejar esto fácilmente.

El AudioSource.playSound() function toma los siguientes argumentos:

• entity: Sobre qué entity aplicar el sonido. El sonido se escuchará desde la posición de esta entity, lo que significa que se oirá más fuerte a medida que el jugador se acerque.

• src: La ubicación del archivo de sonido dentro de tu proyecto.

💡 Consejo: Para mayor claridad, recomendamos mantener tus archivos de sonido separados en una carpeta assets/sounds dentro de tu scene.

• resetCursor: (opcional) Si es true, el sonido siempre empieza desde el principio. 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 component en una entity. Usa este enfoque para tener más control sobre el sonido, por ejemplo para hacerlo loop o configurar el volume.

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

// 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 configurado como false, y luego cambiarlo a true más adelante.

• volume: (opcional) El volumen del archivo de sonido. 1 por defecto, que es 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.

💡 Consejo: Para evitar que un efecto de sonido se vuelva demasiado repetitivo durante una partida, es útil aleatorizar pequeñas variaciones del pitch del sonido cada vez que se reproduce.

• currentTime: (opcional) 0 por defecto. Establece este valor para evitar comenzar desde el principio del archivo de sonido.

Cada entity solo puede tener un único AudioSource component, que solo puede reproducir un solo 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 múltiples entidades secundarias invisibles, cada una con su propio sonido.

📔 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.

Pre Loading de un sonido

Si una entity usa un sonido, pero no se reproduce inmediatamente en tiempo de ejecución de la scene, puede tardar un tiempo en descargarse. Puede estar disponible en tiempo de ejecución de la scene usando AssetLoad componente.

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

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

Para más información, consulta la documentación de Pre Load Resources .

Detener sonidos

Para impedir que una entity reproduzca su sonido, usa la AudioSource.stopSound() function. Solo necesitas especificar la entity, ya que cada entity tiene un único AudioSource component, y cada AudioSource component reproduce un solo archivo a la vez.

AudioSource.stopSound(sourceEntity)

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

// 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 de fuente de audio
	const audioSource = AudioSource.getMutable(entity)

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

// llamar a la función
stopSound(sourceEntity)

Looping

Para mantener un sonido reproduciéndose en un loop continuo, establece el loop campo del AudioSource component en true antes de empezar a reproducirlo.

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

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

Reproducir sonidos en loop es especialmente útil para añadir música de fondo u otros sonidos de fondo.

Configurar volume

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

El volumen se expresa como un número de 0 a 1.

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

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

📔 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.

Sonidos globales

De forma predeterminada, todos los sonidos de un AudioSource son posicionales. Esto significa que parecen generarse desde la posición del Transform component, y sonarán más fuerte 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 esté el jugador. Esto es ideal para usarlo en música de fondo, sonidos de notificación y otros sonidos no posicionales.

📔 Nota: Global Sounds es una función que solo es compatible con el cliente de escritorio DCL 2.0.

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

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

Reproducir un segmento de un sonido

Para reproducir un segmento de un archivo de sonido más largo, usa la playSoundSegment() en la librería SDK Utils. Ver SDK7 Utils.

También puedes lograr esto estableciendo explícitamente la currentTime propiedad en un AudioSource component, y luego deteniéndolo después de esperar un período de tiempo.

Streaming de audio

Consulta Streaming de audio 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 para aprender cómo leer datos de amplitud y frecuencia en tiempo real desde un AudioSource y generar visuales reactivos a partir de ello, como cubos que laten con el bajo o visualizadores de barras estilo ecualizador.