How to use

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.

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',
        step:        256,
        playable:    true,
        overlayclr:  'pink', // #abc #123456
        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;
        }
    });
});

Options

element (string): 'id' of, or reference to, a DOM element to hold the graph.

uri (string): Address of the sound file to process.

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.

linewidth (number): Supplied to the canvas context, defaults to 1.

Events

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.

Instantiation of the object creates the image.

Discuss

A note on comments here: These comments are moderated. No comments will show up until they are approved. Comments that are not productive (i.e. inflammatory, rude, etc) will not be approved.

Found a bug in this plugin? Please report it this repository's Github Issues.