func-midi-visualizer

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

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