Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A MooTools plugin to simply create PCM waveform graph images from audio files using the Web Audio API
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
Demo
Docs
Source
.gitignore
README.md
package.yml

README.md

PcmImage

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.

Screenshot

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.

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;
        }
    });
});

Options

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?

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.

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.

Screenshots

Screenshot of supplied pluck.wav

0.6 Updates

Make frequency colouring optional.

0.5 Updates

Frequncy colouring.

0.4 Updates

Updated to replace the noteGrain* methods with the new start/stop methods.

Something went wrong with that request. Please try again.