JS API Reference

Script Template

/**
 * @name My Mode
 * @author Your Name
 * @hue 32
 * @sat 220
 * @param_label Motion
 * @description One-line summary shown in the web UI.
 * @tags Tilt, Generative
 * @sound Warm pluck
 */

var state = 0;

function activate(m) {
  state = 0;
  m.clear();
  m.show();
}

function update(m) {
  // Called every frame. Draw pixels and trigger notes here.
  m.show();
}

// Optional:
// function deactivate(m) {}

Metadata Tags

Tag Guide

Use up to four tags that describe how the script behaves. Tags are shown in the script library and drive the tag filter.

Example: @tags Tilt, MIDI in, Physics, Humidity

m Properties

Grid Reference

m.px(col, row, ...) uses col 0 on the left and row 0 at the top.

Accelerometer Patterns

// Slow tilt smoothing
var smooth = 0;
smooth += (m.accelY - smooth) * (m.dt / 8000.0);

// Motion knock detection
if (m.motion > 150 && lastMotion <= 150) {
  // fires once per knock
}
lastMotion = m.motion;

Pixel Functions

MIDI Functions

degree maps through the active scale and root. Degree 0 is the selected root MIDI note exactly; degrees 0-6 span one octave diatonically and 7-13 continue into the next.

MIDI In

Incoming USB and DIN MIDI messages are available each frame via read-once properties, filtered by the mode's selected MIDI In channel.

function update(m) {
  if (m.midiType === 1) {
    var col = Math.floor(m.midiNote * m.COLS / 128);
    // spawn something at col
  }
  m.show();
}

Clock Mode

Timing And Helpers

Practical Rules

• Call m.show() exactly once per update(), at the end.
• Script globals persist while the mode is active. Reset them in activate().
• Use m.dt for movement so speed is frame-rate independent.
• Use m.tick() for rhythmically stable events.
• Clamp unusually large m.dt or m.beatMs before using them in physics or divisions.
• Avoid startup note storms and cap note output in physics-heavy modes.
• Use current API names only: m.dt, m.beatMs, and m.px().
• Avoid browser-only APIs like setTimeout(), document, window, and fetch().