Provides an object, and class methods, that allows a sound file to be played and rendered as a frequency/amplitude waveform, through use of the Web Audio API, with visual indication of the state of play.
There are two ways to use the code: directly from JavaScript, or through HTML5 dataset attributes.
In each case, specific DOM elements are replaced with the graph, either as a canvas or image element.
HTML API / Basic Use
Once this library, and MooTools, have been included, a graph with default settings can be generated by defining a CSS class for its display, and attaching that class to a DOM element. Size and colour settings are extracted from the DOM container and applied to the canvas that is added in its place. The location of the sound file must be specified in the DOM element's data-uri
attribute:
<style>
.pcmimg {
background: orange;
color: white;
width:500px;
height:100px;
border:1px solid black
}
</style>
<div class='pcmimg' data-uri='pluck.wav'></div>
Any PcmImage option that can be supplied via the JavaScript API can be supplied via markup, by supplying the option as an attribute with the data-
prefix. Such options are specified below, and are in lowercase, not camelcase, for this reason.
The automatic application of the substitution to the DOM is handled by PcmImage.parseDOM(selector)
. The selector
is, by default, .pcmimg
.
JavaScript API
document.addEvent('domready', function(){
new PcmImage( {
element: document.id('soundtest-gradient'),
uri: 'pluck.wav',
pauseorjump: 'pause', // Or jump
step: 256,
playable: true,
overlayclr: 'pink', // #abc #123456 red rgba(129,129,0,127)
asimg: true,
strokestyle: 'black', /* foreground colour, defaults to options.element's CSS 'color' */
background: 'lime',
linewidth: 1,
onXhrError: function(){ throw 'XHR Error getting '+this.options.uri },
onNoBufferError: function(){
throw 'Error decoding file data from '+self.options.uri;
},
onCanvasLoaded: function(){
var gradient=this.cctx.createLinearGradient(0,0, 100, 0);
gradient.addColorStop("0","magenta");
gradient.addColorStop("0.5","blue");
gradient.addColorStop("1.0","red");
this.options.strokeStyle = gradient;
}
});
});
element
(string): 'id' of, or reference to, a DOM element to hold the graph.
uri
(string): Address of the sound file to process.
pauseorjump
(pause
or jump
): When graph is clicked, the sound will pause, or jump to the clicked time.
asimg
(boolean): If true, the 'canvas' element on which the graph is drawn will be converted to a standard 'img' element, to allow the user to save the created image.
strokestyle
(string): Supplied to the canvas context to set the foreground colour. Default is to use the value of the color
style setting of the element
.
background
(string): Supplied to the canvas context to set the background color. Defaul tis to use the backgroundColor
style setting of the element
.
overlayclr
(CSS colour value): Any valid CSS colour (hex, rgb, etc). Overlaid when image played
updateinterval
(float): Graph overlay update frequency in milliseconds
fftsize
(number) FFT bin size. (Small=slow and detailed.) An unsigned long value representing the size of the Fast Fourier Transform to be used to determine the frequency domain. It must be a non-zero power of 2 in the range between 512 and 2048, included; its default value is 2048. If not a power of 2, or outside the specified range, the exception INDEX_SIZE_ERR is thrown. https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode
frequencyby
(average
or max
): calculate frequency colour by the average frequency in the FFT bin, or that with the greatest amplitude.`
saturation
(number): HSL saturation value for the wave form frequencies.
lightness
(number): HSL lightness value for the wave form frequencies.
linewidth
(number): Supplied to the canvas context, defaults to 1.
asimg
(boolean): Replace canvas with image.
playable
(boolean): Can the graph be clicked to play?
onXhrError
(code reference): Fires if an error is encounted fetching the sound file from uri
.
onNoBufferError
(code reference): Fires is the data fetched from uri
is invalid/non-existent.
onCanvasLoaded
(code reference): Called after the sound file has been loaded, and the canvas object created, but before rendering begins. Can be used to set rendering options, or to over-ride previously supplied, as in the 'gradient' example in Demo/index.html
.
onRendered
(code reference): Called after the rendering of the waveform. Default behaviour is to call
colourFrequencies()
to colour the waveform based on frequency analysis, but that can be slow for large files,
on slower machines, and unreliable on some clients.
Make frequency colouring optional.
Frequncy colouring.
Updated to replace the noteGrain*
methods with the new start
/stop
methods.