midi-visualizer

A simple, functional-based midi visualization library

Example

const initMidiVisualizer = import 'midi-visualizer';
const config = {
  window: window,
  root: document.getElementById('#my-root'),
  width: 500,
  height: 500,
  midi: {
    data: myFnToFetchMidiData()
  },
  audio: {
    data: myFnToFetchAudioData()
  },
  renderer: setupMyCustomRenderer()
};

initMidiVisualizer(config).then((visualizer) => {
  const playingVisualizer = visualizer.play();
  // all your other fun operations...
}).catch((error) => console.error('Oh man, something bad happened:', error));

API Reference

midiVisualizer

Monad managing visualization animation of midi data

• midiVisualizer
  • ~restart(playheadSec) ⇒
  • ~pause() ⇒
  • ~stop() ⇒
  • ~resize() ⇒

midiVisualizer~restart(playheadSec) ⇒

put MidiVisualizer into "play" state

Kind: inner method of midiVisualizer
Returns: MidiVisualizer

| Param | Type | Description | | --- | --- | --- | | playheadSec | number | offset in seconds to start playback |

midiVisualizer~pause() ⇒

put MidiVisualizer into "pause" state

Kind: inner method of midiVisualizer
Returns: MidiVisualizer

midiVisualizer~stop() ⇒

put MidiVisualizer into "stop" state

Kind: inner method of midiVisualizer
Returns: MidiVisualizer

midiVisualizer~resize() ⇒

handle resize of page MidiVisualizer is rendering into

Kind: inner method of midiVisualizer
Returns: MidiVisualizer

midi-visualizer : object

Kind: global namespace

midi-visualizer~initMidiVisualizer(config) ⇒ Promise(MidiVisualizer, Error)

initializes MidiVisualizer monad

Kind: inner method of midi-visualizer
Returns: Promise(MidiVisualizer, Error) - promise that fulfills with MidiVisualizer instance

| Param | Type | Description | | --- | --- | --- | | config | object | configuration data to set up MidiVisualizer | | config.midi.data | UInt8Array | array of unsigned 8-bit integers representing Midi data | | config.audio.data | UInt8Array | array of unsigned 8-bit integers representing audio data | | config.window | Window | Window of page holding the player | | config.root | HTMLElement | HTMLElement that will be the root node of the visualizer | | config.render | Renderer | Renderer strategy to use | | config.width | number | the width of our canvans | | config.height | number | the height of our canvans |

RenderUtils

• RenderUtils
  • ~MAX_RAF_DELTA_MS : number
  • ~play(state, player, renderFn, resumeFn) ⇒ RendererState
  • ~pause(state) ⇒ RendererState
  • ~stop(state) ⇒ RendererState
  • ~transformEvents(state, trackTransforms, animEvents) ⇒ Array.<RenderEvent>
  • ~mapEvents(state, midi, config) ⇒ RendererState
  • ~maxNote(currentMaxNote, event) ⇒ number
  • ~minNote(currentMinNote, event) ⇒ number
  • ~isNoteToggleEvent(event) ⇒ boolean
  • ~isNoteOnEvent(event) ⇒ boolean
  • ~render(state, cleanupFn, rafFn, currentRunningEvents, renderEvents, nowMs) ⇒ Array.<RenderEvent>

RenderUtils~MAX_RAF_DELTA_MS : number

Kind: inner constant of RenderUtils
Default: 16

RenderUtils~play(state, player, renderFn, resumeFn) ⇒ RendererState

Put visualizer in "play" state (where audio player is playing and animations are running)

Kind: inner method of RenderUtils
Returns: RendererState - - new monad state

| Param | Type | Description | | --- | --- | --- | | state | RendererState | current monad state | | player | AudioPlayer | audio player used for audio playback we are syncing to | | renderFn | RenderUtils~render | callback for actual rendering | | resumeFn | RenderUtils~resume | callback for resuming playback after stopping |

RenderUtils~pause(state) ⇒ RendererState

Put visualizer in "paused" state (where audio player is paused and animations are not running)

Kind: inner method of RenderUtils
Returns: RendererState - - new monad state

| Param | Type | Description | | --- | --- | --- | | state | RendererState | current monad state |

RenderUtils~stop(state) ⇒ RendererState

Put visualizer in "stopped" state (where audio player is stopped and animations are not running)

Kind: inner method of RenderUtils
Returns: RendererState - - new monad state

| Param | Type | Description | | --- | --- | --- | | state | RendererState | current monad state |

RenderUtils~transformEvents(state, trackTransforms, animEvents) ⇒ Array.<RenderEvent>

Applies given track transforms to animation events

Kind: inner method of RenderUtils
Returns: Array.<RenderEvent> - array of transformed renderEvents

| Param | Type | Description | | --- | --- | --- | | state | RendererState | state monad | | trackTransforms | Array.<function()> | callback functions (TODO: document) | | animEvents | Array.<AnimEvent> | given animation events to transform |

RenderUtils~mapEvents(state, midi, config) ⇒ RendererState

Map over given Midi data, transforming MidiEvents into RenderEvents

Kind: inner method of RenderUtils
Returns: RendererState - - new monad state

| Param | Type | Description | | --- | --- | --- | | state | RendererState | current monad state | | midi | Midi | midi data to map to RenderEvents | | config | object | configuration data |

RenderUtils~maxNote(currentMaxNote, event) ⇒ number

Compare given note with note in given RenderEvent, returning whichever is larger

Kind: inner method of RenderUtils
Returns: number - - largest of two notes

| Param | Type | Description | | --- | --- | --- | | currentMaxNote | number | value of current "max" note | | event | RenderEvent | RenderEvent containing note to compare |

RenderUtils~minNote(currentMinNote, event) ⇒ number

Compare given note with note in given RenderEvent, returning whichever is smaller

Kind: inner method of RenderUtils
Returns: number - - smallest of two notes

| Param | Type | Description | | --- | --- | --- | | currentMinNote | number | value of current "min" note | | event | RenderEvent | RenderEvent containing note to compare |

RenderUtils~isNoteToggleEvent(event) ⇒ boolean

Predicate to test whether given RenderEvent is for a note on/off event

Kind: inner method of RenderUtils
Returns: boolean - - is it a note on/off event

| Param | Type | Description | | --- | --- | --- | | event | RenderEvent | RenderEvent to test |

RenderUtils~isNoteOnEvent(event) ⇒ boolean

Predicate to test whether given RenderEvent is for a note on event

Kind: inner method of RenderUtils
Returns: boolean - - is it a note on event

| Param | Type | Description | | --- | --- | --- | | event | RenderEvent | RenderEvent to test |

RenderUtils~render(state, cleanupFn, rafFn, currentRunningEvents, renderEvents, nowMs) ⇒ Array.<RenderEvent>

render function

Kind: inner method of RenderUtils
Returns: Array.<RenderEvent> - - active running render events for this render call

| Param | Type | Description | | --- | --- | --- | | state | RendererState | monad state | | cleanupFn | function | callback to remove expired animation artifacts | | rafFn | function | RAF callback to do actual animation | | currentRunningEvents | Array.<RenderEvent> | RenderEvents currently being animated | | renderEvents | Array.<RenderEvent> | new RenderEvents to animate | | nowMs | number | current time in milliseconds |

ThreeJsRenderer

• ThreeJsRenderer
  • ~prepDOM(midi, config) ⇒ ThreeJsRendererState
  • ~resize(state, dimension) ⇒ ThreeJsRendererState
  • [~cleanup(state, currentRunningEvents[, expiredEvents) ⇒ undefined
  • ~generateReturnFn(midi, config) ⇒
  • ~generate(renderConfig, frameRenderer, cleanupFn) ⇒ ThreeJsRenderer~generateReturnFn
  • ~frameRenderCb ⇒

ThreeJsRenderer~prepDOM(midi, config) ⇒ ThreeJsRendererState

handles initialization of DOM for renderer

Kind: inner method of ThreeJsRenderer

| Param | Type | Description | | --- | --- | --- | | midi | Midi | Midi instance of song information | | config | object | configuration information | | config.window | Window | Window where rendering will take place | | config.root | HTMLElement | DOM Element that will hold render canvas | | dimension.width | number | width of the rendering area | | dimension.height | number | height of the renderering area |

ThreeJsRenderer~resize(state, dimension) ⇒ ThreeJsRendererState

deals with resizing of the browser window

Kind: inner method of ThreeJsRenderer

| Param | Type | Description | | --- | --- | --- | | state | ThreeJsRendererState | current renderer state | | dimension | object | dimensions of render area | | dimension.width | number | | | dimension.height | number | |

ThreeJsRenderer~cleanup(state, currentRunningEvents[, expiredEvents[) ⇒ undefined

removes any object from the scene

Kind: inner method of ThreeJsRenderer

| Param | Type | Description | | --- | --- | --- | | state | ThreeJsRendererState | current renderer state | | currentRunningEvents[ | RenderEvent | array of RenderEvents currently active | | expiredEvents[ | RenderEvent | array of RenderEvents that are no longer active and should be cleaned up |

ThreeJsRenderer~generateReturnFn(midi, config) ⇒

function returned to user for creating instance of ThreeJsRenderer

Kind: inner method of ThreeJsRenderer
Returns: ThreeJsRenderer

| Param | Type | Description | | --- | --- | --- | | midi | Midi | Midi data to be renderered | | config | object | configuration information | | config.window | Window | Window where rendering will take place | | config.root | HTMLElement | DOM Element that will hold render canvas | | dimension.width | number | width of the rendering area | | dimension.height | number | height of the renderering area |

ThreeJsRenderer~generate(renderConfig, frameRenderer, cleanupFn) ⇒ ThreeJsRenderer~generateReturnFn

generator to create ThreeJsRenderer

Kind: inner method of ThreeJsRenderer

| Param | Type | Description | | --- | --- | --- | | renderConfig | object | configuration information for setup | | frameRenderer | ThreeJsRenderer~frameRenderCb | callback for rendering events | | cleanupFn | cleanupCb | callback for cleaning up THREEJS |

ThreeJsRenderer~frameRenderCb ⇒

callback for actual rendering of frame

Kind: inner typedef of ThreeJsRenderer
Returns: undefined

| Param | Type | Description | | --- | --- | --- | | eventsToAdd[ | ThreeJsRenderEvent | events that are queued up to be rendered in the next frame | | scene | THREEJS~Scene | ThreeJS scene events should be renderered in | | camera | THREEJS~Camera | ThreeJS camera for given scene | | THREE | THREEJS | ThreeJS |

D3Renderer

• D3Renderer
  • ~prepDOM(midi, config) ⇒ D3RendererState
  • ~resize(state, dimension) ⇒ D3RendererState
  • ~generateReturnFn(midi, config) ⇒
  • ~generate(renderConfig) ⇒ D3Renderer

D3Renderer~prepDOM(midi, config) ⇒ D3RendererState

handles initialization of DOM for renderer

Kind: inner method of D3Renderer

| Param | Type | Description | | --- | --- | --- | | midi | Midi | Midi instance of song information | | config | object | configuration information | | config.window | Window | Window where rendering will take place | | config.root | HTMLElement | DOM Element that will hold render canvas | | dimension.width | number | width of the rendering area | | dimension.height | number | height of the renderering area |

D3Renderer~resize(state, dimension) ⇒ D3RendererState

deals with resizing of the browser window

Kind: inner method of D3Renderer

| Param | Type | Description | | --- | --- | --- | | state | D3RendererState | current renderer state | | dimension | object | dimensions of render area | | dimension.width | number | | | dimension.height | number | |

D3Renderer~generateReturnFn(midi, config) ⇒

function returned to user for creating instance of D3Renderer

Kind: inner method of D3Renderer
Returns: D3Renderer

| Param | Type | Description | | --- | --- | --- | | midi | Midi | Midi data to be renderered | | config | object | configuration information | | config.window | Window | Window where rendering will take place | | config.root | HTMLElement | DOM Element that will hold render canvas | | dimension.width | number | width of the rendering area | | dimension.height | number | height of the renderering area |

D3Renderer~generate(renderConfig) ⇒ D3Renderer

generator to create D3Renderer

Kind: inner method of D3Renderer

| Param | Type | Description | | --- | --- | --- | | renderConfig | object | configuration data for renderer | | renderConfig.frameRenderer | frameRenderCb | callback for rendering individual frames |

AudioPlayer

Kind: global class

• AudioPlayer
  • new AudioPlayer(params)
  • instance
    • .getPlayheadTime() ⇒
    • .play([startTimeOffset], [playheadSec])
    • .pause(stopAfter)
  • static
    • .getAudioContextFromWindow(window) ⇒
  • inner
    • ~loadDataCallback : function

new AudioPlayer(params)

manages audio playback

Returns: AudioPlayer

| Param | Type | Description | | --- | --- | --- | | params | object | settings for audio player | | params.window | Window | Window used to retrieve AudioContext |

audioPlayer.getPlayheadTime() ⇒

gets the playhead time in milliseconds

Kind: instance method of AudioPlayer
Returns: playheadTimeMs

audioPlayer.play([startTimeOffset], [playheadSec])

initiates playing of audio

Kind: instance method of AudioPlayer

| Param | Type | Default | Description | | --- | --- | --- | --- | | [startTimeOffset] | number | 0 | offset in seconds to wait before playing | | [playheadSec] | number | 0 | where to start playback within audio in seconds |

audioPlayer.pause(stopAfter)

pauses playing of audio

Kind: instance method of AudioPlayer

| Param | Type | Description | | --- | --- | --- | | stopAfter | number | number of seconds to wait before stopping |

AudioPlayer.getAudioContextFromWindow(window) ⇒

cross-browser fetch of AudioContext from given window

Kind: static method of AudioPlayer
Returns: AudioContext

| Param | Type | Description | | --- | --- | --- | | window | Window | Window to fetch AudioContext from |

AudioPlayer~loadDataCallback : function

loads given audio data and invokes callback when done

Kind: inner typedef of AudioPlayer

| Param | Type | Default | Description | | --- | --- | --- | --- | | audioData | ArrayBuffer | | ArrayBuffer of data for audio to play | | callback | loadDataCallback | | callback to invoke when audioData is finished loading | | [err] | string | null | string of error message (null if no error) | | [self] | AudioPlayer | | ref to AudioPlayer instance if loading successful (undefined otherwise) |

DataTypes

• DataTypes
  • ~MidiVisualizerState
    • new MidiVisualizerState(params)
  • ~RendererState
    • new RendererState(params)
  • ~D3RendererState ⇐ RendererState
    • new D3RendererState()
  • ~ThreeJsRendererState ⇐ RendererState
    • new ThreeJsRendererState()
  • ~AnimEvent
    • new AnimEvent([id])
  • ~RenderEvent
    • new RenderEvent()
  • ~D3RenderEvent ⇐ RenderEvent
    • new D3RenderEvent()
  • ~ThreeJsRenderEvent ⇐ RenderEvent
    • new ThreeJsRenderEvent()

DataTypes~MidiVisualizerState

Kind: inner class of DataTypes

new MidiVisualizerState(params)

top-level data type representing state of MidiVisualizer

Returns: MidiVisualizerState

| Param | Type | Default | Description | | --- | --- | --- | --- | | params | object | | properties to set | | params.audioPlayer | AudioPlayer | | AudioPlayer instance managing audio to sync with | | params.renderer | Renderer | | Renderer used to draw visualization | | [params.animEventsByTimeMs] | object | {} | AnimEvent to render, grouped by millisecond-based mark where they should be rendered | | [params.isPlaying] | boolean | false | flag indicating whether currently playing |

DataTypes~RendererState

Kind: inner class of DataTypes

new RendererState(params)

top-level data type representing state of Renderer

Returns: RendererState

| Param | Type | Default | Description | | --- | --- | --- | --- | | params | object | | properties to set | | params.id | string | | unique identifier for renderer | | params.root | HTMLElement | | HTMLElement to use as root node for renderer canvas placement | | params.window | Window | | Window we are rendering in (note, Window must have a 'document') | | [params.width] | number | 0 | width for rendering canvas | | [params.height] | number | 0 | height for rendering canvas | | [param.renderEvents] | Array.<RenderEvents> | [] | RenderEvents to render | | [params.scales] | Array.<object> | [] | Scales for normalizing position/sizing | | [params.isPlaying] | boolean | false | flag indicating whether currently playing |

DataTypes~D3RendererState ⇐ RendererState

Kind: inner class of DataTypes
Extends: RendererState

new D3RendererState()

data type representing state of Renderer that uses D3

Returns: D3RendererState

| Param | Type | Description | | --- | --- | --- | | params.svg | SVGElement | SVGElement for renderering |

DataTypes~ThreeJsRendererState ⇐ RendererState

Kind: inner class of DataTypes
Extends: RendererState

new ThreeJsRendererState()

data type representing state of Renderer that uses D3

Returns: ThreeJsRendererState

| Param | Type | Description | | --- | --- | --- | | params.THREE | THREEJS | ThreeJs object | | params.camera | Camera | ThreeJs Camera to use | | params.scene | Scene | ThreeJs Scene to use | | params.renderer | Renderer | Renderer monad to use |

DataTypes~AnimEvent

Kind: inner class of DataTypes

new AnimEvent([id])

data type representing individual animation event

Returns: AnimEvent

| Param | Type | Default | Description | | --- | --- | --- | --- | | params.event | MidiEvent | | MidiEvent being renderered | | [params.track] | number | 0 | index of midi track event belongs to | | [params.startTimeMicroSec] | number | 0 | offset in microseconds from beginning of song when event starts | | [params.lengthMicroSec] | number | 0 | length of event in microseconds | | [params.microSecPerBeat] | number | 500000 | number of microseconds per beat | | [id] | string | "<track>-<event.note || startTimeInMicroSec>" | unique ID of event |

DataTypes~RenderEvent

Kind: inner class of DataTypes

new RenderEvent()

base data type representing individual render event

Returns: RenderEvent

| Param | Type | Default | Description | | --- | --- | --- | --- | | params.id | id | | unique string identifier for event | | params.track | number | | index of midi track event belongs to | | params.subtype | string | | midi event subtype | | params.x | number | | x position for element | | params.y | number | | y position for element | | params.lengthMicroSec | number | | length of event in microseconds | | params.microSecPerBeat | number | | number of microseconds per beat | | [params.z] | number | 0 | z position for element | | [params.microSecPerBeat] | number | 500000 | number of microseconds per beat | | [params.color] | string | "'#FFFFFF'" | color of element to render |

DataTypes~D3RenderEvent ⇐ RenderEvent

Kind: inner class of DataTypes
Extends: RenderEvent

new D3RenderEvent()

data type representing individual render event using D3

Returns: D3RenderEvent

| Param | Type | Description | | --- | --- | --- | | [params.path] | string | SVG path string (required if no 'radius' given) | | [params.radius] | number | radius to use for rendering circle (required if no 'path' given) | | [params.scale] | d3.Scale | D3.Scale (required if 'path' is given) |

DataTypes~ThreeJsRenderEvent ⇐ RenderEvent

Kind: inner class of DataTypes
Extends: RenderEvent

new ThreeJsRenderEvent()

data type representing individual render event using ThreeJS

Returns: ThreeJsRenderEvent

| Param | Type | Default | Description | | --- | --- | --- | --- | | [params.scale] | number | 1 | scaling factor | | [params.zRot] | number | 0 | z-rotation | | [params.xRot] | number | 0 | x-rotation | | [params.yRot] | number | 0 | y-rotation | | [params.note] | number | | midi note value (0-127) | | [params.shape] | THREEJS~Object3D | | ThreeJs Object3D of shape representing this event |