Untitled

📰Getting Started | ⭐**Updates |** 📝 Guides | 🔢 API | ❓FAQ

Guides Overview

The Audio API is available on any Element whose Asset contains an audio clip. It's recommended to use a null check to ensure all instances of your script have their dependencies.

if (!this.audio) {
    log.error('Asset missing audio support!');
return;
}

Controlling Playback

A visible Element containing audio can be started and stopped using play and stop.

this.audio.play();

this.audio.stop();

Modifying Properties

These are the most commonly used audio properties.

// Volume
this.audio.volume = 0.5;

// How "3D" the audio is. 3D audio is surround and will get quieter as you get further from it.
// Set to 0 for 2D sound that can be heard from anywhere.
this.audio.spatialBlend = 0.0;

// Whether or not the audio should loop
this.audio.loop = true;

// Mute
this.audio.mute = true;

// whether or not the audio should play when the element becomes visible
this.audio.playOnAwake = true;

// the channel of the audio. See Setting Channel in Script for what to provide here.
this.audio.channel = "music";

Audio Mixing and Channels

If you include this line in any script:

// {[AM:audioMixing]}

You’ll find that an audio mixing UI appears in the inspector. This will let you modify some of the most used properties. (anything else can be modified in script)

image.png

You might notice the “Audio Channel” dropdown.

Enklu includes a simple audio mixing system split into a number of pre-set channels.

If you go to Scene > Audio Settings in the left sidebar, you will be able to change the volume, compression, and gain of any of the available channels.

image.png

If you use the script-enabled UI above to set a channel, the sound settings you’ve applied in Audio Settings will be applied to that asset. By extension, the Audio Settings will be applied to all audio assets that have set a channel!

Use the above to group different sounds and music into groups, and then apply global audio settings over them to achieve a nice mix for your experience.

<aside> 💡

Tip: for making most voices audible: bring down compression significantly and turn up gain.

</aside>

Setting Channel in Script

To set a channel in script, pay attention to how the script enabled UI changes the channel property in the element’s schema, and set it accordingly. Generally, the names are the same but in lowercase.

this.audio.channel = "environment";

You can even directly set it via schema.

this.schema.setString("channel", "music");

Audio Settings in Script

There are currently no specific functions to modify the global Audio Settings in scripts, but this can be achieved by modifying schema.

You might notice that all audio properties result in some changes to the element’s schema in the Advanced tab.

All mixing settings are stored in the root element’s schema, and will be modified in real time as those schema values change. Look at the advanced tab to see what is there. You will need to make modifications to audio settings of specific channels to see the schema populate.

Then, you can use the App API to get the root element, and then modify schema to set Audio Settings programatically.

var all = app.scenes.all;
var mainScene = app.scenes.root(all[0]); // this will give the scene you see in the Web Editor

mainScene.schema.setNumber("audio.sfx.volume", 5);

Tween Integration

Tweening can be used to modify volume over time.

const tween = require('tween');

var twnVolume = tween.number(this, 'audio.volume')
    .from(0)
    .to(1)
    .duration(10);
twnVolume.start();

Instance Properties

length <number>

The length of the audio source in seconds.

isPlaying <bool>

If the audio source is currently playing or not.

volume <number>

The volume of the audio source (0.0 to 1.0).

loop <bool>

Whether or not the audio source should loop.

mute <bool>

Mutes or unmnutes the audio source. Mute sets the volume to 0.0. Unmuting restores the previous volume.

playOnAwake <bool>

Whether or not the audio source will automatically start playing on awake.

spatialBlend <float>

How much the audio source is affected by 3D spatialization. 0.0 is full 2D; 1.0 is full 3D.

minDistance <float>

Within the minimum distance, the sound will no longer grow louder.

maxDistance <float>

The maximum distance to which the audio source will attenuate.

dopplerLevel <float>

The doppler scale for the audio source.

hangTime <float>

The amount of time processing should hold at a dB level.

Instance Methods

play()

Plays the audio source.

stop()

Stops playback on the audio source.

mapLevelFloat(element, schemaKey, minDb, maxDb, minVal, maxVal)

Maps output level to a schema float value of an element.

unmapLevelFloat(element, schemaKey)

Removes output level to schema key mapping.

mapLevelVec3(element, schemaKey, minDb, maxDb, minVal, maxVal)

Untitled