norns-web API docs

back to demo

Getting Started

norns-web provides three ES modules that mirror the monome norns Lua APIs for use in the browser:

• midi — virtual MIDI bus
• softcut — 6-voice sample player/recorder (Web Audio)
• screen — 128×64 pixel display (Canvas 2D)
• clock — coroutine-based clock system for tempo-synced scheduling

Basic script structure

import midi from "./lib/midi.js";
import softcut from "./lib/softcut.js";
import screen from "./lib/screen.js";

// Initialize screen (pass a <canvas> element)
screen.init(document.getElementById("norns-screen"));

// Initialize audio (must be called from a user gesture)
const ctx = new AudioContext({ sampleRate: 48000 });
await softcut.init(ctx);

// Your script's redraw loop
function redraw() {
  screen.clear();
  screen.level(15);
  screen.move(10, 10);
  screen.text("hello norns-web");
  screen.update();
  requestAnimationFrame(redraw);
}
redraw();

Scripts directory

On hardware norns, scripts live in ~/dust/code/. In norns-web, place scripts in a scripts/ directory and register them in scripts/index.json:

norns-web/
├── lib/
│   ├── midi.js
│   ├── softcut.js
│   ├── screen.js
│   └── script-loader.js
├── scripts/
│   ├── index.json         ← manifest of available scripts
│   ├── my-script.js       ← your scripts go here
│   └── another-script.js
├── index.html
└── docs.html

Manifest format (scripts/index.json)

[
  {
    "name": "my-script",
    "description": "A brief description shown in the launcher",
    "file": "my-script.js"
  }
]

Scripts listed in the manifest appear in the dropdown on the main page. You can also drag and drop any .js file onto the drop zone to run it without adding it to the manifest.

Each script is an ES module that imports from ../lib/. See the script template below.

midi

import midi from "./lib/midi.js"

Software-only virtual MIDI bus. Up to 16 ports. Ports can be wired together for internal routing.

Module functions

Global callbacks

Port object

Routing

Send methods

All channel (ch) params are 1-based (1–16), defaulting to 1.

Example

const a = midi.connect(1);
const b = midi.connect(2);
a.wire(b);

b.event = (data) => {
  const msg = midi.to_msg(data);
  console.log(msg); // {type:"note_on", note:60, vel:100, ch:1}
};

a.note_on(60, 100, 1);

softcut

import softcut from "./lib/softcut.js"

6-voice sample player/recorder with 2 mono buffers (~350 seconds each at 48 kHz). Backed by an AudioWorklet.

Initialization

Voice control

All voice params are 1-based (1–6).

Recording

Buffer operations

Phase polling

Example

await softcut.init();

// Play a loop
softcut.enable(1, 1);
softcut.buffer(1, 1);
softcut.level(1, 0.8);
softcut.rate(1, 1.0);
softcut.loop(1, 1);
softcut.loop_start(1, 0);
softcut.loop_end(1, 2.0);
softcut.position(1, 0);
softcut.play(1, 1);

// Record with overdub
softcut.enable(2, 1);
softcut.buffer(2, 2);
softcut.rec(2, 1);
softcut.rec_level(2, 1.0);
softcut.pre_level(2, 0.5);  // keep 50% of previous
softcut.play(2, 1);

screen

import screen from "./lib/screen.js"

128×64 pixel display with 16 brightness levels (0–15), matching the norns OLED. Double-buffered: draw calls accumulate on an offscreen canvas, then screen.update() copies to the visible canvas.

Initialization

Drawing state

Path operations

Shapes

Text

Transforms & state

Pixel access

Canvas setup

The canvas internal resolution is always 128×64. Scale it up with CSS for visibility:

<canvas id="norns-screen"></canvas>

<style>
  #norns-screen {
    width: 512px;    /* 4x scale */
    height: 256px;
    image-rendering: pixelated;
    background: #000;
  }
</style>

<script type="module">
  import screen from "./lib/screen.js";
  screen.init(document.getElementById("norns-screen"));
</script>

Example

function redraw() {
  screen.clear();

  // Gradient bar
  for (let i = 0; i <= 15; i++) {
    screen.level(i);
    screen.rect_fill(i * 8, 0, 7, 10);
  }

  // Circle
  screen.level(15);
  screen.circle(64, 32, 12);
  screen.stroke();

  // Text
  screen.level(10);
  screen.font_size(8);
  screen.move(2, 54);
  screen.text("norns-web");

  screen.update();
  requestAnimationFrame(redraw);
}
redraw();

clock

import clock from "./lib/clock.js"

Coroutine-based clock system matching the norns Lua API. Provides tempo-synced scheduling via clock.run(), clock.sync(), and clock.sleep(). Local-only implementation (no network Link peers).

Coroutines

The norns clock.run() uses Lua coroutines. In norns-web, we use async functions + AbortController:

Tempo & beat queries

Clock source

Internal clock

Link (local-only)

These match the norns Link API signatures but operate locally (no network peers).

Transport callbacks

MIDI clock output

Example

import clock from "../lib/clock.js";

// Set tempo and start transport
clock.internal.set_tempo(128);
clock.internal.start();

// Run a coroutine that fires every beat
const id = clock.run(async () => {
  while (true) {
    await clock.sync(1); // every beat
    console.log("beat!", clock.get_beats());
  }
});

// Run another at sixteenth notes
clock.run(async () => {
  while (true) {
    await clock.sync(1/4);
    // trigger a note, advance a sequencer step, etc.
  }
});

// Change tempo later
clock.internal.set_tempo(140);

// Stop a specific coroutine
clock.cancel(id);

// Or stop everything
clock.cleanup();

Script template

Save this as scripts/my-script.js:

import midi from "../lib/midi.js";
import softcut from "../lib/softcut.js";
import screen from "../lib/screen.js";
import clock from "../lib/clock.js";

// -- state --
let counter = 0;

// -- init --
export async function init(canvas, audioCtx) {
  screen.init(canvas);
  await softcut.init(audioCtx);

  // set up MIDI
  const port = midi.connect(1);
  port.event = (data) => {
    const msg = midi.to_msg(data);
    console.log("midi:", msg);
  };

  // set up clock
  clock.internal.set_tempo(120);
  clock.internal.start();
  clock.run(async () => {
    while (true) {
      await clock.sync(1);
      // do something every beat
    }
  });

  // set up softcut voices, load buffers, etc.
  // ...

  // start redraw loop
  redraw();
}

// -- redraw (called at ~60fps) --
function redraw() {
  screen.clear();
  screen.level(15);
  screen.move(10, 10);
  screen.text("my script");
  screen.level(8);
  screen.move(10, 24);
  screen.text(`frame: ${counter++}`);
  screen.update();
  requestAnimationFrame(redraw);
}

// -- cleanup --
export function cleanup() {
  midi.cleanup();
  clock.cleanup();
  softcut.reset();
}

Load it from HTML:

<script type="module">
  import { init } from "./scripts/my-script.js";

  document.getElementById("start").addEventListener("click", async () => {
    const ctx = new AudioContext({ sampleRate: 48000 });
    await init(document.getElementById("norns-screen"), ctx);
  });
</script>