JavaScript Audio Control API

README.md

Audio Control API

Control audio with this slick api for controlling one or many audio tracks at simultaneously.

Audio methods

Audio.play(number:volume)

This method plays the audio track from the current position (default position if not set is 0, the beginning)

Audio.pause()

This method pauses the audio track.

Audio.toggle()

This method toggles between the play and pause methods. It will pause if it is playing and play if it is paused.

Audio.stop()

This method stops the audio track and sets the position back to the beginning.

Audio.setVolume(number:volume)

This method sets the volume of the audio track. The volume parameter is a percentage of complete volume: a value from 0 to 100.

Audio.setPosition(number:position)

This method sets the position of the audio track. The position parameter is a 'double' representing seconds in the track.

Audio.setRate(number:rate)

This method sets the rate at which the audio track is played. The default rate value is 1. Anything lower than one makes it slower, likewise anything higher than 1 makes it faster.

Audio.load(string:filePath)

This method loads a different audio track from the file in the path specified. The filePath parameter must be a path to an audio file that exists or none of these audio methods will work.

Audio.reload()

This method reloads the already loaded audio file. This can be used as a kind of refresh. It will in fact completely reload the original audio file, making a network call.

Audio.setLoop(bool:on)

This method sets the boolean value of whether or not the audio track should loop back to the beginning when it reaches the end.

Audio.seamlessLoop(number:fadeLength)

This method starts a seamless loop. The fadeLength parameter is a number representing the number of seconds it should use to fade back into itself and fade into at the beginning.

A seamless loop fades into the audio track and then proceeds to play seamlessly. The track will only be seamless if the audio file doesn't contain any silence at the beginning or end of the file. The track MUST be more than two times longer than the fadeLength used. NOTE: this is meant to be used for ambient sound files not music or short clips of sound effects.

Audio.stopSeamlessLoop()

This method is the proper way to stop a seamless loop. If you use the stop method it will most likely not completely stop and odd behaviour may occur. If you want to stop the seamless loop less abruptly you can use the fadeOutSeamlessLoop method.

Audio.fadeOutSeamlessLoop(number:fadeLength)

This method is for fading out the seamless loop. This method is a good alternative for stopSeamlessLoop seeing as it stops it after fading it out, giving a more seamless feel.

Audio.toggleSeamlessLoop()

This function will fade a seamless loop in or out depending on its previous state.

Audio.fadeIn(number:fadeLength,function:finished)

This method fades in the audio track. The fadeLength parameter is a number representing the duration of the effect in seconds. NOTE: the track must being longer than the number of seconds given for the fadeIn effect. The optional parameter 'finished' is a callback function for when the audio track is finished fading in.

Audio.fadeOut(number:fadeLength,function:finished)

This method fades out the audio track. The fadeLength parameter is a number representing the duration of the effect in seconds. NOTE: the track must being longer than the number of seconds given for the fadeOut effect. The optional parameter 'finished' is a callback function for when the audio track is finished fading out.

Audio.fadeOutAtEnd(number:fadeLength,function:started,function:finished)

This method will wait to fade out until it reaches the end of the audio track. Specifically, it will start fading the audio track out when the track is as many seconds away from the end as the fadeLength that is specified. In this way, you can think of the fadeLength acting as a "startFade" parameter, being both the duration of the effect and the specified beginning of the effect itself. In other words: when the track's current position is equal to the end of the track minus the fadeLength, the fade effect will begin.

The optional parameter 'started' is a callback function for when the audio track has started fading out. The optional parameter 'finished' is a callback function for when the audio track is finished fading out.

Audio Gallery

The audio gallery object gives you the ability to manage a group of audio tracks.

Syntax: AudioGallery(audioTracks, rootPath)

The audio gallery constructor has two parameters: audioTracks and rootPath

audioTracks: is an object containing audio track names and file paths. rootPath: is an optional parameter that allows you to set a root path that will be appended to all file paths in the audio gallery. So if you have all of your audio files in a directory called "audio", you would want to set the rootPath to "audio/".

Example:

var ag = new AudioGallery({
  birdSounds: "animals/birdSounds.wav",
  rainSounds: "lightRain.mp3",
  thunderSound: "thunder.mp3"
}, "audio/");

Gallery.play(string:name, number:vol, bool:only)

This method plays the given audio track. The name parameter is the name of the audio track to play. The vol parameter is the number value of the volume, going from 0 (off) to 100 (as loud as possible). The default volume value is 100. If the optional 'only' parameter is set to true then only this track will play and all other tracks will be stopped.

Gallery.pause(string:name)

This method pauses the given audio track.

Gallery.toggle(string:name)

This method toggles the given track between playing is pausing.

Gallery.stop(string:name)

This method stops the given track. (See Audio.stop() )

Gallery.stopAll()

This method stops all audio tracks in this gallery.

Gallery.toggleSeamlessLoop(string:name, number:fadeLength)

This method toggles a seamless loop for the given audio track, using the provided fadeLength.

Gallery.playRandom()

This method will randomly play an audio track in the gallery from the beginning. If the audio track it selects to play is already playing it will stop it first.

audio.js

function Audio(name, url) {

  // Declare
  var media = this;
  media.name = name || "untitled";
  media.url = url || "";
  media.state = 0; // 0 = pause, 1 = playing
  media.loopState = 0; // 0 = not playing, 1 = playing

  // Init
  var element = document.createElement("AUDIO");
  element.src = media.url;
  element.style.display = "none";
  element.id = media.name;
  document.body.appendChild(element);
  media.element = document.getElementById(media.name);

  //Methods
  media.play = function (vol) {
    media.volume = vol || 1;
    media.element.play();
  };
  media.pause = function () {
    media.element.pause();
  };
  media.toggle = function () {
    if (media.state) {
      media.element.pause();
    } else {
      media.element.play();
    }
    media.state = media.state == 1 ? 0 : 1;
  }
  media.reload = function () {
    media.element.load();
  };
  media.load = function (src) {
    if (src) {
      media.element.setAttribute("src", src);
    }
    media.element.load();
  };
  media.stop = function () {
    media.element.pause();
    media.element.currentTime = 0;
  };
  media.setLoop = function (loop) {
    if (loop) {
      media.element.setAttribute("loop", loop);
    } else {
      media.element.removeAttribute("loop");
    }
  };
  media.seamlessLoop = function (fadeLength) { // in seconds
    if (!media.loopCopy) {
      media.loopCopy = new Audio(media.name + "Copy", media.url);
    }
    media.loopCopy.stop();
    media.stop();
    media.loopCopy.stop();
    media.loopSelection = 0;

    function SL() {
      if (!!media.loopSelection) {
        media.loopSelection = 0;
        media.loopCopy.fadeIn(fadeLength - 1);
        media.loopCopy.fadeOutAtEnd(fadeLength, SL);
      } else {
        media.loopSelection = 1;
        media.fadeIn(fadeLength - 1);
        media.fadeOutAtEnd(fadeLength, SL);
      }
    }
    SL();
  };
  media.stopSeamlessLoop = function () {
    media.stop();
    media.loopCopy.stop();
  };
  media.fadeOutSeamlessLoop = function (fadeLength) {
    if (media.loopSelection) {
      media.loopCopy.stop();
      clearInterval(media.fadeOutListener);
      media.fadeOut(fadeLength);
    } else {
      media.stop();
      clearInterval(media.loopCopy.fadeOutListener);
      media.loopCopy.fadeOut(fadeLength);
    }
  };
  media.toggleSeamlessLoop = function (fadeLength) {
    if (media.loopState) {
      media.fadeOutSeamlessLoop(fadeLength);
    } else {
      media.seamlessLoop(fadeLength);
    }
    media.loopState = media.loopState == 1 ? 0 : 1;
  };
  media.fadeIn = function (fadeLength, finished) {
    var playing = false;
    media.stop();
    media.setVolume(0);
    var fader = setInterval(function () {
      if (!playing) {
        media.element.play();
        playing = true;
      }
      if (media.element.currentTime < fadeLength) {
        try {
          media.element.volume += 1 / (fadeLength * 100);
        } catch (e) {
          finished && finished();
          clearInterval(fader);
        }
      } else {
        finished && finished();
        clearInterval(fader);
      }
    }, 10);
  };
  media.fadeOutAtEnd = function (fadeLength, started, finished) {
    var fadingOut = false;
    media.fadeOutListener = setInterval(function () {
      function end() {
        if (finished) {
          finished();
        }
        media.stop();
        clearInterval(media.fadeOutListener);
      }
      var currentTime = media.element.currentTime,
        length = media.element.duration;
      if (currentTime <= length) {
        if (currentTime >= length - fadeLength) {
          if (!fadingOut) {
            fadingOut = true;
            if (started) {
              started();
            }
          }
          if (media.element.volume > 0) {
            try {
              media.element.volume -= 1 / (fadeLength * 100);
            } catch (e) {
              end();
            }
          } else {
            end();
          }
        }
      } else {
        end();
      }
    }, 10);
  };
  media.fadeOut = function (fadeLength, finished) {
    clearInterval(media.fadeOutListener);
    media.fadeOutListener = setInterval(function () {
      function end() {
        finished && finished();
        media.stop();
        clearInterval(media.fadeOutListener);
      }
      if (media.element.volume > 0) {
        try {
          media.element.volume -= 1 / (fadeLength * 100);
        } catch (e) {
          end();
        }
      } else {
        end();
      }
    }, 10);
  };
  media.setPosition = function (n) {
    media.element.currentTime = n;
  };
  media.setVolume = function (percent) {
    media.element.volume = percent * 0.01;
  };
  media.setRate = function (rate) {
    media.element.playbackRate = rate;
  };
}

function AudioGallery(audio, root) {

  // Delcare
  var gallery = this;
  gallery.audio = {};
  gallery.root = root || false;

  // Init
  for (var name in audio) {
    gallery.audio[name] = new Audio(name, (root && root || "") + audio[name]);
  }

  // Methods
  gallery.play = function (name, vol, only) {
    if (only) {
      gallery.stopAll();
    }
    gallery.audio[name].play(vol);
  };
  gallery.pause = function (name) {
    gallery.audio[name].pause();
  };
  gallery.toggle = function (name) {
    gallery.audio[name].toggle();
  };
  gallery.stop = function (name) {
    gallery.audio[name].stop();
  };
  gallery.stopAll = function () {
    for (var name in gallery.audio) {
      gallery.audio[name].stop();
    }
  };
  gallery.toggleSeamlessLoop = function (name, fadeLength) {
    gallery.audio[name].toggleSeamlessLoop(fadeLength);
  };
  gallery.playRandom = function () {
    var audio = Object.keys(gallery.audio);
    var audioFile = gallery.audio[
      audio[
        Math.floor(Math.random() * audio.length)
      ]
    ];
    audioFile.stop();
    audioFile.play();
  }
}