Audio5js

The HTML Audio Compatibility Layer

Audio5js is a Javascript library that provides a seamless compatibility layer to the HTML5 Audio playback API, with multiple codec support and a Flash-based MP3 playback fallback for older or unsupported browsers.

The motivation for creating Audio5js is to provide a light-weight, library-agnostic, Javascript-only interface for audio playback in the browser.

Quick Demo

Engine: html. Codec: mp3

Getting Started

Audio5js requires two components to properly work: the Javascript library itself and the MP3 Flash fallback SWF file.

Simply download the source code, extract, and place both files somewhere in your project. For the purpose of demonstration, let's assume your project directory structure looks like this:

            /  -/public  --/js  --- audio5.js  --/swf  --- audio5js.swf                  

Now, you can include the Javascript in your HTML, and instantiate the Audio player.

By default, Audio5js will look for the MP3 fallback SWF under /swf/audio5js.swf

            <script src="/js/audio5.js"></script>  <script>    function initAudio () {      var audio5js = new Audio5js({        ready: function () {          this.load('/someaudio.mp3');          this.play();        }      });    }    initAudio();  </script>                  

Audio Codec Support

Audio codec browser-support is a mess. It's more than likely that you'd like to play the same audio in different formats to support a wider crowd.

Luckily, Audio5js can cleverly determine which audio codec is supported by the browser, and initialize itself with the most suitable playback engine, while letting you know which engine (HTML or Flash) it's using and which codec is supported.

To enable multiple codec support, pass an array of codec strings to the codecs array of the settings object in order of precedence. Upon initialization, Audio5js will call the ready callback function in the settings object, passing it an object containing the playback engine type (HTML or Flash) and the selected codec.

By default, Audio5js will only use MP3 as a playback codec, and if no other suitable codec is supported by the browser, it wil select MP3 as a playback codec and use either Flash or HTML as the underlying playback engine.

            var audio5js = new Audio5js({    swf_path: './swf/audio5js.swf',    codecs: ['mp4', 'vorbis', 'mp3'],    ready: function(player) {      var audio_url;      switch (player.codec) {      case 'mp4':        audio_url = '/audio/song.mp4';        break;      case 'vorbis':        audio_url = '/audio/song.ogg';        break;      default:        audio_url = '/audio/song.mp3';        break;      }      this.load(audio_url);      this.play();    }  });                  

Playback API

Audio5js lets you control the life-cycle of audio playback with the following API:

• load - Load an audio file to the player
• play - Play loaded audio
• pause - Pause playing audio
• playPause - Toggle audio play / pause
• volume - Get / Set audio volume
• seek - Seek audio to time

You should note the following when using the playback API:

• Volume values range from 0 to 1.
• Seek values are should be passed as seconds of total audio duration.

            <a id="play">Play / Pause</a>  <a id="seek">Move to Start</a>  <script>    var play = document.getElementById('play');    var seek = document.getElementById('seek');    var playPause = function () {      this[this.playing ? 'pause' : 'play']();      // or simply call this.playPause();    }    var moveToStart = function () {      this.seek(0);      this.volume(1);    }    var audio5js = new Audio5js({      ready: function () {        this.load('/audio/song.mp3');        play.addEventListener('click',          playPause.bind(this));        seek.addEventListener('click',          moveToStart.bind(this));      }    });  </script>                  

Playback Events

Being a good citizen of the Javascript world, Audio5js provides some useful events that you can subscribe to when implementing your shiny audio player.

• canplay - triggered when enough audio is buffered for playback to begin. Analogue to HTML5 Audio canplay event.
• play - triggered when the audio begins playing. Analogue to HTML5 Audio play event.
• pause - triggered when the audio is paused. Analogue to HTML5 Audio pause event.
• ended - triggered when the audio playback has ended. Analogue to HTML5 Audio ended event.
• error - triggered when the audio load error occurred. Analogue to HTML5 Audio error event.
• timeupdate - triggered when the audio playhead position changes (during playback). Analogue to HTML5 Audio timeupdate event.
• progress - triggered while audio file is being downloaded by the browser. Analogue to HTML5 Audio progress event.

To subscribe to an event triggered by Audio5js, you can use the on method. Similarly, to unsubscribe from an event, you can use the off method.

            var audioReady = function () {    //this points to the Audio5js instance    this.on('play', function () {      console.log('play');    }, this);    this.on('pause', function () {      console.log('pause');    }, this);    this.on('ended', function () {      console.log('ended');    }, this);    // timeupdate event passes audio    // duration and position to callback    this.on('timeupdate', function (position, duration) {      console.log(duration, position);    }, this);    // progress event passes load_percent to callback    this.on('progress', function (load_percent) {      console.log(load_percent);    }, this);    //error event passes error object to callback    this.on('error', function (error) {      console.log(error.message);    }, this);  }  var audio5js = new Audio5js({    ready: audioReady  });                  

RequireJS & Ender.js

You can use Audio5js with RequireJS.

            require(["audio5.min"], function (Audio5js) {    var audio5js = new Audio5js({});  });                  

You can use Audio5js with Ender.js.

            $ ender add audio5  // As a global package  var Audio5js = require('audio5');  var audio5js = new Audio5js({    swf_path: 'node_modules/audio5/swf/audio5js.swf'  });  // Or via Ender client  var audio5 = new $.audio5({    swf_path: 'node_modules/audio5/swf/audio5js.swf'  });                  

Source Code & Documentation

Audio5js is freely available on Github along with a more detailed documentation and complete code comments.

Feel free to fork, add, fix and send me pull requests, or open issues in the project's issue tracker on Github.

Demos

• Angular.js by @altryne
• SoundCloud by @gryzzly

Feel free to add more demos by forking and adding them to the demos folder.