Hello! Please choose your
desired language:
Dismiss

Sounds

Note: We’re working on an improved sound controller that will allow for multiple tracks and positional sound. This feature will be unveiled soon.

Sound is a great way to provide feedback to user actions and events, background sounds can also give your scene more context and improve the user’s immersion into it.

You can either trigger sounds from a specific entity, or from the scene itself.

Note: Keep in mind that sounds from your scene will be also heard by users that are outside your scene but in hearing range, so be considerate with neighboring scenes when setting volumes and volume curves.

Supported sound formats vary depending on the browser, but it’s safe to use .mp3, .accc and .ogg.

.wav files are also supported but not generally recommended as they are significantly larger.

Import the sound controller

To use sounds, you must first import the SoundController into your scene:

import { playSound } from "@decentraland/SoundController"

Play a sound from the scene

You can play a sound directly from your scene. Sounds played in this way are heard as sounding from the center of your scene. This is a good way to handle ambience and general notification sounds that don’t need to have a specific source.

executeTask(async () => {
  try {
    await playSound("mySound", "sounds/wind_blowing.mp3", {
      volume: 100
    })
  } catch {
    log("failed to play sound")
  }
})

The src property points to the location of the sound file.

In the example above, the audio file is located in a sounds folder, which is located at root level of the scene project folder.

Tip: We recommend keeping your sound files separate in a /sounds folder inside your scene.

Loop a sound

To keep a sound playing in a continuous loop, set the loop field to true. This is useful for adding background music or other background sounds.

Setting loop to false stops the audio, it doesn’t pause it. So when setting loop to true again, the audio sample will start from the beginning.

executeTask(async () => {
  try {
    await playSound("mySound","sounds/wind_blowing.mp3", {
      loop: true,
      volume: 100
    })
  } catch {
    log("failed to play sound")
  }
})

Pause a sound

To pause a sound that was playing, simply use pauseSound(), calling the sound by the name you provided in the arguments.

executeTask(async () => {
  try {
    await pauseSound("mySound")
})