moontide-mcp 2.1.0 → 2.4.0

package/page/scratch-gesture.js

@@ -0,0 +1,239 @@
+// Pure module for the Scratchpad roll: the numbers behind a pointer. Distances are written in rem, the unit the whole page is sized
+// in; the caller multiplies them by the root font size it reads when a press starts, so a larger root makes the targets larger too.
+// A point on the roll becomes a cell, a drawn length, a move or a new length through the same whole units the model keeps, so what is
+// previewed is what is committed. The rows of the roll are worked out from the notes, so every row function takes the number of rows
+// shown and the pitch of the top row. No DOM access and no timers here, so node:test and the view import the module without a build step.
+
+/** A press that moves less than this is a click; a press that moves more is a drag. */
+export const DRAG_THRESHOLD_REM = 0.25;
+
+/** The width of the handle at a note's right side that resizes it, and the most of a short note it may take. */
+export const EDGE_HANDLE_REM = 0.5;
+export const EDGE_HANDLE_SHARE = 0.4;
+
+/** A drag within this distance of the edge of the visible roll scrolls it, by `EDGE_SCROLL_REM` on each pointer move. */
+export const EDGE_ZONE_REM = 1.5;
+export const EDGE_SCROLL_REM = 1;
+
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+
+/** The nearest grid line to `position` for lines `size` apart, with a tie going to the earlier line; `position` may be fractional. */
+function nearestLine(position, size) {
+  return Math.ceil(position / size - 0.5);
+}
+
+/** Turns a negative zero into 0, so a start of 0 is the same value however it was worked out. */
+const whole = (value) => value + 0;
+
+/**
+ * Where the pointer is along the motif, in units, even outside the grid (a negative number left of it, more than `units` right of it).
+ * `rect` is the grid's box in the page (`left`, `width`), `units` the motif's length in units.
+ */
+export function pointerUnit({ rect, x, units }) {
+  return ((x - rect.left) / rect.width) * units;
+}
+
+/** The row the pointer is in, counted from the top row at 0, even outside the grid. `rect` has `top` and `height` for the `rows` rows shown. */
+export function pointerRow({ rect, y, rows }) {
+  return Math.floor((y - rect.top) / (rect.height / rows));
+}
+
+/**
+ * The cell under a point: `{ unit, pitch }`, where `unit` is the start of the grid step that holds the point and `pitch` the pitch
+ * of its row (the top of the `rows` rows shown is `high`). A point outside the grid's box gives null.
+ */
+export function cellAt({ rect, x, y, units, gridUnit, rows, high }) {
+  if (x < rect.left || x >= rect.left + rect.width || y < rect.top || y >= rect.top + rect.height) return null;
+  const unit = Math.floor(pointerUnit({ rect, x, units }) / gridUnit) * gridUnit;
+  return { unit, pitch: high - pointerRow({ rect, y, rows }) };
+}
+
+/**
+ * The box a selection drag spans, in units and rows counted from the top row at 0: `{ fromUnit, toUnit, topRow, bottomRow }`, the same
+ * whichever way the pointer went from the press (`x0`, `y0`) to where it is (`x1`, `y1`), and held inside the grid. The numbers are
+ * fractions, so a box over part of a cell still says which part. `rect` is the grid's box (`left`, `top`, `width`, `height`), `units` the
+ * motif's length and `rows` the rows the grid shows.
+ */
+export function selectionBox({ rect, x0, y0, x1, y1, units, rows }) {
+  const unitOf = (x) => clamp(pointerUnit({ rect, x, units }), 0, units);
+  const rowOf = (y) => clamp(((y - rect.top) / rect.height) * rows, 0, rows);
+  const [a, b] = [unitOf(x0), unitOf(x1)];
+  const [c, d] = [rowOf(y0), rowOf(y1)];
+  return { fromUnit: whole(Math.min(a, b)), toUnit: whole(Math.max(a, b)), topRow: whole(Math.min(c, d)), bottomRow: whole(Math.max(c, d)) };
+}
+
+/**
+ * The ids of the notes a selection box touches: a note whose span overlaps the box's span and whose row lies between the rows the box's
+ * top and bottom fall in. A note that only ends where the box starts, or starts where it ends, is not touched; a box with no width
+ * touches the note whose span holds it. `high` is the pitch of the top row, so a note's row is `high` minus its pitch.
+ */
+export function notesInBox({ notes, box, high }) {
+  const first = Math.floor(box.topRow);
+  const last = Math.floor(box.bottomRow);
+  const flat = box.toUnit <= box.fromUnit;
+  return notes
+    .filter((note) => {
+      const row = high - note.pitch;
+      if (row < first || row > last) return false;
+      const end = note.start + note.length;
+      return flat ? note.start <= box.fromUnit && end > box.fromUnit : note.start < box.toUnit && end > box.fromUnit;
+    })
+    .map((note) => note.id);
+}
+
+/**
+ * The length of a note drawn from `start` to the pointer: up to the end of the grid step under the pointer, that step included, at
+ * least one step and at most to the motif's end. A pointer before the start gives one step. `pointerUnit` is where the pointer is, in units.
+ */
+export function drawLength({ start, pointerUnit: at, gridUnit, units }) {
+  const end = (Math.floor(at / gridUnit) + 1) * gridUnit;
+  return clamp(end - start, gridUnit, units - start);
+}
+
+/**
+ * Where a dragged note lands: `{ start, pitch }`. The start is the nearest grid line to where the note's start was dragged to (`dUnits`
+ * units from where it began; a tie goes to the earlier line), held from 0 to the last start that keeps the note inside the motif.
+ * The pitch is `dRows` rows lower (negative: higher), held between `low` and `high`, the lowest and highest shown pitch.
+ */
+export function moveTarget({ note, dUnits, dRows, gridUnit, units, low, high }) {
+  const last = Math.floor((units - note.length) / gridUnit) * gridUnit;
+  return {
+    start: whole(clamp(nearestLine(note.start + dUnits, gridUnit) * gridUnit, 0, last)),
+    pitch: clamp(note.pitch - dRows, low, high),
+  };
+}
+
+/**
+ * Where a dragged group of notes lands, as one move for the whole group: `{ dStart, dPitch }` in units and semitones. The start move is
+ * `dUnits` snapped to the nearest grid line (a tie goes to the earlier line) and held so the earliest note stays at or after 0 and the
+ * latest end at or before `units`; the group keeps its shape, so one note decides how far it can go. The pitch move is `dRows` rows lower
+ * (negative: higher) held so every pitch stays between `low` and `high`, the lowest and highest shown pitch. A note already outside those
+ * rows is not pulled in: the group just cannot go further out.
+ */
+export function groupMoveTarget({ notes, dUnits, dRows, gridUnit, units, low, high }) {
+  const first = Math.min(...notes.map((note) => note.start));
+  const last = Math.max(...notes.map((note) => note.start + note.length));
+  const lowest = Math.min(...notes.map((note) => note.pitch));
+  const highest = Math.max(...notes.map((note) => note.pitch));
+  return {
+    dStart: whole(clamp(nearestLine(dUnits, gridUnit) * gridUnit, -first, units - last)),
+    dPitch: whole(clamp(-dRows, Math.min(0, low - lowest), Math.max(0, high - highest))),
+  };
+}
+
+/**
+ * The length a dragged edge gives a note that starts at `start`: it ends on the nearest grid line to the pointer (a tie goes to the
+ * earlier line), at least one step long and at most to the motif's end.
+ */
+export function resizeLength({ start, pointerUnit: at, gridUnit, units }) {
+  return clamp(nearestLine(at, gridUnit) * gridUnit - start, gridUnit, units - start);
+}
+
+/**
+ * Which part of a note a press is on: `'edge'` when it is within `EDGE_HANDLE_REM` of the note's right side, or within the share of a
+ * short note that `EDGE_HANDLE_SHARE` allows, else `'body'`. `left` and `width` are the note's box in pixels, `remPx` the root font size.
+ */
+export function pickPart({ left, width, x, remPx }) {
+  const handle = Math.min(EDGE_HANDLE_REM * remPx, EDGE_HANDLE_SHARE * width);
+  return x >= left + width - handle ? 'edge' : 'body';
+}
+
+/** True once a pointer that went down has moved `thresholdPx` pixels or more (`dx` and `dy` are its distance from the press). */
+export function lockDrag({ dx, dy, thresholdPx }) {
+  return Math.hypot(dx, dy) >= thresholdPx;
+}
+
+/**
+ * How far to scroll the roll, in pixels, for a drag whose pointer is at `x`: minus one `EDGE_SCROLL_REM` toward the left edge when the
+ * pointer is within `EDGE_ZONE_REM` of `left`, plus one toward the right edge when it is within that distance of `right` (a pointer
+ * past an edge counts), else 0. `left` and `right` are the edges of the part of the roll that shows. A box with no width gives 0.
+ */
+export function edgeScrollPx({ x, left, right, remPx }) {
+  if (right <= left) return 0;
+  const zone = EDGE_ZONE_REM * remPx;
+  const fromLeft = x - left;
+  const fromRight = right - x;
+  if (fromLeft <= zone && fromLeft <= fromRight) return -EDGE_SCROLL_REM * remPx;
+  if (fromRight <= zone) return EDGE_SCROLL_REM * remPx;
+  return 0;
+}
+
+/**
+ * How far to scroll the box vertically after an Undo or a Redo, so the rows it touched show between the ruler and the velocity lane.
+ * `tops` are the screen tops of the rows to show (one per note, may repeat), `cursorTop` the top of the cursor row, `rowHeight` one row,
+ * and `visibleTop` and `visibleBottom` the band between the ruler and the lane. Returns `{ by, nearest }`: `by` is the pixels to add to
+ * the box's scroll (negative scrolls up), and `nearest` the index in `tops` of the row closest to the cursor row (null with no rows).
+ * When the cursor row and the nearest row cannot both fit in the band, `by` is null: the caller has to move the cursor.
+ * Everything that fits together is brought in with the smallest move; otherwise the cursor row goes to the band's edge that leaves the
+ * most room on the side of the nearest row.
+ */
+export function historyScroll({ tops, cursorTop, rowHeight, visibleTop, visibleBottom }) {
+  if (!(rowHeight > 0)) throw new Error(`Moontide: a history scroll needs a row height above 0, got ${String(rowHeight)}`);
+  if (!(visibleBottom > visibleTop)) throw new Error(`Moontide: a history scroll needs a visible band with a height, got ${String(visibleTop)} to ${String(visibleBottom)}`);
+  let nearest = null;
+  tops.forEach((top, index) => {
+    if (nearest === null || Math.abs(top - cursorTop) < Math.abs(tops[nearest] - cursorTop)) nearest = index;
+  });
+  const band = visibleBottom - visibleTop;
+  const spanTop = Math.min(cursorTop, ...tops);
+  const spanBottom = Math.max(cursorTop, ...tops) + rowHeight;
+  if (spanBottom - spanTop <= band) {
+    if (spanTop < visibleTop) return { by: spanTop - visibleTop, nearest };
+    if (spanBottom > visibleBottom) return { by: spanBottom - visibleBottom, nearest };
+    return { by: 0, nearest };
+  }
+  if (nearest === null) return { by: cursorTop - visibleTop, nearest };
+  const target = tops[nearest];
+  const pairTop = Math.min(cursorTop, target);
+  const pairBottom = Math.max(cursorTop, target) + rowHeight;
+  if (pairBottom - pairTop > band) return { by: null, nearest };
+  const cursorAtBottom = target < cursorTop || (target === cursorTop && tops.filter((top) => top < cursorTop).length > tops.filter((top) => top > cursorTop).length);
+  return { by: cursorAtBottom ? cursorTop + rowHeight - visibleBottom : cursorTop - visibleTop, nearest };
+}
+
+/** The width of the column of piano names at the left of the roll, in rem; the stylesheet draws the same width. */
+export const GUTTER_REM = 4.5;
+
+/** The smallest a beat gets while the motif's cycles are shown, in rem (a sixteenth is 1 rem); less room than that scrolls sideways. */
+export const BEAT_MIN_REM = 4;
+/** The smallest a beat gets while the live view shows 8 cycles, in rem: eight cycles need to fit more often than the motif's. */
+export const LIVE_BEAT_MIN_REM = 2.5;
+/** A row is held from 0.625 rem to 1.25 rem high. */
+const ROW_REM_RANGE = [0.625, 1.25];
+
+/** The width of a beat in rem: the room divided by the beats shown, never less than `minRem` and never capped, so the roll takes all its width. */
+export function beatWidthRem({ availableRem, beats, minRem = BEAT_MIN_REM }) {
+  return Math.max(minRem, availableRem / beats);
+}
+
+/** The height of a row in rem: the room divided by the `rows` rows shown, held from 0.625 to 1.25 rem. More rows than fit at the least scroll. */
+export function rowHeightRem({ availableRem, rows }) {
+  return clamp(availableRem / rows, ...ROW_REM_RANGE);
+}
+
+/** A bar of the velocity lane is at least this wide, with a little air on each side: the room one bar of a chord takes. */
+export const BAR_SLOT_REM = 0.375;
+
+/**
+ * The velocity a pointer at height `y` gives in a lane whose bars area is `rect` (`top` and `height`): the height above the lane's
+ * bottom as a share of its height, in whole hundredths, held from 1 (the bottom edge) to 100 (the top edge). A pointer past either edge is held there.
+ */
+export function velocityAt({ rect, y }) {
+  return clamp(Math.round(((rect.top + rect.height - y) / rect.height) * 100), 1, 100);
+}
+
+/**
+ * The note whose bar is under a pointer at `x`. A bar belongs to the column of its note's start, one grid step wide; notes that start
+ * together share the column side by side, and a bar's share is never narrower than `BAR_SLOT_REM`, so a crowded chord on a narrow step
+ * spreads to the right. `bars` lists `{ id, start, slot, slots }`, `rect` is the bars area (`left` and `width`) for `units` units, and
+ * `remPx` the root font size. Returns the id, or null where no bar is.
+ */
+export function barAt({ rect, x, bars, units, gridUnit, remPx }) {
+  const column = (gridUnit / units) * rect.width;
+  for (const bar of bars) {
+    const share = Math.max(BAR_SLOT_REM * remPx, column / bar.slots);
+    const left = rect.left + (bar.start / units) * rect.width + bar.slot * share;
+    if (x >= left && x < left + share) return bar.id;
+  }
+  return null;
+}

package/page/scratch-listen.js

@@ -0,0 +1,260 @@
+// The Scratchpad's Listen player: it plays the motif's notes, lengths and velocities on an output the user chose, by handing timed notes to an
+// injected `emit`. It holds no browser global and no timer of its own (the page gives it the clock, the timer and the output, like
+// page/midi-in.js), so node:test drives it with fakes, and it knows nothing of Web MIDI: `emit` is page/midi-out.js's sendListenNote.
+//
+// A pass runs every LISTEN_PASS_MS and hands over only the notes due within LISTEN_AHEAD_MS, because Chrome cannot take back a message that
+// has a time stamp. Each note's time is worked out when it is next to go, never far ahead, so a tempo ramp of the music is followed. The player
+// keeps its own record of every note-on it handed over and of every note that sounds, and Stop ends exactly those, with targeted note-offs
+// (never an All Notes Off, which would cut a playing track on a shared channel): an off now for a note that sounds, and an off a moment after
+// the stamp of a note handed over for later.
+//
+// Start 'now' begins a short look-ahead after the press and runs at the music's tempo. Start 'music' begins on a cycle line of the music, so
+// the motif is heard in context. With Loop on the player reads the motif again at each lap, so an edit is heard from the next pass.
+
+import { UNITS_PER_CYCLE, listenSchedule, motifUnits } from './scratch-model.js';
+
+/** How often a pass runs, in milliseconds. */
+export const LISTEN_PASS_MS = 25;
+/** How far ahead of now a note may be handed over: above the page's measured margin for a stamped note, far below its fault limit. */
+export const LISTEN_AHEAD_MS = 150;
+/** How long after the press a start at once begins. */
+export const LISTEN_LEAD_MS = 100;
+/** A cycle line nearer than this when Listen is pressed is too close to catch: the next one is taken. */
+export const LISTEN_LINE_MARGIN_MS = 60;
+/** A note ends this long before its written end, as the music's own MIDI path ends its notes, so two notes of one pitch back to back both sound. */
+export const LISTEN_OFF_EARLY_MS = 10;
+/** The note-off of a note handed over for later goes out this long after its stamp (the same constant as page/midi-out.js). */
+export const LISTEN_QUEUED_OFF_AFTER_MS = 1;
+
+const STARTS = ['now', 'music'];
+
+/**
+ * Builds the player and returns `{ play, stop, setLoop, position, state }`.
+ *
+ * - `perfNow()` is the page clock in milliseconds, the clock the stamps are on; `setTimer(fn, ms)` and `clearTimer(handle)` run the passes.
+ * - `emit({ instrumentId, channel, kind, pitch, velocity, at })` plays one note on or off at the stamp `at` (none: at once) and answers
+ *   `{ ok: true }` or `{ refused: word, ... }`. A refusal ends the play.
+ * - `stampOfCycle(cycle)` gives the stamp of a cycle line of the music, or null; `musicCycle()` the music's cycle now, or null while it does not
+ *   play; `readCps()` the tempo in cycles a second.
+ * - `onState(state)` is told every change: `{ kind: 'waiting', cycle }`, `{ kind: 'playing', loop }`, `{ kind: 'ended' }`, `{ kind: 'stopped', reason }` or
+ *   `{ kind: 'refused', refused, ..., mid }`, each with `instrumentId` and `channel`; `mid` says whether a note had been handed over.
+ *
+ * `play({ readMotif, instrumentId, channel, start, loop })` starts a play ('now' or 'music'; `readMotif()` gives the motif, read again at each lap),
+ * ends one that is playing without a word, and answers whether the new one started. `stop(reason)` silences what the play started and reports it;
+ * it does nothing when nothing plays. `setLoop(on)` changes what happens at the end of the pass. `position()` is the unit in the motif now, or null
+ * while it waits or nothing plays.
+ */
+export function createScratchListen({ perfNow, setTimer, clearTimer, emit, stampOfCycle, musicCycle, readCps, onState = () => {} }) {
+  for (const [name, value] of Object.entries({ perfNow, setTimer, clearTimer, emit, stampOfCycle, musicCycle, readCps, onState })) {
+    if (typeof value !== 'function') throw new TypeError(`Moontide: the Listen player needs ${name}, a function.`);
+  }
+
+  // The play in progress, or null: { readMotif, instrumentId, channel, start, loop, laps, handed, started, finishAt, waiting, timer }.
+  let run = null;
+  let last = { kind: 'idle' };
+
+  function report(state) {
+    last = state;
+    onState(state);
+  }
+
+  const here = () => ({ instrumentId: run.instrumentId, channel: run.channel });
+
+  // One note handed to the output. A refusal comes back as the answer's word; an exception counts as a refusal, so a pass never dies.
+  function send(kind, pitch, velocity, at) {
+    try {
+      const answer = emit({ instrumentId: run.instrumentId, channel: run.channel, kind, pitch, velocity, at });
+      if (answer !== null && typeof answer === 'object' && answer.refused !== undefined) return answer;
+      return null;
+    } catch {
+      return { refused: 'send-failed' };
+    }
+  }
+
+  // Ends what the play started: an off now for a note that sounds, an off just after the stamp of a note whose on is still to come. Best
+  // effort: an output that has gone refuses these too, and there is nothing more to do for it.
+  function silence() {
+    const now = perfNow();
+    for (const entry of run.handed) {
+      if (entry.offAt !== null && entry.offAt <= now) continue;
+      if (entry.onAt > now) send('off', entry.pitch, 0, entry.onAt + LISTEN_QUEUED_OFF_AFTER_MS);
+      else send('off', entry.pitch, 0, undefined);
+    }
+    run.handed = [];
+  }
+
+  // Ends the play with a state to report: the sound is cut, the pass is cancelled and nothing is left to run.
+  function finish(state) {
+    const closing = run;
+    if (closing.timer !== null) clearTimer(closing.timer);
+    closing.timer = null;
+    if (state.kind !== 'ended') silence();
+    run = null;
+    report({ ...state, instrumentId: closing.instrumentId, channel: closing.channel });
+  }
+
+  const refuse = (answer, extra = {}) => finish({ kind: 'refused', ...answer, ...extra, mid: run.started });
+
+  // The next lap of the play, or null after it has finished the play with the reason. `after` is the lap before it (null for the first).
+  // A lap holds the events of the motif as read now, `timeOf(unit)` (the stamp of a unit of the lap, or null when the music's clock gives none),
+  // `unitAt()` (the unit the lap is at now, or null before it begins) and `begun()`.
+  function startLap(after) {
+    const motif = run.readMotif();
+    const events = listenSchedule(motif);
+    if (events.length === 0) return refuse({ refused: 'empty' }) ?? null;
+    const units = motifUnits(motif);
+    const lap = { events, units, next: 0, onAt: new Map() };
+    if (run.start === 'music') {
+      let line;
+      if (after === null) {
+        const cycleNow = musicCycle();
+        if (cycleNow === null) return refuse({ refused: 'music-not-playing' }) ?? null;
+        line = Math.floor(cycleNow) + 1;
+        let stamp = stampOfCycle(line);
+        if (stamp !== null && stamp - perfNow() < LISTEN_LINE_MARGIN_MS) {
+          line += 1;
+          stamp = stampOfCycle(line);
+        }
+        if (stamp === null) return refuse({ refused: 'no-clock' }) ?? null;
+      } else {
+        line = after.line + after.units / UNITS_PER_CYCLE;
+      }
+      return {
+        ...lap,
+        line,
+        timeOf: (unit) => stampOfCycle(line + unit / UNITS_PER_CYCLE),
+        unitAt: () => {
+          const cycle = musicCycle();
+          if (cycle === null) return null;
+          const unit = (cycle - line) * UNITS_PER_CYCLE;
+          return unit < 0 ? null : Math.min(unit, units);
+        },
+        begun: () => {
+          const cycle = musicCycle();
+          return cycle !== null && cycle >= line;
+        },
+      };
+    }
+    const cps = readCps();
+    if (typeof cps !== 'number' || !(cps > 0) || !Number.isFinite(cps)) return refuse({ refused: 'tempo' }) ?? null;
+    const msPerUnit = 1000 / (cps * UNITS_PER_CYCLE);
+    const startPerf = after === null ? perfNow() + LISTEN_LEAD_MS : after.endPerf;
+    return {
+      ...lap,
+      endPerf: startPerf + units * msPerUnit,
+      timeOf: (unit) => startPerf + unit * msPerUnit,
+      unitAt: () => {
+        const unit = (perfNow() - startPerf) / msPerUnit;
+        return unit < 0 ? null : Math.min(unit, units);
+      },
+      begun: () => perfNow() >= startPerf,
+    };
+  }
+
+  // The stamp an event goes out at: its time, with a note ended a little before its written end but never less than 1 ms after it began. Null
+  // when the music's clock gives no time.
+  function stampOf(lap, event) {
+    const at = lap.timeOf(event.unit);
+    if (at === null || event.kind === 'on') return at;
+    return Math.max(at - LISTEN_OFF_EARLY_MS, (lap.onAt.get(event.pitch) ?? -Infinity) + 1);
+  }
+
+  // Records what a handed-over note adds to what is sounding.
+  function note(lap, event, at) {
+    if (event.kind === 'on') {
+      lap.onAt.set(event.pitch, at);
+      run.handed.push({ pitch: event.pitch, onAt: at, offAt: null });
+      return;
+    }
+    const open = run.handed.find((entry) => entry.pitch === event.pitch && entry.offAt === null && entry.onAt <= at);
+    if (open !== undefined) open.offAt = at;
+    run.finishAt = Math.max(run.finishAt, at);
+  }
+
+  function pass() {
+    run.timer = null;
+    const now = perfNow();
+    // In the music, the play ends when the music does: there is no cycle line to play on any more.
+    if (run.start === 'music' && musicCycle() === null) {
+      finish({ kind: 'stopped', reason: 'music-stopped' });
+      return;
+    }
+    run.handed = run.handed.filter((entry) => entry.offAt === null || entry.offAt > now);
+    while (run.laps.length > 1 && run.laps[1].begun()) run.laps.shift();
+    if (run.waiting && run.laps[0].begun()) {
+      run.waiting = false;
+      report({ kind: 'playing', ...here(), loop: run.loop });
+    }
+    for (;;) {
+      let lap = run.laps[run.laps.length - 1];
+      if (lap.next >= lap.events.length) {
+        if (run.loop) {
+          lap = startLap(lap);
+          if (lap === null) return;
+          run.laps.push(lap);
+          continue;
+        }
+        if (now >= run.finishAt) {
+          finish({ kind: 'ended' });
+          return;
+        }
+        break;
+      }
+      const event = lap.events[lap.next];
+      const at = stampOf(lap, event);
+      if (at === null) {
+        refuse({ refused: 'no-clock' });
+        return;
+      }
+      if (at - now > LISTEN_AHEAD_MS) break;
+      const refused = send(event.kind, event.pitch, event.velocity, at);
+      if (refused !== null) {
+        refuse(refused);
+        return;
+      }
+      run.started = true;
+      note(lap, event, at);
+      lap.next += 1;
+    }
+    run.timer = setTimer(pass, LISTEN_PASS_MS);
+  }
+
+  function play({ readMotif, instrumentId, channel, start, loop }) {
+    if (typeof readMotif !== 'function') throw new TypeError('Moontide: the Listen player needs readMotif, a function that gives the motif.');
+    if (!STARTS.includes(start)) throw new Error(`Moontide: a Listen start is 'now' or 'music', got ${String(start)}`);
+    if (run !== null) {
+      if (run.timer !== null) clearTimer(run.timer);
+      silence();
+      run = null;
+    }
+    run = { readMotif, instrumentId, channel, start, loop: loop === true, laps: [], handed: [], started: false, finishAt: -Infinity, waiting: start === 'music', timer: null };
+    const lap = startLap(null);
+    if (lap === null) return false;
+    run.laps.push(lap);
+    report(run.waiting ? { kind: 'waiting', ...here(), cycle: lap.line } : { kind: 'playing', ...here(), loop: run.loop });
+    pass();
+    return run !== null;
+  }
+
+  function stop(reason = 'stop') {
+    if (run === null) return;
+    finish({ kind: 'stopped', reason });
+  }
+
+  function setLoop(on) {
+    if (run === null) return;
+    run.loop = on === true;
+    if (!run.waiting) report({ kind: 'playing', ...here(), loop: run.loop });
+  }
+
+  function position() {
+    if (run === null) return null;
+    for (let index = run.laps.length - 1; index >= 0; index--) {
+      const unit = run.laps[index].unitAt();
+      if (unit !== null) return unit;
+    }
+    return null;
+  }
+
+  return { play, stop, setLoop, position, state: () => last };
+}