entangled-worlds-orbiters-shared 2.11.0 → 2.12.0

package/dist/notes/index.d.ts

@@ -0,0 +1,72 @@
+export type NoteEventType = 'on' | 'off';
+export interface NoteEvent {
+    type: NoteEventType;
+    /** Unique per sounding note; an `off` carries the id of the `on` it ends. */
+    id: string;
+    /** MIDI note number, 0 … 127 (integers today; the field allows fractions later). */
+    pitch: number;
+    /** 0 … 1. An `off` may carry a release velocity; nothing reads it yet. */
+    velocity: number;
+    /** Audio-context seconds when it should sound; at or before now means now. */
+    time: number;
+    /** Who sent it: a device, the keyboard, a MIDI effect's slot, a room client. */
+    source: string;
+}
+export declare const NOTE_PITCH_MIN = 0;
+export declare const NOTE_PITCH_MAX = 127;
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export declare function isNoteEvent(value: unknown): value is NoteEvent;
+/** What a channel message means to a note player. Channels are 0 … 15, as on the wire. */
+export type MidiNoteMessage = {
+    kind: 'on';
+    channel: number;
+    pitch: number;
+    velocity: number;
+} | {
+    kind: 'off';
+    channel: number;
+    pitch: number;
+    velocity: number;
+}
+/** Pitch bend, −1 … 1 (0 is the centre). */
+ | {
+    kind: 'bend';
+    channel: number;
+    value: number;
+}
+/** A control change, its value 0 … 1. */
+ | {
+    kind: 'cc';
+    channel: number;
+    controller: number;
+    value: number;
+};
+/** The mod wheel. */
+export declare const MIDI_CC_MOD_WHEEL = 1;
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export declare function decodeMidiMessage(status: number, data1?: number, data2?: number): MidiNoteMessage | null;
+/**
+ * A MIDI note-off names only a channel and a pitch. This gives each held key its note id, so the
+ * off pairs with its on by id like every other source.
+ *
+ * - `on` mints a fresh id. If that key was already held (a device that sends two ons without an off)
+ *   the old note's id comes back as `replaced`, so the caller can end it first: nothing sticks.
+ * - `off` returns the id the key was playing, or null when it was never down (an off arriving after
+ *   a panic, or from before the page listened).
+ * - `releaseDevice` hands back every id a device holds: it went away, and they all end.
+ */
+export interface MidiNoteIds {
+    on(device: string, channel: number, pitch: number): {
+        id: string;
+        replaced: string | null;
+    };
+    off(device: string, channel: number, pitch: number): string | null;
+    releaseDevice(device: string): string[];
+    releaseAll(): string[];
+    /** How many keys are down, across devices. */
+    readonly size: number;
+}
+export declare function createMidiNoteIds(prefix?: string): MidiNoteIds;

package/dist/notes/index.js

@@ -0,0 +1,94 @@
+// Notes as events, shared by every note source (MIDI in, the on-screen keyboard, a capability call, a
+// MIDI effect, a room peer) and everything that routes or sounds them.
+//
+// On and off are separate events with no duration: a live key has no known length when it goes
+// down. They pair by `id`, never by pitch, since two sources can hold the same pitch at once and a
+// chord or an echo plays the same pitch more than once. Pairing by pitch alone gives stuck notes.
+//
+// App-agnostic: nothing here knows about Orbiters, dimensions or the audio graph.
+export const NOTE_PITCH_MIN = 0;
+export const NOTE_PITCH_MAX = 127;
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export function isNoteEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const event = value;
+    return ((event.type === 'on' || event.type === 'off') &&
+        typeof event.id === 'string' &&
+        event.id.length > 0 &&
+        isFiniteNumber(event.pitch) &&
+        event.pitch >= NOTE_PITCH_MIN &&
+        event.pitch <= NOTE_PITCH_MAX &&
+        isFiniteNumber(event.velocity) &&
+        event.velocity >= 0 &&
+        event.velocity <= 1 &&
+        isFiniteNumber(event.time) &&
+        typeof event.source === 'string');
+}
+/** The mod wheel. */
+export const MIDI_CC_MOD_WHEEL = 1;
+const BEND_CENTRE = 8192;
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export function decodeMidiMessage(status, data1 = 0, data2 = 0) {
+    const channel = status & 0x0f;
+    switch (status & 0xf0) {
+        case 0x90:
+            return data2 > 0
+                ? { kind: 'on', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 }
+                : { kind: 'off', channel, pitch: data1 & 0x7f, velocity: 0 };
+        case 0x80:
+            return { kind: 'off', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 };
+        case 0xe0: {
+            // 14 bits, least significant first. The top is 8191 above the centre and the bottom 8192 below
+            // it, so each side is scaled on its own and both ends reach ±1.
+            const raw = ((data2 & 0x7f) << 7) | (data1 & 0x7f);
+            const offset = raw - BEND_CENTRE;
+            return { kind: 'bend', channel, value: offset >= 0 ? offset / (BEND_CENTRE - 1) : offset / BEND_CENTRE };
+        }
+        case 0xb0:
+            return { kind: 'cc', channel, controller: data1 & 0x7f, value: (data2 & 0x7f) / 127 };
+        default:
+            return null;
+    }
+}
+export function createMidiNoteIds(prefix = 'midi') {
+    const held = new Map();
+    let next = 0;
+    const keyOf = (device, channel, pitch) => `${device}\u0000${channel}\u0000${pitch}`;
+    const deviceOf = (key) => key.slice(0, key.indexOf('\u0000'));
+    const take = (predicate) => {
+        const ids = [];
+        for (const [key, id] of held) {
+            if (!predicate(key))
+                continue;
+            ids.push(id);
+            held.delete(key);
+        }
+        return ids;
+    };
+    return {
+        on(device, channel, pitch) {
+            const key = keyOf(device, channel, pitch);
+            const replaced = held.get(key) ?? null;
+            next += 1;
+            const id = `${prefix}:${next}`;
+            held.set(key, id);
+            return { id, replaced };
+        },
+        off(device, channel, pitch) {
+            const key = keyOf(device, channel, pitch);
+            const id = held.get(key) ?? null;
+            held.delete(key);
+            return id;
+        },
+        releaseDevice: (device) => take((key) => deviceOf(key) === device),
+        releaseAll: () => take(() => true),
+        get size() {
+            return held.size;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -42,6 +42,10 @@
       "types": "./dist/capabilities/index.d.ts",
       "import": "./dist/capabilities/index.js"
     },
+    "./notes": {
+      "types": "./dist/notes/index.d.ts",
+      "import": "./dist/notes/index.js"
+    },
     "./studio": {
       "types": "./dist/studio/index.d.ts",
       "import": "./dist/studio/index.js"
@@ -109,10 +113,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:clock": "node --test --import tsx src/clock/*.test.ts",
     "test:capabilities": "node --test --import tsx src/capabilities/*.test.js",
+    "test:notes": "node --test --import tsx src/notes/*.test.ts",
     "test:studio": "node --test --import tsx src/studio/*.test.js",
     "test:uploads": "node --test --import tsx src/uploads/*.test.js",
     "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:capabilities && npm run test:studio && npm run test:uploads && npm run test:render && npm run test:moons && npm run test:star",
+    "test": "npm run test:clock && npm run test:capabilities && npm run test:notes && npm run test:studio && npm run test:uploads && npm run test:render && npm run test:moons && npm run test:star",
     "test:moons": "node --test src/moons/*.test.js",
     "test:star": "node --test --import tsx src/star/*.test.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",

package/src/notes/index.ts

@@ -0,0 +1,146 @@
+// Notes as events, shared by every note source (MIDI in, the on-screen keyboard, a capability call, a
+// MIDI effect, a room peer) and everything that routes or sounds them.
+//
+// On and off are separate events with no duration: a live key has no known length when it goes
+// down. They pair by `id`, never by pitch, since two sources can hold the same pitch at once and a
+// chord or an echo plays the same pitch more than once. Pairing by pitch alone gives stuck notes.
+//
+// App-agnostic: nothing here knows about Orbiters, dimensions or the audio graph.
+
+export type NoteEventType = 'on' | 'off'
+
+export interface NoteEvent {
+  type: NoteEventType
+  /** Unique per sounding note; an `off` carries the id of the `on` it ends. */
+  id: string
+  /** MIDI note number, 0 … 127 (integers today; the field allows fractions later). */
+  pitch: number
+  /** 0 … 1. An `off` may carry a release velocity; nothing reads it yet. */
+  velocity: number
+  /** Audio-context seconds when it should sound; at or before now means now. */
+  time: number
+  /** Who sent it: a device, the keyboard, a MIDI effect's slot, a room client. */
+  source: string
+}
+
+export const NOTE_PITCH_MIN = 0
+export const NOTE_PITCH_MAX = 127
+
+const isFiniteNumber = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export function isNoteEvent(value: unknown): value is NoteEvent {
+  if (!value || typeof value !== 'object') return false
+  const event = value as Record<string, unknown>
+  return (
+    (event.type === 'on' || event.type === 'off') &&
+    typeof event.id === 'string' &&
+    event.id.length > 0 &&
+    isFiniteNumber(event.pitch) &&
+    event.pitch >= NOTE_PITCH_MIN &&
+    event.pitch <= NOTE_PITCH_MAX &&
+    isFiniteNumber(event.velocity) &&
+    event.velocity >= 0 &&
+    event.velocity <= 1 &&
+    isFiniteNumber(event.time) &&
+    typeof event.source === 'string'
+  )
+}
+
+// ── MIDI ────────────────────────────────────────────────────────────────────
+
+/** What a channel message means to a note player. Channels are 0 … 15, as on the wire. */
+export type MidiNoteMessage =
+  | { kind: 'on'; channel: number; pitch: number; velocity: number }
+  | { kind: 'off'; channel: number; pitch: number; velocity: number }
+  /** Pitch bend, −1 … 1 (0 is the centre). */
+  | { kind: 'bend'; channel: number; value: number }
+  /** A control change, its value 0 … 1. */
+  | { kind: 'cc'; channel: number; controller: number; value: number }
+
+/** The mod wheel. */
+export const MIDI_CC_MOD_WHEEL = 1
+const BEND_CENTRE = 8192
+
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export function decodeMidiMessage(status: number, data1 = 0, data2 = 0): MidiNoteMessage | null {
+  const channel = status & 0x0f
+  switch (status & 0xf0) {
+    case 0x90:
+      return data2 > 0
+        ? { kind: 'on', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 }
+        : { kind: 'off', channel, pitch: data1 & 0x7f, velocity: 0 }
+    case 0x80:
+      return { kind: 'off', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 }
+    case 0xe0: {
+      // 14 bits, least significant first. The top is 8191 above the centre and the bottom 8192 below
+      // it, so each side is scaled on its own and both ends reach ±1.
+      const raw = ((data2 & 0x7f) << 7) | (data1 & 0x7f)
+      const offset = raw - BEND_CENTRE
+      return { kind: 'bend', channel, value: offset >= 0 ? offset / (BEND_CENTRE - 1) : offset / BEND_CENTRE }
+    }
+    case 0xb0:
+      return { kind: 'cc', channel, controller: data1 & 0x7f, value: (data2 & 0x7f) / 127 }
+    default:
+      return null
+  }
+}
+
+/**
+ * A MIDI note-off names only a channel and a pitch. This gives each held key its note id, so the
+ * off pairs with its on by id like every other source.
+ *
+ * - `on` mints a fresh id. If that key was already held (a device that sends two ons without an off)
+ *   the old note's id comes back as `replaced`, so the caller can end it first: nothing sticks.
+ * - `off` returns the id the key was playing, or null when it was never down (an off arriving after
+ *   a panic, or from before the page listened).
+ * - `releaseDevice` hands back every id a device holds: it went away, and they all end.
+ */
+export interface MidiNoteIds {
+  on(device: string, channel: number, pitch: number): { id: string; replaced: string | null }
+  off(device: string, channel: number, pitch: number): string | null
+  releaseDevice(device: string): string[]
+  releaseAll(): string[]
+  /** How many keys are down, across devices. */
+  readonly size: number
+}
+
+export function createMidiNoteIds(prefix = 'midi'): MidiNoteIds {
+  const held = new Map<string, string>()
+  let next = 0
+  const keyOf = (device: string, channel: number, pitch: number) => `${device}\u0000${channel}\u0000${pitch}`
+  const deviceOf = (key: string) => key.slice(0, key.indexOf('\u0000'))
+  const take = (predicate: (key: string) => boolean) => {
+    const ids: string[] = []
+    for (const [key, id] of held) {
+      if (!predicate(key)) continue
+      ids.push(id)
+      held.delete(key)
+    }
+    return ids
+  }
+  return {
+    on(device, channel, pitch) {
+      const key = keyOf(device, channel, pitch)
+      const replaced = held.get(key) ?? null
+      next += 1
+      const id = `${prefix}:${next}`
+      held.set(key, id)
+      return { id, replaced }
+    },
+    off(device, channel, pitch) {
+      const key = keyOf(device, channel, pitch)
+      const id = held.get(key) ?? null
+      held.delete(key)
+      return id
+    },
+    releaseDevice: (device) => take((key) => deviceOf(key) === device),
+    releaseAll: () => take(() => true),
+    get size() {
+      return held.size
+    },
+  }
+}