Have ideas to improve npm?Join in the discussion! »

    audio2d
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    Logo

    Audio2D

    Audio2D is an easy way to add web audio to your JavaScript game.

    NPM version Known Vulnerabilities npm NPM downloads issues license Gitter

    Table of Contents

    Installation

    To install audio2d, you can use:

    $ npm install audio2d

    and then initialize it like so:

    Current Version

    import { Audio2D } from 'audio2d';

    Pre 1.0.0

    import Audio2D from 'audio2d';

    or you can use it as a script from unpkg like so:

    <script type="module" src="https://unpkg.com/audio2d@latest/audio2d.js"></script>

    A Note About Preloading

    After some thought while creating Audio2D, I decided that it should not offer loading of audio assets.

    I was going to initally offer it as a feature but after trying to figure out signal timing and letting the user know when the audio was loaded and ready to go, it turned into a signal based monstrosity. The great thing is that it doesn't need to be a monstrosity, there are preloaders out there, like musk-ox for example, that offer to load any of your assets for you, including audio buffers which is what Audio2D works with.

    For an example on basic usage with musk-ox, check out the following example:

    const a2d = new Audio2D();
    const muskox = new MuskOx();
     
    muskox.onComplete.add(loaded);
     
    const loaded = () => {
      const levelUpBuffer = muskox.fetch.audioBuffer('level-up');
     
      const levelUp = a2d.addAudio('level-up', levelUp);
     
      levelUp.play();
    }
     
    muskox.load.audioBuffer('level-up', './assets/audio/level-up.m4a');
     
    muskox.start();

    API

    All examples are assumed to be running using existing audio buffers.

    addAudio

    Creates a web audio clip from an AudioBuffer and returns it so you can play it or perform other actions.

    param type description default
    name string The name of the audio clip used to reference it.
    buffer AudioBuffer The buffer of the audio clip.
    options Object
    options.markers Array<Marker> Markers that can define specific points during the audio track that can be played independently of each other.
    options.trigger string An id or classname of a dom element that when clicked will trigger the clip to play.

    examples:

    Creating a basic audio clip with no markers:

    const levelUp = a2d.addAudio('level-up', levelUpBuffer);

    Creating an audio clip with specific markers:

    const sfxMarkers = [
      { name: 'walk', start: 1500, duration: 1000 },
      { name: 'fall': start: 2500, duration: 1500 },
      { name: 'collect-coin': start: 4000, duration: 750 }
    ];
     
    const sfx = a2d.addAudio('sfx', sfxBuffer, { markers: sxfMarkers });

    In the Audio API you can see how to use the markers and play only parts of a track.

    getAudio

    Gets an audio clip added to the media library with addAudio.

    param type description default
    name string The name of the audio clip to get.

    example:

    a2d.addAudio('track1', buffer);
     
    const clip = a2d.getAudio('track1');

    removeAudio

    Removes an audio clip from the media library.

    param type description default
    name string The name of the audio clip to remove.

    example:

    a2d.addAudio('track1', buffer);
     
    a2d.removeAudio('track1');

    removeAllAudio

    Removes all audio clips from the media library.

    example:

    a2d.addAudio('track1', buffer1);
    a2d.addAudio('track2', buffer2);
     
    a2d.removeAllAudio();

    Audio Clip

    The following properties and methods are available to use on audio clips after they have been created with addAudio.

    Audio Clip Properties

    name

    Returns the name of the clip.

    state

    Returns the current state of the clip. These states are either 'STOPPED', 'PLAYING', or 'PAUSED'.

    timesPlayed

    Returns the number of times that this clip has been played.

    currentTime

    Returns the current time of the clip.

    duration

    Returns the duration of the audio clip.

    volume

    Returns the current volume of this clip. This overrides the global volume if one was set.

    volume

    Sets the volume for the clip to use from here on out. The volume provided can be any number from 0-100. This overrides any global volume set.

    param type description default
    vol number The new volume for this clip

    Audio Clip Methods

    addNode

    You can choose to add a web audio node to the clip. Nodes will be connected to each other in the order added with the source always at the start and the gain always at the end of the chain.

    The available nodes are:

    • biquadFilter

    and they can be created through the nodes property on the audio2d instance like so:

    example:

    const track = a2d.addAudio('track-1', track1Buffer);
     
    const bf = a2d.nodes.biquadFilter();
     
    track.addNode(bf);

    After adding nodes, you can then modify the properties of the nodes by the nodes property of the audio clip and the name of the node like so:

    const track = a2d.addAudio('track-1', track1Buffer);
     
    a2d.nodes.biquadFilter();
     
    track.addNode(bf);
     
    // Modifying the biquad filter.
    track.nodes.biquadFilter.Q.value = 100;
    track.nodes.biquadFilter.frequency.value = 1;

    play

    Plays an audio clip fully or at one of the markers.

    param type description default
    marker string The name of the marker to play instead of playing the whole clip. ''

    examples:

    Creating an audio clip and playing it in its entirety:

    const levelUp = a2d.addAudio('level-up', levelUpBuffer);
     
    levelUp.play();

    Creating an audio clip and defining markers to play:

    const sfxMarkers = [
      { name: 'walk', start: 1500, duration: 1000 },
      { name: 'fall': start: 2500, duration: 1500 },
      { name: 'collect-coin': start: 4000, duration: 750 }
    ];
     
    const sfx = a2d.addAudio('sfx', sfxBuffer, { markers: sxfMarkers });
     
    // play just the falling sound.
    sfx.play('fall');

    pause

    Pauses an audio clip.

    example:

    const sfx = a2d.addAudio('sfx', sfxBuffer);
     
    sfx.play();
     
    setTimeout(() => {
      sfx.pause();
    }, 1000);

    resume

    Resumes playing an audio clip from a paused state.

    *example:

    const sfx = a2d.addAudio('sfx', sfxBuffer);
     
    sfx.play();
     
    setTimeout(() => {
      sfx.pause();
     
      setTimeout(() => {
        sfx.resume();
      }, 1000);
    }, 1000);

    stop

    Completely stops the playback of an audio clip and resets it so next time it plays it will play from the beginning.

    example:

    const sfx = a2d.addAudio('sfx', sfxBuffer);
     
    sfx.play();
     
    setTimeout(() => {
      sfx.stop();
    }, 1000);

    seek

    Seeks to a specific time in the clip.

    param type description default
    time number The time, in milliseconds, to seek to.

    example:

    const sfx = a2d.addAudio('sfx', sfxBuffer);
     
    sfx.play();
     
    setTimeout(() => {
      // After a second, we skip to the 12 second mark.
      sfx.seek(12000);
    }, 1000);

    mute

    Mutes an audio clip but saves the previous volume so when its unmuted it will go back to the volume it was before.

    example:

    const sfx = a2d.addAudio('sfx', sfxBuffer);
     
    sfx.play();
    sfx.mute();

    unmute

    Unmutes an audio clip and sets the volume to what it was before it was muted.

    example:

    const sfx = a2d.addAudio('sfx', sfxBuffer);
     
    sfx.play();
     
    sfx.mute();
    sfx.unmute();

    Tests

    The tests for Audio2D are browser based so to run them you will need to use:

    $ npm run test

    and then you'll have to navigate to localhost:8888/test/index.html to see all of the tests run.

    License

    MIT

    Install

    npm i audio2d

    DownloadsWeekly Downloads

    2

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    3.88 MB

    Total Files

    35

    Last publish

    Collaborators

    • avatar