0.1.0 • Published 7 years ago

akko v0.1.0

Weekly downloads
4
License
GPL-3.0
Repository
github
Last release
7 years ago

Akko Music Visualising Framework

npm npm

Music visualising framework based on WebGL and Web Audio API.

This project is still in early development stage, some APIs are likely to change. Please create a new issue if you find any bugs.

Introduction

Akko's main purpose is to make writing music visualisers easy. It defines a robust, standardised framework for the task - you can focus on writing your visualiser without worrying about music playback, controls, or audio analysis. Once you're happy with your visualiser, you can put it into .js file and publish it online for other Akko users to enjoy.

Akko uses WebGL and Web Audio API. This somewhat limits browser support, so you might want to check if it's supported in your browser: here for WebGL and here for Web Audio API.

The graphics component of Akko is based on three.js. This means you'll be using three.js to write your visualisers. There are tons of learning resources online and Akko comes with several default visualisers to help you get started (see lib/visualisers/).

API

See the detailed API reference.

Examples

Akko custom visualiser example

(online demo)

Example Akko setups are located in the examples/ folder. If you have Node.js installed, you can clone this repo then run npm install and npm run examples to start a local server. Alternatively, you could upload clone this repo to your own web server.

If you want to see what a simple Akko visualiser looks like, check out the lib/visualisers/ folder. Examples there are pretty basic, but remember that you have all three.js features at your disposal.

Features

  • Audio playback, analysis and control using Web Audio API.
  • Visualisation framework built on WebGL and three.js.
  • Visualiser selection menu allowing users to switch between multiple visualisers.
  • Simple visualiser abstraction that lets you publish your visualiser and use visualisers developed by others.
  • Real-time playlist allowing users to add tracks by URL, as a file upload or by drag & dropping a file into the visualiser.

Getting started

To try Akko, add it's JS and CSS files, as well as 2 of its external dependencies to your page. You might also have to set the height for Akko's container.

<!-- Akko's dependencies -->
<script src="https://cdn.jsdelivr.net/bluebird/latest/bluebird.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/86/three.min.js"></script>

<!-- Akko files -->
<link rel="stylesheet" href="path/to/akko.min.css"/>
<script src="path/to/akko.min.js"></script>

<!-- Set the height for Akko's container -->
<style>
#akko {
    height: 500px;
}
</style>

Then, inside the <body> of your page, create a <div> container and launch Akko:

<div id="akko"></div>
<script>
    var akko = new Akko();
    akko.start();
</script>

You can now drag & drop an audio file into the visualiser to start playback. You could also use one of the input buttons in the menu in the top left of the screen. See Examples to learn how to define custom visualisers.

Alternatively, if you're using Node.js for your project:

npm install --save akko

Then:

const Akko = require('akko');

Contributing

This project is still in its early development phase, so a lot of things are likely to change. If you want to extend the source code, please create a new issue so we can discuss the changes you want to make before you start.

All of the source code is written in ES6, except for some inline JS in the examples/ directory. For developers' convenience, npm run examples and npm run watch are provided, starting the local dev server and Webpack watchers respectively. When making a pull request, make sure npm run lint returns no errors. Units and integrations tests coming soon.