Sounds

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

📔 Nota: Ten en cuenta que los sonidos solo los oyen los jugadores que estén situados dentro de los parcels que conforman la escena donde se generó el sonido, incluso si de otro modo estarían dentro del rango de audición. Los jugadores también pueden elegir desactivar todos los sonidos en sus ajustes.

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

.wav los archivos también son compatibles pero no se recomiendan generalmente, 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 in Creator Hub y configurarlo en Start Playing y Loop. Ver Add Components.

También puedes activar la reproducción de un sonido sin código mediante Actions, ver Make any item smart.

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

// Create entity
const sourceEntity = engine.addEntity()

// Play sound
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 está ubicado en una assets/sounds carpeta, que se encuentra en el nivel raíz de la carpeta del proyecto de la escena.

📔 Nota: El AudioSource componente debe importarse mediante

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

Ver Imports para ver cómo manejarlos fácilmente.

El AudioSource.playSound() la función toma los siguientes argumentos:

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

• 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 assets/sounds carpeta dentro de tu escena.

• resetCursor: (opcional) Si es true, el sonido siempre comienza 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 componente en una entidad. Usa este enfoque para tener más control sobre el sonido, por ejemplo para hacerlo en bucle o ajustar el volumen.

// Create entity
const sourceEntity = engine.addEntity()

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

Las siguientes propiedades se pueden establecer:

• 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 establecerlo en true en un momento posterior.

• volume: (opcional) El volumen del archivo de sonido. 1 por defecto, que es volumen completo.

• pitch: (opcional) Modifica el tono de un sonido. 1 es el valor por defecto; 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 un juego, es útil aleatorizar pequeñas variaciones en el 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 entidad solo puede tener un único AudioSource componente, que solo puede reproducir una pista a la vez. Esta limitación se puede superar fácilmente modificando la fuente de audio en el momento de reproducir un nuevo sonido, o incluyendo múltiples entidades hijas invisibles, cada una con su propio sonido.

📔 Nota: Los sonidos se reproducen en la instancia local de cada jugador. Otros jugadores cercanos no oirán los mismos sonidos a menos que su escena local también los reproduzca explícitamente.

Detener sonidos

Para detener que una entidad reproduzca su sonido, usa la función AudioSource.stopSound() . Solo necesitas especificar la entidad, ya que cada entidad tiene un único AudioSource componente, y cada AudioSource componente reproduce un solo archivo a la vez.

AudioSource.stopSound(sourceEntity)

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

// Create entity
const sourceEntity = engine.addEntity()

// Create AudioSource component
AudioSource.create(sourceEntity, {
	audioClipUrl: 'sounds/explosion.mp3',
	playing: true,
})

// Define a simple function
function stopSound(entity: Entity) {
	// fetch mutable version of audio source component
	const audioSource = AudioSource.getMutable(entity)

	// modify its playing value
	audioSource.playing = false
}

// call function
stopSound(sourceEntity)

Bucle

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

// Create entity
const sourceEntity = engine.addEntity()

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

Los sonidos en bucle son especialmente útiles para añadir música de fondo u otros sonidos de fondo.

Ajustar volumen

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

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

// Create entity
const sourceEntity = engine.addEntity()

// Create AudioSource component
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

Por defecto, todos los sonidos de un AudioSource son posicionales. Esto significa que parecen generarse desde la posición del Transform componente, y se escuchará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 esté el jugador. Esto es ideal para usar en música de fondo, sonidos de notificación y otros sonidos no posicionales.

📔 Nota: Los Global Sounds son una característica que solo está soportada en el cliente de escritorio DCL 2.0.

Para hacer un sonido global, establece la propiedad global 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 función playSoundSegment() en la biblioteca SDK Utils. Ver SDK7 Utils.

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

Transmisión de audio

Ver Transmisión de audio para aprender cómo puedes reproducir una transmisión de audio en vivo desde una fuente externa.