AudioChart

Allows the user to explore charts on web pages using sound and the keyboard rather than, or in conjunction with, visually and with the mouse. The code can easily be added to any page containing charts.

Thanks to The Paciello Group for allowing me to share this with you, and to The Sonification Handbook for the research behind it.

AudioChart uses the Web Audio API, which has great support amongst browsers, including Microsoft Edge, though is not (yet) supported by Internet Explorer.

Use Cases and Examples

What does it let your users do?

What sort of charts/data does it work with?

The examples gallery covers using AudioChart with Google Charts, JSON and HTML tables.

"Hello, World" Tutorial (using Google Charts)

You can check out the finished "hello, world" HTML file. Note that you can also use AudioChart with JSON and HTML tables (there are examples to demonstrate this).

Google Charts Bits

More details on this can be found in the Google Charts documentation.

  1. Load the Google Charts API.

    <script src="https://www.google.com/jsapi"></script>
  2. Have an element in your document to contain the chart.

    <div id="chart"></div>
  3. Instantiate the Google Charts API and hook it up to a function to draw the chart when the page has loaded (you could put this code in a <script> element in your document's <head>, for example).

    google.load('visualization', '1.0', {'packages':['corechart']});
    google.setOnLoadCallback(draw_chart);
    
    function draw_chart() {
    		. . .
    }

    The rest of the JavaScript code goes inside draw_chart().

  4. Create a Google Charts API DataTable and populate it with some data.

    var data = new google.visualization.DataTable();
    
    data.addColumn('string', 'Top Secret Evil Project');
    data.addColumn('number', 'Watermelons');
    data.addRows([
    		['Alpha',   293],
    		['Beta',    329],
    		['Gamma',   261],
    		['Delta',   130],
    		['Epsilon', 196],
    		['Zeta',    196],
    ]);

    Note that there are other ways to add data to DataTable objects; the AudioChart examples include a sine wave, generated by code, and the DataTable documentation gives other approaches.

  5. Prepare chart options and create a Google Charts API chart.

    var chart_options = {
    		'title': 'Evil Project Efficacy',
    		'width': 800,
    		'height': 450,
    		'curveType': 'function'
    };
    
    var chart = new google.visualization.LineChart(document.getElementById('chart'));
    chart.draw(data, chart_options);

AudioChart Bits

  1. Load AudioChart.

    <script src="https://raw.githubusercontent.com/matatk/audiochart/gh-pages/lib/audiochart.min.js"></script>
  2. Create an element in your document to trigger audio playback.

    <button id="play">Play</button>
  3. Wire up the button, data table and chart to AudioChart; include the following code in draw_chart(). The chart is passed in so that AudioChart can visually highlight the chart data points during playback (this is optional).

    document.getElementById('play').onclick = function() {
    		new AudioChart({
    				'type': 'google',      // (see the docs)
    				'data': data,          // the GoogleDataTable
    				'chart': chart,        // the Google Chart object
    				'duration': 5000,      // milliseconds
    				'frequency_low': 200,  // Hz
    				'frequency_high': 600  // Hz
    		});
    }

Other Chart Types and Options

The REFERENCE details all the options you can pass to AudioChart.

Components

The following objects are present in AudioChart (JavaScript code).

Development

A Gruntfile is provided to run the tests and automate things like linting and minification. Unit tests can be run in-browser or via the Gruntfile, printing output to the terminal. You can also view the test coverage details.

Development is carried out in a test-driven manner. The pre-commit hook can be used to ensure only code that passes tests is committed. You can make a symlink from the .git/hooks/ directory to it and thus it (and the tests) will be run before you are asked for a commit message.

Setting up for development

The build process uses Grunt and therefore also Node. You can get set up for development as follows (most of these instructions require the use of a command line).

  1. Install Node (if you're a Mac user doing this via Homebrew is recommended: brew install node).
  2. Install Grunt globally via npm -g install grunt-cli in order to be able to run the grunt command in any directory.
  3. Get AudioChart's code by using git clone https://github.com/matatk/audiochart.git or downloading a ZIP of the latest code.
  4. Locally install AudioChart's dependencies by running npm install in the newly-cloned/extracted audiochart/ directory (the packages will be stored inside node_modules/).
  5. Running grunt will lint the code, run the tests and make a minified production version.

Windows users: this has not yet been extensively tested on Windows, but it doesn't use anything platform-specific, so should work fine.

Hosting the AudioChart Site and Examples Locally

You can use Jekyll to host the AudioChart site locally and run the in-browser tests. It is recommended to use Bundler to manage the gems on which Jekyll depends.

On the Mac, having your own Ruby install, e.g. from Homebrew, can keep things clean: brew install ruby gives you a ruby that is separate to the stock OS X one. You'll need to start a new shell session before /usr/local/bin/ruby and /usr/local/bin/gem will supersede the system ones.

To get up-and-running with Jekyll via Bundler, follow these steps.

  1. gem install bundler will grab the gem-management tool.
  2. bundle install when you are in the audiochart/ repository/code directory will use the Gemfile and Gemfile.lock to ensure you have a compatible set of gems -- currently this is particularly targeted at ensuring the site will work on GitHub Pages with Jekyll.
  3. bundle exec jekyll serve will perpetually (re-)generate and serve the site locally. Changes to files will be reflected when you reload a page in the browser.

Windows users: Jekyll is not officially supported on Windows, but the developers provide some documentation on installing and using Jekyll on Windows.

Future Work Ideas

Patches for and feedback on the following are welcome!