It's easy to add audio into your 3D scenes using the web editor UI. But the awe.js API also gives you the power to add and control sounds through custom Javascript. This guide gives you a simple example of how to get started.

It's important to note that all mobile browsers require at least one user gesture (e.g. a tap) before any audio can be played. This is to prevent abuse of autoplay media by advertisers.

Your awe project automatically handles this and if the .play() request fails it shows a modal to prompt the user to tap the screen which then unlocks your media playback.

If you are loading audio manually via your own custom Javascript then you will need to handle any failures when you call .play().

One way you can add your sound file into your scene is as an audio projection. Upload your audio file to your media library under the audio tab and then select use to place it into your scene. Then you can get your sound object directly from the projection itself.

var projection = awe.projections.view(YOUR_PROJECTION_ID);
my_sound = projection.sound();

Audio projections allow you to add spatialized sound so you can control where the sound appears to be coming from by moving it around within your scene. This adjusts the stereo levels to create the illusion that the playing sound is in a specific location relative to the listener.

To load and play audio programmatically via the awe API just add a sound file to your media library (as above) then get it's URL.

Then use code like this to load your audio.

awe.sounds.add({ id:'YOUR_AUDIO_ID_HERE', autoplay:false, path:'YOUR_URL' });

Once sounds are created you can access them through the standard awe API. If you know the id then you can grab that directly.

var my_sound = awe.sounds.view('YOUR_AUDIO_ID_HERE');

If you only have one then you can just grab that easily.

var my_sound = awe.sounds.list()[0];

Or you can loop through these and look for items that have a .path that matches your asset id e.g.

var my_asset_id = 12345;
var my_sound;
awe.sounds.list().forEach(function(sound) {
  if (sound.get_data().path.match("/file/assets/"+my_asset_id+"-")) {
    my_sound = sound;
  }
});

To play it again just call .play()

my_sound.play();

To pause it again just call .pause()

my_sound.pause();

To resume it again just call .resume()

my_sound.resume();

Or to stop it just call .stop()

my_sound.stop();

You can choose to create, play and pause your audio via an Action.

You can choose to create, play, pause and mute your audio via custom javascript fired by an Action.

There's a range of ways you can access and control your audio via the awe projection too.

• projection.is_audio() This returns true if the projection is an audio projection.
• projection.mute() This applies to both audio and video projections. It mutes the audio and, or video asset.
• projection.unmute() This applies to both audio and video projections. It unmutes the audio and, or video asset.
• projection.toggle_mute() This applies to both audio and video projections. It toggles the mute state of the audio and, or video asset.
• projection.play(options) This applies to both audio and video projections. It starts the playback of the audio and, or video asset.
  • options = { start_at: float } The options object and start_at key are optional. If not supplied, plays from current position or from the start if not played yet.
• projection.pause() This applies to both audio and video projections. It pauses the playback of the audio and, or video asset.
• projection.toggle_play() This applies to both audio and video projections. It resumes playback of audio or video from current position.

Or if you have a sound related to a projection then you can access it directly from there too.

var projection = awe.projections.view(YOUR_PROJECTION_ID);
Object.keys(projection.action_sounds].forEach(function(action_id) {
  my_sound = projection.action_sounds[action_id];
  // use controls like .play() and .stop() to control the sound here
});

This should give you a good idea of how easy it is to add and control audio using custom Javascript and the awe.js API.