Skip to content

Latest commit

 

History

History
153 lines (106 loc) · 8.37 KB

API.md

File metadata and controls

153 lines (106 loc) · 8.37 KB
Raw

Akko v0.1.0 API reference

Table of contents:

new Akko([options])

Creates a new instance of Akko. A single page can have multiple instances of Akko running at the same time, although this is not recommended. Example usage:

let options = {
    autoPlay: true,
};
let akko = new Akko(options);
akko.addTrack('https://<your-website>/music.mp3');
akko.start();

The optional options object defines Akko's behaviour. Available options:

Property Description Type Default
containerId ID of the element to which Akko's <canvas> and UI will be appended. String 'akko'
useDefaultVisualisers If you only want to use custom visualisers, you can tweak this setting to disable Akko's default visualisers out-of-the-box. Boolean true
autoPlay Automatically start playing the first track (if it's available) as soon as .start() method is called. Boolean false

Methods

.start()

Starts the instance. This method bootstraps Akko's Preact UI, enables its visualisation core and music player, and sets up event listeners.

.addVisualiser(visualiser)

  • visualiser - Instance of Akko.Visualiser.

Adds a visualiser to the current Akko instance. Users can switch between all available visualisers using the controls on Akko's canvas.

Visualiser instances cannot be shared by multiple Akko instances, so make sure to create brand new instance of a Visualiser for every Akko instance.

.addTrack(source[, title])

  • source - An instance of File or ArrayBuffer, or a string representing the URL of an audio file.
  • title (optional) - Title of the track as it will be shown in the track list.

Adds a track to the music player. If this method is called after .start() the player will automatically play the newly added track once it's loaded. If no title was specified, the title is extracted from the filename. If source is an ArrayBuffer, the default title is Untitled.

Akko.visualisers

Object defining default visualisers. Available visualisers: BarVisualiser, RingVisualiser. Example usage:

let akko = new Akko({useDefaultVisualisers: false});
akko.addVisualiser(new Akko.visualisers.RingVisualiser());
akko.addVisualiser(new Akko.visualisers.BarVisualiser());
akko.start();

Akko.Visualiser

Abstract class defining a visualiser. Should be extended when creating custom visualisers. Example usage in ES6:

class MyVisualiser extends Akko.Visualiser {
    constructor() {
        super({
            code: 'Mv',
            name: 'My Visualiser!',
            fftSize: 128,
            smoothingTimeConstant: 0.5,
        });
    }
    onInit(data) { /* ... */ }
    onUpdate(data) { /* ... */ }
    onDestroy(data) { /* ... */ }
    onResize(data) { /* ... */ }
    onPause(data) { /* ... */ }
    onRevive(data) { /* ... */ }
}

let akko = new Akko({useDefaultVisualisers: false});
akko.addVisualiser(new MyVisualiser());
akko.start();

Constructor

new Akko.Visualiser(options)

  • options
    • options.code - A 2 character long string to be used a shorthand for visualiser's name.
    • options.name - The name of this visualiser, will be displayed in the visualiser selection menu.
    • options.fftSize - Current visualiser's desired fftSize for Web Audio API AnalyserNode.
    • options.smoothingTimeConstant - Current visualiser's desired smoothingTimeConstant for Web Audio API AnalyserNode.

Should be called as super(options) in your code (see example above). fftSize and smoothingTimeConstant will be applied to the AnalyserNode every time the visualiser is initialised or revived, only need to declare them here.

Abstract methods (must be overridden)

.onInit(data)

  • data
    • data.renderer - Instance of three.js WebGLRenderer. Shared by all visualisers.
    • data.analyser - Instance of Web Audio API AnalyserNode. Handles audio analysis. Shared by all visualisers.
    • data.width - Current width of the <canvas> as an integer.
    • data.height - Current height of the <canvas> as an integer.

Called once when the visualiser is selected for the first time. This method should setup your THREE.Scene, THREE.Camera and any other relevant variables. You can also adjust data.renderer settings to match your desired setup.

.onUpdate(data)

Called 30 times every second (i.e. 30 FPS) while your visualiser is active. This method should be used to update the graphics of your visualiser to match the music.

.onDestroy()

Called on all visualisers when the instance of Akko is destroyed. This method should free any objects you were using, clear all timeouts, etc. The purpose of this method is to make sure that the visualiser can be garbage collected.

Instance methods (can be overridden)

.onResize(data)

  • data
    • data.renderer - Instance of three.js WebGLRenderer. Shared by all visualisers.
    • data.analyser - Instance of Web Audio API AnalyserNode. Handles audio analysis. Shared by all visualisers.
    • data.width - Current width of the <canvas> as an integer.
    • data.height - Current height of the <canvas> as an integer.

Called every time Akko's container element is resized. This method should adjust the aspect ratio of your cameras and perform any other relevant tweaks. Note that this does not necessarily correlate with the window being resized, because Akko can be used as an inline element.

onResize() is also called every time the visualiser is initialised or revived.

.onPause()

Called every time Akko switches from your visualiser to some other visualiser. Once this method is called, you no longer have control over the visualisation process so make sure to clear any timeouts and put your visualiser into the 'idle' mode.

.onRevive(data)

  • data
    • data.renderer - Instance of three.js WebGLRenderer. Shared by all visualisers.
    • data.analyser - Instance of Web Audio API AnalyserNode. Handles audio analysis. Shared by all visualisers.
    • data.width - Current width of the <canvas> as an integer.
    • data.height - Current height of the <canvas> as an integer.

Called every time Akko switches from some other visualiser to your visualiser, given it has already been initialised. I.e. the first time your visualiser is selected, onInit(data) is called, but all subsequent activations will call onRevive(data). This method should change data.renderer to your desired setup and make any other relevant tweaks.