moontide-mcp 2.0.2 → 2.1.0

package/page/index.html

@@ -97,13 +97,14 @@
         <div id="timeline-body" hidden>
           <div id="timeline-ruler"></div>
           <div id="timeline-sections"></div>
-          <div id="timeline-lanes"></div>
+          <div id="timeline-lanes" tabindex="0" role="group" aria-label="Timeline notes"></div>
           <div id="timeline-playhead"><span class="playhead-cycle"></span></div>
         </div>
+        <section id="timeline-note" aria-label="Note" hidden><p id="timeline-note-line" role="status" aria-live="polite"></p></section>
       </div>
       <div id="mixer-view" hidden><p id="mixer-notice" hidden></p><p id="mixer-message" hidden></p><div id="mixer-body" hidden><div id="mixer-strips"></div><div id="mixer-inspector" hidden></div></div><p id="mixer-nonotes" hidden></p></div>
-      <div id="parts-view" hidden><p id="parts-message"></p><button type="button" id="parts-ask" hidden></button><p id="parts-ask-status" hidden></p><div id="parts-rows"></div></div>
-      <div id="jam-view" hidden><div id="jam-message" hidden><p id="jam-message-text"></p><p id="jam-message-sub" hidden></p></div><div id="jam-body" hidden><div id="jam-info"><p id="jam-declared" hidden><span id="jam-declared-label"></span><span id="jam-declared-value"></span></p><div id="jam-scale"><span id="jam-scale-label" hidden></span><h2 id="jam-scale-name"></h2><p id="jam-scale-sub"></p></div><div id="jam-degrees" role="list"></div><div id="jam-status" role="status" aria-live="polite" hidden><p id="jam-status-text"><strong id="jam-status-lead"></strong><span id="jam-status-rest"></span></p><span id="jam-status-time" aria-hidden="true"></span><span id="jam-status-spoken"></span></div><p id="jam-paused" hidden></p><div id="jam-coming"><p id="jam-coming-caption"></p><div id="jam-rows"></div></div></div><div id="jam-instrument"><div id="jam-controls"><div id="jam-instrument-switch" role="group"><button type="button" id="jam-instrument-piano">Piano</button><button type="button" id="jam-instrument-guitar">Guitar</button></div><label id="jam-chord-tones-label"><input type="checkbox" id="jam-chord-tones"> <span id="jam-chord-tones-text"></span></label><div id="jam-legend"><span id="jam-legend-chord" class="jam-legend-entry" hidden></span></div></div><p id="jam-chord" hidden></p><div id="jam-board"><div id="jam-piano" role="img"></div><div id="jam-guitar" role="img" hidden></div></div></div></div></div>
+      <div id="parts-view" hidden><p id="parts-message"></p><button type="button" id="parts-ask" hidden></button><p id="parts-ask-status" hidden></p><div id="song-notes" hidden></div><div id="song-bar" hidden><span id="song-launch-label"></span><div id="song-launch" role="group" aria-labelledby="song-launch-label"></div><p id="song-now" hidden></p></div><p id="song-line" hidden role="status" aria-live="polite"></p><div id="parts-rows"></div><div id="song-cell-list" hidden role="listbox" tabindex="-1"></div></div>
+      <div id="jam-view" hidden><div id="jam-message" hidden><p id="jam-message-text"></p><p id="jam-message-sub" hidden></p></div><div id="jam-body" hidden><div id="jam-info"><p id="jam-declared" hidden><span id="jam-declared-label"></span><span id="jam-declared-value"></span><span id="jam-declared-section" hidden></span></p><div id="jam-scale"><span id="jam-scale-label" hidden></span><h2 id="jam-scale-name"></h2><p id="jam-scale-sub"></p></div><div id="jam-degrees" role="list"></div><div id="jam-status" role="status" aria-live="polite" hidden><p id="jam-status-text"><strong id="jam-status-lead"></strong><span id="jam-status-rest"></span></p><span id="jam-status-time" aria-hidden="true"></span><span id="jam-status-spoken"></span></div><p id="jam-paused" hidden></p><div id="jam-coming"><p id="jam-coming-caption"></p><div id="jam-rows"></div></div></div><div id="jam-instrument"><div id="jam-controls"><div id="jam-instrument-switch" role="group"><button type="button" id="jam-instrument-piano">Piano</button><button type="button" id="jam-instrument-guitar">Guitar</button></div><label id="jam-chord-tones-label"><input type="checkbox" id="jam-chord-tones"> <span id="jam-chord-tones-text"></span></label><div id="jam-legend"><span id="jam-legend-chord" class="jam-legend-entry" hidden></span></div></div><p id="jam-chord" hidden></p><div id="jam-board"><div id="jam-piano" role="img"></div><div id="jam-guitar" role="img" hidden></div></div></div></div></div>
       <div id="instruments-view" hidden tabindex="-1"><p id="instruments-notice" hidden></p><div id="instruments-message" hidden><p id="instruments-message-text"></p><code id="instruments-folder" hidden></code><p id="instruments-message-sub" hidden></p><ul id="instruments-problems" hidden></ul><p id="instruments-message-closing" hidden></p></div><div id="instruments-body" hidden><ul id="instruments-list" role="list" aria-label="Instruments"></ul><p id="instruments-footer"></p></div><span id="instruments-status" role="status" aria-live="polite"></span></div>
     </section>
   </div>

package/page/jam-model.js

@@ -44,6 +44,8 @@ export const JAM_COPY = {
   heardLabel: 'Heard:',
   noFitDeclared: 'The notes fit none of the nine scales.',
   heardUnclearLabel: 'The heard scale is not clear.',
+  // The muted words after the Declared value of a piece with sections: the section whose harmony the line shows.
+  declaredSection: 'section {section}',
   declaredReasons: {
     'not-const': 'Not readable: harmony is declared with let or var; the page reads only const.',
     computed: 'Not readable: harmony is computed ({source}); the page reads only written text.',
@@ -473,9 +475,13 @@ function statusOf(position, paused) {
  * (even an unreadable declaration) no sentence says 'No clear scale', and a reading with no pitched note is a ready
  * model of kind 'none' instead of the message model, so the Declared line stays on screen. The heard scale, the
  * degrees, the status, the rows and the instrument roles are the ones of the same notes without a declaration.
+ * A piece with sections shows the harmony of the section that plays: `declaredOverride` (the same shapes as a reading's
+ * `declared`) replaces the one in the reading, and `section` is that section's name as the page shows it, quoted; every
+ * ready model carries `section`, the words 'section {name}' for a piece with sections and null otherwise.
  */
-export function buildJamModel({ position, chordTones = false }) {
-  const declaredState = position.reading.declared ?? { state: 'none' };
+export function buildJamModel({ position, chordTones = false, declaredOverride, section = null }) {
+  const declaredState = declaredOverride ?? position.reading.declared ?? { state: 'none' };
+  const sectionText = section === null || section === undefined ? null : JAM_COPY.declaredSection.replace('{section}', () => section);
   const declaredMode = declaredState.state !== 'none';
   const declared = declaredLine(declaredState);
   if (position.reading.status === 'none' && !declaredMode) {
@@ -507,6 +513,7 @@ export function buildJamModel({ position, chordTones = false }) {
       chordLine,
       noteScaleName,
       declared,
+      section: sectionText,
     };
   }
   if (scale.status === 'clear') {
@@ -536,6 +543,7 @@ export function buildJamModel({ position, chordTones = false }) {
       chordLine,
       noteScaleName,
       declared,
+      section: sectionText,
     };
   }
   if (scale.status === 'ambiguous' || scale.status === 'no-fit') {
@@ -551,6 +559,7 @@ export function buildJamModel({ position, chordTones = false }) {
       chordLine,
       noteScaleName,
       declared,
+      section: sectionText,
     };
   }
   throw new Error(`Moontide: the Jam model cannot draw a scale reading with status '${String(scale.status)}'`);

package/page/jam-view.js

@@ -24,6 +24,7 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
   const jamDeclared = document.getElementById('jam-declared');
   const jamDeclaredLabel = document.getElementById('jam-declared-label');
   const jamDeclaredValue = document.getElementById('jam-declared-value');
+  const jamDeclaredSection = document.getElementById('jam-declared-section');
   const jamScaleLabel = document.getElementById('jam-scale-label');
   const jamScaleName = document.getElementById('jam-scale-name');
   const jamScaleSub = document.getElementById('jam-scale-sub');
@@ -165,6 +166,7 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
   let shownDeclaredKind = null;
   let shownDeclaredText = null;
   let shownDeclaredTitle = null;
+  let shownDeclaredSection = null;
   let shownName = null;
   let shownKind = null;
   let shownSub = null;
@@ -222,6 +224,20 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
     }
   }
 
+  // The section the Declared line speaks for: its words after the value, hidden for a piece without sections.
+  function renderDeclaredSection(section) {
+    if (section === undefined) throw new Error('Moontide: a ready Jam model needs its section field (null without sections).');
+    if (section === shownDeclaredSection) return;
+    if (section === null) {
+      jamDeclaredSection.textContent = '';
+      jamDeclaredSection.hidden = true;
+    } else {
+      jamDeclaredSection.textContent = section;
+      jamDeclaredSection.hidden = false;
+    }
+    shownDeclaredSection = section;
+  }
+
   function renderScale(scale, degrees) {
     if (scale.text !== shownName) {
       jamScaleName.textContent = scale.text;
@@ -477,6 +493,7 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
     }
     lastModel = model;
     renderDeclared(model.declared);
+    renderDeclaredSection(model.section);
     renderScale(model.scale, model.degrees);
     renderStatus(model.status);
     if (model.paused !== shownPaused) {

package/page/lights.js

@@ -0,0 +1,278 @@
+// The lights of the Mixer: the state behind the small dot on every track strip and every group.
+//
+// Pure: no DOM, and the clocks are handed in, so node:test drives it with fake time. The page tells it which tracks
+// the Mixer shows (setLayout), which notes were played (noteSeen) and, once per animation frame, asks which lights
+// changed (frame). It never draws: the Mixer view writes what frame returns.
+//
+// What a light shows. With motion on, a light goes to full in the first frame at or after the moment its note is
+// heard and falls in a straight line to nothing over LIGHT_FADE_MS; a note that comes while it fades starts it over.
+// With motion off nothing blinks: a light stays lit while a note was heard within the last cycle. A group's light
+// shows the brightest of the tracks below it, at any depth, folded or not.
+//
+// Why a note is kept as a time to convert, not as a converted time. A browser sound is due at a time on the audio
+// clock; it is heard later, after the output delay, and the page maps one to the other from the audio context's
+// output timestamp. That timestamp is read once per frame (not once per note: at 40 tracks that would be hundreds of
+// reads a second), so the note waits here as its audio time and `toPerf` turns it into the page clock when a frame runs.
+// A MIDI note already has the time its port got and needs no conversion.
+//
+// Why frame returns only what changed: the page writes to the document only for those lights, in steps of 1/64 of
+// the brightness, so a fading light does not rewrite the same value and 40 tracks stay far under a frame's budget.
+//
+// The two offsets start at 0 and the fade at 180 ms. They are meant to be tuned by ear on real hardware.
+
+import { FRESH_PAIR_MAX_AGE_MS } from './midi-clock.js';
+
+/** How long a light takes to fall from full to dark, with motion on. */
+export const LIGHT_FADE_MS = 180;
+/** Added to the moment a browser sound is heard (positive: later). */
+export const BROWSER_LIGHT_OFFSET_MS = 0;
+/** Added to the timestamp a MIDI note got (positive: later). */
+export const MIDI_LIGHT_OFFSET_MS = 0;
+/** A light's brightness is rounded to this many steps from dark to full. */
+export const LIGHT_STEPS = 64;
+/** The most notes a track keeps waiting; the oldest goes first. */
+export const MAX_PENDING_NOTES = 256;
+
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+
+/**
+ * Maps the audio time a note is due to the moment it is heard, on the page clock (performance.now()).
+ * `pair` is the audio context's output timestamp `{ contextTime, performanceTime }`; while it is fresh the mapping goes
+ * through it. Otherwise (right after the context starts, or while it is suspended) the time is shifted by the context's
+ * own latencies, a missing latency counting as 0.
+ */
+export function heardMapper({ pair, currentTime, baseLatency, outputLatency, perfNow }) {
+  if (!isFiniteNumber(perfNow)) {
+    throw new Error(`Moontide: the lights need the page clock as a number, got ${String(perfNow)}.`);
+  }
+  const fresh =
+    pair !== null &&
+    typeof pair === 'object' &&
+    isFiniteNumber(pair.contextTime) &&
+    isFiniteNumber(pair.performanceTime) &&
+    pair.contextTime > 0 &&
+    pair.performanceTime > 0 &&
+    perfNow - pair.performanceTime < FRESH_PAIR_MAX_AGE_MS;
+  if (fresh) {
+    return (target) => pair.performanceTime + (target - pair.contextTime) * 1000 + BROWSER_LIGHT_OFFSET_MS;
+  }
+  if (!isFiniteNumber(currentTime)) {
+    throw new Error(`Moontide: the lights need the audio clock as a number, got ${String(currentTime)}.`);
+  }
+  const latencyMs = ((isFiniteNumber(baseLatency) ? baseLatency : 0) + (isFiniteNumber(outputLatency) ? outputLatency : 0)) * 1000;
+  return (target) => perfNow + (target - currentTime) * 1000 + latencyMs + BROWSER_LIGHT_OFFSET_MS;
+}
+
+/** Whether `cps` can drive the lights: a number above 0. A piece can set the tempo to 0 and set it back later. */
+export function usableTempo(cps) {
+  return isFiniteNumber(cps) && cps > 0;
+}
+
+/**
+ * The audio context's output timestamp for `heardMapper`, or null when this browser has no such method; the mapper then
+ * shifts a time by the context's own latencies, as it does while the pair is stale.
+ */
+export function readOutputPair(audio) {
+  return typeof audio.getOutputTimestamp === 'function' ? audio.getOutputTimestamp() : null;
+}
+
+/**
+ * What the lights need to know about a Mixer model: `{ tracks, ancestors }`. `tracks` has one entry
+ * `{ key, id, sounding }` for every strip that has a light key (`key` is what a note names, `id` the strip's identity,
+ * which the view finds the light by). A strip that plays MIDI cannot sound in a browser without Web MIDI, so it counts as
+ * not sounding there. `ancestors` maps a strip's id to the keys of the groups above it, outermost first. A model that
+ * is not ready gives an empty layout.
+ */
+export function lightLayout(model, { webMidi }) {
+  const tracks = [];
+  const ancestors = new Map();
+  if (model === null || typeof model !== 'object' || model.status !== 'ready') return { tracks, ancestors };
+  for (const strip of model.strips) {
+    if (strip.lightKey === null || strip.lightKey === undefined) continue;
+    const playsMidi = (strip.midi !== null && strip.midi !== undefined) || strip.playsMidi === true;
+    tracks.push({ key: strip.lightKey, id: strip.identity, sounding: strip.sounding === true && (webMidi === true || !playsMidi) });
+  }
+  if (model.layout !== null && model.layout !== undefined) {
+    for (const group of model.layout.groups) {
+      for (const id of group.members) {
+        const above = ancestors.get(id);
+        if (above === undefined) ancestors.set(id, [group.key]);
+        else above.push(group.key);
+      }
+    }
+  }
+  return { tracks, ancestors };
+}
+
+/**
+ * The light state. `setLayout(layout)` says which tracks and groups exist (see lightLayout); `noteSeen(key, heard)` queues
+ * a note, `heard` being `{ at }` (a time on the page clock, in ms) or `{ target }` (an audio time, in seconds);
+ * `frame(ts, { motion, cps, toPerf })` lights what is due at `ts` and returns `[{ kind, id, value }]` for the lights whose
+ * value changed since the last frame; `reset()` forgets every note and every lit light.
+ */
+export function createLights() {
+  // key -> { id, sounding }
+  let tracks = new Map();
+  // strip id -> keys of the groups above it
+  let ancestors = new Map();
+  // key -> the notes waiting to be heard, each { at } or { target }
+  const pending = new Map();
+  const pendingKeys = new Set();
+  // key -> { litAt, lastHeard }: when a track last lit in a frame, and the latest heard time among its notes
+  const states = new Map();
+  // The keys whose light may be lit now: the only ones a frame looks at.
+  const active = new Set();
+  // What the last frame returned that is not dark: key -> { id, value } for tracks, group key -> value for groups.
+  const shownTracks = new Map();
+  const shownGroups = new Map();
+  // Scratch maps of one frame, kept to write nothing new on the common path.
+  const trackValues = new Map();
+  const groupValues = new Map();
+
+  function forget(key) {
+    pending.delete(key);
+    pendingKeys.delete(key);
+    states.delete(key);
+    active.delete(key);
+  }
+
+  return {
+    setLayout(layout) {
+      if (layout === null || typeof layout !== 'object' || !Array.isArray(layout.tracks) || !(layout.ancestors instanceof Map)) {
+        throw new Error('Moontide: the lights need a layout of tracks and ancestors.');
+      }
+      const next = new Map();
+      // Strips can share a key (a muted copy `hats_` kept next to `hats`): the one that sounds owns the key, so the
+      // copy stays dark and the audible track blinks.
+      for (const track of layout.tracks) {
+        const known = next.get(track.key);
+        if (known !== undefined && known.sounding) continue;
+        next.set(track.key, { id: track.id, sounding: track.sounding === true });
+      }
+      tracks = next;
+      ancestors = layout.ancestors;
+      // A track that is gone or silent drops its notes and reads dark from the next frame on.
+      for (const key of [...pending.keys(), ...states.keys()]) {
+        const track = tracks.get(key);
+        if (track === undefined || !track.sounding) forget(key);
+      }
+    },
+
+    noteSeen(key, heard) {
+      const hasAt = heard !== null && typeof heard === 'object' && isFiniteNumber(heard.at);
+      const hasTarget = heard !== null && typeof heard === 'object' && isFiniteNumber(heard.target);
+      if (!hasAt && !hasTarget) {
+        throw new Error('Moontide: a note for the lights needs a heard time (at) or an audio time (target) that is a number.');
+      }
+      const track = tracks.get(key);
+      if (track === undefined || !track.sounding) return;
+      let queue = pending.get(key);
+      if (queue === undefined) {
+        queue = [];
+        pending.set(key, queue);
+      }
+      queue.push(hasAt ? { at: heard.at } : { target: heard.target });
+      if (queue.length > MAX_PENDING_NOTES) queue.shift();
+      pendingKeys.add(key);
+    },
+
+    frame(ts, { motion, cps, toPerf } = {}) {
+      if (!isFiniteNumber(ts)) throw new Error(`Moontide: a light frame needs a time that is a number, got ${String(ts)}.`);
+      if (motion !== 'on' && motion !== 'off') throw new Error(`Moontide: a light frame needs motion 'on' or 'off', got ${String(motion)}.`);
+      if (!isFiniteNumber(cps) || cps <= 0) throw new Error(`Moontide: a light frame needs a tempo above 0, got ${String(cps)}.`);
+      if (typeof toPerf !== 'function') throw new Error('Moontide: a light frame needs toPerf, the function that turns an audio time into the page clock.');
+
+      // Notes heard by now light their track in this frame. The whole queue is read: a note that arrives out of order must
+      // not wait behind one that is heard later.
+      for (const key of pendingKeys) {
+        const queue = pending.get(key);
+        let latest = -Infinity;
+        let kept = 0;
+        for (let i = 0; i < queue.length; i++) {
+          const note = queue[i];
+          const heard = note.at !== undefined ? note.at : toPerf(note.target);
+          if (!isFiniteNumber(heard)) throw new Error(`Moontide: toPerf gave ${String(heard)} for an audio time, not a number.`);
+          if (heard <= ts) {
+            if (heard > latest) latest = heard;
+          } else {
+            queue[kept++] = note;
+          }
+        }
+        queue.length = kept;
+        if (kept === 0) pendingKeys.delete(key);
+        if (latest === -Infinity) continue;
+        let state = states.get(key);
+        if (state === undefined) {
+          state = { litAt: ts, lastHeard: latest };
+          states.set(key, state);
+        } else {
+          state.litAt = ts;
+          if (latest > state.lastHeard) state.lastHeard = latest;
+        }
+        active.add(key);
+      }
+
+      // The value of every light that may be lit; a track whose value reached 0 leaves the active set.
+      trackValues.clear();
+      groupValues.clear();
+      const cycleMs = 1000 / cps;
+      for (const key of active) {
+        const state = states.get(key);
+        const track = tracks.get(key);
+        let value = 0;
+        if (state !== undefined && track !== undefined && track.sounding) {
+          if (motion === 'on') {
+            value = Math.round(Math.min(1, Math.max(0, 1 - (ts - state.litAt) / LIGHT_FADE_MS)) * LIGHT_STEPS) / LIGHT_STEPS;
+          } else {
+            value = ts - state.lastHeard <= cycleMs ? 1 : 0;
+          }
+        }
+        if (value <= 0) {
+          active.delete(key);
+          continue;
+        }
+        trackValues.set(key, value);
+        const above = ancestors.get(track.id);
+        if (above === undefined) continue;
+        for (const group of above) {
+          if (value > (groupValues.get(group) ?? 0)) groupValues.set(group, value);
+        }
+      }
+
+      const changes = [];
+      for (const [key, value] of trackValues) {
+        const shown = shownTracks.get(key);
+        if (shown !== undefined && shown.value === value) continue;
+        const id = tracks.get(key).id;
+        if (shown === undefined) shownTracks.set(key, { id, value });
+        else shown.value = value;
+        changes.push({ kind: 'track', id, value });
+      }
+      for (const [key, shown] of shownTracks) {
+        if (trackValues.has(key)) continue;
+        shownTracks.delete(key);
+        changes.push({ kind: 'track', id: shown.id, value: 0 });
+      }
+      for (const [group, value] of groupValues) {
+        if (shownGroups.get(group) === value) continue;
+        shownGroups.set(group, value);
+        changes.push({ kind: 'group', id: group, value });
+      }
+      for (const group of shownGroups.keys()) {
+        if (groupValues.has(group)) continue;
+        shownGroups.delete(group);
+        changes.push({ kind: 'group', id: group, value: 0 });
+      }
+      return changes;
+    },
+
+    reset() {
+      pending.clear();
+      pendingKeys.clear();
+      states.clear();
+      active.clear();
+      shownTracks.clear();
+      shownGroups.clear();
+    },
+  };
+}