Skip to content

Doidel/webaudiox

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

85 Commits
build
build
 
 
examples
examples
 
 
lib
lib
 
 
MIT-LICENSE.txt
MIT-LICENSE.txt
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
TODO.md
TODO.md
 
 

Repository files navigation

webaudiox.js is a bunch of helpers for WebAudio API. It isn't a library per se. You can use any of those helpers independantly. This makes it very light to include these in your own code. There is a webaudiox.js provided though. This is for convenience. It is just the concatenation of all the helpers.

Usage

Here is a boilerplate, a good example to start with. It initializes the AudioContext, the lineOut and downloads a sound.

<script src='webaudiox.js'></script>
<script>
	// create WebAudio API context
	var context	= new AudioContext()

	// Create lineOut
	var lineOut	= new WebAudiox.LineOut(context)

	// load a sound and play it immediatly
	WebAudiox.loadBuffer(context, 'sound.wav', function(buffer){
		// init AudioBufferSourceNode
		var source	= context.createBufferSource();
		source.buffer	= buffer
		source.connect(lineOut.destination)
		
		// start the sound now
		source.start(0);
	});
</script>

Installation

Download the helpers with a usual <script>. the easiest is to get webaudiox.js in /build directory.

<script src='webaudiox.js'></script>

bower is supported if it fit your needs. just use bower install webaudiox

Requirements

No real requirements: there are no external dependancies. Well WebAudio API must be available obviously :) Currently Chrome, Firefox, iOS and Opera support it.

Contributings

Feel free to send pull requests. i love little helpers which are useful :)

ChangeLogs

  • v1.0.1 bower support
  • you can try with bower install webaudiox
  • v1.0.0 initial release

Plugins

  • webaudiox.ConvolverHelper is a plugin by @erichlof . It provides a simple mean to use convolvers, thus you can simulate being thru an old telephone, in a hall, or in a tunnel.

API for Each Helpers

Here is all the helpers provided and their respective API. the source contains a jsdoc which is authoritative.

webaudiox.bytetonormalizedfloat32array.js

This helpers converts a byteArray to a normalized Float32Array. The destination Array is normalized because values are garanted to be between 0 and 1. It works even if the destination array has a different value than the source array. It is useful when playing with frequency spectrum.

Show Don't Tell

Usage

WebAudiox.ByteToNormalizedFloat32Array(srcArray, dstArray);
// bytesFreq is from a analyser.getByteFrequencyData(bytesFreq)
// histogram is destination array, e.g. new Float32Array(10)
WebAudiox.ByteToNormalizedFloat32Array(bytesFreq, histogram)

webaudiox.analyser2canvas.js

This helpers displays various visualisation of the played sound, the one analysed by analyser. It display a FFT histogram, a waveform, and a volume. It is there mainly for debug.

Show Don't Tell

Usage

First you create the object

var analyser2canvas	= new WebAudiox.Analyser2Canvas(analyser, canvas);

Then every time you want to draw on the canvas do

analyser2canvas.update()

webaudiox.analyser2volume.js

This helper makes an average on a ByteFrequencyData from an analyser node. clear ? :) In brief, it makes an fft to extract the frequency of the sound, all that in real time. It is often used to detect pulse in some frequency range. like detecting pulse in the low frequencies can be a easy beat detector.

Show Don't Tell

Usage

// create the object
var analyser2Volume	= new WebAudiox.Analyser2Volume(analyser)
var rawVolume		= analyser2Volume.rawValue()
var smoothedVolume	= analyser2Volume.smoothedValue()

It is possible to directly compute the raw volume.

var rawVolume	= new WebAudiox.Analyser2Volume.compute(analyser, width, offset);
// rawVolume is a Number of the computed average

width is optional and default to analyser.frequencyBinCount. offset is optional and default to 0.

webaudiox.lineout.js

This helper provides a main line out with the good practices from "Developing Game Audio with the Web Audio API" on html5rocks. So it provides a clipping detection and a dynamic compressor to reduce clipping to improve sound quality.

Additionaly it provides some tools useful in real-life cases. Such as the ability for the user to mute the sound. Its is useful when the user is at the office or any place where it isn't polite to have a loud computer :) Another thing, there is a muteIfHidden feature. so if the browser tab is hidden, the sound is mute using PageVisibility API. and obviously ability to tune the volume globally for all sounds.

Show Don't Tell

Now let's see it's API

create a lineOut

var lineOut	= new WebAudiox.LineOut(context)

to set the volume/gain

lineOut.volume	= 0.8;

To connect a sound to your lineOut

use lineOut.destination as you would use context.destination.

source.connect(lineOut.destination)

test if currently muted by user

if( lineOut.isMuted === true ){
	console.log('sound has been muted by user')
}

toggle mute status

typically when the user click on the mute button, you want to toggle the mute status.

lineOut.toggeMute()

webaudiox.shim.js

This helper does a shim which handle the vendor prefix, so you don't have to. Typically it contains code like

window.AudioContext	= window.AudioContext || window.webkitAudioContext;

Show Don't Tell

webaudiox.jsfx.js

jsfx.js is a library to generate procedural sound, very 8-bit kindof sound. See jsfx demo page for details on this fun library by @egonelbre. It is usefull because you can generate lots of different sound easily without downloading anything.

Show Don't Tell

Usage

Here is a usage example

// create the audio context 
var context	= new AudioContext()
// parameter for jsfx.js - http://www.egonelbre.com/js/jsfx/
var lib		= ["square",0.0000,0.4000,0.0000,0.3200,0.0000,0.2780,20.0000,496.0000,2400.0000,0.4640,0.0000,0.0000,0.0100,0.0003,0.0000,0.0000,0.0000,0.0235,0.0000,0.0000,0.0000,0.0000,1.0000,0.0000,0.0000,0.0000,0.0000]
var buffer	= WebAudiox.getBufferFromJsfx(context, lib)

webaudiox.loadbuffer.js

This helper loads sound. It is a function which load the sound from an url and decode it.

Show Don't Tell

Usage

WebAudiox.loadBuffer(context, url, function(buffer){
	// notified when the url has been downloaded and the sound decoded.
}, function(){
	// notified if an error occurs
});

Scheduling Download

In real-life cases, like game, you want to be sure all your sounds are ready to play before the user start playing. So here is way to schedule your sound downloads simply. There is global onLoad callback WebAudiox.loadBuffer.onLoad This function is notified everytime .loadBuffer() load something. you can overload it to fit your need. here for an usage example.

// context is the webaudio API context
// url is where to download the sound
// buffer is the just loaded buffer
WebAudiox.loadBuffer.onLoad = function(context, url, buffer){
	// put your own stuff here	
	// ... 
}

Additionally there is WebAudiox.loadBuffer.inProgressCount. it is counter of all the .loadBuffer in progress. it useful to know is all your sounds as been loaded.

webaudiox.three.js

This is useful lf you have a three.js scene and would like to play spacial sound in it. When a sound is played in 3d space, there are 2 actors: the listener which hears the sound and the sound source which emits the sound. Each of them must be localised in 3d space.

In practice when you use it with three.js you need to constantly update the position of the listener and all the sound sources. First in your init, you instance the updater objects. Then at each iteration of your rendering loop, you update all the positions.

Show Don't Tell

Usage

Here is the API details.

listener localisation

First let's localise the listener. most of the time it will be the the viewer camera. So you create a ListenerObject3DUpdater for that

// context is your WebAudio context
// object3d is the object which represent the listener
var listenerUpdater = new WebAudiox.ListenerObject3DUpdater(context, object3d)

then you call .update() everytime you update the position of your object3d listener.

// delta is the time between the last update in seconds
// now is the absolute time in seconds
listenerUpdater.update(delta, now)

sound source localisation

Now let's localise a sound source. A sound source is localised only if it has a panner node.

if you want a sound to follow a Object3D

So you create a PannerObject3DUpdater for that

// panner is the panner node from WebAudio API
// object3d is the object which represent the sound source in space
var pannerUpdater = new WebAudiox.PannerObject3DUpdater(panner, object3d)

then you call .update() everytime you update the position of your object3d listener

// delta is the time between the last update in seconds
// now is the absolute time in seconds
pannerUpdater.update(delta, now)

if you want a sound to be played at a given position

var panner	= context.createPanner()
var position	= new THREE.Vector3(1,0,0)
WebAudiox.PannerSetPosition(panner, position)

if you want a sound to be played from a THREE.Object3D

var panner	= context.createPanner()
var object3d	= new THREE.Object3D
WebAudiox.PannerSetObject3D(panner, object3d)

Other Examples

here are the various examples:

  • a possible way to handle soundback: here
  • how to get a track from sound cloud: here
  • how to load and play a sound only with the API: here
  • how to use it with beatdetektor.js: here
  • how load and play a sound with webaudio api raw. no helper at all: here

TODO

About

helpers for WebAudio API

jeromeetienne.github.io/webaudiox

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

2 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%