Add THREE.AudioLoader

[EvilPeanut]

I have added THREE.AudioLoader to asynchronously load an AudioBuffer and provide callbacks for onLoad, onProgress and onError. Related issues: #8176, #8367.

The THREE.AudioLoader depreciates THREE.AudioBuffer and THREE.Audio's .load, I have added depreciation messages to the old functions.

I have also made a documentation page for THREE.AudioLoader which is included.

Here is an example how THREE.AudioLoader can be used to load and play a sound once loaded

// instantiate a listener
var audioListener = new THREE.AudioListener();

// add the listener to the camera
camera.add( audioListener );

// instantiate audio object
var oceanAmbientSound = new THREE.Audio( audioListener );

// add the audio object to the scene
scene.add( oceanAmbientSound );

// instantiate a loader
var loader = new THREE.AudioLoader();

// load a resource
loader.load(
    // resource URL
    'audio/ambient_ocean.ogg',
    // Function when resource is loaded
    function ( audioBuffer ) {
        // set the audio object buffer to the loaded object
        oceanAmbientSound.setBuffer( audioBuffer );

        // play the audio
        oceanAmbientSound.play();
    },
    // Function called when download progresses
    function ( xhr ) {
        console.log( (xhr.loaded / xhr.total * 100) + '% loaded' );
    },
    // Function called when download errors
    function ( xhr ) {
        console.log( 'An error happened' );
    }
);

[Mugen87]

Hi Reece! Can you also adjust the following sound showcase in the three.js example directory? Some of the code would be deprecated after your changes.

Example:

var sound1 = new THREE.PositionalAudio( listener );
sound1.load( 'sounds/358232_j_s_song.ogg' );

Besides, it's maybe a good idea to place the deprecated code into Three.Legacy.js. The actual source files are more clear then.

[Mugen87]

Do you think there is a way to use THREE.AudioLoader in THREE.AudioBuffer .load to provide backwards compatibility? It would be good if THREE.AudioBuffer and THREE.Audio .load are still working after your changes (even when they are deprecated).

[EvilPeanut]

@Mugen87 Thanks for your suggestions :) I will update the example now and add THREE.AudioLoader in the deprecated functions

[EvilPeanut]

@Mugen87 My latest commits should tackle your suggestions

[Mugen87]

Looks good! After studying at your changes, i realize that the code in THREE.AudioBuffer is not necessary after all. So i think we can remove it and just log the warnings. Before doing that, we should consider some other opinions 😉

@mrdoob What do you think about @EvilPeanut's implementation? Using THREE.AudioLoader in this way would make THREE.AudioBuffer obsolet. I assume THREE.AudioBuffer is more an internal entity of THREE.Audio and not used by users of the library. Do you think we can remove it?

[Mugen87]

@EvilPeanut One more thing 😉. Can you add THREE.AudioLoader to utils/build/includes/common.json (see here)? If you don't do this, THREE.AudioLoader won't be part of the build.

[EvilPeanut]

@Mugen87 Added it :)

[mrdoob]

Seems like you removed the space in function () { in a bunch of places. Do you mind reverting that?

[EvilPeanut]

I'll change that now. Sorry for these little mistakes. It is my first time contributing :).

I have tried to follow the contribution guidelines though and used http://zz85.github.io/mrdoobapproves/ which is why I removed the spaces, is it an issue with the site?

[mrdoob]

It is an issue with the site indeed.
@zz85 do you mind addressing this?

[mrdoob]

@mrdoob What do you think about @EvilPeanut's implementation? Using THREE.AudioLoader in this way would make THREE.AudioBuffer obsolet. I assume THREE.AudioBuffer is more an internal entity of THREE.Audio and not used by users of the library. Do you think we can remove it?

Sounds good to me 😊

[EvilPeanut]

@mrdoob @Mugen87 I have removed THREE.AudioBuffer and added back the removed whitespace 😃

[mrdoob]

Looks good!

[mrdoob]

Thanks!

[mrdoob]

FYI I've added THREE.AudioContext. That way we don't have pass the audio context around... e207eb5